RygelTrackableContainer

## RygelTrackableContainer RygelTrackableContainer — The base class for containers that provide automatic change tracking. |

## Synopsis

    void                rygel_trackable_container_clear     (RygelTrackableContainer *self,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);
    void                rygel_trackable_container_clear_finish
                                                            (RygelTrackableContainer *self,
                                                             GAsyncResult *_res_);
    void                rygel_trackable_container_add_child (RygelTrackableContainer *self,
                                                             RygelMediaObject *object,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);
    void                rygel_trackable_container_add_child_finish
                                                            (RygelTrackableContainer *self,
                                                             GAsyncResult *_res_);
    void                rygel_trackable_container_add_child_tracked
                                                            (RygelTrackableContainer *self,
                                                             RygelMediaObject *object,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);
    void                rygel_trackable_container_add_child_tracked_finish
                                                            (RygelTrackableContainer *self,
                                                             GAsyncResult *_res_);
    void                rygel_trackable_container_remove_child
                                                            (RygelTrackableContainer *self,
                                                             RygelMediaObject *object,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);
    void                rygel_trackable_container_remove_child_finish
                                                            (RygelTrackableContainer *self,
                                                             GAsyncResult *_res_);
    void                rygel_trackable_container_remove_child_tracked
                                                            (RygelTrackableContainer *self,
                                                             RygelMediaObject *object,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);
    void                rygel_trackable_container_remove_child_tracked_finish
                                                            (RygelTrackableContainer *self,
                                                             GAsyncResult *_res_);
    gchar *             rygel_trackable_container_get_service_reset_token
                                                            (RygelTrackableContainer *self);
    void                rygel_trackable_container_set_service_reset_token
                                                            (RygelTrackableContainer *self,
                                                             const gchar *token);
    guint32             rygel_trackable_container_get_system_update_id
                                                            (RygelTrackableContainer *self);
                        RygelTrackableContainer;
    struct              RygelTrackableContainerIface;

## Object Hierarchy

      GInterface
       +----RygelTrackableContainer

## Prerequisites

RygelTrackableContainer requires RygelMediaContainer.

## Signals

      "child-added"                                    : Run Last
      "child-removed"                                  : Run Last

## Description

Derived classes should implement the `add_child()` and `remove_child()` virtual functions to keep track of child items and child containers.

Rygel server plugins (See RygelMediaServer) may then call `rygel_trackable_container_add_child_tracked()` and `rygel_trackable_container_remove_child_tracked()` to add and remove items, which will then cause the "container_updated" signal to be emitted.

## Details

### rygel_trackable_container_clear ()

    void                rygel_trackable_container_clear     (RygelTrackableContainer *self,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);

See also: `rygel_trackable_container_clear_finish()`

`self` : | the RygelTrackableContainer instance
`_callback_` : | callback to call when the request is satisfied. [scope async]
`_user_data_` : | the data to pass to `_callback_` function. [closure]

### rygel_trackable_container_clear_finish ()

    void                rygel_trackable_container_clear_finish
                                                            (RygelTrackableContainer *self,
                                                             GAsyncResult *_res_);

See also: `rygel_trackable_container_clear()`

`self` : | the RygelTrackableContainer instance
`_res_` : | a GAsyncResult

### rygel_trackable_container_add_child ()

    void                rygel_trackable_container_add_child (RygelTrackableContainer *self,
                                                             RygelMediaObject *object,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);

Derived classes should implement this, keeping track of the child item or child container. See the `remove_child()` virtual function.

See also: `rygel_trackable_container_add_child_finish()`

`self` : | the RygelTrackableContainer instance
`object` : |
`_callback_` : | callback to call when the request is satisfied. [scope async]
`_user_data_` : | the data to pass to `_callback_` function. [closure]

### rygel_trackable_container_add_child_finish ()

    void                rygel_trackable_container_add_child_finish
                                                            (RygelTrackableContainer *self,
                                                             GAsyncResult *_res_);

Derived classes should implement this, keeping track of the child item or child container. See the `remove_child()` virtual function.

See also: `rygel_trackable_container_add_child()`

`self` : | the RygelTrackableContainer instance
`_res_` : | a GAsyncResult

### rygel_trackable_container_add_child_tracked ()

    void                rygel_trackable_container_add_child_tracked
                                                            (RygelTrackableContainer *self,
                                                             RygelMediaObject *object,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);

Add a child object, emitting the "container_updated" signal with the object.

See also: `rygel_trackable_object_remove_child_tracked()`, `rygel_trackable_container_add_child_tracked_finish()`

`self` : | the RygelTrackableContainer instance
`object` : | . The child item or child container to be added. [in]
`_callback_` : | callback to call when the request is satisfied. [scope async]
`_user_data_` : | the data to pass to `_callback_` function. [closure]

### rygel_trackable_container_add_child_tracked_finish ()

    void                rygel_trackable_container_add_child_tracked_finish
                                                            (RygelTrackableContainer *self,
                                                             GAsyncResult *_res_);

Add a child object, emitting the "container_updated" signal with the object.

See also: `rygel_trackable_object_remove_child_tracked()`, `rygel_trackable_container_add_child_tracked()`

`self` : | the RygelTrackableContainer instance
`_res_` : | a GAsyncResult

### rygel_trackable_container_remove_child ()

    void                rygel_trackable_container_remove_child
                                                            (RygelTrackableContainer *self,
                                                             RygelMediaObject *object,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);

Derived classes should implement this, removing the child item or child container from its set of objects. See the `add_child()` virtual function.

See also: `rygel_trackable_container_remove_child_finish()`

`self` : | the RygelTrackableContainer instance
`object` : |
`_callback_` : | callback to call when the request is satisfied. [scope async]
`_user_data_` : | the data to pass to `_callback_` function. [closure]

### rygel_trackable_container_remove_child_finish ()

    void                rygel_trackable_container_remove_child_finish
                                                            (RygelTrackableContainer *self,
                                                             GAsyncResult *_res_);

Derived classes should implement this, removing the child item or child container from its set of objects. See the `add_child()` virtual function.

See also: `rygel_trackable_container_remove_child()`

`self` : | the RygelTrackableContainer instance
`_res_` : | a GAsyncResult

### rygel_trackable_container_remove_child_tracked ()

    void                rygel_trackable_container_remove_child_tracked
                                                            (RygelTrackableContainer *self,
                                                             RygelMediaObject *object,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);

Add a child object, emitting the "container_updated" signal with the object.

See also: `rygel_trackable_object_add_child_tracked()`, `rygel_trackable_container_remove_child_tracked_finish()`

`self` : | the RygelTrackableContainer instance
`object` : | . The child item or child container to be added. [in]
`_callback_` : | callback to call when the request is satisfied. [scope async]
`_user_data_` : | the data to pass to `_callback_` function. [closure]

### rygel_trackable_container_remove_child_tracked_finish ()

    void                rygel_trackable_container_remove_child_tracked_finish
                                                            (RygelTrackableContainer *self,
                                                             GAsyncResult *_res_);

Add a child object, emitting the "container_updated" signal with the object.

See also: `rygel_trackable_object_add_child_tracked()`, `rygel_trackable_container_remove_child_tracked()`

`self` : | the RygelTrackableContainer instance
`_res_` : | a GAsyncResult

### rygel_trackable_container_get_service_reset_token ()

    gchar *             rygel_trackable_container_get_service_reset_token
                                                            (RygelTrackableContainer *self);

Used to query the (persisted) service reset token from the plug-in.

If a plugin implements PLUGIN_CAPABILITIES_TRACK_CHANGES, it should persist the ServiceResetToken. To do this override this virtual function in the root container implementation and provide the persisted version.

`self` : | the RygelTrackableContainer instance

### rygel_trackable_container_set_service_reset_token ()

    void                rygel_trackable_container_set_service_reset_token
                                                            (RygelTrackableContainer *self,
                                                             const gchar *token);

Set a new service reset token.

If the service reset procedure has to be performed, the content directory service will set the new service reset token.

`self` : | the RygelTrackableContainer instance
`token` : | . the new service reset token. [in]

### rygel_trackable_container_get_system_update_id ()

    guint32             rygel_trackable_container_get_system_update_id
                                                            (RygelTrackableContainer *self);

Query the current system update ID, used for the UPnP GetSystemUpdateID implementation.

This should be overriden by the root container of the back-end implementation. This will only be called once, at service startup, to discover the cached system Update ID, if any, that was known when the service last shut down.

Derived classes may need to delay part of their initialization until this function has been called, doing that initialization in the function override. That can prevent other parts of their implementation from changing the cached System Update ID before it has been provided.

`self` : | the RygelTrackableContainer instance
Returns : | the current SystemUpdateID as persisted by the back-end.

### RygelTrackableContainer

    typedef struct _RygelTrackableContainer RygelTrackableContainer;

The base class for containers that provide automatic change tracking.

Derived classes should implement the `add_child()` and `remove_child()` virtual functions to keep track of child items and child containers.

Rygel server plugins (See RygelMediaServer) may then call `rygel_trackable_container_add_child_tracked()` and `rygel_trackable_container_remove_child_tracked()` to add and remove items, which will then cause the "container_updated" signal to be emitted.

### struct RygelTrackableContainerIface

    struct RygelTrackableContainerIface {
    	GTypeInterface parent_iface;
    	void (*add_child) (RygelTrackableContainer* self, RygelMediaObject* object, GAsyncReadyCallback _callback_, gpointer _user_data_);
    	void (*add_child_finish) (RygelTrackableContainer* self, GAsyncResult* _res_);
    	void (*remove_child) (RygelTrackableContainer* self, RygelMediaObject* object, GAsyncReadyCallback _callback_, gpointer _user_data_);
    	void (*remove_child_finish) (RygelTrackableContainer* self, GAsyncResult* _res_);
    	gchar* (*get_service_reset_token) (RygelTrackableContainer* self);
    	void (*set_service_reset_token) (RygelTrackableContainer* self, const gchar* token);
    	guint32 (*get_system_update_id) (RygelTrackableContainer* self);
    };

Interface for creating RygelTrackableContainer implementations.

GTypeInterface `parent_iface`; | the parent interface structure
`add_child` () | virtual method used internally
`add_child_finish` () | asynchronous finish function used internally
`remove_child` () | virtual method used internally
`remove_child_finish` () | asynchronous finish function used internally
`get_service_reset_token` () | virtual method called by `rygel_trackable_container_get_service_reset_token()`
`set_service_reset_token` () | virtual method called by `rygel_trackable_container_set_service_reset_token()`
`get_system_update_id` () | virtual method called by `rygel_trackable_container_get_system_update_id()`

## Signal Details

### The `"child-added"` signal

    void                user_function                      (RygelTrackableContainer *trackable_container,
                                                            RygelMediaObject        *object,
                                                            gpointer                 user_data)                : Run Last

`trackable_container` : | the RygelTrackableContainer instance that received the signal
`object` : |
`user_data` : | user data set when the signal handler was connected.

### The `"child-removed"` signal

    void                user_function                      (RygelTrackableContainer *trackable_container,
                                                            RygelMediaObject        *object,
                                                            gpointer                 user_data)                : Run Last

`trackable_container` : | the RygelTrackableContainer instance that received the signal
`object` : |
`user_data` : | user data set when the signal handler was connected.