TotemPlParser

TotemPlParser — playlist parser

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

Includes

#include <totem-pl-parser.h>

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);
}

Functions

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().

Parameters

parser

a TotemPlParser

 

uri

the URI of the playlist to parse

 

fallback

TRUE if the parser should add the playlist URI to the end of the playlist on parse failure

 

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.

Parameters

parser

a TotemPlParser

 

uri

the URI of the playlist to parse

 

fallback

TRUE if the parser should add the playlist URI to the end of the playlist on parse failure

 

cancellable

optional GCancellable object, or NULL.

[allow-none]

callback

a GAsyncReadyCallback to call when parsing is finished.

[allow-none]

user_data

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.

Parameters

parser

a TotemPlParser

 

async_result

a GAsyncResult

 

error

a GError, or NULL

 

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.

Parameters

parser

a TotemPlParser

 

uri

the URI of the playlist to parse

 

base

the base path for relative filenames, or NULL.

[allow-none]

fallback

TRUE if the parser should add the playlist URI to the end of the playlist on parse failure

 

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.

Parameters

parser

a TotemPlParser

 

uri

the URI of the playlist to parse

 

base

the base path for relative filenames, or NULL.

[allow-none]

fallback

TRUE if the parser should add the playlist URI to the end of the playlist on parse failure

 

cancellable

optional GCancellable object, or NULL.

[allow-none]

callback

a GAsyncReadyCallback to call when parsing is finished.

[allow-none]

user_data

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.

Parameters

parser

a TotemPlParser

 

playlist

a TotemPlPlaylist

 

dest

output GFile

 

title

the playlist title

 

type

a TotemPlParserType for the outputted playlist

 

error

return location for a GError, or NULL

 

Returns

TRUE on success


totem_pl_parser_save_async ()

void
totem_pl_parser_save_async (TotemPlParser *parser,
                            TotemPlPlaylist *playlist,
                            GFile *dest,
                            const gchar *title,
                            TotemPlParserType type,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Starts asynchronous version of totem_pl_parser_save(). For more details see totem_pl_parser_save().

When the operation is finished, callback will be called. You can then call totem_pl_parser_save_finish() to get the results of the operation.

Parameters

parser

a TotemPlParser

 

playlist

a TotemPlPlaylist

 

dest

output GFile

 

title

the playlist title

 

type

a TotemPlParserType for the outputted playlist

 

cancellable

a GCancellable, or NULL.

[allow-none]

callback

a GAsyncReadyCallback to call when saving has finished.

[allow-none]

user_data

data to pass to the callback function

 

totem_pl_parser_save_finish ()

gboolean
totem_pl_parser_save_finish (TotemPlParser *parser,
                             GAsyncResult *async_result,
                             GError **error);

Finishes an asynchronous playlist saving operation started with totem_pl_parser_save_async().

If saving of the playlist is cancelled part-way through, G_IO_ERROR_CANCELLED will be returned when this function is called.

Parameters

parser

a TotemPlParser

 

async_result

a GAsyncResult

 

error

a GError, or NULL

 

Returns

TRUE on success, FALSE on failure.


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.

Parameters

duration

the duration string to parse

 

debug

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.

Parameters

date_str

the date string to parse

 

debug

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.

Parameters

parser

a TotemPlParser

 

scheme

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.

Parameters

parser

a TotemPlParser

 

mimetype

the mimetype to ignore

 

totem_pl_parser_add_ignored_glob ()

void
totem_pl_parser_add_ignored_glob (TotemPlParser *parser,
                                  const char *glob);

Adds a glob to the list of mimetypes to ignore, so that any URI of that glob is ignored during playlist parsing.

Parameters

parser

a TotemPlParser

 

glob

a glob to ignore

 

Since: 3.26.4

Types and Values

TotemPlParser

typedef struct {
	GObject parent;
	TotemPlParserPrivate *priv;
} 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.

Members

entry_parsed ()

the generic signal handler for the “entry-parsed” signal, which can be overridden by inheriting classes

 

playlist_started ()

the generic signal handler for the “playlist-started” signal, which can be overridden by inheriting classes

 

playlist_ended ()

the generic signal handler for the “playlist-ended” signal, which can be overridden by inheriting classes

 

enum TotemPlParserResult

Gives the result of parsing a playlist.

Members

TOTEM_PL_PARSER_RESULT_UNHANDLED

The playlist could not be handled.

 

TOTEM_PL_PARSER_RESULT_ERROR

There was an error parsing the playlist.

 

TOTEM_PL_PARSER_RESULT_SUCCESS

The playlist was parsed successfully.

 

TOTEM_PL_PARSER_RESULT_IGNORED

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()).

 

TOTEM_PL_PARSER_RESULT_CANCELLED

Parsing of the playlist was cancelled part-way through.

 

enum TotemPlParserType

The type of playlist a TotemPlParser will parse.

Members

TOTEM_PL_PARSER_PLS

PLS parser

 

TOTEM_PL_PARSER_M3U

M3U parser

 

TOTEM_PL_PARSER_M3U_DOS

M3U (DOS linebreaks) parser

 

TOTEM_PL_PARSER_XSPF

XSPF parser

 

TOTEM_PL_PARSER_IRIVER_PLA

iRiver PLA parser

 

enum TotemPlParserError

Allows you to differentiate between different errors occurring during file operations in a TotemPlParser.

Members

TOTEM_PL_PARSER_ERROR_NO_DISC

Error attempting to open a disc device when no disc is present

 

TOTEM_PL_PARSER_ERROR_MOUNT_FAILED

An attempted mount operation failed

 

TOTEM_PL_PARSER_ERROR_EMPTY_PLAYLIST

Playlist to be saved is empty

 

TotemPlParserMetadata

typedef GHashTable TotemPlParserMetadata;

An alias for GHashTable, used in the “entry-parsed” and “playlist-started” signals due to GHashTable not being a boxed type when totem-pl-parser was originally written.

The hash table is a mapping from field names (such as TOTEM_PL_PARSER_FIELD_ALBUM) to their associated values.

It is safe to use GHashTable instead of TotemPlParserMetadata everywhere.


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.


TOTEM_PL_PARSER_FIELD_CONTENT_TYPE

#define TOTEM_PL_PARSER_FIELD_CONTENT_TYPE "content-type"

Metadata field for an entry's content-type (usually a mime-type coming from a web server).