Diffusion C API
6.2.7
|
A fetch request. More...
Data Structures | |
struct | diffusion_fetch_request_params_s |
Structure describing a fetch request. More... | |
Typedefs | |
typedef struct DIFFUSION_FETCH_REQUEST_T | DIFFUSION_FETCH_REQUEST_T |
An opaque fetch request struct. | |
typedef struct DIFFUSION_FETCH_RESULT_T | DIFFUSION_FETCH_RESULT_T |
An opaque fetch result struct. | |
typedef struct DIFFUSION_TOPIC_RESULT_T | DIFFUSION_TOPIC_RESULT_T |
An opaque topic result struct. | |
typedef int(* | on_fetch_result_cb )(const DIFFUSION_FETCH_RESULT_T *fetch_result, void *context) |
Callback when a fetch request has returned a result. More... | |
typedef struct diffusion_fetch_request_params_s | DIFFUSION_FETCH_REQUEST_PARAMS_T |
Structure describing a fetch request. | |
Functions | |
LIST_T * | diffusion_fetch_result_get_topic_results (const DIFFUSION_FETCH_RESULT_T *fetch_result) |
Returns a results LIST_T of DIFFUSION_TOPIC_RESULT_T s from the fetch operation. More... | |
bool | diffusion_fetch_result_has_more (const DIFFUSION_FETCH_RESULT_T *fetch_result) |
Indicates whether the fetch could have returned more results if it had not been constrained by the diffusion_fetch_request_first or diffusion_fetch_request_last limits. More... | |
char * | diffusion_topic_result_get_path (const DIFFUSION_TOPIC_RESULT_T *topic_result) |
Returns the topic path. More... | |
TOPIC_TYPE_T | diffusion_topic_result_get_topic_type (const DIFFUSION_TOPIC_RESULT_T *topic_result) |
Returns the topic type. More... | |
DIFFUSION_VALUE_T * | diffusion_topic_result_get_value (const DIFFUSION_TOPIC_RESULT_T *topic_result) |
Returns the topic value. More... | |
TOPIC_SPECIFICATION_T * | diffusion_topic_result_get_specification (const DIFFUSION_TOPIC_RESULT_T *topic_result) |
Returns the topic specification. More... | |
void | diffusion_topic_result_free (DIFFUSION_TOPIC_RESULT_T *topic_result) |
Free a memory allocated DIFFUSION_TOPIC_RESULT_T . More... | |
bool | diffusion_fetch_request_from (const DIFFUSION_FETCH_REQUEST_T *fetch_request, const char *topic_path, DIFFUSION_API_ERROR *error) |
Specifies a logical start point within the topic tree. More... | |
bool | diffusion_fetch_request_after (const DIFFUSION_FETCH_REQUEST_T *fetch_request, const char *topic_path, DIFFUSION_API_ERROR *error) |
Specifies a logical start point within the topic tree. More... | |
bool | diffusion_fetch_request_to (const DIFFUSION_FETCH_REQUEST_T *fetch_request, const char *topic_path, DIFFUSION_API_ERROR *error) |
Specifies a logical end point within the topic tree. More... | |
bool | diffusion_fetch_request_before (const DIFFUSION_FETCH_REQUEST_T *fetch_request, const char *topic_path, DIFFUSION_API_ERROR *error) |
Specifies a logical end point within the topic tree. More... | |
bool | diffusion_fetch_request_topic_types (const DIFFUSION_FETCH_REQUEST_T *fetch_request, SET_T *topic_types, DIFFUSION_API_ERROR *error) |
Specifies that only topics of the specified topic types should be returned. More... | |
bool | diffusion_fetch_request_with_values (const DIFFUSION_FETCH_REQUEST_T *fetch_request, DIFFUSION_DATATYPE *datatype, DIFFUSION_API_ERROR *error) |
Specifies that values should be returned for selected topics, and constraining the selection to only those topics with a data type compatible with the specified value datatype. More... | |
bool | diffusion_fetch_request_without_values (const DIFFUSION_FETCH_REQUEST_T *fetch_request, DIFFUSION_API_ERROR *error) |
Specifies that the fetch request should not return values. More... | |
bool | diffusion_fetch_request_with_properties (const DIFFUSION_FETCH_REQUEST_T *fetch_request, DIFFUSION_API_ERROR *error) |
Specifies that all properties associated with each topic's specification should be returned. More... | |
bool | diffusion_fetch_request_first (const DIFFUSION_FETCH_REQUEST_T *fetch_request, uint32_t number, DIFFUSION_API_ERROR *error) |
Specifies a maximum number of topic results to be returned from the start of the required range. More... | |
bool | diffusion_fetch_request_last (const DIFFUSION_FETCH_REQUEST_T *fetch_request, uint32_t number, DIFFUSION_API_ERROR *error) |
Specifies a maximum number of topic results to be returned from the end of the required range. More... | |
bool | diffusion_fetch_request_maximum_result_size (const DIFFUSION_FETCH_REQUEST_T *fetch_request, uint32_t maximum, DIFFUSION_API_ERROR *error) |
Specifies the maximum data size of the result set. More... | |
void | diffusion_fetch_request_fetch (SESSION_T *session, DIFFUSION_FETCH_REQUEST_PARAMS_T params) |
Sends a fetch request to the server. More... | |
A fetch request.
This defines a fetch request to be made to the server. A new request can be created using the diffusion_fetch_request_init
function and modified to specify a range of topics and/or various levels of detail.
typedef int(* on_fetch_result_cb)(const DIFFUSION_FETCH_RESULT_T *fetch_result, void *context) |
Callback when a fetch request has returned a result.
fetch_result | The result of the fetch request |
context | User supplied context passed in from DIFFUSION_FETCH_REQUEST_PARAMS_T |
bool diffusion_fetch_request_after | ( | const DIFFUSION_FETCH_REQUEST_T * | fetch_request, |
const char * | topic_path, | ||
DIFFUSION_API_ERROR * | error | ||
) |
Specifies a logical start point within the topic tree.
If specified, only results for topics with a path that is lexically 'after' the specified path will be returned.
This is the non inclusive equivalent of diffusion_fetch_request_from
and if used will override any previous diffusion_fetch_request_from
or diffusion_fetch_request_after
constraint.
fetch_request | Fetch request to mutate |
topic_path | The topic path after which results are to be returned |
error | Populated if an error occurs. Can be NULL. |
DIFFUSION_API_ERROR
pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free
. bool diffusion_fetch_request_before | ( | const DIFFUSION_FETCH_REQUEST_T * | fetch_request, |
const char * | topic_path, | ||
DIFFUSION_API_ERROR * | error | ||
) |
Specifies a logical end point within the topic tree.
If specified, only results for topics with a path that is lexically 'before' the specified path will be returned.
This is the non inclusive equivalent of diffusion_fetch_request_to
and if used will override any previous diffusion_fetch_request_to
or diffusion_fetch_request_before
constraint.
fetch_request | Fetch request to mutate |
topic_path | The topic path before which results are to be returned |
error | Populated if an error occurs. Can be NULL. |
DIFFUSION_API_ERROR
pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free
. void diffusion_fetch_request_fetch | ( | SESSION_T * | session, |
DIFFUSION_FETCH_REQUEST_PARAMS_T | params | ||
) |
Sends a fetch request to the server.
Results are returned for all topics matching the selector that satisfy the request constraints within any range defined by diffusion_fetch_request_from
/diffusion_fetch_request_after
and/or diffusion_fetch_request_to
/diffusion_fetch_request_before
.
session | The session handle. If NULL, the function returns immediately. |
params | Parameters describing the fetch request and callbacks handlers which may be invoked in response. |
bool diffusion_fetch_request_first | ( | const DIFFUSION_FETCH_REQUEST_T * | fetch_request, |
uint32_t | number, | ||
DIFFUSION_API_ERROR * | error | ||
) |
Specifies a maximum number of topic results to be returned from the start of the required range.
If this is not specified, the number of results returned will only be limited by other constraints of the request.
This should be used to retrieve results in manageable batches and prevent very large result sets.
If there are potentially more results that would satisfy the other constraints then the fetch result will indicate so via the diffusion_fetch_result_has_more
function.
Either this or diffusion_fetch_request_last
may be specified. This will therefore override any previous diffusion_fetch_request_last
or diffusion_fetch_request_first
constraint.
fetch_request | Fetch request to mutate |
number | The maximum number of results to return from the start of the range |
error | Populated if an error occurs. Can be NULL. |
DIFFUSION_API_ERROR
pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free
. bool diffusion_fetch_request_from | ( | const DIFFUSION_FETCH_REQUEST_T * | fetch_request, |
const char * | topic_path, | ||
DIFFUSION_API_ERROR * | error | ||
) |
Specifies a logical start point within the topic tree.
If specified, only results for topics with a path that is lexically equal to or 'after' the specified path will be returned.
This is the inclusive equivalent of diffusion_fetch_request_after
and if used will override any previous diffusion_fetch_request_after
or diffusion_fetch_request_from
constraint.
fetch_request | Fetch request to mutate |
topic_path | The topic path from which results are to be returned |
error | Populated if an error occurs. Can be NULL. |
DIFFUSION_API_ERROR
pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free
. bool diffusion_fetch_request_last | ( | const DIFFUSION_FETCH_REQUEST_T * | fetch_request, |
uint32_t | number, | ||
DIFFUSION_API_ERROR * | error | ||
) |
Specifies a maximum number of topic results to be returned from the end of the required range.
This is similar to diffusion_fetch_request_first
except that the specified number of results are returned from the end of the range. This is useful for paging backwards through a range of topics. The results will be returned in topic path order (not reverse order).
Either this or diffusion_fetch_request_first
may be specified. This will therefore override any previous diffusion_fetch_request_first
or diffusion_fetch_request_last
constraint.
fetch_request | Fetch request to mutate |
number | The maximum number of results to return from the end of the range |
error | Populated if an error occurs. Can be NULL. |
DIFFUSION_API_ERROR
pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free
. bool diffusion_fetch_request_maximum_result_size | ( | const DIFFUSION_FETCH_REQUEST_T * | fetch_request, |
uint32_t | maximum, | ||
DIFFUSION_API_ERROR * | error | ||
) |
Specifies the maximum data size of the result set.
This may be used to constrain the size of the result.
maximum | the maximum size of the result set in bytes. |
DIFFUSION_API_ERROR
pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free
. bool diffusion_fetch_request_to | ( | const DIFFUSION_FETCH_REQUEST_T * | fetch_request, |
const char * | topic_path, | ||
DIFFUSION_API_ERROR * | error | ||
) |
Specifies a logical end point within the topic tree.
If specified, only results for topics with a path that is lexically equal to or 'before' the specified path will be returned.
This is the inclusive equivalent of diffusion_fetch_request_before
and if used will override any previous diffusion_fetch_request_before
or diffusion_fetch_request_to
constraint.
fetch_request | Fetch request to mutate |
topic_path | The topic path before which results are to be returned |
error | Populated if an error occurs. Can be NULL. |
DIFFUSION_API_ERROR
pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free
. bool diffusion_fetch_request_topic_types | ( | const DIFFUSION_FETCH_REQUEST_T * | fetch_request, |
SET_T * | topic_types, | ||
DIFFUSION_API_ERROR * | error | ||
) |
Specifies that only topics of the specified topic types should be returned.
If this is not specified, all types will be returned (unless constrained by diffusion_fetch_request_with_values
).
This may be used instead to further constrain the results when using diffusion_fetch_request_with_values
. For example, you can specify DATATYPE_JSON
to diffusion_fetch_request_with_values
then specify TOPIC_TYPE_JSON
here to ensure that only JSON topics are returned and not those topics that are logically value subtypes of JSON (e.g. TOPIC_TYPE_STRING
).
If diffusion_fetch_request_with_values
has been specified then the types specified here must be compatible with the value datatype specified.
TOPIC_TYPE_SLAVE
or TOPIC_TYPE_ROUTING
may not be specified as only target topic types may be selected.
fetch_request | Fetch request to mutate |
topic_types | Topic types to be selected |
error | Populated if an error occurs. Can be NULL. |
DIFFUSION_API_ERROR
pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free
. bool diffusion_fetch_request_with_properties | ( | const DIFFUSION_FETCH_REQUEST_T * | fetch_request, |
DIFFUSION_API_ERROR * | error | ||
) |
Specifies that all properties associated with each topic's specification should be returned.
fetch_request | Fetch request to mutate |
error | Populated if an error occurs. Can be NULL. |
DIFFUSION_API_ERROR
pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free
. bool diffusion_fetch_request_with_values | ( | const DIFFUSION_FETCH_REQUEST_T * | fetch_request, |
DIFFUSION_DATATYPE * | datatype, | ||
DIFFUSION_API_ERROR * | error | ||
) |
Specifies that values should be returned for selected topics, and constraining the selection to only those topics with a data type compatible with the specified value datatype.
If datatype
is NULL, values will be returned for all topic types (unless constrained by diffusion_fetch_request_topic_types
).
The specified value constrains the topic types. So, any topic types specified in a previous call to diffusion_fetch_request_topic_types
that cannot be read as the specified datatype will be removed from the list of topic types.
fetch_request | Fetch request to mutate |
datatype | Pointer to the datatype of the required values |
error | Populated if an error occurs. Can be NULL. |
DIFFUSION_API_ERROR
pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free
. bool diffusion_fetch_request_without_values | ( | const DIFFUSION_FETCH_REQUEST_T * | fetch_request, |
DIFFUSION_API_ERROR * | error | ||
) |
Specifies that the fetch request should not return values.
fetch_request | fetch request to mutate |
error | Populated if an error occurs. Can be NULL. |
DIFFUSION_API_ERROR
pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free
. LIST_T* diffusion_fetch_result_get_topic_results | ( | const DIFFUSION_FETCH_RESULT_T * | fetch_result | ) |
Returns a results LIST_T
of DIFFUSION_TOPIC_RESULT_T
s from the fetch operation.
The LIST_T
returned from this function is a copy, and as such should be freed with list_free(topic_results_list, (void (*)(void *))diffusion_topic_result_free)
.
Results are always returned in path order.
fetch_result | Fetch result to retrieve the topic results from |
bool diffusion_fetch_result_has_more | ( | const DIFFUSION_FETCH_RESULT_T * | fetch_result | ) |
Indicates whether the fetch could have returned more results if it had not been constrained by the diffusion_fetch_request_first
or diffusion_fetch_request_last
limits.
fetch_result | Fetch result to query |
void diffusion_topic_result_free | ( | DIFFUSION_TOPIC_RESULT_T * | topic_result | ) |
Free a memory allocated DIFFUSION_TOPIC_RESULT_T
.
topic_result | topic result to be freed |
char* diffusion_topic_result_get_path | ( | const DIFFUSION_TOPIC_RESULT_T * | topic_result | ) |
Returns the topic path.
topic_result | topic result to retrieve the topic path from |
topic_result
is NULL. TOPIC_SPECIFICATION_T* diffusion_topic_result_get_specification | ( | const DIFFUSION_TOPIC_RESULT_T * | topic_result | ) |
Returns the topic specification.
If the request specified diffusion_fetch_request_with_properties
, the result reflect the topic's specification and can be used to create an identical topic. If the request did not specify diffusion_fetch_request_with_properties
, the specification's property map will be empty.
topic_result | the topic result to retrieve the topic specification from |
topic_result
is NULL. TOPIC_TYPE_T diffusion_topic_result_get_topic_type | ( | const DIFFUSION_TOPIC_RESULT_T * | topic_result | ) |
Returns the topic type.
topic_result | topic result to retrieve the topic type from |
topic_result
is NULL. DIFFUSION_VALUE_T* diffusion_topic_result_get_value | ( | const DIFFUSION_TOPIC_RESULT_T * | topic_result | ) |
Returns the topic value.
This will only return a value if the fetch request specified diffusion_fetch_request_with_values
and the topic actually had a value. For topics that have no value this will return null.
topic_result | topic result to retrieve the value from |
topic_result
is NULL, NULL will also be returned.