XMMS2
Functions
CollectionStructure

The API to be used to work with collection structures. More...

Functions

xmmsv_coll_txmmsv_coll_ref (xmmsv_coll_t *coll)
 Increases the references for the xmmsv_coll_t. More...
 
xmmsv_coll_txmmsv_coll_new (xmmsv_coll_type_t type)
 Allocate a new collection of the given type. More...
 
void xmmsv_coll_unref (xmmsv_coll_t *coll)
 Decreases the references for the xmmsv_coll_t When the number of references reaches 0 it will be freed and all its operands unreferenced as well. More...
 
void xmmsv_coll_set_idlist (xmmsv_coll_t *coll, int ids[])
 Set the list of ids in the given collection. More...
 
void xmmsv_coll_add_operand (xmmsv_coll_t *coll, xmmsv_coll_t *op)
 Add the operand to the given collection. More...
 
void xmmsv_coll_remove_operand (xmmsv_coll_t *coll, xmmsv_coll_t *op)
 Remove all the occurences of the operand in the given collection. More...
 
int xmmsv_coll_idlist_append (xmmsv_coll_t *coll, int id)
 Append a value to the idlist. More...
 
int xmmsv_coll_idlist_insert (xmmsv_coll_t *coll, int index, int id)
 Insert a value at a given position in the idlist. More...
 
int xmmsv_coll_idlist_move (xmmsv_coll_t *coll, int index, int newindex)
 Move a value of the idlist to a new position. More...
 
int xmmsv_coll_idlist_remove (xmmsv_coll_t *coll, int index)
 Remove the value at a given index from the idlist. More...
 
int xmmsv_coll_idlist_clear (xmmsv_coll_t *coll)
 Empties the idlist. More...
 
int xmmsv_coll_idlist_get_index (xmmsv_coll_t *coll, int index, int32_t *val)
 Retrieves the value at the given position in the idlist. More...
 
int xmmsv_coll_idlist_set_index (xmmsv_coll_t *coll, int index, int32_t val)
 Sets the value at the given position in the idlist. More...
 
size_t xmmsv_coll_idlist_get_size (xmmsv_coll_t *coll)
 Get the size of the idlist. More...
 
xmmsv_coll_type_t xmmsv_coll_get_type (xmmsv_coll_t *coll)
 Return the type of the collection. More...
 
const int32_t * xmmsv_coll_get_idlist (xmmsv_coll_t *coll)
 Return the list of ids stored in the collection. More...
 
xmmsv_txmmsv_coll_idlist_get (xmmsv_coll_t *coll)
 Return the list of ids stored in the collection. More...
 
xmmsv_txmmsv_coll_operands_get (xmmsv_coll_t *coll)
 
xmmsv_txmmsv_coll_attributes_get (xmmsv_coll_t *coll)
 
void xmmsv_coll_attribute_set (xmmsv_coll_t *coll, const char *key, const char *value)
 Set an attribute in the given collection. More...
 
int xmmsv_coll_attribute_remove (xmmsv_coll_t *coll, const char *key)
 Remove an attribute from the given collection. More...
 
int xmmsv_coll_attribute_get (xmmsv_coll_t *coll, const char *key, char **value)
 Retrieve the value of the attribute of the given collection. More...
 
void xmmsv_coll_attribute_foreach (xmmsv_coll_t *coll, xmmsv_coll_attribute_foreach_func func, void *user_data)
 Iterate over all key/value-pair of the collection attributes. More...
 
xmmsv_coll_txmmsv_coll_universe ()
 Return a collection referencing the whole media library, that is a reference to the "All Media" collection. More...
 

Detailed Description

The API to be used to work with collection structures.

Function Documentation

◆ xmmsv_coll_add_operand()

void xmmsv_coll_add_operand ( xmmsv_coll_t coll,
xmmsv_coll_t op 
)

Add the operand to the given collection.

Parameters
collThe collection to add the operand to.
opThe operand to add.

Definition at line 195 of file coll.c.

Referenced by bind_all_references().

◆ xmmsv_coll_attribute_foreach()

void xmmsv_coll_attribute_foreach ( xmmsv_coll_t coll,
xmmsv_coll_attribute_foreach_func  func,
void *  user_data 
)

Iterate over all key/value-pair of the collection attributes.

Calls specified function for each key/value-pair of the attribute list.

void function (const char *key, const char *value, void *user_data);

Parameters
collthe xmmsv_coll_t.
funcfunction that is called for each key/value-pair
user_dataextra data passed to func

Definition at line 538 of file coll.c.

◆ xmmsv_coll_attribute_get()

int xmmsv_coll_attribute_get ( xmmsv_coll_t coll,
const char *  key,
char **  value 
)

Retrieve the value of the attribute of the given collection.

The return value is 1 if the attribute was found and 0 otherwise. The value of the attribute is owned by the collection and must not be freed by the caller.

Parameters
collThe collection to retrieve the attribute from.
keyThe name of the attribute.
valueThe value of the attribute if found (owned by the collection).
Returns
1 if the attribute was found, 0 otherwise

Definition at line 498 of file coll.c.

Referenced by bind_all_references(), and xmms_collection_get_int_attr().

◆ xmmsv_coll_attribute_remove()

int xmmsv_coll_attribute_remove ( xmmsv_coll_t coll,
const char *  key 
)

Remove an attribute from the given collection.

The return value indicated whether the attribute was found (and removed)

Parameters
collThe collection to remove the attribute from.
keyThe name of the attribute to remove.
Returns
1 upon success, 0 otherwise

Definition at line 481 of file coll.c.

◆ xmmsv_coll_attribute_set()

void xmmsv_coll_attribute_set ( xmmsv_coll_t coll,
const char *  key,
const char *  value 
)

Set an attribute in the given collection.

Parameters
collThe collection in which to set the attribute.
keyThe name of the attribute to set.
valueThe value of the attribute.

Definition at line 460 of file coll.c.

Referenced by xmms_collection_set_int_attr(), and xmmsv_coll_universe().

◆ xmmsv_coll_attributes_get()

xmmsv_t* xmmsv_coll_attributes_get ( xmmsv_coll_t coll)

Definition at line 445 of file coll.c.

◆ xmmsv_coll_get_idlist()

const int32_t* xmmsv_coll_get_idlist ( xmmsv_coll_t coll)

Return the list of ids stored in the collection.

The list is owned by the collection. Note that this must not be confused with the content of the collection, which must be queried using xmmsc_coll_query_ids!

Also note that this function is deprecated (use xmmsv_coll_idlist_get instead) and that changes to the returned array will be ignored. The array is also not updated when the idlist is changed using the supplied functions. Additionally every call to this function allocates a new array, so calling it repetitively will be a performance penalty.

Parameters
collThe collection to consider.
Returns
The 0-terminated list of ids.

Definition at line 390 of file coll.c.

◆ xmmsv_coll_get_type()

xmmsv_coll_type_t xmmsv_coll_get_type ( xmmsv_coll_t coll)

Return the type of the collection.

Parameters
collThe collection to consider.
Returns
The xmmsv_coll_type_t of the collection, or -1 if invalid.

Definition at line 367 of file coll.c.

Referenced by bind_all_references().

◆ xmmsv_coll_idlist_append()

int xmmsv_coll_idlist_append ( xmmsv_coll_t coll,
int  id 
)

Append a value to the idlist.

Parameters
collThe collection to update.  
idThe id to append to the idlist.
Returns
TRUE on success, false otherwise.

Definition at line 252 of file coll.c.

◆ xmmsv_coll_idlist_clear()

int xmmsv_coll_idlist_clear ( xmmsv_coll_t coll)

Empties the idlist.

Parameters
collThe collection to update.
Returns
TRUE on success, false otherwise.

Definition at line 309 of file coll.c.

◆ xmmsv_coll_idlist_get()

xmmsv_t* xmmsv_coll_idlist_get ( xmmsv_coll_t coll)

Return the list of ids stored in the collection.

This function does not increase the refcount of the list, the reference is still owned by the collection.

Note that this must not be confused with the content of the collection, which must be queried using xmmsc_coll_query_ids!

Parameters
collThe collection to consider.
Returns
The 0-terminated list of ids.

Definition at line 429 of file coll.c.

◆ xmmsv_coll_idlist_get_index()

int xmmsv_coll_idlist_get_index ( xmmsv_coll_t coll,
int  index,
int32_t *  val 
)

Retrieves the value at the given position in the idlist.

Parameters
collThe collection to update.
indexThe position of the value to retrieve.
valThe pointer at which to store the found value.
Returns
TRUE on success, false otherwise.

Definition at line 324 of file coll.c.

◆ xmmsv_coll_idlist_get_size()

size_t xmmsv_coll_idlist_get_size ( xmmsv_coll_t coll)

Get the size of the idlist.

Parameters
collThe collection to update.
Returns
The size of the idlist.

Definition at line 352 of file coll.c.

Referenced by xmmsv_coll_get_idlist().

◆ xmmsv_coll_idlist_insert()

int xmmsv_coll_idlist_insert ( xmmsv_coll_t coll,
int  index,
int  id 
)

Insert a value at a given position in the idlist.

Parameters
collThe collection to update.  
idThe id to insert in the idlist.  
indexThe position at which to insert the value.
Returns
TRUE on success, false otherwise.

Definition at line 267 of file coll.c.

◆ xmmsv_coll_idlist_move()

int xmmsv_coll_idlist_move ( xmmsv_coll_t coll,
int  index,
int  newindex 
)

Move a value of the idlist to a new position.

Parameters
collThe collection to update.
indexThe index of the value to move.
newindexThe newindex to which to move the value.
Returns
TRUE on success, false otherwise.

Definition at line 282 of file coll.c.

◆ xmmsv_coll_idlist_remove()

int xmmsv_coll_idlist_remove ( xmmsv_coll_t coll,
int  index 
)

Remove the value at a given index from the idlist.

Parameters
collThe collection to update.
indexThe index at which to remove the value.
Returns
TRUE on success, false otherwise.

Definition at line 296 of file coll.c.

◆ xmmsv_coll_idlist_set_index()

int xmmsv_coll_idlist_set_index ( xmmsv_coll_t coll,
int  index,
int32_t  val 
)

Sets the value at the given position in the idlist.

Parameters
collThe collection to update.
indexThe position of the value to set.
valThe new value.
Returns
TRUE on success, false otherwise.

Definition at line 339 of file coll.c.

◆ xmmsv_coll_new()

xmmsv_coll_t* xmmsv_coll_new ( xmmsv_coll_type_t  type)

Allocate a new collection of the given type.

The pointer will have to be deallocated using xmmsv_coll_unref.

Parameters
typethe xmmsv_coll_type_t specifying the type of collection to create.
Returns
a pointer to the newly created collection, or NULL if the type is invalid.

Definition at line 78 of file coll.c.

Referenced by xmmsv_coll_universe().

◆ xmmsv_coll_operands_get()

xmmsv_t* xmmsv_coll_operands_get ( xmmsv_coll_t coll)

Definition at line 437 of file coll.c.

◆ xmmsv_coll_ref()

xmmsv_coll_t* xmmsv_coll_ref ( xmmsv_coll_t coll)

Increases the references for the xmmsv_coll_t.

Parameters
collthe collection to reference.
Returns
coll

Definition at line 61 of file coll.c.

Referenced by xmms_collection_update_pointer(), and xmmsv_coll_new().

◆ xmmsv_coll_remove_operand()

void xmmsv_coll_remove_operand ( xmmsv_coll_t coll,
xmmsv_coll_t op 
)

Remove all the occurences of the operand in the given collection.

Parameters
collThe collection to remove the operand from.
opThe operand to remove.

Definition at line 226 of file coll.c.

◆ xmmsv_coll_set_idlist()

void xmmsv_coll_set_idlist ( xmmsv_coll_t coll,
int  ids[] 
)

Set the list of ids in the given collection.

The list must be 0-terminated. Note that the idlist is only relevant for idlist collections.

Parameters
collthe collection to modify.
idsthe 0-terminated list of ids to store in the collection.

Definition at line 161 of file coll.c.

◆ xmmsv_coll_universe()

xmmsv_coll_t* xmmsv_coll_universe ( void  )

Return a collection referencing the whole media library, that is a reference to the "All Media" collection.

The returned structure must be unref'd using xmmsv_coll_unref after usage.

Returns
a collection referring to the "All Media" collection.

Definition at line 555 of file coll.c.

◆ xmmsv_coll_unref()

void xmmsv_coll_unref ( xmmsv_coll_t coll)

Decreases the references for the xmmsv_coll_t When the number of references reaches 0 it will be freed and all its operands unreferenced as well.

Parameters
collthe collection to unref.

Definition at line 140 of file coll.c.