diff options
Diffstat (limited to 'Src/playlist/api_playlists.h')
| -rw-r--r-- | Src/playlist/api_playlists.h | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/Src/playlist/api_playlists.h b/Src/playlist/api_playlists.h new file mode 100644 index 00000000..6e205b0f --- /dev/null +++ b/Src/playlist/api_playlists.h @@ -0,0 +1,290 @@ +#ifndef NULLSOFT_PLAYLIST_API_PLAYLISTS_H +#define NULLSOFT_PLAYLIST_API_PLAYLISTS_H + +#include <bfc/dispatch.h> +#include <bfc/platform/guid.h> +#include <bfc/std_mkncc.h> +// manages Winamp's master list of playlists + +/* Important note to users of this API: + This API does not actually parse or in any way read the contents of the playlist files themselves. + It only manages the master "list" of playlists, used in e.g. ml_playlists. + + --- important --- + This also means that some information retrieved through this API can be inaccurate, + such as playlist item length or total time. These values are provided as a cache, + to speed up display of UI. They are not to be relied on for determining how many items + are actually in the playlist. Don't use this value to allocate memory for data structures, + unless it's just an initial guess and you allow for realloc'ing if the count is higher. + ----------------- + + It is recommended (but not required) that you call SetInfo to update calculated values, + such as playlist item length, whenever you parse the playlist and have accurate information. + + If you need playlist parsing, use api_playlistmanager. + + This API is thread-safe, as long as you properly call Lock/Unlock + Methods which don't require external locking are marked with [*] + Note that these methods still lock internally + */ + +enum +{ + API_PLAYLISTS_SUCCESS = 0, + API_PLAYLISTS_FAILURE = 1, // general purpose failure + API_PLAYLISTS_UNKNOWN_INFO_GUID = 2, // bad GUID passed to Set/GetInfo + API_PLAYLISTS_UNABLE_TO_LOAD_PLAYLISTS = 3, // take that variable name, FORTRAN77! + API_PLAYLISTS_INVALID_INDEX = 4, // index you passed was out of range + API_PLAYLISTS_BAD_SIZE = 5, // bad dataLen passed to Set/GetInfo +}; + +class api_playlists : public Dispatchable +{ +protected: + api_playlists() {} + virtual ~api_playlists() {} + +public: + // call these to lock the list of playlists so no one changes in the middle of an operation. be careful with this! + // you can use AutoLockT<api_playlists> to help you out + // indices are only valid between these two calls. call GetGUID() if you need session-persistent identifiers + void Lock(); + void Unlock(); + + size_t GetIterator(); + /* this value changes each time a modification is made that would invalidate indices previously retrieved. + It does not change when information is changed + Use it to test if your index is out of date. + example: + size_t playlistIterator = playlists->GetIterator(); + playlists->GetPosition(myGUID, &index); + // ... do a bunch of stuff + if (playlistIterator != playlists->GetIterator()) + playlists->GetPosition(myGUID, &index); + + This is meant as a tool to aid implementations that want to cache indices to prevent too many GetPosition() lookups + you don't need this function for casual usage of the API + */ + + int Sort( size_t sort_type ); + + void Flush(); // [*] flushes playlists to disk. avoid usage - mainly useful when some program is parsing the playlists.xml file externally + + // get information about playlists + size_t GetCount(); // returns number of playlists + + const wchar_t *GetFilename( size_t index ); // returns API_PLAYLISTS_SUCCESS or API_PLAYLISTS_FAILURE. only valid until you Unlock() + const wchar_t *GetName( size_t index ); // returns API_PLAYLISTS_SUCCESS or API_PLAYLISTS_FAILURE. only valid until you Unlock() + + GUID GetGUID( size_t index ); // retrieves a unique ID which identifies this playlist + + int GetPosition( GUID playlist_guid, size_t *index ); // retrieves the index where a particular playlist ID lives. returns API_PLAYLISTS_SUCCESS or API_PLAYLISTS_FAILURE + int GetInfo( size_t index, GUID info, void *data, size_t dataLen ); // This is for getting "extra" data, see list of GUIDs below. returns API_PLAYLISTS_SUCCESS or API_PLAYLISTS_FAILURE + + // manipulating playlists + // at this time, it is not recommended that you use this API. It is reserved for ml_playlists. + int MoveBefore( size_t index1, size_t index2 ); // moves playlist at position index1 to before index2. setting index2 to anything larger than GetCount() moves to end + + size_t AddPlaylist( const wchar_t *filename, const wchar_t *playlistName, GUID playlist_guid = INVALID_GUID ); // [*] adds a new playlist, returns new index. Generates a GUID if you don't pass third parameter. returns (size_t)-1 on error and (size_t)-2 if already exists + // note: AddPlaylist locks internally, but you need to lock externally if you want to trust the return value + + size_t AddCloudPlaylist( const wchar_t *filename, const wchar_t *playlistName, GUID playlist_guid = INVALID_GUID ); // [*] adds a new playlist, returns new index. Generates a GUID if you don't pass third parameter. returns (size_t)-1 on error and (size_t)-2 if already exists + // note: AddCloudPlaylist locks internally, but you need to lock externally if you want to trust the return value + + size_t AddPlaylist_NoCallback( const wchar_t *filename, const wchar_t *playlistName, GUID playlist_guid = INVALID_GUID ); + // same as AddPlaylist, but doesn't do a syscallback, use when you want to make a few SetInfo calls, + // when you are done, call WASABI_API_SYSCB->syscb_issueCallback(api_playlists::SYSCALLBACK, api_playlists::PLAYLIST_REMOVED_POST, index, 0); yourself + + int SetGUID( size_t index, GUID playlist_guid ); // sets (overrides) a playlist ID. Don't use unless you have some very specific need + int RenamePlaylist( size_t index, const wchar_t *name ); + int MovePlaylist( size_t index, const wchar_t *filename ); // sets a new filename. NOTE: IT'S UP TO YOU TO PHYSICALLY MOVE/RENAME/CREATE THE NEW FILENAME. + int SetInfo( size_t index, GUID info, void *data, size_t dataLen ); // returns API_PLAYLISTS_SUCCESS or API_PLAYLISTS_FAILURE + int RemovePlaylist( size_t index ); // removes a particular playlist + int ClearPlaylists(); // [*] clears the entire list of playlists. Use at your own risk :) + + /* + callbacks. these are sent through api_syscb. + callbacks are typically done within the api_playlists Lock, + so be careful not to deadlock by waiting on another thread that is also using api_playlists + TODO + probably want move, remove, add + need to think through adding, though. Someone might add a playlist and then SetInfo, so don't want to call syscb too early + */ + + enum + { + SYSCALLBACK = MK4CC( 'p', 'l', 'a', 'y' ), + PLAYLIST_ADDED = 10, // param1 = index + PLAYLIST_REMOVED_PRE = 20, // param1 = index, called BEFORE it's removed internally, so you can still query for data (Get* function calls) + PLAYLIST_REMOVED_POST = 30, // no parameters, called after it's removed internally + PLAYLIST_RENAMED = 40, // param1 = index + /* These two callbacks are made by you (not api_playlists) + * pass some unique ID as param2 (e.g. some function pointer or pointer to a global variable) + * so that you can identify your own callbacks if you also listen for these events + */ + PLAYLIST_SAVED = 50, // param1 = index. You should send this when you save a playlist. Surround with Lock()/Unlock() so that the index is valid + PLAYLIST_FLUSH_REQUEST = 60, // param1 = index. Call before you load a playlist to request anyone who might be currently modifying the same playlist to save + }; + + enum + { + SORT_TITLE_ASCENDING, + SORT_TITLE_DESCENDING, + SORT_NUMBER_ASCENDING, + SORT_NUMBER_DESCENDING, + }; + + DISPATCH_CODES + { + API_PLAYLISTS_LOCK = 10, + API_PLAYLISTS_UNLOCK = 20, + API_PLAYLISTS_GETITERATOR = 30, + API_PLAYLISTS_FLUSH = 40, + API_PLAYLISTS_GETCOUNT = 50, + API_PLAYLISTS_GETFILENAME = 60, + API_PLAYLISTS_GETNAME = 70, + API_PLAYLISTS_GETGUID = 80, + API_PLAYLISTS_GETPOSITION = 90, + API_PLAYLISTS_GETINFO = 100, + API_PLAYLISTS_MOVEBEFORE = 110, + API_PLAYLISTS_ADDPLAYLIST = 120, + API_PLAYLISTS_ADDPLAYLISTNOCB = 121, + API_PLAYLISTS_ADDCLOUDPLAYLIST = 122, + API_PLAYLISTS_SETGUID = 130, + API_PLAYLISTS_RENAMEPLAYLIST = 140, + API_PLAYLISTS_MOVEPLAYLIST = 150, + API_PLAYLISTS_SETINFO = 160, + API_PLAYLISTS_REMOVEPLAYLIST = 170, + API_PLAYLISTS_CLEARPLAYLISTS = 180, + API_PLAYLISTS_SORT = 190, + }; +}; + +// Info GUIDS + +// {C4FAD6CE-DA38-47b0-AAA9-E966D8E8E7C5} +static const GUID api_playlists_itemCount = +{ 0xc4fad6ce, 0xda38, 0x47b0, { 0xaa, 0xa9, 0xe9, 0x66, 0xd8, 0xe8, 0xe7, 0xc5 } }; + +// {D4E0E000-A3F5-4f18-ADA5-F2BA40689593} +static const GUID api_playlists_totalTime = +{ 0xd4e0e000, 0xa3f5, 0x4f18, { 0xad, 0xa5, 0xf2, 0xba, 0x40, 0x68, 0x95, 0x93 } }; + +// {F6E1AB19-6931-4cc9-BCBA-4B40DE2A959F} +static const GUID api_playlists_iTunesID = +{ 0xf6e1ab19, 0x6931, 0x4cc9, { 0xbc, 0xba, 0x4b, 0x40, 0xde, 0x2a, 0x95, 0x9f } }; + +// {B83AD244-7CD3-4a24-B2C5-41F42CA37F14} +static const GUID api_playlists_cloud = +{ 0xb83ad244, 0x7cd3, 0x4a24, { 0xb2, 0xc5, 0x41, 0xf4, 0x2c, 0xa3, 0x7f, 0x14 } }; + + +inline void api_playlists::Lock() +{ + _voidcall( API_PLAYLISTS_LOCK ); +} +inline void api_playlists::Unlock() +{ + _voidcall( API_PLAYLISTS_UNLOCK ); +} + +inline size_t api_playlists::GetIterator() +{ + return _call( API_PLAYLISTS_GETITERATOR, 0 ); +} + +inline void api_playlists::Flush() +{ + _voidcall( API_PLAYLISTS_FLUSH ); +} + +inline int api_playlists::Sort( size_t sort_type ) +{ + return _call( API_PLAYLISTS_SORT, 0, sort_type ); +} + +inline size_t api_playlists::GetCount() +{ + return _call( API_PLAYLISTS_GETCOUNT, 0 ); +} + +inline const wchar_t *api_playlists::GetFilename( size_t index ) +{ + return _call( API_PLAYLISTS_GETFILENAME, (const wchar_t *)0, index ); +} + +inline const wchar_t *api_playlists::GetName( size_t index ) +{ + return _call( API_PLAYLISTS_GETNAME, (const wchar_t *)0, index ); +} + +inline GUID api_playlists::GetGUID( size_t index ) +{ + return _call( API_PLAYLISTS_GETGUID, INVALID_GUID, index ); +} + +inline int api_playlists::GetPosition( GUID playlist_guid, size_t *index ) +{ + return _call( API_PLAYLISTS_GETPOSITION, API_PLAYLISTS_FAILURE, playlist_guid, index ); +} + +inline int api_playlists::GetInfo( size_t index, GUID info, void *data, size_t dataLen ) +{ + return _call( API_PLAYLISTS_GETINFO, API_PLAYLISTS_FAILURE, index, info, data, dataLen ); +} + +inline int api_playlists::MoveBefore( size_t index1, size_t index2 ) +{ + return _call( API_PLAYLISTS_MOVEBEFORE, API_PLAYLISTS_FAILURE, index1, index2 ); +} + +inline size_t api_playlists::AddPlaylist( const wchar_t *filename, const wchar_t *playlistName, GUID playlist_guid ) +{ + return _call( API_PLAYLISTS_ADDPLAYLIST, (size_t)-1, filename, playlistName, playlist_guid ); +} + +inline size_t api_playlists::AddPlaylist_NoCallback( const wchar_t *filename, const wchar_t *playlistName, GUID playlist_guid ) +{ + return _call( API_PLAYLISTS_ADDPLAYLISTNOCB, (size_t)-1, filename, playlistName, playlist_guid ); +} + +inline size_t api_playlists::AddCloudPlaylist( const wchar_t *filename, const wchar_t *playlistName, GUID playlist_guid ) +{ + return _call( API_PLAYLISTS_ADDCLOUDPLAYLIST, (size_t)-1, filename, playlistName, playlist_guid ); +} + +inline int api_playlists::SetGUID( size_t index, GUID playlist_guid ) +{ + return _call( API_PLAYLISTS_SETGUID, API_PLAYLISTS_FAILURE, index, playlist_guid ); +} + +inline int api_playlists::RenamePlaylist( size_t index, const wchar_t *name ) +{ + return _call( API_PLAYLISTS_RENAMEPLAYLIST, API_PLAYLISTS_FAILURE, index, name ); +} + +inline int api_playlists::MovePlaylist( size_t index, const wchar_t *filename ) +{ + return _call( API_PLAYLISTS_MOVEPLAYLIST, API_PLAYLISTS_FAILURE, index, filename ); +} + +inline int api_playlists::SetInfo( size_t index, GUID info, void *data, size_t dataLen ) +{ + return _call( API_PLAYLISTS_SETINFO, API_PLAYLISTS_FAILURE, index, info, data, dataLen ); +} + +inline int api_playlists::RemovePlaylist( size_t index ) +{ + return _call( API_PLAYLISTS_REMOVEPLAYLIST, API_PLAYLISTS_FAILURE, index ); +} + +inline int api_playlists::ClearPlaylists() +{ + return _call( API_PLAYLISTS_CLEARPLAYLISTS, API_PLAYLISTS_FAILURE ); +} + +// {2DC3C390-D9B8-4a49-B230-EF240ADDDCDB} +static const GUID api_playlistsGUID = +{ 0x2dc3c390, 0xd9b8, 0x4a49, { 0xb2, 0x30, 0xef, 0x24, 0xa, 0xdd, 0xdc, 0xdb } }; + +#endif
\ No newline at end of file |