290 lines
12 KiB
C
290 lines
12 KiB
C
|
#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
|