Totem Playlist Parser Reference Manual | ||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
Synopsis
#include <totem-pl-parser.h> TotemPlParser; TotemPlParserClass; enum TotemPlParserResult; enum TotemPlParserType; enum TotemPlParserError; typedef TotemPlParserMetadata; TotemPlParser * totem_pl_parser_new (void
); TotemPlParserResult totem_pl_parser_parse (TotemPlParser *parser
,const char *uri
,gboolean fallback
); void totem_pl_parser_parse_async (TotemPlParser *parser
,const char *uri
,gboolean fallback
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
); TotemPlParserResult totem_pl_parser_parse_finish (TotemPlParser *parser
,GAsyncResult *async_result
,GError **error
); TotemPlParserResult totem_pl_parser_parse_with_base (TotemPlParser *parser
,const char *uri
,const char *base
,gboolean fallback
); void totem_pl_parser_parse_with_base_async (TotemPlParser *parser
,const char *uri
,const char *base
,gboolean fallback
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
); gboolean totem_pl_parser_save (TotemPlParser *parser
,TotemPlPlaylist *playlist
,GFile *dest
,const gchar *title
,TotemPlParserType type
,GError **error
); gint64 totem_pl_parser_parse_duration (const char *duration
,gboolean debug
); guint64 totem_pl_parser_parse_date (const char *date_str
,gboolean debug
); void totem_pl_parser_add_ignored_scheme (TotemPlParser *parser
,const char *scheme
); void totem_pl_parser_add_ignored_mimetype (TotemPlParser *parser
,const char *mimetype
); gboolean totem_pl_parser_can_parse_from_data (const char *data
,gsize len
,gboolean debug
); gboolean totem_pl_parser_can_parse_from_filename (const char *filename
,gboolean debug
); gboolean totem_pl_parser_can_parse_from_uri (const char *uri
,gboolean debug
); #define TOTEM_PL_PARSER_FIELD_URI #define TOTEM_PL_PARSER_FIELD_GENRE #define TOTEM_PL_PARSER_FIELD_TITLE #define TOTEM_PL_PARSER_FIELD_AUTHOR #define TOTEM_PL_PARSER_FIELD_ALBUM #define TOTEM_PL_PARSER_FIELD_BASE #define TOTEM_PL_PARSER_FIELD_VOLUME #define TOTEM_PL_PARSER_FIELD_AUTOPLAY #define TOTEM_PL_PARSER_FIELD_DURATION #define TOTEM_PL_PARSER_FIELD_DURATION_MS #define TOTEM_PL_PARSER_FIELD_STARTTIME #define TOTEM_PL_PARSER_FIELD_ENDTIME #define TOTEM_PL_PARSER_FIELD_COPYRIGHT #define TOTEM_PL_PARSER_FIELD_ABSTRACT #define TOTEM_PL_PARSER_FIELD_DESCRIPTION #define TOTEM_PL_PARSER_FIELD_SUMMARY #define TOTEM_PL_PARSER_FIELD_MOREINFO #define TOTEM_PL_PARSER_FIELD_SCREENSIZE #define TOTEM_PL_PARSER_FIELD_UI_MODE #define TOTEM_PL_PARSER_FIELD_PUB_DATE #define TOTEM_PL_PARSER_FIELD_FILESIZE #define TOTEM_PL_PARSER_FIELD_LANGUAGE #define TOTEM_PL_PARSER_FIELD_CONTACT #define TOTEM_PL_PARSER_FIELD_IMAGE_URI #define TOTEM_PL_PARSER_FIELD_DOWNLOAD_URI #define TOTEM_PL_PARSER_FIELD_ID #define TOTEM_PL_PARSER_FIELD_IS_PLAYLIST #define TOTEM_PL_PARSER_FIELD_SUBTITLE_URI #define TOTEM_PL_PARSER_FIELD_CONTENT_TYPE
Properties
"debug" gboolean : Read / Write "disable-unsafe" gboolean : Read / Write "force" gboolean : Read / Write "recurse" gboolean : Read / Write / Construct
Description
TotemPlParser is a general-purpose playlist parser and writer, with support for several different types of playlist. Note that totem-pl-parser requires a main loop to operate properly (e.g. for the "entry-parsed" signal to be emitted).
Example 1. Reading a Playlist
1 2 3 4 5 6 7 8 9 |
TotemPlParser *pl = totem_pl_parser_new (); g_object_set (pl, "recurse", FALSE, "disable-unsafe", TRUE, NULL); g_signal_connect (G_OBJECT (pl), "playlist-started", G_CALLBACK (playlist_started), NULL); g_signal_connect (G_OBJECT (pl), "entry-parsed", G_CALLBACK (entry_parsed), NULL); if (totem_pl_parser_parse (pl, "http://example.com/playlist.pls", FALSE) != TOTEM_PL_PARSER_RESULT_SUCCESS) g_error ("Playlist parsing failed."); g_object_unref (pl); |
Example 2. Reading a Playlist Asynchronously
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
TotemPlParser *pl = totem_pl_parser_new (); g_object_set (pl, "recurse", FALSE, "disable-unsafe", TRUE, NULL); g_signal_connect (G_OBJECT (pl), "playlist-started", G_CALLBACK (playlist_started), NULL); g_signal_connect (G_OBJECT (pl), "entry-parsed", G_CALLBACK (entry_parsed), NULL); totem_pl_parser_parse_async (pl, "http://example.com/playlist.pls", FALSE, NULL, parse_cb, NULL); g_object_unref (pl); static void parse_cb (TotemPlParser *parser, GAsyncResult *result, gpointer user_data) { GError *error = NULL; if (totem_pl_parser_parse_finish (parser, result, &error) != TOTEM_PL_PARSER_RESULT_SUCCESS) { g_error ("Playlist parsing failed: %s", error->message); g_error_free (error); } } |
Example 3. Getting Metadata from Entries
1 2 3 4 5 6 7 8 9 |
static void entry_parsed (TotemPlParser *parser, const gchar *uri, GHashTable *metadata, gpointer user_data) { gchar *title = g_hash_table_lookup (metadata, TOTEM_PL_PARSER_FIELD_TITLE); if (title != NULL) g_message ("Entry title: %s", title); else g_message ("Entry (URI: %s) has no title.", uri); } |
Example 4. Writing a Playlist
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
{ TotemPlParser *pl; TotemPlPlaylist *playlist; TotemPlPlaylistIter iter; GFile *file; pl = totem_pl_parser_new (); playlist = totem_pl_playlist_new (); file = g_file_new_for_path ("/tmp/playlist.pls"); totem_pl_playlist_append (playlist, &iter); totem_pl_playlist_set (playlist, &iter, TOTEM_PL_PARSER_FIELD_URI, "file:///1.ogg", TOTEM_PL_PARSER_FIELD_TITLE, "1.ogg", NULL); totem_pl_playlist_append (playlist, &iter); totem_pl_playlist_set (playlist, &iter, TOTEM_PL_PARSER_FIELD_URI, "file:///2.ogg", NULL); if (totem_pl_parser_save (pl, playlist, file, "Title", TOTEM_PL_PARSER_PLS, NULL) != TRUE) { g_error ("Playlist writing failed."); } g_object_unref (playlist); g_object_unref (pl); g_object_unref (file); } |
Details
TotemPlParser
typedef struct _TotemPlParser TotemPlParser;
All the fields in the TotemPlParser structure are private and should never be accessed directly.
TotemPlParserClass
typedef struct { GObjectClass parent_class; /* signals */ void (*entry_parsed) (TotemPlParser *parser, const char *uri, GHashTable *metadata); void (*playlist_started) (TotemPlParser *parser, const char *uri, GHashTable *metadata); void (*playlist_ended) (TotemPlParser *parser, const char *uri); } TotemPlParserClass;
The class structure for the TotemPlParser type.
GObjectClass |
the parent class |
the generic signal handler for the "entry-parsed" signal, which can be overridden by inheriting classes | |
the generic signal handler for the "playlist-started" signal, which can be overridden by inheriting classes | |
the generic signal handler for the "playlist-ended" signal, which can be overridden by inheriting classes |
enum TotemPlParserResult
typedef enum { TOTEM_PL_PARSER_RESULT_UNHANDLED, TOTEM_PL_PARSER_RESULT_ERROR, TOTEM_PL_PARSER_RESULT_SUCCESS, TOTEM_PL_PARSER_RESULT_IGNORED, TOTEM_PL_PARSER_RESULT_CANCELLED } TotemPlParserResult;
Gives the result of parsing a playlist.
The playlist could not be handled. | |
There was an error parsing the playlist. | |
The playlist was parsed successfully. | |
The playlist was ignored due to its scheme or MIME type (see totem_pl_parser_add_ignored_scheme()
and totem_pl_parser_add_ignored_mimetype() ).
|
|
Parsing of the playlist was cancelled part-way through. |
enum TotemPlParserType
typedef enum { TOTEM_PL_PARSER_PLS, TOTEM_PL_PARSER_M3U, TOTEM_PL_PARSER_M3U_DOS, TOTEM_PL_PARSER_XSPF, TOTEM_PL_PARSER_IRIVER_PLA, } TotemPlParserType;
The type of playlist a TotemPlParser will parse.
enum TotemPlParserError
typedef enum { TOTEM_PL_PARSER_ERROR_NO_DISC, TOTEM_PL_PARSER_ERROR_MOUNT_FAILED, TOTEM_PL_PARSER_ERROR_EMPTY_PLAYLIST } TotemPlParserError;
Allows you to differentiate between different errors occurring during file operations in a TotemPlParser.
totem_pl_parser_new ()
TotemPlParser * totem_pl_parser_new (void
);
Creates a TotemPlParser object.
Returns : |
a new TotemPlParser |
totem_pl_parser_parse ()
TotemPlParserResult totem_pl_parser_parse (TotemPlParser *parser
,const char *uri
,gboolean fallback
);
Parses a playlist given by the absolute URI uri
. This method is
synchronous, and will block on (e.g.) network requests to slow
servers. totem_pl_parser_parse_async()
is recommended instead.
Return values are as totem_pl_parser_parse_with_base()
.
|
a TotemPlParser |
|
the URI of the playlist to parse |
|
TRUE if the parser should add the playlist URI to the
end of the playlist on parse failure |
Returns : |
a TotemPlParserResult |
totem_pl_parser_parse_async ()
void totem_pl_parser_parse_async (TotemPlParser *parser
,const char *uri
,gboolean fallback
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Starts asynchronous parsing of a playlist given by the absolute URI uri
. parser
and uri
are both reffed/copied
when this function is called, so can safely be freed after this function returns.
For more details, see totem_pl_parser_parse()
, which is the synchronous version of this function.
When the operation is finished, callback
will be called. You can then call totem_pl_parser_parse_finish()
to get the results of the operation.
|
a TotemPlParser |
|
the URI of the playlist to parse |
|
TRUE if the parser should add the playlist URI to the
end of the playlist on parse failure |
|
optional GCancellable object, or NULL . [allow-none]
|
|
a GAsyncReadyCallback to call when parsing is finished. [allow-none] |
|
data to pass to the callback function |
totem_pl_parser_parse_finish ()
TotemPlParserResult totem_pl_parser_parse_finish (TotemPlParser *parser
,GAsyncResult *async_result
,GError **error
);
Finishes an asynchronous playlist parsing operation started with totem_pl_parser_parse_async()
or totem_pl_parser_parse_with_base_async()
.
If parsing of the playlist is cancelled part-way through, TOTEM_PL_PARSER_RESULT_CANCELLED
is returned when
this function is called.
|
a TotemPlParser |
|
a GAsyncResult |
|
a GError, or NULL
|
Returns : |
a TotemPlParserResult |
totem_pl_parser_parse_with_base ()
TotemPlParserResult totem_pl_parser_parse_with_base (TotemPlParser *parser
,const char *uri
,const char *base
,gboolean fallback
);
Parses a playlist given by the absolute URI uri
, using
base
to resolve relative paths where appropriate.
|
a TotemPlParser |
|
the URI of the playlist to parse |
|
the base path for relative filenames, or NULL . [allow-none]
|
|
TRUE if the parser should add the playlist URI to the
end of the playlist on parse failure |
Returns : |
a TotemPlParserResult |
totem_pl_parser_parse_with_base_async ()
void totem_pl_parser_parse_with_base_async (TotemPlParser *parser
,const char *uri
,const char *base
,gboolean fallback
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Starts asynchronous parsing of a playlist given by the absolute URI uri
, using base
to resolve relative paths where appropriate.
parser
and uri
are both reffed/copied when this function is called, so can safely be freed after this function returns.
For more details, see totem_pl_parser_parse_with_base()
, which is the synchronous version of this function.
When the operation is finished, callback
will be called. You can then call totem_pl_parser_parse_finish()
to get the results of the operation.
|
a TotemPlParser |
|
the URI of the playlist to parse |
|
the base path for relative filenames, or NULL . [allow-none]
|
|
TRUE if the parser should add the playlist URI to the
end of the playlist on parse failure |
|
optional GCancellable object, or NULL . [allow-none]
|
|
a GAsyncReadyCallback to call when parsing is finished. [allow-none] |
|
data to pass to the callback function |
totem_pl_parser_save ()
gboolean totem_pl_parser_save (TotemPlParser *parser
,TotemPlPlaylist *playlist
,GFile *dest
,const gchar *title
,TotemPlParserType type
,GError **error
);
Writes the playlist held by parser
and playlist
out to the path
pointed by dest
. The playlist is written in the format type
and is
given the title title
.
If the output
file is a directory the G_IO_ERROR_IS_DIRECTORY error
will be returned, and if the file is some other form of non-regular file
then a G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some file
systems don't allow all file names, and may return a
G_IO_ERROR_INVALID_FILENAME error, and if the name is too long,
G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible
too, and depend on what kind of filesystem the file is on.
In extreme cases, a G_IO_ERROR_INVALID_ARGUMENT error can be returned, if parts of the playlist to be written are too long.
If writing a PLA playlist and there is an error converting a URI's encoding, a code from GConvertError will be returned.
|
a TotemPlParser |
|
a TotemPlPlaylist |
|
output GFile |
|
the playlist title |
|
a TotemPlParserType for the outputted playlist |
|
return loction for a GError, or NULL
|
Returns : |
TRUE on success |
totem_pl_parser_parse_duration ()
gint64 totem_pl_parser_parse_duration (const char *duration
,gboolean debug
);
Parses the given duration string and returns it as a gint64 denoting the duration in seconds.
|
the duration string to parse |
|
TRUE if debug statements should be printed |
Returns : |
the duration in seconds, or -1 on error |
totem_pl_parser_parse_date ()
guint64 totem_pl_parser_parse_date (const char *date_str
,gboolean debug
);
Parses the given date string and returns it as a gint64 denoting the date in seconds since the UNIX Epoch.
|
the date string to parse |
|
TRUE if debug statements should be printed |
Returns : |
the date in seconds, or -1 on error |
totem_pl_parser_add_ignored_scheme ()
void totem_pl_parser_add_ignored_scheme (TotemPlParser *parser
,const char *scheme
);
Adds a scheme to the list of schemes to ignore, so that any URI using that scheme is ignored during playlist parsing.
|
a TotemPlParser |
|
the scheme to ignore |
totem_pl_parser_add_ignored_mimetype ()
void totem_pl_parser_add_ignored_mimetype (TotemPlParser *parser
,const char *mimetype
);
Adds a mimetype to the list of mimetypes to ignore, so that any URI of that mimetype is ignored during playlist parsing.
|
a TotemPlParser |
|
the mimetype to ignore |
totem_pl_parser_can_parse_from_data ()
gboolean totem_pl_parser_can_parse_from_data (const char *data
,gsize len
,gboolean debug
);
totem_pl_parser_can_parse_from_filename ()
gboolean totem_pl_parser_can_parse_from_filename (const char *filename
,gboolean debug
);
totem_pl_parser_can_parse_from_uri ()
gboolean totem_pl_parser_can_parse_from_uri (const char *uri
,gboolean debug
);
TOTEM_PL_PARSER_FIELD_URI
#define TOTEM_PL_PARSER_FIELD_URI "url"
Metadata field for an entry's URI.
Since 2.26
TOTEM_PL_PARSER_FIELD_GENRE
#define TOTEM_PL_PARSER_FIELD_GENRE "genre"
Metadata field for an entry's genre.
TOTEM_PL_PARSER_FIELD_TITLE
#define TOTEM_PL_PARSER_FIELD_TITLE "title"
Metadata field for an entry's displayable title.
TOTEM_PL_PARSER_FIELD_AUTHOR
#define TOTEM_PL_PARSER_FIELD_AUTHOR "author"
Metadata field for an entry's author/composer/director.
TOTEM_PL_PARSER_FIELD_ALBUM
#define TOTEM_PL_PARSER_FIELD_ALBUM "album"
Metadata field for an entry's album.
TOTEM_PL_PARSER_FIELD_BASE
#define TOTEM_PL_PARSER_FIELD_BASE "base"
Metadata field for an entry's base path.
TOTEM_PL_PARSER_FIELD_VOLUME
#define TOTEM_PL_PARSER_FIELD_VOLUME "volume"
Metadata field for an entry's playback volume.
TOTEM_PL_PARSER_FIELD_AUTOPLAY
#define TOTEM_PL_PARSER_FIELD_AUTOPLAY "autoplay"
Metadata field for an entry's "autoplay" flag, which is TRUE
if the entry should play automatically.
TOTEM_PL_PARSER_FIELD_DURATION
#define TOTEM_PL_PARSER_FIELD_DURATION "duration"
Metadata field for an entry's playback duration, which should be parsed using totem_pl_parser_parse_duration()
.
TOTEM_PL_PARSER_FIELD_DURATION_MS
#define TOTEM_PL_PARSER_FIELD_DURATION_MS "duration-ms"
Metadata field for an entry's playback duration, in milliseconds. It's only used when an entry's
duration is available in that format, so one would get either the TOTEM_PL_PARSER_FIELD_DURATION
or TOTEM_PL_PARSER_FIELD_DURATION_MS
as metadata.
TOTEM_PL_PARSER_FIELD_STARTTIME
#define TOTEM_PL_PARSER_FIELD_STARTTIME "starttime"
Metadata field for an entry's playback start time, which should be parsed using totem_pl_parser_parse_duration()
.
TOTEM_PL_PARSER_FIELD_ENDTIME
#define TOTEM_PL_PARSER_FIELD_ENDTIME "endtime"
Metadata field for an entry's playback end time.
TOTEM_PL_PARSER_FIELD_COPYRIGHT
#define TOTEM_PL_PARSER_FIELD_COPYRIGHT "copyright"
Metadata field for an entry's copyright line.
TOTEM_PL_PARSER_FIELD_ABSTRACT
#define TOTEM_PL_PARSER_FIELD_ABSTRACT "abstract"
Metadata field for an entry's abstract text.
TOTEM_PL_PARSER_FIELD_DESCRIPTION
#define TOTEM_PL_PARSER_FIELD_DESCRIPTION "description"
Metadata field for an entry's description.
TOTEM_PL_PARSER_FIELD_SUMMARY
#define TOTEM_PL_PARSER_FIELD_SUMMARY TOTEM_PL_PARSER_FIELD_DESCRIPTION
Metadata field for an entry's summary. (In practice, identical to TOTEM_PL_PARSER_FIELD_DESCRIPTION
.)
TOTEM_PL_PARSER_FIELD_MOREINFO
#define TOTEM_PL_PARSER_FIELD_MOREINFO "moreinfo"
Metadata field for an entry's "more info" URI.
TOTEM_PL_PARSER_FIELD_SCREENSIZE
#define TOTEM_PL_PARSER_FIELD_SCREENSIZE "screensize"
Metadata field for an entry's preferred screen size.
TOTEM_PL_PARSER_FIELD_UI_MODE
#define TOTEM_PL_PARSER_FIELD_UI_MODE "ui-mode"
Metadata field for an entry's preferred UI mode.
TOTEM_PL_PARSER_FIELD_PUB_DATE
#define TOTEM_PL_PARSER_FIELD_PUB_DATE "publication-date"
Metadata field for an entry's publication date, which should be parsed using totem_pl_parser_parse_date()
.
TOTEM_PL_PARSER_FIELD_FILESIZE
#define TOTEM_PL_PARSER_FIELD_FILESIZE "filesize"
Metadata field for an entry's filesize in bytes. This is only advisory, and can sometimes not match the actual filesize of the stream.
TOTEM_PL_PARSER_FIELD_LANGUAGE
#define TOTEM_PL_PARSER_FIELD_LANGUAGE "language"
Metadata field for an entry's audio language.
TOTEM_PL_PARSER_FIELD_CONTACT
#define TOTEM_PL_PARSER_FIELD_CONTACT "contact"
Metadata field for an entry's contact details for the webmaster.
TOTEM_PL_PARSER_FIELD_IMAGE_URI
#define TOTEM_PL_PARSER_FIELD_IMAGE_URI "image-url"
Metadata field for an entry's thumbnail image URI.
Since 2.26
TOTEM_PL_PARSER_FIELD_DOWNLOAD_URI
#define TOTEM_PL_PARSER_FIELD_DOWNLOAD_URI "download-url"
Metadata field for an entry's download URI. Only used if an alternate download location is available for the entry.
Since 2.26
TOTEM_PL_PARSER_FIELD_ID
#define TOTEM_PL_PARSER_FIELD_ID "id"
Metadata field for an entry's identifier. Its use is dependent on the format of the playlist parsed, and its origin.
TOTEM_PL_PARSER_FIELD_IS_PLAYLIST
#define TOTEM_PL_PARSER_FIELD_IS_PLAYLIST "is-playlist"
Metadata field used to tell the calling code that the parsing of a playlist
started. It is only TRUE
for the metadata passed to "playlist-started" or
"playlist-ended" signal handlers.
TOTEM_PL_PARSER_FIELD_SUBTITLE_URI
#define TOTEM_PL_PARSER_FIELD_SUBTITLE_URI "subtitle-uri"
The URI of the entry's subtitle file.
Property Details
The "debug"
property
"debug" gboolean : Read / Write
If TRUE
, the parser will output debug information.
Default value: FALSE
The "disable-unsafe"
property
"disable-unsafe" gboolean : Read / Write
If TRUE
, the parser will not parse unsafe locations, such as local devices
and local files if the playlist isn't local. This is useful if the library
is parsing a playlist from a remote location such as a website.
Default value: FALSE
The "force"
property
"force" gboolean : Read / Write
If TRUE
, the parser will attempt to parse a playlist, even if it
appears to be unsupported (usually because of its filename extension).
Default value: FALSE
Signal Details
The "entry-parsed"
signal
void user_function (TotemPlParser *parser,
gchar *uri,
TotemPlParserMetadata *metadata,
gpointer user_data) : Run Last
The ::entry-parsed signal is emitted when a new entry is parsed.
|
the object which received the signal |
|
the URI of the entry parsed |
|
a GHashTable of metadata relating to the entry added. [type GHashTable][element-type utf8 utf8] |
|
user data set when the signal handler was connected. |
The "playlist-ended"
signal
void user_function (TotemPlParser *parser,
gchar *uri,
gpointer user_data) : Run Last
The ::playlist-ended signal is emitted when a playlist is finished parsing. It is only called when "playlist-started" has been called for that playlist.
|
the object which received the signal |
|
the URI of the playlist that finished parsing. |
|
user data set when the signal handler was connected. |
The "playlist-started"
signal
void user_function (TotemPlParser *parser,
gchar *uri,
TotemPlParserMetadata *metadata,
gpointer user_data) : Run Last
The ::playlist-started signal is emitted when a playlist parsing has started. This signal isn't emitted for all types of playlists, but can be relied on to be called for playlists which support playlist metadata, such as title.
|
the object which received the signal |
|
the URI of the new playlist started |
|
a GHashTable of metadata relating to the playlist that started. [type GHashTable][element-type utf8 utf8] |
|
user data set when the signal handler was connected. |