## RygelSearchableContainer

RygelSearchableContainer — The base class for searchable containers.

## Synopsis

    void                rygel_searchable_container_search   (RygelSearchableContainer *self,
                                                             RygelSearchExpression *expression,
                                                             guint offset,
                                                             guint max_count,
                                                             const gchar *sort_criteria,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);
    RygelMediaObjects * rygel_searchable_container_search_finish
                                                            (RygelSearchableContainer *self,
                                                             GAsyncResult *_res_,
                                                             guint *total_matches,
                                                             GError **error);
    void                rygel_searchable_container_simple_search
                                                            (RygelSearchableContainer *self,
                                                             RygelSearchExpression *expression,
                                                             guint offset,
                                                             guint max_count,
                                                             const gchar *sort_criteria,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);
    RygelMediaObjects * rygel_searchable_container_simple_search_finish
                                                            (RygelSearchableContainer *self,
                                                             GAsyncResult *_res_,
                                                             guint *total_matches,
                                                             GError **error);
    void                rygel_searchable_container_find_object
                                                            (RygelSearchableContainer *self,
                                                             const gchar *id,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);
    RygelMediaObject *  rygel_searchable_container_find_object_finish
                                                            (RygelSearchableContainer *self,
                                                             GAsyncResult *_res_,
                                                             GError **error);
    GeeArrayList *      rygel_searchable_container_get_search_classes
                                                            (RygelSearchableContainer *self);
    void                rygel_searchable_container_set_search_classes
                                                            (RygelSearchableContainer *self,
                                                             GeeArrayList *value);
                        RygelSearchableContainer;
    struct              RygelSearchableContainerIface;

## Object Hierarchy

      GInterface
       +----RygelSearchableContainer

## Prerequisites

RygelSearchableContainer requires RygelMediaContainer.

## Known Implementations

RygelSearchableContainer is implemented by RygelSimpleContainer.

## Properties

      "search-classes"           GeeArrayList*         : Read / Write

## Description

Classes that implement this interface can, for instance:

1. Allow backends to implement a UPnP Search call using native searching (such as SQL or SPARQL queries).

2. Implement searching via the naïve default implementation provided by `rygel_searchable_container_simple_search()`, which does a recursive tree walk.

The search_classes property lists what information this container may be searched for. It is mapped to upnp:searchClass (with includeDerived assumed to be false),

## Details

### rygel_searchable_container_search ()

    void                rygel_searchable_container_search   (RygelSearchableContainer *self,
                                                             RygelSearchExpression *expression,
                                                             guint offset,
                                                             guint max_count,
                                                             const gchar *sort_criteria,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);

Recursively searches for all media objects that satisfy the given search expression in this container.

See also: `rygel_searchable_container_search_finish()`

`self` : | the RygelSearchableContainer instance
`expression` : | . the search expression or null for wildcard. [in][allow-none]
`offset` : | . zero-based index of the first object to return. [in]
`max_count` : | . maximum number of objects to return. [in]
`total_matches` : | . sets it to the actual number of objects that satisfy. [out]
`cancellable` : | . optional cancellable for this operation. [in][allow-none]
`sort_criteria` : |
`_callback_` : | callback to call when the request is satisfied. [scope async]
`_user_data_` : | the data to pass to `_callback_` function. [closure]

### rygel_searchable_container_search_finish ()

    RygelMediaObjects * rygel_searchable_container_search_finish
                                                            (RygelSearchableContainer *self,
                                                             GAsyncResult *_res_,
                                                             guint *total_matches,
                                                             GError **error);

Recursively searches for all media objects that satisfy the given search expression in this container.

See also: `rygel_searchable_container_search()`

`self` : | the RygelSearchableContainer instance
`_res_` : | a GAsyncResult
`error` : | location to store the error occuring, or `NULL` to ignore
Returns : | A list of matching media objects or null if no object matched.

### rygel_searchable_container_simple_search ()

    void                rygel_searchable_container_simple_search
                                                            (RygelSearchableContainer *self,
                                                             RygelSearchExpression *expression,
                                                             guint offset,
                                                             guint max_count,
                                                             const gchar *sort_criteria,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);

Utility method that retrieves all children and recursively searches for all media objects that satisfy the given search expression in this container.

See also: `rygel_searchable_container_simple_search_finish()`

`self` : | the RygelSearchableContainer instance
`expression` : | . the search expression or `null` for wildcard. [in][allow-none]
`offset` : | . zero-based index of the first object to return. [in]
`max_count` : | . maximum number of objects to return. [in]
`total_matches` : | . sets it to the actual number of objects that satisfy the given search expression. If it is not possible to compute this value (in a timely mannger), it is set to '0'. [out]
`cancellable` : | . optional cancellable for this operation. [in][allow-none]
`sort_criteria` : |
`_callback_` : | callback to call when the request is satisfied. [scope async]
`_user_data_` : | the data to pass to `_callback_` function. [closure]

### rygel_searchable_container_simple_search_finish ()

    RygelMediaObjects * rygel_searchable_container_simple_search_finish
                                                            (RygelSearchableContainer *self,
                                                             GAsyncResult *_res_,
                                                             guint *total_matches,
                                                             GError **error);

Utility method that retrieves all children and recursively searches for all media objects that satisfy the given search expression in this container.

See also: `rygel_searchable_container_simple_search()`

`self` : | the RygelSearchableContainer instance
`_res_` : | a GAsyncResult
`error` : | location to store the error occuring, or `NULL` to ignore
Returns : | A list of media objects.

### rygel_searchable_container_find_object ()

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

Recursively searches for media object with the given id in this container.

See also: `rygel_searchable_container_find_object_finish()`

`callback` : | function to call when result is ready
`self` : | the RygelSearchableContainer 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_searchable_container_find_object_finish ()

    RygelMediaObject *  rygel_searchable_container_find_object_finish
                                                            (RygelSearchableContainer *self,
                                                             GAsyncResult *_res_,
                                                             GError **error);

Recursively searches for media object with the given id in this container.

See also: `rygel_searchable_container_find_object()`

`self` : | the RygelSearchableContainer instance
`_res_` : | a GAsyncResult
`error` : | location to store the error occuring, or `NULL` to ignore
Returns : | the found media object.

### rygel_searchable_container_get_search_classes ()

    GeeArrayList *      rygel_searchable_container_get_search_classes
                                                            (RygelSearchableContainer *self);

Get and return the current value of the "search-classes" property.

`self` : | the RygelSearchableContainer instance to query
Returns : | the value of the "search-classes" property

### rygel_searchable_container_set_search_classes ()

    void                rygel_searchable_container_set_search_classes
                                                            (RygelSearchableContainer *self,
                                                             GeeArrayList *value);

Set the value of the "search-classes" property to `value`.

`self` : | the RygelSearchableContainer instance to modify
`value` : | the new value of the "search-classes" property

### RygelSearchableContainer

    typedef struct _RygelSearchableContainer RygelSearchableContainer;

The base class for searchable containers.

Classes that implement this interface can, for instance:

1. Allow backends to implement a UPnP Search call using native searching (such as SQL or SPARQL queries).

2. Implement searching via the naïve default implementation provided by `rygel_searchable_container_simple_search()`, which does a recursive tree walk.

The search_classes property lists what information this container may be searched for. It is mapped to upnp:searchClass (with includeDerived assumed to be false),

### struct RygelSearchableContainerIface

    struct RygelSearchableContainerIface {
    	GTypeInterface parent_iface;
    	void (*search) (RygelSearchableContainer* self, RygelSearchExpression* expression, guint offset, guint max_count, const gchar* sort_criteria, GCancellable* cancellable, GAsyncReadyCallback _callback_, gpointer _user_data_);
    	RygelMediaObjects* (*search_finish) (RygelSearchableContainer* self, GAsyncResult* _res_, guint* total_matches, GError** error);
    	GeeArrayList* (*get_search_classes) (RygelSearchableContainer* self);
    	void (*set_search_classes) (RygelSearchableContainer* self, GeeArrayList* value);
    };

Interface for creating RygelSearchableContainer implementations.

GTypeInterface `parent_iface`; | the parent interface structure
`search` () | virtual method called by `rygel_searchable_container_search()`
`search_finish` () | asynchronous finish function for `search`, called by `rygel_searchable_container_search()`
`get_search_classes` () | getter method for the abstract property "search-classes"
`set_search_classes` () | setter method for the abstract property "search-classes"

## Property Details

### The `"search-classes"` property

      "search-classes"           GeeArrayList*         : Read / Write

search-classes.