RygelMediaContainer: librygel-server Reference Manual

## RygelMediaContainer RygelMediaContainer — This is a container (folder) for media items and child containers. |

## Functions

void | rygel_media_container_get_children ()
RygelMediaObjects * | rygel_media_container_get_children_finish ()
void | rygel_media_container_find_object ()
RygelMediaObject * | rygel_media_container_find_object_finish ()
void | rygel_media_container_updated ()
gint | rygel_media_container_get_child_count ()
void | rygel_media_container_set_child_count ()
gint | rygel_media_container_get_empty_child_count ()
void | rygel_media_container_set_empty_child_count ()
gint | rygel_media_container_get_all_child_count ()
gboolean | rygel_media_container_get_create_mode_enabled ()
void | rygel_media_container_set_create_mode_enabled ()
const gchar * | rygel_media_container_get_sort_criteria ()
void | rygel_media_container_set_sort_criteria ()
gboolean | rygel_media_container_equal_func ()

## Properties

gint | all-child-count | Read
gint | child-count | Read / Write / Construct
gboolean | create-mode-enabled | Read / Write
gint | empty-child-count | Read / Write
GUPnPOCMFlags | ocm-flags | Read
gchar * | sort-criteria | Read / Write

## Signals

void | container-updated | Run Last
void | sub-tree-updates-finished | Run Last

## Types and Values

#define | RYGEL_TYPE_MEDIA_CONTAINER
#define | RYGEL_MEDIA_CONTAINER_ANY
#define | RYGEL_MEDIA_CONTAINER_UPNP_CLASS
#define | RYGEL_MEDIA_CONTAINER_STORAGE_FOLDER
#define | RYGEL_MEDIA_CONTAINER_MUSIC_ALBUM
#define | RYGEL_MEDIA_CONTAINER_MUSIC_ARTIST
#define | RYGEL_MEDIA_CONTAINER_MUSIC_GENRE
#define | RYGEL_MEDIA_CONTAINER_PLAYLIST
#define | RYGEL_MEDIA_CONTAINER_ALBUM_SORT_CRITERIA
struct | RygelMediaContainer
struct | RygelMediaContainerClass
enum | RygelObjectEventType

## Object Hierarchy

        GEnum
        ╰── RygelObjectEventType
        GObject
        ╰── RygelMediaObject
            ╰── RygelMediaContainer
                ╰── RygelSimpleContainer

## Known Derived Interfaces

RygelMediaContainer is required by RygelSearchableContainer, RygelTrackableContainer and RygelWritableContainer.

## Description

It provides a basic serialization implementation (to DIDLLiteWriter).

A derived class should provide a working implementation of get_children and should emit the container_updated signal.

When used as a root container, you may wish to use the variables, such as REALNAME, in in the title. See the title property of the RygelMediaObject.

If the container should support UPnP search operations then you also implement the RygelSearchableContainer interface.

If the container should be writable, meaning that it allows adding (via upload), removal and editing of items then you should also implement the RygelWritableContainer interface.

If the container should support the change tracking profile of the UPnP ContentDirectory:3 specification then you should also implement the RygelTrackableContainer interface.

The RygelSimpleContainer class contains a simple memory-based container implementation, but most real-world uses will require custom container implementations.

## Functions

### rygel_media_container_get_children ()

    void
    rygel_media_container_get_children (RygelMediaContainer *self,
                                        guint offset,
                                        guint max_count,
                                        const gchar *sort_criteria,
                                        GCancellable *cancellable,
                                        GAsyncReadyCallback _callback_,
                                        gpointer _user_data_);

Fetches the list of media objects directly under this container.

See also: `rygel_media_container_get_children_finish()`

#### Parameters

self | the RygelMediaContainer instance |
offset | . zero-based index of the first item to return . | [in]
max_count | . maximum number of objects to return . | [in]
sort_criteria | . sorting order of objects to return . | [in]
cancellable | . optional cancellable for this operation . | [in][allow-none]
_callback_ | callback to call when the request is satisfied. | [scope async]
_user_data_ | the data to pass to `_callback_` function. | [closure]

### rygel_media_container_get_children_finish ()

    RygelMediaObjects *
    rygel_media_container_get_children_finish
                                   (RygelMediaContainer *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Fetches the list of media objects directly under this container.

See also: `rygel_media_container_get_children()`

#### Parameters

self | the RygelMediaContainer instance |
_res_ | a GAsyncResult |
error | location to store the error occuring, or `NULL` to ignore |

#### Returns

A list of media objects.

### rygel_media_container_find_object ()

    void
    rygel_media_container_find_object (RygelMediaContainer *self,
                                       const gchar *id,
                                       GCancellable *cancellable,
                                       GAsyncReadyCallback _callback_,
                                       gpointer _user_data_);

Recursively searches this container for a media object with the given ID.

See also: `rygel_media_container_find_object_finish()`

#### Parameters

self | the RygelMediaContainer instance |
id | . ID of the media object to search for . | [in]
cancellable | . optional cancellable for this operation . | [in][allow-none]
_callback_ | callback to call when the request is satisfied. | [scope async]
_user_data_ | the data to pass to `_callback_` function. | [closure]

### rygel_media_container_find_object_finish ()

    RygelMediaObject *
    rygel_media_container_find_object_finish
                                   (RygelMediaContainer *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Recursively searches this container for a media object with the given ID.

See also: `rygel_media_container_find_object()`

#### Parameters

self | the RygelMediaContainer instance |
_res_ | a GAsyncResult |
error | location to store the error occuring, or `NULL` to ignore |

#### Returns

the found media object.

### rygel_media_container_updated ()

    void
    rygel_media_container_updated (RygelMediaContainer *self,
                                   RygelMediaObject *object,
                                   RygelObjectEventType event_type,
                                   gboolean sub_tree_update);

This method should be called each time this container is updated.

For instance, this should be called if there are metadata changes for this container, if items under it are removed or added, if there are metadata changes to items under it, etc.

If sub_tree_update is true then the caller should later emit the sub_tree_updates_finished signal on the root container of the sub-tree that was updated.

It will eventually result in the server emitting a UPnP LastChange event, though that may be for a batch of these calls.

See the “container_updated” signal.

#### Parameters

self | the RygelMediaContainer instance |
object | . The object that has changed, or null to mean the container itself. . | [in][allow-none]
event_type | . This describes what actually happened to the object. . | [in]
sub_tree_update | . Whether the modification is part of a sub-tree update. . | [in]

### rygel_media_container_get_child_count ()

    gint
    rygel_media_container_get_child_count (RygelMediaContainer *self);

Get and return the current value of the "child-count" property.

#### Parameters

self | the RygelMediaContainer instance to query |

#### Returns

the value of the "child-count" property

### rygel_media_container_set_child_count ()

    void
    rygel_media_container_set_child_count (RygelMediaContainer *self,
                                           gint value);

Set the value of the "child-count" property to `value` .

#### Parameters

self | the RygelMediaContainer instance to modify |
value | the new value of the "child-count" property |

### rygel_media_container_get_empty_child_count ()

    gint
    rygel_media_container_get_empty_child_count
                                   (RygelMediaContainer *self);

Get and return the current value of the "empty-child-count" property.

#### Parameters

self | the RygelMediaContainer instance to query |

#### Returns

the value of the "empty-child-count" property

### rygel_media_container_set_empty_child_count ()

    void
    rygel_media_container_set_empty_child_count
                                   (RygelMediaContainer *self,
                                    gint value);

Set the value of the "empty-child-count" property to `value` .

#### Parameters

self | the RygelMediaContainer instance to modify |
value | the new value of the "empty-child-count" property |

### rygel_media_container_get_all_child_count ()

    gint
    rygel_media_container_get_all_child_count
                                   (RygelMediaContainer *self);

Get and return the current value of the "all-child-count" property.

#### Parameters

self | the RygelMediaContainer instance to query |

#### Returns

the value of the "all-child-count" property

### rygel_media_container_get_create_mode_enabled ()

    gboolean
    rygel_media_container_get_create_mode_enabled
                                   (RygelMediaContainer *self);

Get and return the current value of the "create-mode-enabled" property.

#### Parameters

self | the RygelMediaContainer instance to query |

#### Returns

the value of the "create-mode-enabled" property

### rygel_media_container_set_create_mode_enabled ()

    void
    rygel_media_container_set_create_mode_enabled
                                   (RygelMediaContainer *self,
                                    gboolean value);

Set the value of the "create-mode-enabled" property to `value` .

#### Parameters

self | the RygelMediaContainer instance to modify |
value | the new value of the "create-mode-enabled" property |

### rygel_media_container_get_sort_criteria ()

    const gchar *
    rygel_media_container_get_sort_criteria
                                   (RygelMediaContainer *self);

Get and return the current value of the "sort-criteria" property.

#### Parameters

self | the RygelMediaContainer instance to query |

#### Returns

the value of the "sort-criteria" property

### rygel_media_container_set_sort_criteria ()

    void
    rygel_media_container_set_sort_criteria
                                   (RygelMediaContainer *self,
                                    const gchar *value);

Set the value of the "sort-criteria" property to `value` .

#### Parameters

self | the RygelMediaContainer instance to modify |
value | the new value of the "sort-criteria" property |

### rygel_media_container_equal_func ()

    gboolean
    rygel_media_container_equal_func (RygelMediaContainer *a,
                                      RygelMediaContainer *b);

#### Parameters

a |  |
b |  |

## Types and Values

### RYGEL_TYPE_MEDIA_CONTAINER

    #define RYGEL_TYPE_MEDIA_CONTAINER (rygel_media_container_get_type ())

The type for RygelMediaContainer.

### RYGEL_MEDIA_CONTAINER_ANY

    #define RYGEL_MEDIA_CONTAINER_ANY "DLNA.ORG_AnyContainer"

### RYGEL_MEDIA_CONTAINER_UPNP_CLASS

    #define RYGEL_MEDIA_CONTAINER_UPNP_CLASS "object.container"

### RYGEL_MEDIA_CONTAINER_STORAGE_FOLDER

    #define RYGEL_MEDIA_CONTAINER_STORAGE_FOLDER RYGEL_MEDIA_CONTAINER_UPNP_CLASS ".storageFolder"

### RYGEL_MEDIA_CONTAINER_MUSIC_ALBUM

    #define RYGEL_MEDIA_CONTAINER_MUSIC_ALBUM RYGEL_MEDIA_CONTAINER_UPNP_CLASS ".album.musicAlbum"

### RYGEL_MEDIA_CONTAINER_MUSIC_ARTIST

    #define RYGEL_MEDIA_CONTAINER_MUSIC_ARTIST RYGEL_MEDIA_CONTAINER_UPNP_CLASS ".person.musicArtist"

### RYGEL_MEDIA_CONTAINER_MUSIC_GENRE

    #define RYGEL_MEDIA_CONTAINER_MUSIC_GENRE RYGEL_MEDIA_CONTAINER_UPNP_CLASS ".genre.musicGenre"

### RYGEL_MEDIA_CONTAINER_PLAYLIST

    #define RYGEL_MEDIA_CONTAINER_PLAYLIST RYGEL_MEDIA_CONTAINER_UPNP_CLASS ".playlistContainer"

### RYGEL_MEDIA_CONTAINER_ALBUM_SORT_CRITERIA

    #define RYGEL_MEDIA_CONTAINER_ALBUM_SORT_CRITERIA "+upnp:class," "+rygel:originalVolumeNumber," "+upnp:originalTrackNumber," "+dc:title"

### struct RygelMediaContainer

    struct RygelMediaContainer;

This is a container (folder) for media items and child containers.

It provides a basic serialization implementation (to DIDLLiteWriter).

A derived class should provide a working implementation of get_children and should emit the container_updated signal.

When used as a root container, you may wish to use the variables, such as REALNAME, in in the title. See the title property of the RygelMediaObject.

If the container should support UPnP search operations then you also implement the RygelSearchableContainer interface.

If the container should be writable, meaning that it allows adding (via upload), removal and editing of items then you should also implement the RygelWritableContainer interface.

If the container should support the change tracking profile of the UPnP ContentDirectory:3 specification then you should also implement the RygelTrackableContainer interface.

The RygelSimpleContainer class contains a simple memory-based container implementation, but most real-world uses will require custom container implementations.

### struct RygelMediaContainerClass

    struct RygelMediaContainerClass {
    	RygelMediaObjectClass parent_class;
    	void (*get_children) (RygelMediaContainer* self, guint offset, guint max_count, const gchar* sort_criteria, GCancellable* cancellable, GAsyncReadyCallback _callback_, gpointer _user_data_);
    	RygelMediaObjects* (*get_children_finish) (RygelMediaContainer* self, GAsyncResult* _res_, GError** error);
    	void (*find_object) (RygelMediaContainer* self, const gchar* id, GCancellable* cancellable, GAsyncReadyCallback _callback_, gpointer _user_data_);
    	RygelMediaObject* (*find_object_finish) (RygelMediaContainer* self, GAsyncResult* _res_, GError** error);
    };

The class structure for `RYGEL_TYPE_MEDIA_CONTAINER`. All the fields in this structure are private and should never be accessed directly.

#### Members

`get_children` () | virtual method called by `rygel_media_container_get_children()` |
`get_children_finish` () | asynchronous finish function for `get_children`, called by `rygel_media_container_get_children()` |
`find_object` () | virtual method called by `rygel_media_container_find_object()` |
`find_object_finish` () | asynchronous finish function for `find_object`, called by `rygel_media_container_find_object()` |

### enum RygelObjectEventType

#### Members

RYGEL_OBJECT_EVENT_TYPE_ADDED |  |
RYGEL_OBJECT_EVENT_TYPE_MODIFIED |  |
RYGEL_OBJECT_EVENT_TYPE_DELETED |  |

## Property Details

### The `“all-child-count”` property

      “all-child-count”          gint

all-child-count.

Flags: Read

Default value: 0

### The `“child-count”` property

      “child-count”              gint

child-count.

Flags: Read / Write / Construct

Default value: 0

### The `“create-mode-enabled”` property

      “create-mode-enabled”      gboolean

create-mode-enabled.

Flags: Read / Write

Default value: FALSE

### The `“empty-child-count”` property

      “empty-child-count”        gint

empty-child-count.

Flags: Read / Write

Default value: 0

### The `“ocm-flags”` property

      “ocm-flags”                GUPnPOCMFlags

ocm-flags.

Flags: Read

### The `“sort-criteria”` property

      “sort-criteria”            gchar *

sort-criteria.

Flags: Read / Write

Default value: NULL

## Signal Details

### The `“container-updated”` signal

    void
    user_function (RygelMediaContainer *media_container,
                   RygelMediaContainer *container,
                   RygelMediaObject    *object,
                   RygelObjectEventType event_type,
                   gboolean             sub_tree_update,
                   gpointer             user_data)

The container_updated signal is emitted if the subtree unter this container has been modified. The object parameter is set to the MediaObject that is the source of the container update. Note that it may even be set to the container itself.

See also: `rygel_media_container_updated()`.

#### Parameters

media_container | the RygelMediaContainer instance that received the signal |
container | . The child container that has been updated. |
object | . The object that has changed. This may be the container itself, or a child item. |
event_type | . This describes what actually happened to the object. |
sub_tree_update | . Whether the modification is part of a sub-tree update. See the “sub_tree_updates_finished” signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“sub-tree-updates-finished”` signal

    void
    user_function (RygelMediaContainer *media_container,
                   RygelMediaObject    *sub_tree_root,
                   gpointer             user_data)

The sub_tree_updates_finished signal is emitted when all of the sub-tree operations are finished. See the “container_updated” signal.

#### Parameters

media_container | the RygelMediaContainer instance that received the signal |
sub_tree_root | . - root of a sub-tree where all operations were performed. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last