Diffusion C API  6.4.3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
fetch-request.h File Reference

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_Tdiffusion_fetch_result_get_topic_results (const DIFFUSION_FETCH_RESULT_T *fetch_result)
 Returns a results LIST_T of DIFFUSION_TOPIC_RESULT_Ts 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...
 
int diffusion_fetch_result_size (const DIFFUSION_FETCH_RESULT_T *fetch_result)
 The number of elements in the fetch result. More...
 
int diffusion_fetch_result_is_empty (const DIFFUSION_FETCH_RESULT_T *fetch_result)
 Returns 1 (true) if the result contains zero elements. 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_Tdiffusion_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, int32_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, int32_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...
 
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. More...
 
void diffusion_fetch_request_fetch (SESSION_T *session, DIFFUSION_FETCH_REQUEST_PARAMS_T params)
 Sends a fetch request to the server. More...
 

Detailed Description

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 Documentation

typedef int(* on_fetch_result_cb)(const DIFFUSION_FETCH_RESULT_T *fetch_result, void *context)

Callback when a fetch request has returned a result.

Parameters
fetch_resultThe result of the fetch request
contextUser supplied context passed in from DIFFUSION_FETCH_REQUEST_PARAMS_T
Returns
HANDLERS_SUCCESS or HANDLER_FAILURE.

Function Documentation

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.

Parameters
fetch_requestFetch request to mutate
topic_pathThe topic path after which results are to be returned
errorPopulated if an error occurs. Can be NULL.
Returns
true if the fetch request was successfully mutated. False, otherwise. In this case, if a non-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.

Parameters
fetch_requestFetch request to mutate
topic_pathThe topic path before which results are to be returned
errorPopulated if an error occurs. Can be NULL.
Returns
true if the fetch request was successfully mutated. False, otherwise. In this case, if a non-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.

Parameters
sessionThe session handle. If NULL, the function returns immediately.
paramsParameters 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.

Parameters
fetch_requestFetch request to mutate
numberThe maximum number of results to return from the start of the range. Must be non-negative.
errorPopulated if an error occurs. Can be NULL.
Returns
true if the fetch request was successfully mutated. False, otherwise. In this case, if a non-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.

Parameters
fetch_requestFetch request to mutate
topic_pathThe topic path from which results are to be returned
errorPopulated if an error occurs. Can be NULL.
Returns
true if the fetch request was successfully mutated. False, otherwise. In this case, if a non-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.

Parameters
fetch_requestFetch request to mutate
numberThe maximum number of results to return from the end of the range. Must be non-negative.
errorPopulated if an error occurs. Can be NULL.
Returns
true if the fetch request was successfully mutated. False, otherwise. In this case, if a non-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.

Parameters
fetch_requestFetch request to mutate
deep_branch_depthThe number of parts in the root path of a branch for it to be considered deep
deep_branch_limitThe maximum number of results to return for each deep branch
errorPopulated if an error occurs. Can be NULL.
Returns
true if the fetch request was successfully mutated. False, otherwise. In this case, if a non-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.

Parameters
maximumthe maximum size of the result set in bytes.
Returns
true if the fetch request was successfully mutated. False, otherwise. In this case, if a non-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.

Parameters
fetch_requestFetch request to mutate
topic_pathThe topic path before which results are to be returned
errorPopulated if an error occurs. Can be NULL.
Returns
true if the fetch request was successfully mutated. False, otherwise. In this case, if a non-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.

Parameters
fetch_requestFetch request to mutate
topic_typesTopic types to be selected
errorPopulated if an error occurs. Can be NULL.
Returns
true if the fetch request was successfully mutated. False, otherwise. In this case, if a non-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.

Parameters
fetch_requestFetch request to mutate
errorPopulated if an error occurs. Can be NULL.
Returns
true if the fetch request was successfully mutated. False, otherwise. In this case, if a non-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.

Parameters
fetch_requestFetch request to mutate
datatypePointer to the datatype of the required values
errorPopulated if an error occurs. Can be NULL.
Returns
true if the fetch request was successfully mutated. False, otherwise. In this case, if a non-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.

Parameters
fetch_requestfetch request to mutate
errorPopulated if an error occurs. Can be NULL.
Returns
true if the fetch request was successfully mutated. False, otherwise. In this case, if a non-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_Ts 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.

Parameters
fetch_resultFetch result to retrieve the topic results from
Returns
a list of topic results, each representing a result single topic selected by the fetch operation. NULL, if the fetch result is NULL.
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.

Parameters
fetch_resultFetch result to query
Returns
true if a limit was specified and more results could have been returned, otherwise false
int diffusion_fetch_result_is_empty ( const DIFFUSION_FETCH_RESULT_T fetch_result)

Returns 1 (true) if the result contains zero elements.

Parameters
fetch_resultFetch result to query
Returns
1 if fetch result list is empty, 0 otherwise. -1 is returned if the fetch result is NULL.
int diffusion_fetch_result_size ( const DIFFUSION_FETCH_RESULT_T fetch_result)

The number of elements in the fetch result.

Parameters
fetch_resultFetch result to query
Returns
the size of the fetch result list. -1 is returned if the fetch result is NULL.
void diffusion_topic_result_free ( DIFFUSION_TOPIC_RESULT_T topic_result)

Free a memory allocated DIFFUSION_TOPIC_RESULT_T.

Parameters
topic_resulttopic result to be freed
char* diffusion_topic_result_get_path ( const DIFFUSION_TOPIC_RESULT_T topic_result)

Returns the topic path.

Parameters
topic_resulttopic result to retrieve the topic path from
Returns
the topic path. NULL, if 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.

Parameters
topic_resultthe topic result to retrieve the topic specification from
Returns
the topic specification. NULL, if topic_result is NULL.
TOPIC_TYPE_T diffusion_topic_result_get_topic_type ( const DIFFUSION_TOPIC_RESULT_T topic_result)

Returns the topic type.

Parameters
topic_resulttopic result to retrieve the topic type from
Returns
the topic type. -1, if 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.

Parameters
topic_resulttopic result to retrieve the value from
Returns
the topic value or NULL if none available. If topic_result is NULL, NULL will also be returned.