Library: Update doxygen documentation
Also, remove the library section from the DESIGN document. Signed-off-by: Anna Schumaker <Anna@OcarinaProject.net>
This commit is contained in:
parent
0758f08642
commit
7ec7026863
93
DESIGN
93
DESIGN
|
@ -66,99 +66,6 @@ Callbacks:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Library:
|
|
||||||
The library is in charge of scanning and updating library paths added
|
|
||||||
to the tag database. In addition, the library layer is also in charge
|
|
||||||
of managing a library queue used by the UI. This queue has a special
|
|
||||||
file format, and will be saved to the file "library.q".
|
|
||||||
|
|
||||||
- Queue:
|
|
||||||
class LibraryQueue : public Queue {
|
|
||||||
public:
|
|
||||||
LibraryQueue();
|
|
||||||
save();
|
|
||||||
load();
|
|
||||||
set_flag(queue_flag);
|
|
||||||
unset_flag(queue_flag);
|
|
||||||
sort(sort_t, bool);
|
|
||||||
};
|
|
||||||
|
|
||||||
File << flags << _sort_order.size()
|
|
||||||
File << _sort_order[N].field << _sort_order[N].ascending << ...
|
|
||||||
|
|
||||||
- Validation:
|
|
||||||
Use a single idle function to loop over each track in the track
|
|
||||||
database. Check if the track still exists in the filesystem and remove
|
|
||||||
it from the tagdb if not.
|
|
||||||
|
|
||||||
- Updating:
|
|
||||||
Scan over all files in the current directory directory.
|
|
||||||
For each encountered directory:
|
|
||||||
Use the idle queue to call the update function with the new
|
|
||||||
directory as the "current" directory.
|
|
||||||
For each encountered file:
|
|
||||||
Attempt to add the file to the track_db.
|
|
||||||
Commit the database if at least one new file has been added.
|
|
||||||
|
|
||||||
- Testing:
|
|
||||||
The script tests/library/gen_library.sh will create a sample library
|
|
||||||
in the /tmp/ directory for testing purposes. All the track files are
|
|
||||||
complete silence, but the script will fake up tags for each file.
|
|
||||||
|
|
||||||
To test importing, create several mock library files and copy them to
|
|
||||||
~/.ocarina-test/library/ and attempt to read them in.
|
|
||||||
|
|
||||||
- LibraryQueue API:
|
|
||||||
LibraryQueue :: LibraryQueue();
|
|
||||||
Initialize a Queue with the flags Q_ENABLED and Q_REPEAT. The
|
|
||||||
default sorting order should be artist, year, track.
|
|
||||||
|
|
||||||
LibraryQueue :: save();
|
|
||||||
Write a library queue to disk.
|
|
||||||
|
|
||||||
LibraryQueue :: load();
|
|
||||||
Read a library queue from disk.
|
|
||||||
|
|
||||||
LibraryQueue :: set_flag(queue_flag f);
|
|
||||||
LibraryQueue :: unset_flag(queue_flag f);
|
|
||||||
LibraryQueue :: sort(sort_t field, bool reset);
|
|
||||||
These functions are wrappers around the default Queue
|
|
||||||
implementation. First call the original function, then use
|
|
||||||
save() to store the changes.
|
|
||||||
|
|
||||||
- API
|
|
||||||
void library :: init();
|
|
||||||
Scan the tagdb track list, and add each track to the library
|
|
||||||
queue.
|
|
||||||
|
|
||||||
Library *library :: add(string dir);
|
|
||||||
If dir is not a directory:
|
|
||||||
return NULL
|
|
||||||
|
|
||||||
Add a new path to the tag database, trigger an update, and
|
|
||||||
then return the corresponding Library tag to the caller.
|
|
||||||
|
|
||||||
void library :: remove(Library *library);
|
|
||||||
Invalidate a library_db row and all tracks owned by that path.
|
|
||||||
Do not use the library pointer after calling this function.
|
|
||||||
|
|
||||||
void library :: update(Library *library);
|
|
||||||
First, validate all tracks in the given library.
|
|
||||||
Next, trigger an update on the given library.
|
|
||||||
|
|
||||||
void library :: update_all();
|
|
||||||
Update all valid library paths.
|
|
||||||
|
|
||||||
void library :: set_enabled(Library *library, bool enabled);
|
|
||||||
Toggle if a library path is enabled or not. A disabled
|
|
||||||
library path will have its tracks removed from the
|
|
||||||
LibraryQueue.
|
|
||||||
|
|
||||||
Queue *library :: get_queue();
|
|
||||||
Return the LibraryQueue to the caller.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Playlist:
|
Playlist:
|
||||||
Playlists are a new feature in Ocarina 6 and are modeled after Gmail
|
Playlists are a new feature in Ocarina 6 and are modeled after Gmail
|
||||||
labels. Ocarina 6.2 will support two different playlists that the
|
labels. Ocarina 6.2 will support two different playlists that the
|
||||||
|
|
|
@ -10,13 +10,22 @@
|
||||||
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Namespace for library access.
|
* The Library is in charge of scanning and updating Library tags along
|
||||||
|
* with every other tag in the tag database. This code will also manage
|
||||||
|
* a special Queue used by the UI to display all enabled Tracks.
|
||||||
|
*
|
||||||
|
* The library queue is dynamic, so saving involves only storing the current
|
||||||
|
* flags and sort order.
|
||||||
|
*
|
||||||
|
* ... << flags << _sort_order.size()
|
||||||
|
* ... << _sort_order[N].field << _sort_order[N].ascending << ...
|
||||||
*/
|
*/
|
||||||
namespace library
|
namespace library
|
||||||
{
|
{
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Initialize the library queue with all the tracks in the tagdb.
|
* Scan over every Track tag and add each enabled Track to the
|
||||||
|
* library queue.
|
||||||
*/
|
*/
|
||||||
void init();
|
void init();
|
||||||
|
|
||||||
|
@ -24,31 +33,38 @@ namespace library
|
||||||
* Add a new directory to the library.
|
* Add a new directory to the library.
|
||||||
*
|
*
|
||||||
* @param dir The directory that should be scanned.
|
* @param dir The directory that should be scanned.
|
||||||
* @return The newly created library object.
|
* @return The newly created Library tag or NULL if a
|
||||||
|
* tag could not be created.
|
||||||
*/
|
*/
|
||||||
Library *add(const std::string &);
|
Library *add(const std::string &);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Remove a library from the database.
|
* Remove a Library tag from the database along with every
|
||||||
|
* Track associated with this library.
|
||||||
*
|
*
|
||||||
* @param library The library path that should be removed.
|
* @param library The library path that should be removed.
|
||||||
*/
|
*/
|
||||||
void remove(Library *);
|
void remove(Library *);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Update a specific library path.
|
* First, scan over every Track in the database and remove
|
||||||
|
* tracks that no longer exist in the filesystem.
|
||||||
|
*
|
||||||
|
* Next, scan over every file in the Library's root directory
|
||||||
|
* and create new Track tags for every file found.
|
||||||
*
|
*
|
||||||
* @param library The library path that should be updated.
|
* @param library The library path that should be updated.
|
||||||
*/
|
*/
|
||||||
void update(Library *);
|
void update(Library *);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Rescan and update all library paths.
|
* Call library :: update() on all Library tags.
|
||||||
*/
|
*/
|
||||||
void update_all();
|
void update_all();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Use to enable or disable a library path.
|
* Use to enable or disable a library path. When a Library path
|
||||||
|
* is disabled, its tracks will be removed from the Library queue.
|
||||||
*
|
*
|
||||||
* @param library The library to be enabled or disabled.
|
* @param library The library to be enabled or disabled.
|
||||||
* @param enabled Set to true if the library should be enabled,
|
* @param enabled Set to true if the library should be enabled,
|
||||||
|
|
Loading…
Reference in New Issue