GrlOperationOptions: Grilo Reference Manual

## GrlOperationOptions GrlOperationOptions — Describes the options to be passed to an operation |

## Functions

GrlOperationOptions * | grl_operation_options_new ()
GrlOperationOptions * | grl_operation_options_copy ()
gint | grl_operation_options_get_count ()
GrlResolutionFlags | grl_operation_options_get_resolution_flags ()
GValue * | grl_operation_options_get_key_filter ()
GList * | grl_operation_options_get_key_filter_list ()
void | grl_operation_options_get_key_range_filter ()
GList * | grl_operation_options_get_key_range_filter_list ()
guint | grl_operation_options_get_skip ()
GrlTypeFilter | grl_operation_options_get_type_filter ()
gboolean | grl_operation_options_obey_caps ()
gboolean | grl_operation_options_set_count ()
gboolean | grl_operation_options_set_resolution_flags ()
gboolean | grl_operation_options_set_key_filter_dictionary ()
gboolean | grl_operation_options_set_key_filter_value ()
gboolean | grl_operation_options_set_key_filters ()
gboolean | grl_operation_options_set_key_range_filter ()
gboolean | grl_operation_options_set_key_range_filter_value ()
gboolean | grl_operation_options_set_skip ()
gboolean | grl_operation_options_set_type_filter ()

## Types and Values

| GrlOperationOptions
| GrlOperationOptionsClass
#define | GRL_COUNT_INFINITY

## Object Hierarchy

        GObject
        ╰── GrlOperationOptions

## Includes

    #include <grilo.h>

## Description

## Functions

### grl_operation_options_new ()

    GrlOperationOptions *
    grl_operation_options_new (GrlCaps *caps);

Creates a new GrlOperationOptions object.

#### Parameters

caps | caps that options will have to match. If `NULL`, all options will be accepted. | [allow-none]

#### Returns

a new GrlOperationOptions instance.

Since: 0.2.0

### grl_operation_options_copy ()

    GrlOperationOptions *
    grl_operation_options_copy (GrlOperationOptions *options);

#### Parameters

options | a GrlOperationOptions instance |

#### Returns

a new GrlOperationOptions instance with its values being copies of the values of `options` .

[transfer full]

Since: 0.2.0

### grl_operation_options_get_count ()

    gint
    grl_operation_options_get_count (GrlOperationOptions *options);

Get the count option, that is, the number of elements to retrieve in an operation done with `options` .

#### Parameters

options | a GrlOperationOptions instance |

#### Returns

the value of the count option, or a default value if it is not set.

Since: 0.2.0

### grl_operation_options_get_resolution_flags ()

    GrlResolutionFlags
    grl_operation_options_get_resolution_flags
                                   (GrlOperationOptions *options);

#### Parameters

options | a GrlOperationOptions instance |

#### Returns

resolution flags of `options` .

Since: 0.2.12

### grl_operation_options_get_key_filter ()

    GValue *
    grl_operation_options_get_key_filter (GrlOperationOptions *options,
                                          GrlKeyID key);

#### Parameters

options | a GrlOperationOptions instance |

#### Returns

the filter.

[transfer none]

Since: 0.2.0

### grl_operation_options_get_key_filter_list ()

    GList *
    grl_operation_options_get_key_filter_list
                                   (GrlOperationOptions *options);

#### Parameters

options | a GrlOperationOptions instance |

#### Returns

.

[transfer container][element-type GrlKeyID]

Since: 0.2.0

### grl_operation_options_get_key_range_filter ()

    void
    grl_operation_options_get_key_range_filter
                                   (GrlOperationOptions *options,
                                    GrlKeyID key,
                                    GValue **min_value,
                                    GValue **max_value);

Stores the limits of the range in the filter for `key` in `min_value` and `max_value` . If some of the values has no limit, it will set a `NULL`.

#### Parameters

options | a GrlOperationOptions instance |
key | a GrlKeyID |
min_value | the minimum value for the range. | [out][allow-none][transfer none]
max_value | the maximum value for the range. | [out][allow-none][transfer none]

Since: 0.2.0

### grl_operation_options_get_key_range_filter_list ()

    GList *
    grl_operation_options_get_key_range_filter_list
                                   (GrlOperationOptions *options);

#### Parameters

options | a GrlOperationOptions instance |

#### Returns

.

[transfer container][element-type GrlKeyID]

Since: 0.2.0

### grl_operation_options_get_skip ()

    guint
    grl_operation_options_get_skip (GrlOperationOptions *options);

Get the skip option, that is, the number of elements to skip before retrieving media items in an operation done with `options` .

#### Parameters

options | a GrlOperationOptions instance |

#### Returns

the value of the skip option, or a default value if it is not set.

Since: 0.2.0

### grl_operation_options_get_type_filter ()

    GrlTypeFilter
    grl_operation_options_get_type_filter (GrlOperationOptions *options);

#### Parameters

options | a GrlOperationOptions instance |

#### Returns

resolution flags of `options`

Since: 0.2.0

### grl_operation_options_obey_caps ()

    gboolean
    grl_operation_options_obey_caps (GrlOperationOptions *options,
                                     GrlCaps *caps,
                                     GrlOperationOptions **supported_options,
                                     GrlOperationOptions **unsupported_options);

Check whether `options` obey to `caps` . Optionally provide the options that match (respectively don't match) `caps` in `supported_options` (respectively `unsupported_options` ). This would typically (but not necessarily) be used with a GrlOperationOptions instance that was created with `NULL` caps.

#### Parameters

options | a GrlOperationOptions instance |
caps | capabilities against which we want to test `options` |
supported_options | if not `NULL`, will contain a newly-allocated GrlOperationOptions instance containing all the values of `options` that match `caps` . | [out callee-allocates]
unsupported_options | if not `NULL`, will contain a newly-allocated GrlOperationOptions instance containing all the values of `options` that do not match `caps` . | [out callee-allocates]

#### Returns

`TRUE` if `options` obey to `caps` , `FALSE` otherwise.

Since: 0.2.0

### grl_operation_options_set_count ()

    gboolean
    grl_operation_options_set_count (GrlOperationOptions *options,
                                     gint count);

Set the count option for an operation. Will only succeed if `count` obey to the inherent capabilities of `options` .

#### Parameters

options | a GrlOperationOptions instance |
count | number of elements to retrieve in an operation |

#### Returns

`TRUE` if `count` could be set, `FALSE` otherwise.

Since: 0.2.0

### grl_operation_options_set_resolution_flags ()

    gboolean
    grl_operation_options_set_resolution_flags
                                   (GrlOperationOptions *options,
                                    GrlResolutionFlags flags);

Set the resolution flags for an operation. Will only succeed if `flags` obey to the inherent capabilities of `options` .

#### Parameters

options | a GrlOperationOptions instance |
flags | the resolution flags to be set for an operation. See GrlResolutionFlags for possible values. |

#### Returns

`TRUE` if `flags` could be set, `FALSE` otherwise.

Since: 0.2.12

### grl_operation_options_set_key_filter_dictionary ()

    gboolean
    grl_operation_options_set_key_filter_dictionary
                                   (GrlOperationOptions *options,
                                    GHashTable *filters);

[rename-to grl_operation_options_set_key_filters]

#### Parameters

options | a GrlOperationOptions instance |
filters | . | [transfer none][element-type GrlKeyID GValue]

#### Returns

`TRUE` on success

Since: 0.2.0

### grl_operation_options_set_key_filter_value ()

    gboolean
    grl_operation_options_set_key_filter_value
                                   (GrlOperationOptions *options,
                                    GrlKeyID key,
                                    GValue *value);

Set filter as "`key` == `value` ".

#### Parameters

options | a GrlOperationOptions instance |
key | a GrlKeyID |
value | a GValue |

#### Returns

`TRUE` on success

Since: 0.2.0

### grl_operation_options_set_key_filters ()

    gboolean
    grl_operation_options_set_key_filters (GrlOperationOptions *options,
                                           ...);

Set filter as "k1 == v1 AND k2 == v2 AND ..."

Example 2.

Elements from album "Frozen" with a bitrate of 256kbs.

      grl_operation_options_set_key_filters (my_options,
                                             GRL_METADATA_KEY_ALBUM, "Frozen",
                                             GRL_METADATA_KEY_BITRATE, 256,
                                             NULL);

#### Parameters

options | a GrlOperationOptions instance |
... | pairs of GrlKeyID, value |

#### Returns

`TRUE` on success

Since: 0.2.0

### grl_operation_options_set_key_range_filter ()

    gboolean
    grl_operation_options_set_key_range_filter
                                   (GrlOperationOptions *options,
                                    ...);

Set filter as "min1 <= k1 <= max1 AND min2 <= k2 <= max2 AND ..."

For non numeric types, the range can be open if some of the minX, maxX values are `NULL`. Leaving NULL for numeric types leads to underifned behavior.

Example 3.

Album must start with "T" and the bitrate should be 256kbs or greater.

      grl_operation_options_set_key_range_filters (my_options,
                                                   GRL_METADATA_KEY_ALBUM, "Ta", "Tz",
                                                   GRL_METADATA_KEY_BITRATE, 256, G_MAXINT,
                                                   NULL);

#### Parameters

options | a GrlOperationOptions instance |
... | triplets of GrlKeyID, minvalue, maxvalue |

#### Returns

`TRUE` on success

Since: 0.2.0

### grl_operation_options_set_key_range_filter_value ()

    gboolean
    grl_operation_options_set_key_range_filter_value
                                   (GrlOperationOptions *options,
                                    GrlKeyID key,
                                    GValue *min_value,
                                    GValue *max_value);

Set filter as "`min_value` <= `key` <= `max_value` ".

If `min_value` is `NULL`, then filter is "`key` <= `max_value` ".

If `max_value` is `NULL`, then filter is "`key` >= `min_value` ".

Note that `key` will always respect the limits defined at creation time. e.g: Core's GRL_METADATA_KEY_ORIENTATION has "max = 359" and "min = 0", user can set "`max_value` = 180" but "`max_value` = 720" would be ignored.

#### Parameters

options | a GrlOperationOptions instance |
key | a GrlKeyID |
min_value | minimum value for range. | [in][allow-none]
max_value | maximum value for range. | [in][allow-none]

#### Returns

`TRUE` on success

Since: 0.2.0

### grl_operation_options_set_skip ()

    gboolean
    grl_operation_options_set_skip (GrlOperationOptions *options,
                                    guint skip);

Set the skip option for an operation. Will only succeed if `skip` obeys to the inherent capabilities of `options` .

#### Parameters

options | a GrlOperationOptions instance |
skip | number of elements to skip in an operation |

#### Returns

`TRUE` if `skip` could be set, `FALSE` otherwise.

Since: 0.2.0

### grl_operation_options_set_type_filter ()

    gboolean
    grl_operation_options_set_type_filter (GrlOperationOptions *options,
                                           GrlTypeFilter filter);

Set the type of media filter for an operation. Only those media elements that match the `filter` will be returned. Will only succeed if `filter` obey to the inherent capabilities of `options` .

#### Parameters

options | a GrlOperationOptions instance |
filter | the type of media to get |

#### Returns

`TRUE` if `flags` could be set, `FALSE` otherwise

Since: 0.2.0

## Types and Values

### GrlOperationOptions

    typedef struct _GrlOperationOptions GrlOperationOptions;

### GrlOperationOptionsClass

    typedef struct {
      GObjectClass parent;
    } GrlOperationOptionsClass;

Grilo Operation Options class.

#### Members

GObjectClass `parent`; | the parent class structure |

### GRL_COUNT_INFINITY

    #define GRL_COUNT_INFINITY (-1)

## See Also

GrlCaps, `grl_source_resolve()`, `grl_source_search()`, `grl_source_browse()`, `grl_source_query()`