![]() |
Diffusion C API 6.11.5
|
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. | |
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. | |
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. | |
int | diffusion_fetch_result_size (const DIFFUSION_FETCH_RESULT_T *fetch_result) |
The number of elements in the fetch result. | |
int | diffusion_fetch_result_is_empty (const DIFFUSION_FETCH_RESULT_T *fetch_result) |
Returns 1 (true) if the result contains zero elements. | |
char * | diffusion_topic_result_get_path (const DIFFUSION_TOPIC_RESULT_T *topic_result) |
Returns the topic path. | |
TOPIC_TYPE_T | diffusion_topic_result_get_topic_type (const DIFFUSION_TOPIC_RESULT_T *topic_result) |
Returns the topic type. | |
DIFFUSION_VALUE_T * | diffusion_topic_result_get_value (const DIFFUSION_TOPIC_RESULT_T *topic_result) |
Returns the topic value. | |
TOPIC_SPECIFICATION_T * | diffusion_topic_result_get_specification (const DIFFUSION_TOPIC_RESULT_T *topic_result) |
Returns the topic specification. | |
void | diffusion_topic_result_free (DIFFUSION_TOPIC_RESULT_T *topic_result) |
Free a memory allocated DIFFUSION_TOPIC_RESULT_T . | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
bool | diffusion_fetch_request_with_unpublished_delayed_topics (const DIFFUSION_FETCH_REQUEST_T *fetch_request, DIFFUSION_API_ERROR *error) |
Include the details of reference topics that are not yet published. | |
bool | diffusion_fetch_request_first (const DIFFUSION_FETCH_REQUEST_T *fetch_request, int32_t number, DIFFUSION_API_ERROR *error) |
Specifies a maximum number of topic results to be returned from the start of the required range. | |
bool | diffusion_fetch_request_last (const DIFFUSION_FETCH_REQUEST_T *fetch_request, int32_t number, DIFFUSION_API_ERROR *error) |
Specifies a maximum number of topic results to be returned from the end of the required range. | |
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. | |
bool | diffusion_fetch_request_limit_deep_branches (const DIFFUSION_FETCH_REQUEST_T *fetch_request, uint32_t deep_branch_depth, uint32_t deep_branch_limit, DIFFUSION_API_ERROR *error) |
Specifies a limit on the number of results returned for each deep branch. | |
void | diffusion_fetch_request_fetch (SESSION_T *session, DIFFUSION_FETCH_REQUEST_PARAMS_T params) |
Sends a fetch request to the server. | |
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, |
int32_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.
Zero can be supplied to return no results. Such a request can be used together with diffusion_fetch_result_has_more
to query whether there are topics that match the selector provided to diffusion_fetch_request_fetch
without retrieving the details of any of the topics. To retrieve unlimited topics use INT_MAX
which is the default value.
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. Must be non-negative. |
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, |
int32_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.
Zero can be supplied to return no results. Such a request can be used together with diffusion_fetch_result_has_more
to query whether there are topics that match the selector provided to diffusion_fetch_request_fetch
without retrieving the details of any of the topics. To retrieve unlimited topics use INT_MAX
which is the default value.
fetch_request | Fetch request to mutate |
number | The maximum number of results to return from the end of the range. Must be non-negative. |
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_limit_deep_branches | ( | const DIFFUSION_FETCH_REQUEST_T * | fetch_request, |
uint32_t | deep_branch_depth, | ||
uint32_t | deep_branch_limit, | ||
DIFFUSION_API_ERROR * | error | ||
) |
Specifies a limit on the number of results returned for each deep branch.
A deep branch has a root path that has a number of parts equal to the deep_branch_depth
parameter. The deep_branch_limit
specifies the maximum number of results for each deep branch.
This method is particularly useful for incrementally exploring a topic tree from the root, allowing a breadth-first search strategy.
For example, given a topic tree containing the topics with the following paths:
x/0 x/x/1 x/x/x/2 y/y/y/y/3 y/y/y/4 z/5 z/z/6
Then
DIFFUSION_FETCH_REQUEST_T *fetch_request = diffusion_fetch_request_init(session); diffusion_fetch_request_limit_deep_branches(fetch_request, 1, 1, NULL); DIFFUSION_FETCH_REQUEST_PARAMS_T params = { .topic_selector = "?.//", .fetch_request = fetch_request, .on_fetch_result = on_fetch_result }; diffusion_fetch_request_fetch(session, params);
will return results with the paths x/0
, y/y/y/y/3
, and z/5
. The application can then determine the roots of the tree are x
, y
, and z
.
The deep_branch_limit
parameter can usefully be set to 0
. For example, given the same example topic tree,
DIFFUSION_FETCH_REQUEST_T *fetch_request = diffusion_fetch_request_init(session); diffusion_fetch_request_limit_deep_branches(fetch_request, 3, 0, NULL); DIFFUSION_FETCH_REQUEST_PARAMS_T params = { .topic_selector = "?.//", .fetch_request = fetch_request, .on_fetch_result = on_fetch_result }; diffusion_fetch_request_fetch(session, params);
will only return results having paths with fewer than three parts; namely x/0
, and z/5
.
The fetch result does not indicate whether this option caused some results to be filtered from deep branches. It has no affect on the diffusion_fetch_result_has_more
result. If the result set contains deep_branch_limit
results for a particular deep branch, some topics from that branch may have been filtered.
fetch_request | Fetch request to mutate |
deep_branch_depth | The number of parts in the root path of a branch for it to be considered deep |
deep_branch_limit | The maximum number of results to return for each deep branch |
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.
fetch_request | Fetch request to mutate |
maximum | the maximum size of the result set in bytes. |
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_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.
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_unpublished_delayed_topics | ( | const DIFFUSION_FETCH_REQUEST_T * | fetch_request, |
DIFFUSION_API_ERROR * | error | ||
) |
Include the details of reference topics that are not yet published.
Topic views that use the delay by
clause create reference topics in an unpublished state. The topics are published once the delay time has expired. A topic in the unpublished state prevents a lower priority topic view from creating a reference topic with the same path.
A reference topic in the unpublished state which matches the query will only be included in the fetch results if the session has PATH_PERMISSION_READ_TOPIC permission for the reference's source topic as well as PATH_PERMISSION_READ_TOPIC permission for the reference topic. Requiring PATH_PERMISSION_READ_TOPIC permission for the source topic ensures less privileged sessions cannot derive information from the existence of the reference topic before the delay time has expired.
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 |
int diffusion_fetch_result_is_empty | ( | const DIFFUSION_FETCH_RESULT_T * | fetch_result | ) |
Returns 1
(true) if the result contains zero elements.
fetch_result | Fetch result to query |
NULL
. int diffusion_fetch_result_size | ( | const DIFFUSION_FETCH_RESULT_T * | fetch_result | ) |
The number of elements in the fetch result.
fetch_result | Fetch result to query |
NULL
. 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.