![]() |
![]() |
![]() |
totem-pl-parser Reference Manual | ![]() |
---|---|---|---|---|
#include <totem-pl-parser.h> typedef TotemPlParser; typedef TotemPlParserClass; enum TotemPlParserResult; enum TotemPlParserType; enum TotemPlParserError; void (*TotemPlParserIterFunc) (GtkTreeModel *model, GtkTreeIter *iter, char **uri, char **title, gboolean *custom_title, gpointer user_data); TotemPlParser* totem_pl_parser_new (void); TotemPlParserResult totem_pl_parser_parse (TotemPlParser *parser, const char *url, gboolean fallback); TotemPlParserResult totem_pl_parser_parse_with_base (TotemPlParser *parser, const char *url, const char *base, gboolean fallback); gboolean totem_pl_parser_write (TotemPlParser *parser, GtkTreeModel *model, TotemPlParserIterFunc func, const char *output, TotemPlParserType type, gpointer user_data, GError **error); gboolean totem_pl_parser_write_with_title (TotemPlParser *parser, GtkTreeModel *model, TotemPlParserIterFunc func, const char *output, const char *title, TotemPlParserType type, gpointer user_data, 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); #define TOTEM_PL_PARSER_FIELD_URL #define TOTEM_PL_PARSER_FIELD_GENRE #define TOTEM_PL_PARSER_FIELD_TITLE #define TOTEM_PL_PARSER_FIELD_AUTHOR #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_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_URL #define TOTEM_PL_PARSER_FIELD_IS_PLAYLIST
"debug" gboolean : Read / Write "disable-unsafe" gboolean : Read / Write "force" gboolean : Read / Write "recurse" gboolean : Read / Write / Construct
TotemPlParser is a general-purpose playlist parser and writer, with support for several different types of playlist.
Example 1. Reading a Playlist
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. Getting Metadata from Entries
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 3. Writing a Playlist
void parser_func (GtkTreeModel *model, GtkTreeIter *iter, gchar **uri, gchar **title, gboolean *custom_title, gpointer user_data) { gtk_tree_model_get (model, iter, 0, uri, 1, title, 2, custom_title, -1); } { TotemPlParser *pl; GtkTreeModel *tree_model; pl = totem_pl_parser_new (); /* Your tree model can be as simple or as complex as you like; * parser_func() will just have to return the entry title, URI and custom title flag from it. */ tree_model = gtk_list_store_new (3, G_TYPE_STRING, G_TYPE_STRING, G_TYPE_BOOLEAN); populate_model (tree_model); if (totem_pl_parser_write (pl, tree_model, parser_func, "/tmp/playlist.pls", TOTEM_PL_PARSER_PLS, NULL, NULL) != TRUE) g_error ("Playlist writing failed."); g_object_unref (tree_model); g_object_unref (pl); }
typedef struct TotemPlParser TotemPlParser;
All the fields in the TotemPlParser structure are private and should never be accessed directly.
typedef struct TotemPlParserClass TotemPlParserClass;
The class structure for the TotemPlParser type.
typedef enum { TOTEM_PL_PARSER_RESULT_UNHANDLED, TOTEM_PL_PARSER_RESULT_ERROR, TOTEM_PL_PARSER_RESULT_SUCCESS, TOTEM_PL_PARSER_RESULT_IGNORED } 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() ).
|
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.
typedef enum { TOTEM_PL_PARSER_ERROR_VFS_OPEN, TOTEM_PL_PARSER_ERROR_VFS_WRITE, } TotemPlParserError;
Allows you to differentiate between different errors occurring during file operations in a TotemPlParser.
void (*TotemPlParserIterFunc) (GtkTreeModel *model, GtkTreeIter *iter, char **uri, char **title, gboolean *custom_title, gpointer user_data);
Functions such as totem_pl_parser_write()
accept pointers to TotemPlParserIterFunc()
s
as callbacks to call for each entry in the playlist. These functions
are specific to each use of the playlist API, and should set the entry's
uri
, title
and custom_title
return values, getting the data from model
or otherwise.
|
a GtkTreeModel containing the playlist entries |
|
a GtkTreeIter pointing to the current row |
|
return location for the entry's URI, or NULL
|
|
return location for the entry's title, or NULL
|
|
return location for a boolean which, if TRUE , indicates that the entry's title is custom; or NULL
|
|
user data to pass to the function |
TotemPlParser* totem_pl_parser_new (void);
Creates a TotemPlParser object.
Returns : |
a new TotemPlParser |
TotemPlParserResult totem_pl_parser_parse (TotemPlParser *parser, const char *url, gboolean fallback);
Parses a playlist given by the absolute URL url
.
|
a TotemPlParser |
|
the URL of the playlist to parse |
|
TRUE if the parser should add the playlist URL to the
end of the playlist on parse failure
|
Returns : |
a TotemPlParserResult |
TotemPlParserResult totem_pl_parser_parse_with_base (TotemPlParser *parser, const char *url, const char *base, gboolean fallback);
Parses a playlist given by the absolute URL url
, using
base
to resolve relative paths where appropriate.
|
a TotemPlParser |
|
the URL of the playlist to parse |
|
the base path for relative filenames |
|
TRUE if the parser should add the playlist URL to the
end of the playlist on parse failure
|
Returns : |
a TotemPlParserResult |
gboolean totem_pl_parser_write (TotemPlParser *parser, GtkTreeModel *model, TotemPlParserIterFunc func, const char *output, TotemPlParserType type, gpointer user_data, GError **error);
Writes the playlist held by parser
and model
out to the file of
path output
. The playlist is written in the format type
and is given
a NULL
title.
For each entry in the model
, the function func
is called (and passed
user_data
), which gets various metadata values about the entry for
the playlist writer.
|
a TotemPlParser |
|
a GtkTreeModel |
|
a pointer to a TotemPlParserIterFunc callback function |
|
the output path and filename |
|
a TotemPlParserType for the ouputted playlist |
|
a pointer to be passed to each call of func
|
|
return location for a GError, or NULL
|
Returns : |
TRUE on success
|
gboolean totem_pl_parser_write_with_title (TotemPlParser *parser, GtkTreeModel *model, TotemPlParserIterFunc func, const char *output, const char *title, TotemPlParserType type, gpointer user_data, GError **error);
Writes the playlist held by parser
and model
out to the file of
path output
. The playlist is written in the format type
and is
given the title title
.
For each entry in the model
, the function func
is called (and passed
user_data
), which gets various metadata values about the entry for
the playlist writer.
|
a TotemPlParser |
|
a GtkTreeModel |
|
a pointer to a TotemPlParserIterFunc callback function |
|
the output path and filename |
|
the playlist title |
|
a TotemPlParserType for the ouputted playlist |
|
a pointer to be passed to each call of func
|
|
return location for a GError, or NULL
|
Returns : |
TRUE on success
|
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 |
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 |
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 URL using that scheme is ignored during playlist parsing.
|
a TotemPlParser |
|
the scheme to ignore |
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 URL of that mimetype is ignored during playlist parsing.
|
a TotemPlParser |
|
the mimetype to ignore |
#define TOTEM_PL_PARSER_FIELD_URL "url"
Metadata field for an entry's URL.
#define TOTEM_PL_PARSER_FIELD_GENRE "genre"
Metadata field for an entry's genre.
#define TOTEM_PL_PARSER_FIELD_TITLE "title"
Metadata field for an entry's displayable title.
#define TOTEM_PL_PARSER_FIELD_AUTHOR "author"
Metadata field for an entry's author/composer/director.
#define TOTEM_PL_PARSER_FIELD_BASE "base"
Metadata field for an entry's base path.
#define TOTEM_PL_PARSER_FIELD_VOLUME "volume"
Metadata field for an entry's playback volume.
#define TOTEM_PL_PARSER_FIELD_AUTOPLAY "autoplay"
Metadata field for an entry's "autoplay" flag, which is TRUE
if the entry should play automatically.
#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()
.
#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()
.
#define TOTEM_PL_PARSER_FIELD_ENDTIME "endtime"
Metadata field for an entry's playback end time.
#define TOTEM_PL_PARSER_FIELD_COPYRIGHT "copyright"
Metadata field for an entry's copyright line.
#define TOTEM_PL_PARSER_FIELD_ABSTRACT "abstract"
Metadata field for an entry's abstract text.
#define TOTEM_PL_PARSER_FIELD_DESCRIPTION "description"
Metadata field for an entry's description.
#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
.)
#define TOTEM_PL_PARSER_FIELD_MOREINFO "moreinfo"
Metadata field for an entry's "more info" URL.
#define TOTEM_PL_PARSER_FIELD_SCREENSIZE "screensize"
Metadata field for an entry's preferred screen size.
#define TOTEM_PL_PARSER_FIELD_UI_MODE "ui-mode"
Metadata field for an entry's preferred UI mode.
#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()
.
#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.
#define TOTEM_PL_PARSER_FIELD_LANGUAGE "language"
Metadata field for an entry's audio language.
#define TOTEM_PL_PARSER_FIELD_CONTACT "contact"
Metadata field for an entry's contact details for the webmaster.
#define TOTEM_PL_PARSER_FIELD_IMAGE_URL "image-url"
Metadata field for an entry's thumbnail image URL.
#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.
"debug"
property"debug" gboolean : Read / Write
If TRUE
, the parser will output debug information.
Default value: FALSE
"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
"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
"entry-parsed"
signalvoid user_function (TotemPlParser *parser, gchar *uri, GHashTable *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 |
|
user data set when the signal handler was connected. |
"playlist-ended"
signalvoid 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. |
"playlist-started"
signalvoid user_function (TotemPlParser *parser, gchar *uri, GHashTable *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. |
|
user data set when the signal handler was connected. |