TotemPlParser

## TotemPlParser TotemPlParser — playlist parser |

## Stability Level

Stable, unless otherwise indicated

## 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

## Object Hierarchy

      GObject
       +----TotemPlParser

      GBoxed
       +----TotemPlParserMetadata

## 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. 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 `parent_class`; | the parent class
`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

    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.

`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

    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,
    	TOTEM_PL_PARSER_ERROR_EMPTY_PLAYLIST
    } 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
`TOTEM_PL_PARSER_ERROR_EMPTY_PLAYLIST` | Playlist to be saved is empty

### TotemPlParserMetadata

    typedef GHashTable TotemPlParserMetadata;

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

`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_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.

`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.

`parser` : | a TotemPlParser
`async_result` : | a GAsyncResult
`error` : | 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.

`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
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.

`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.

`parser` : | a TotemPlParser
`playlist` : | a TotemPlPlaylist
`dest` : | output GFile
`title` : | the playlist title
`type` : | a TotemPlParserType for the outputted playlist
`error` : | 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.

`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_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.

### TOTEM_PL_PARSER_FIELD_CONTENT_TYPE

    #define TOTEM_PL_PARSER_FIELD_CONTENT_TYPE "content-type"

## 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. [type GHashTable][element-type utf8 utf8]
`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. [type GHashTable][element-type utf8 utf8]
`user_data` : | user data set when the signal handler was connected.