| Top |  |  |  |  | 
XplayerPlParser is a general-purpose playlist parser and writer, with support for several different types of playlist. Note that xplayer-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 | XplayerPlParser *pl = xplayer_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 (xplayer_pl_parser_parse (pl, "http://example.com/playlist.pls", FALSE) != XPLAYER_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 | XplayerPlParser *pl = xplayer_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); xplayer_pl_parser_parse_async (pl, "http://example.com/playlist.pls", FALSE, NULL, parse_cb, NULL); g_object_unref (pl); static void parse_cb (XplayerPlParser *parser, GAsyncResult *result, gpointer user_data) { GError *error = NULL; if (xplayer_pl_parser_parse_finish (parser, result, &error) != XPLAYER_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 (XplayerPlParser *parser, const gchar *uri, GHashTable *metadata, gpointer user_data) { gchar *title = g_hash_table_lookup (metadata, XPLAYER_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 | { XplayerPlParser *pl; XplayerPlPlaylist *playlist; XplayerPlPlaylistIter iter; GFile *file; pl = xplayer_pl_parser_new (); playlist = xplayer_pl_playlist_new (); file = g_file_new_for_path ("/tmp/playlist.pls"); xplayer_pl_playlist_append (playlist, &iter); xplayer_pl_playlist_set (playlist, &iter, XPLAYER_PL_PARSER_FIELD_URI, "file:///1.ogg", XPLAYER_PL_PARSER_FIELD_TITLE, "1.ogg", NULL); xplayer_pl_playlist_append (playlist, &iter); xplayer_pl_playlist_set (playlist, &iter, XPLAYER_PL_PARSER_FIELD_URI, "file:///2.ogg", NULL); if (xplayer_pl_parser_save (pl, playlist, file, "Title", XPLAYER_PL_PARSER_PLS, NULL) != TRUE) { g_error ("Playlist writing failed."); } g_object_unref (playlist); g_object_unref (pl); g_object_unref (file); } | 
XplayerPlParser *
xplayer_pl_parser_new (void);
Creates a XplayerPlParser object.
XplayerPlParserResult xplayer_pl_parser_parse (XplayerPlParser *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. xplayer_pl_parser_parse_async() is recommended instead.
Return values are as xplayer_pl_parser_parse_with_base().
| parser | ||
| uri | the URI of the playlist to parse | |
| fallback | 
 | 
void xplayer_pl_parser_parse_async (XplayerPlParser *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 xplayer_pl_parser_parse(), which is the synchronous version of this function.
When the operation is finished, callback
 will be called. You can then call xplayer_pl_parser_parse_finish()
to get the results of the operation.
| parser | ||
| uri | the URI of the playlist to parse | |
| fallback | 
 | |
| cancellable |  optional GCancellable object, or  | [allow-none] | 
| callback | a GAsyncReadyCallback to call when parsing is finished. | [allow-none] | 
| user_data | data to pass to the  | 
XplayerPlParserResult xplayer_pl_parser_parse_finish (XplayerPlParser *parser,GAsyncResult *async_result,GError **error);
Finishes an asynchronous playlist parsing operation started with xplayer_pl_parser_parse_async()
or xplayer_pl_parser_parse_with_base_async().
If parsing of the playlist is cancelled part-way through, XPLAYER_PL_PARSER_RESULT_CANCELLED is returned when
this function is called.
XplayerPlParserResult xplayer_pl_parser_parse_with_base (XplayerPlParser *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.
void xplayer_pl_parser_parse_with_base_async (XplayerPlParser *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 xplayer_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 xplayer_pl_parser_parse_finish()
to get the results of the operation.
| parser | ||
| uri | the URI of the playlist to parse | |
| base |  the base path for relative filenames, or  | [allow-none] | 
| fallback | 
 | |
| cancellable |  optional GCancellable object, or  | [allow-none] | 
| callback | a GAsyncReadyCallback to call when parsing is finished. | [allow-none] | 
| user_data | data to pass to the  | 
gboolean xplayer_pl_parser_save (XplayerPlParser *parser,XplayerPlPlaylist *playlist,GFile *dest,const gchar *title,XplayerPlParserType 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.
| parser | ||
| playlist | ||
| dest | output GFile | |
| title | the playlist title | |
| type | a XplayerPlParserType for the outputted playlist | |
| error | 
gint64 xplayer_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.
guint64 xplayer_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.
void xplayer_pl_parser_add_ignored_scheme (XplayerPlParser *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.
void xplayer_pl_parser_add_ignored_mimetype (XplayerPlParser *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.
gboolean xplayer_pl_parser_can_parse_from_data (const char *data,gsize len,gboolean debug);
Checks if the first len
 bytes of data
 can be parsed.
| data | the data to check for parsability | |
| len | the length of data to check | |
| debug | 
 | 
gboolean xplayer_pl_parser_can_parse_from_filename (const char *filename,gboolean debug);
Checks if the file can be parsed. Files can be parsed if:
they have a special mimetype, or
they have a mimetype which could be a video or a playlist.
| filename | the file to check for parsability | |
| debug | 
 | 
gboolean xplayer_pl_parser_can_parse_from_uri (const char *uri,gboolean debug);
Checks if the remote URI can be parsed. Note that this does not actually try to open the remote URI, or deduce its mime-type from filename, as this would bring too many false positives.
| uri | the remote URI to check for parsability | |
| debug | 
 | 
typedef struct _XplayerPlParser XplayerPlParser;
All the fields in the XplayerPlParser structure are private and should never be accessed directly.
typedef struct {
	GObjectClass parent_class;
	/* signals */
	void (*entry_parsed) (XplayerPlParser *parser,
			      const char *uri,
			      GHashTable *metadata);
	void (*playlist_started) (XplayerPlParser *parser,
				  const char *uri,
				  GHashTable *metadata);
	void (*playlist_ended) (XplayerPlParser *parser,
				const char *uri);
} XplayerPlParserClass;
The class structure for the XplayerPlParser 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 | 
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  | ||
| Parsing of the playlist was cancelled part-way through. | 
Allows you to differentiate between different errors occurring during file operations in a XplayerPlParser.
typedef GHashTable XplayerPlParserMetadata;
An alias for GHashTable, used in the “entry-parsed” and “playlist-started” signals due to GHashTable not being a boxed type when xplayer-pl-parser was originally written.
The hash table is a mapping from field names (such as
XPLAYER_PL_PARSER_FIELD_ALBUM) to their associated values.
It is safe to use GHashTable instead of XplayerPlParserMetadata everywhere.
#define XPLAYER_PL_PARSER_FIELD_URI "url"
Metadata field for an entry's URI.
Since: 2.26
#define XPLAYER_PL_PARSER_FIELD_GENRE "genre"
Metadata field for an entry's genre.
#define XPLAYER_PL_PARSER_FIELD_TITLE "title"
Metadata field for an entry's displayable title.
#define XPLAYER_PL_PARSER_FIELD_AUTHOR "author"
Metadata field for an entry's author/composer/director.
#define XPLAYER_PL_PARSER_FIELD_ALBUM "album"
Metadata field for an entry's album.
#define XPLAYER_PL_PARSER_FIELD_BASE "base"
Metadata field for an entry's base path.
#define XPLAYER_PL_PARSER_FIELD_VOLUME "volume"
Metadata field for an entry's playback volume.
#define XPLAYER_PL_PARSER_FIELD_AUTOPLAY "autoplay"
Metadata field for an entry's "autoplay" flag, which is TRUE if the entry should play automatically.
#define XPLAYER_PL_PARSER_FIELD_DURATION "duration"
Metadata field for an entry's playback duration, which should be parsed using xplayer_pl_parser_parse_duration().
#define XPLAYER_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 XPLAYER_PL_PARSER_FIELD_DURATION
or XPLAYER_PL_PARSER_FIELD_DURATION_MS as metadata.
#define XPLAYER_PL_PARSER_FIELD_STARTTIME "starttime"
Metadata field for an entry's playback start time, which should be parsed using xplayer_pl_parser_parse_duration().
#define XPLAYER_PL_PARSER_FIELD_ENDTIME "endtime"
Metadata field for an entry's playback end time.
#define XPLAYER_PL_PARSER_FIELD_COPYRIGHT "copyright"
Metadata field for an entry's copyright line.
#define XPLAYER_PL_PARSER_FIELD_ABSTRACT "abstract"
Metadata field for an entry's abstract text.
#define XPLAYER_PL_PARSER_FIELD_DESCRIPTION "description"
Metadata field for an entry's description.
#define XPLAYER_PL_PARSER_FIELD_SUMMARY XPLAYER_PL_PARSER_FIELD_DESCRIPTION
Metadata field for an entry's summary. (In practice, identical to XPLAYER_PL_PARSER_FIELD_DESCRIPTION.)
#define XPLAYER_PL_PARSER_FIELD_MOREINFO "moreinfo"
Metadata field for an entry's "more info" URI.
#define XPLAYER_PL_PARSER_FIELD_SCREENSIZE "screensize"
Metadata field for an entry's preferred screen size.
#define XPLAYER_PL_PARSER_FIELD_UI_MODE "ui-mode"
Metadata field for an entry's preferred UI mode.
#define XPLAYER_PL_PARSER_FIELD_PUB_DATE "publication-date"
Metadata field for an entry's publication date, which should be parsed using xplayer_pl_parser_parse_date().
#define XPLAYER_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 XPLAYER_PL_PARSER_FIELD_LANGUAGE "language"
Metadata field for an entry's audio language.
#define XPLAYER_PL_PARSER_FIELD_CONTACT "contact"
Metadata field for an entry's contact details for the webmaster.
#define XPLAYER_PL_PARSER_FIELD_IMAGE_URI "image-url"
Metadata field for an entry's thumbnail image URI.
Since: 2.26
#define XPLAYER_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
#define XPLAYER_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.
#define XPLAYER_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.
#define XPLAYER_PL_PARSER_FIELD_SUBTITLE_URI "subtitle-uri"
The URI of the entry's subtitle file.
“debug” property“debug” gboolean
If TRUE, the parser will output debug information.
Flags: Read / Write
Default value: FALSE
“disable-unsafe” property“disable-unsafe” gboolean
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.
Flags: Read / Write
Default value: FALSE
“force” property“force” gboolean
If TRUE, the parser will attempt to parse a playlist, even if it
appears to be unsupported (usually because of its filename extension).
Flags: Read / Write
Default value: FALSE
“entry-parsed” signalvoid user_function (XplayerPlParser *parser, gchar *uri, XplayerPlParserMetadata *metadata, gpointer user_data)
The ::entry-parsed signal is emitted when a new entry is parsed.
| parser | the object which received the signal | |
| uri | the URI of the entry parsed | |
| metadata | a GHashTable of metadata relating to the entry added. | [type GHashTable][element-type utf8 utf8] | 
| user_data | user data set when the signal handler was connected. | 
Flags: Run Last
“playlist-ended” signalvoid user_function (XplayerPlParser *parser, gchar *uri, gpointer user_data)
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.
| parser | the object which received the signal | |
| uri | the URI of the playlist that finished parsing. | |
| user_data | user data set when the signal handler was connected. | 
Flags: Run Last
“playlist-started” signalvoid user_function (XplayerPlParser *parser, gchar *uri, XplayerPlParserMetadata *metadata, gpointer user_data)
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.
| parser | the object which received the signal | |
| uri | the URI of the new playlist started | |
| metadata | a GHashTable of metadata relating to the playlist that started. | [type GHashTable][element-type utf8 utf8] | 
| user_data | user data set when the signal handler was connected. | 
Flags: Run Last