playlist_loader Class Reference

#include <playlist_loader.h>

Inheritance diagram for playlist_loader:

service_base

List of all members.

Public Types

typedef playlist_loader t_interface_entrypoint
typedef playlist_loader t_interface
typedef service_base t_interface_parent

Public Member Functions

virtual void open (const char *p_path, const service_ptr_t< file > &p_file, playlist_loader_callback &p_callback)=0
virtual void write (const char *p_path, const service_ptr_t< file > &p_file, const pfc::list_base_const_t< metadb_handle_ptr > &p_data, abort_callback &p_abort)=0
virtual const char * get_extension ()=0
 Returns extension of file format handled by this playlist_loader implementation (a UTF-8 encoded null-terminated string).
virtual bool can_write ()=0
 Returns whether this playlist_loader implementation supports writing. If can_write() returns false, all write() calls will fail.
virtual bool is_our_content_type (const char *p_content_type)=0
virtual bool is_associatable ()=0
 Returns whether playlist format extension supported by this implementation should be listed on file types associations page.

Static Public Member Functions

static void g_load_playlist (const char *p_path, playlist_loader_callback &p_callback)
static void g_load_playlist_filehint (file::ptr fileHint, const char *p_path, playlist_loader_callback &p_callback)
static void g_save_playlist (const char *p_path, const pfc::list_base_const_t< metadb_handle_ptr > &p_data, abort_callback &p_abort)
static void g_process_path (const char *p_path, playlist_loader_callback_v2 &p_callback, playlist_loader_callback::t_entry_type p_type=playlist_loader_callback::entry_user_requested)
static bool g_process_path_ex (const char *p_path, playlist_loader_callback_v2 &p_callback, playlist_loader_callback::t_entry_type p_type=playlist_loader_callback::entry_user_requested)

Static Public Attributes

static const GUID class_guid


Detailed Description

Service handling playlist file operations. There are multiple implementations handling different playlist formats; you can add new implementations to allow new custom playlist file formats to be read or written.
Also provides static helper functions for turning a filesystem path into a list of playable item locations.
Note that you should typically call playlist_incoming_item_filter methods instead of calling playlist_loader methods directly to get a list of playable items from a specified path; this way you get a core-implemented threading and abortable dialog displaying progress.
To register your own implementation, use playlist_loader_factory_t template.
To call existing implementations, use static helper methods of playlist_loader class.

Member Typedef Documentation

Reimplemented from service_base.


Member Function Documentation

virtual void playlist_loader::open ( const char *  p_path,
const service_ptr_t< file > &  p_file,
playlist_loader_callback p_callback 
) [pure virtual]

Parses specified playlist file into list of playable locations. Throws exception_io or derivatives on failure, exception_aborted on abort. If specified file is not a recognized playlist file, exception_io_unsupported_format is thrown.

Parameters:
p_path Path of playlist file to parse. Used for relative path handling purposes (p_file parameter is used for actual file access).
p_file File interface to use for reading. Read/write pointer must be set to beginning by caller before calling.
p_callback Callback object receiving enumerated playable item locations as well as signaling user aborting the operation.

virtual void playlist_loader::write ( const char *  p_path,
const service_ptr_t< file > &  p_file,
const pfc::list_base_const_t< metadb_handle_ptr > &  p_data,
abort_callback &  p_abort 
) [pure virtual]

Writes a playlist file containing specific item list to specified file. Will fail (pfc::exception_not_implemented) if specified playlist_loader is read-only (can_write() returns false).

Parameters:
p_path Path of playlist file to write. Used for relative path handling purposes (p_file parameter is used for actual file access).
p_file File interface to use for writing. Caller should ensure that the file is empty (0 bytes long) before calling.
p_data List of items to save to playlist file.
p_abort abort_callback object signaling user aborting the operation. Note that aborting a save playlist operation will most likely leave user with corrupted/incomplete file.

virtual const char* playlist_loader::get_extension (  )  [pure virtual]

Returns extension of file format handled by this playlist_loader implementation (a UTF-8 encoded null-terminated string).

virtual bool playlist_loader::can_write (  )  [pure virtual]

Returns whether this playlist_loader implementation supports writing. If can_write() returns false, all write() calls will fail.

virtual bool playlist_loader::is_our_content_type ( const char *  p_content_type  )  [pure virtual]

Returns whether specified content type is one of playlist types supported by this playlist_loader implementation or not.

Parameters:
p_content_type Content type to query, a UTF-8 encoded null-terminated string.

virtual bool playlist_loader::is_associatable (  )  [pure virtual]

Returns whether playlist format extension supported by this implementation should be listed on file types associations page.

static void playlist_loader::g_load_playlist ( const char *  p_path,
playlist_loader_callback p_callback 
) [static]

Attempts to load a playlist file from specified filesystem path. Throws exception_io or derivatives on failure, exception_aborted on abort. If specified file is not a recognized playlist file, exception_io_unsupported_format is thrown.
Equivalent to g_load_playlist_filehint(NULL,p_path,p_callback).

Parameters:
p_path Filesystem path to load playlist from, a UTF-8 encoded null-terminated string.
p_callback Callback object receiving enumerated playable item locations as well as signaling user aborting the operation.

static void playlist_loader::g_load_playlist_filehint ( file::ptr  fileHint,
const char *  p_path,
playlist_loader_callback p_callback 
) [static]

Attempts to load a playlist file from specified filesystem path. Throws exception_io or derivatives on failure, exception_aborted on abort. If specified file is not a recognized playlist file, exception_io_unsupported_format is thrown.

Parameters:
p_path Filesystem path to load playlist from, a UTF-8 encoded null-terminated string.
p_callback Callback object receiving enumerated playable item locations as well as signaling user aborting the operation.
fileHint File object to read from, can be NULL if not available.

static void playlist_loader::g_save_playlist ( const char *  p_path,
const pfc::list_base_const_t< metadb_handle_ptr > &  p_data,
abort_callback &  p_abort 
) [static]

Saves specified list of locations into a playlist file. Throws exception_io or derivatives on failure, exception_aborted on abort.

Parameters:
p_path Filesystem path to save playlist to, a UTF-8 encoded null-terminated string.
p_data List of items to save to playlist file.
p_abort abort_callback object signaling user aborting the operation. Note that aborting a save playlist operation will most likely leave user with corrupted/incomplete file.

static void playlist_loader::g_process_path ( const char *  p_path,
playlist_loader_callback_v2 p_callback,
playlist_loader_callback::t_entry_type  p_type = playlist_loader_callback::entry_user_requested 
) [static]

Processes specified path to generate list of playable items. Includes recursive directory/archive enumeration.
Does not touch playlist files encountered - use g_process_path_ex() if specified path is possibly a playlist file; playlist files found inside directories or archives are ignored regardless.
Warning: caller must handle exceptions which will occur in case of I/O failure.

Parameters:
p_path Filesystem path to process; a UTF-8 encoded null-terminated string.
p_callback Callback object receiving enumerated playable item locations as well as signaling user aborting the operation.
p_type Origin of p_path string. Reserved for internal use in recursive calls, should be left at default value; it controls various internal behaviors.

static bool playlist_loader::g_process_path_ex ( const char *  p_path,
playlist_loader_callback_v2 p_callback,
playlist_loader_callback::t_entry_type  p_type = playlist_loader_callback::entry_user_requested 
) [static]

Calls attempts to process specified path as a playlist; if that fails (i.e. not a playlist), calls g_process_path with same parameters. See g_process_path for parameter descriptions.
Warning: caller must handle exceptions which will occur in case of I/O failure or playlist parsing failure.

Returns:
True if specified path was processed as a playlist file, false otherwise (relevant in some scenarios where output is sorted after loading, playlist file contents should not be sorted).


Member Data Documentation

const GUID playlist_loader::class_guid [static]

Initial value:

 
{ 0xd2e5f92b, 0x3424, 0x4822, { 0xae, 0x60, 0x86, 0x63, 0xe6, 0xd2, 0x6e, 0xab } }


The documentation for this class was generated from the following files:

Generated on Fri Apr 25 18:49:48 2008 for foobar2000 SDK by  doxygen 1.5.5