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...

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_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_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. 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_result	The result of the fetch request
context	User 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_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.

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_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.

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

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.

Parameters

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.

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_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.

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_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.

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_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.

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

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.

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_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.

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_ROUTING may not be specified as only target topic types may be selected.

Parameters

fetch_request	Fetch request to mutate
topic_types	Topic types to be selected
error	Populated 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_request	Fetch request to mutate
error	Populated 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_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.

Parameters

fetch_request	Fetch request to mutate
error	Populated 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_request	Fetch request to mutate
datatype	Pointer to the datatype of the required values
error	Populated 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_request	fetch request to mutate
error	Populated 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_result Fetch 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_result Fetch 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_result Fetch 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_result Fetch 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_result topic result to be freed

char* diffusion_topic_result_get_path ( const DIFFUSION_TOPIC_RESULT_T * topic_result )

Returns the topic path.

Parameters

topic_result topic 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_result the 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_result topic 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_result topic 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.

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation