RygelTrackableContainer: librygel-server Reference Manual

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

## Functions

void | rygel_trackable_container_clear ()
void | rygel_trackable_container_clear_finish ()
void | rygel_trackable_container_add_child ()
void | rygel_trackable_container_add_child_finish ()
void | rygel_trackable_container_add_child_tracked ()
void | rygel_trackable_container_add_child_tracked_finish ()
void | rygel_trackable_container_remove_child ()
void | rygel_trackable_container_remove_child_finish ()
void | rygel_trackable_container_remove_child_tracked ()
void | rygel_trackable_container_remove_child_tracked_finish ()
gchar * | rygel_trackable_container_get_service_reset_token ()
void | rygel_trackable_container_set_service_reset_token ()
guint32 | rygel_trackable_container_get_system_update_id ()

## Signals

void | child-added | Run Last
void | child-removed | Run Last

## Types and Values

| RygelTrackableContainer
struct | RygelTrackableContainerIface

## Object Hierarchy

        GInterface
        ╰── RygelTrackableContainer

## Prerequisites

RygelTrackableContainer requires RygelMediaContainer.

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

## Functions

### rygel_trackable_container_clear ()

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

See also: `rygel_trackable_container_clear_finish()`

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

self | the RygelTrackableContainer instance |

#### Returns

the current SystemUpdateID as persisted by the back-end.

## Types and Values

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

#### Members

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)

#### Parameters

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

Flags: Run Last

### The `“child-removed”` signal

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

#### Parameters

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

Flags: Run Last