TotemPlParser

TotemPlParser — playlist parser

Stability Level

Stable, unless otherwise indicated

Synopsis


#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 *uri,
                                                         gboolean fallback);
TotemPlParserResult  totem_pl_parser_parse_with_base    (TotemPlParser *parser,
                                                         const char *uri,
                                                         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_URI
#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_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_IMAGE_URL
#define             TOTEM_PL_PARSER_FIELD_DOWNLOAD_URI
#define             TOTEM_PL_PARSER_FIELD_DOWNLOAD_URL
#define             TOTEM_PL_PARSER_FIELD_ID
#define             TOTEM_PL_PARSER_FIELD_IS_PLAYLIST

Object Hierarchy

  GObject
   +----TotemPlParser

Properties

  "debug"                    gboolean              : Read / Write
  "disable-unsafe"           gboolean              : Read / Write
  "force"                    gboolean              : Read / Write
  "recurse"                  gboolean              : Read / Write / Construct

Signals

  "entry-parsed"                                   : Run Last
  "playlist-ended"                                 : Run Last
  "playlist-started"                               : Run Last

Description

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


Details

TotemPlParser

typedef struct TotemPlParser	       TotemPlParser;

All the fields in the TotemPlParser structure are private and should never be accessed directly.

TotemPlParserClass

typedef struct TotemPlParserClass      TotemPlParserClass;

The class structure for the TotemPlParser type.

enum TotemPlParserResult

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.

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

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.

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

typedef enum {
	TOTEM_PL_PARSER_ERROR_NO_DISC,
	TOTEM_PL_PARSER_ERROR_MOUNT_FAILED
} TotemPlParserError;

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

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

TotemPlParserIterFunc ()

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.

model :

 a GtkTreeModel containing the playlist entries

iter :

 a GtkTreeIter pointing to the current row

uri :

 return location for the entry's URI, or NULL

title :

 return location for the entry's title, or NULL

custom_title :

 return location for a boolean which, if TRUE, indicates that the entry's title is custom; or NULL

user_data :

 user data to pass to the function

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.

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

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.

parser :

 a TotemPlParser

uri :

 the URI of the playlist to parse

base :

 the base path for relative filenames

fallback :

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

Returns :

 a TotemPlParserResult

totem_pl_parser_write ()

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.

Possible error codes are as per totem_pl_parser_write_with_title().

parser :

 a TotemPlParser

model :

 a GtkTreeModel

func :

 a pointer to a TotemPlParserIterFunc callback function

output :

 the output path and filename

type :

 a TotemPlParserType for the ouputted playlist

user_data :

 a pointer to be passed to each call of func

error :

 return location for a GError, or NULL

Returns :

 TRUE on success

totem_pl_parser_write_with_title ()

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.

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 :

 a TotemPlParser

model :

 a GtkTreeModel

func :

 a pointer to a TotemPlParserIterFunc callback function

output :

 the output path and filename

title :

 the playlist title

type :

 a TotemPlParserType for the ouputted playlist

user_data :

 a pointer to be passed to each call of func

error :

 return location 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.

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.

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.

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.

parser :

 a TotemPlParser

mimetype :

 the mimetype to ignore

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_URL

#define TOTEM_PL_PARSER_FIELD_URL		TOTEM_PL_PARSER_FIELD_URI

Warning

TOTEM_PL_PARSER_FIELD_URL has been deprecated since version 2.26 and should not be used in newly-written code. Use TOTEM_PL_PARSER_FIELD_URI instead.

Metadata field for an entry's URL.

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_IMAGE_URL

#define TOTEM_PL_PARSER_FIELD_IMAGE_URL		TOTEM_PL_PARSER_FIELD_IMAGE_URI

Warning

TOTEM_PL_PARSER_FIELD_IMAGE_URL has been deprecated since version 2.26 and should not be used in newly-written code. Use TOTEM_PL_PARSER_FIELD_IMAGE_URI instead.

Metadata field for an entry's thumbnail image URL.

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_DOWNLOAD_URL

#define TOTEM_PL_PARSER_FIELD_DOWNLOAD_URL TOTEM_PL_PARSER_FIELD_DOWNLOAD_URI

Warning

TOTEM_PL_PARSER_FIELD_DOWNLOAD_URL has been deprecated since version 2.26 and should not be used in newly-written code. Use TOTEM_PL_PARSER_FIELD_DOWNLOAD_URI instead.

Metadata field for an entry's download URL. Only used if an alternate download location is available for the entry.

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.

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

The "recurse" property

  "recurse"                  gboolean              : Read / Write / Construct

If TRUE, the parser will recursively fetch playlists linked to by the current one.

Default value: TRUE

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.

parser :

 the object which received the signal

uri :

 the URI of the entry parsed

metadata :

 a GHashTable of metadata relating to the entry added

user_data :

 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.

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.

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.

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.

user_data :

 user data set when the signal handler was connected.
Generated by GTK-Doc V1.12