## GrlPls GrlPls — playlist handling functions |

## Functions

GrlMedia * | (*GrlPlsFilterFunc) ()
gboolean | grl_pls_media_is_playlist ()
guint | grl_pls_browse ()
GList * | grl_pls_browse_sync ()
void | grl_pls_browse_by_spec ()
GrlMedia * | grl_pls_file_to_media ()
const char * | grl_pls_get_file_attributes ()

## Includes

    #include <grilo.h>

## Description

Grilo only deals with audio, video or image content, but not with playlists. This library allow to identify playlists and browse into them exposing playlist entries as GrlMedia objects.

## Functions

### GrlPlsFilterFunc ()

    GrlMedia *
    (*GrlPlsFilterFunc) (GrlSource *source,
                         GrlMedia *media,
                         gpointer user_data);

Callback type to filter, or modify GrlMedia created when parsing a playlist using one of `grl_pls_browse()`, `grl_pls_browse_sync()` or `grl_pls_browse_by_spec()`.

The callback is responsible for unreffing `media` when returning `NULL` or another GrlMedia.

#### Parameters

source | the GrlSource the browse call came from |
media | a GrlMedia to operate on. | [transfer full]
user_data | user data passed to the browse call |

#### Returns

`NULL` to not add this entry to the results, or a new GrlMedia populated with metadata of your choice.

[transfer full]

### grl_pls_media_is_playlist ()

    gboolean
    grl_pls_media_is_playlist (GrlMedia *media);

Check if a file identified by GrlMedia object is a playlist or not. This function does blocking I/O.

#### Parameters

media | GrlMedia |

#### Returns

`TRUE` if a GrlMedia is recognized as a playlist.

Since: 0.2.0

### grl_pls_browse ()

    guint
    grl_pls_browse (GrlSource *source,
                    GrlMedia *playlist,
                    const GList *keys,
                    GrlOperationOptions *options,
                    GrlPlsFilterFunc filter_func,
                    GrlSourceResultCb callback,
                    gpointer user_data);

Browse into a playlist. The playlist entries are returned via the `callback` function as GrlMedia objects. This function imitates the API and way of working of grl_source_browse.

The `playlist` provided could be of any GrlMedia class, as long as its URI points to a valid playlist file.

This function is asynchronous.

See `grl_source_browse()` function for additional information and sample code.

#### Parameters

source | a source |
playlist | a playlist |
keys | the GList of GrlKeyIDs to request. | [element-type GrlKeyID]
options | options wanted for that operation |
filter_func | A filter function, or `NULL`. | [scope async][allow-none]
callback | the user defined callback. | [scope notified]
user_data | the user data to pass in the callback |

#### Returns

the operation identifier

Since: 0.2.0

### grl_pls_browse_sync ()

    GList *
    grl_pls_browse_sync (GrlSource *source,
                         GrlMedia *playlist,
                         const GList *keys,
                         GrlOperationOptions *options,
                         GrlPlsFilterFunc filter_func,
                         GError **error);

Browse into a playlist. The playlist entries are returned via the `callback` function as GrlMedia objects. This function imitates the API and way of working of grl_source_browse_sync.

The filter function `filter_func` will be used for plugins or applications to be able to refuse particular entries from being listed.

If a `NULL` filter function is passed, the media will be added with only the metadata coming from the playlist included.

This function is synchronous.

See `grl_source_browse_sync()` function for additional information and sample code.

#### Parameters

source | a source |
playlist | a playlist |
keys | the GList of GrlKeyIDs to request. | [element-type GrlKeyID]
filter_func | A filter function, or `NULL`. | [scope async][allow-none]
options | options wanted for that operation |
error | a GError, or `NULL` |

#### Returns

a GList with GrlMedia elements. After use `g_object_unref()` every element and `g_list_free()` the list.

[element-type Grl.Media][transfer full]

Since: 0.2.0

### grl_pls_browse_by_spec ()

    void
    grl_pls_browse_by_spec (GrlSource *source,
                            GrlPlsFilterFunc filter_func,
                            GrlSourceBrowseSpec *bs);

Browse into a playlist. The playlist entries are returned via the bs->callback function as GrlMedia objects. This function is more suitable to be called from plugins, which by design get the GrlSourceBrowseSpec already filled in.

The bs->playlist provided could be of any GrlMedia class, as long as its URI points to a valid playlist file.

This function is asynchronous.

See `grl_pls_browse()` and `grl_source_browse()` function for additional information and sample code.

#### Parameters

source | a source |
filter_func | A filter function, or `NULL`. | [scope async][allow-none]
bs | a GrlSourceBrowseSpec structure with details of the browsing operation |

Since: 0.2.0

### grl_pls_file_to_media ()

    GrlMedia *
    grl_pls_file_to_media (GrlMedia *content,
                           GFile *file,
                           GFileInfo *info,
                           gboolean handle_pls,
                           GrlOperationOptions *options);

This function will update (if `content` is non-`NULL`) or create a GrlMedia and populate it with information from `info` .

If `info` is `NULL`, a call to `g_file_query_info()` will be made.

This function is useful for plugins that browse the local filesystem and want to easily create GrlMedia from filesystem information.

#### Parameters

content | an existing GrlMedia for the file, or `NULL` |
file | a GFile pointing to the file or directory in question |
info | an existing GFileInfo, or `NULL` |
handle_pls | Whether playlists should be handled as containers |
options | a GrlOperationOptions representing the options to apply to this operation. |

#### Returns

a new GrlMedia.

[transfer full]

Since: 0.2.0

### grl_pls_get_file_attributes ()

    const char *
    grl_pls_get_file_attributes (void);

Returns the list of attributes to pass to `g_file_query_info()` to make it possible to populate a GrlMedia using `grl_pls_file_to_media()`.

Do not free the result of this function.

#### Returns

a string containing the list of attributes.

[transfer none]

Since: 0.2.0