The query API allows for finding an ink data object in a list. If you find yourself creating data structures that are a simple mapping from an identifier to an ink data handle, using the query API may be a simpler option.
This is a function from a hypothetical chat room user interface that has a list of participants and shows feedback if they are currently typing. Rather than maintaining a data structure mapping from username to an associated inkd, it uses ink_query to find the inkd that needs updated.
You can match against the fields of an inkd with the following functions:
The field types that can be queried is a subset of the types that can be set on a data object. You cannot match against an ink_image or a float.
If multiple fields are set on a query, an inkd will only match if all of the fields match.
A note on ink_query_charp: The ink_query may (or may not) continue to use the memory pointed to by the value argument. Therefore, any string pointed to by ink_query_charpmust not be modified or deallocated until afterink_query_deinit is called. (This also applies to the C++ overload of Query::match_string that takes a const char*.)
Executing the query
After setting fields on your query, you may use Get, Maybe Get, or Remove.
Return the first matching data entry in the given list.
If there is no match, a new one entry will be appended to the list. It will be initialized with fields set so that it matches the query.
Maybe Get is identical to get except that it will not append a new data entry.
Remove all matching data objects from a list.
This is essentially the same as calling inkd_remove on the result of ink_query_maybe_get for as long as the result is not null. (Or the equivalent calls in your language of choice.)
Initialize / Deinitialize
To reduce heap allocations ink_query is stored on the stack. Call ink_query_init to initialize the memory.
The ink_query may make allocations or increment reference counts internally. Therefore, ink_query_deinit must be called after the ink_query is no longer needed.
// Do stuff
(For C++ and other language bindings, this is handled automatically.)