RygelSearchableContainer: librygel-server Reference Manual

## RygelSearchableContainer RygelSearchableContainer — The base class for searchable containers. |

## Functions

void | rygel_searchable_container_search ()
RygelMediaObjects * | rygel_searchable_container_search_finish ()
void | rygel_searchable_container_simple_search ()
RygelMediaObjects * | rygel_searchable_container_simple_search_finish ()
void | rygel_searchable_container_find_object ()
RygelMediaObject * | rygel_searchable_container_find_object_finish ()
GeeArrayList * | rygel_searchable_container_get_search_classes ()
void | rygel_searchable_container_set_search_classes ()

## Properties

GeeArrayList * | search-classes | Read / Write

## Types and Values

| RygelSearchableContainer
struct | RygelSearchableContainerIface

## Object Hierarchy

        GInterface
        ╰── RygelSearchableContainer

## Prerequisites

RygelSearchableContainer requires RygelMediaContainer.

## Known Implementations

RygelSearchableContainer is implemented by RygelSimpleContainer.

## 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),

## Functions

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

## Types and Values

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

#### Members

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 *

search-classes.

Flags: Read / Write