Typedefs
typedef enum KSI_AsyncHandleState_en	KSI_AsyncHandleState

typedef enum KSI_AsyncOption_en	KSI_AsyncOption

Enumerations
enum	KSI_AsyncHandleState_en { KSI_ASYNC_STATE_UNDEFINED = 0, KSI_ASYNC_STATE_WAITING_FOR_DISPATCH, KSI_ASYNC_STATE_WAITING_FOR_RESPONSE, KSI_ASYNC_STATE_RESPONSE_RECEIVED, KSI_ASYNC_STATE_ERROR }

enum	KSI_AsyncOption_en { KSI_ASYNC_OPT_CON_TIMEOUT = 0, KSI_ASYNC_OPT_RCV_TIMEOUT, KSI_ASYNC_OPT_SND_TIMEOUT, KSI_ASYNC_OPT_REQUEST_CACHE_SIZE, KSI_ASYNC_OPT_MAX_REQUEST_COUNT, __KSI_ASYNC_OPT_COUNT }

Functions
void	KSI_AsyncHandle_free (KSI_AsyncHandle *o)

int	KSI_AsyncAggregationHandle_new (KSI_CTX ctx, KSI_AggregationReq req, KSI_AsyncHandle **o)

KSI_AsyncHandle *	KSI_AsyncHandle_ref (KSI_AsyncHandle *o)

int	KSI_AsyncHandle_setRequestCtx (KSI_AsyncHandle o, void reqCtx, void(reqCtx_free)(void ))

int	KSI_AsyncHandle_getRequestCtx (const KSI_AsyncHandle o, const void *reqCtx)

int	KSI_AsyncHandle_getState (const KSI_AsyncHandle h, int state)

int	KSI_AsyncHandle_getError (const KSI_AsyncHandle h, int error)

int	KSI_AsyncHandle_getExtError (const KSI_AsyncHandle h, long ext)

int	KSI_AsyncHandle_getErrorMessage (const KSI_AsyncHandle h, KSI_Utf8String *msg)

int	KSI_AsyncHandle_getRequestId (const KSI_AsyncHandle h, KSI_uint64_t id)

int	KSI_AsyncHandle_getAggregationReq (const KSI_AsyncHandle h, KSI_AggregationReq *req)

int	KSI_AsyncHandle_getAggregationResp (const KSI_AsyncHandle h, KSI_AggregationResp *resp)

int	KSI_AsyncHandle_getSignature (const KSI_AsyncHandle h, KSI_Signature *signature)

void	KSI_AsyncClient_free (KSI_AsyncClient *c)

int	KSI_AbstractAsyncClient_new (KSI_CTX ctx, KSI_AsyncClient *c)

void	KSI_AsyncService_free (KSI_AsyncService *service)

int	KSI_SigningAsyncService_new (KSI_CTX ctx, KSI_AsyncService *service)

int	KSI_AsyncService_addRequest (KSI_AsyncService s, KSI_AsyncHandle handle)

int	KSI_AsyncService_run (KSI_AsyncService service, KSI_AsyncHandle handle, size_t waiting)

int	KSI_AsyncService_getPendingCount (KSI_AsyncService s, size_t count)

int	KSI_AsyncService_getReceivedCount (KSI_AsyncService s, size_t count)

int	KSI_AsyncService_setOption (KSI_AsyncService s, const KSI_AsyncOption option, void value)

int	KSI_AsyncService_getOption (const KSI_AsyncService s, const KSI_AsyncOption option, void value)

Detailed Description

The asynchronous API provides the ability to send KSI service requests in a non-blocking manner. As a drawback, it is not guaranteed that received responses are returned in the same order as the requests have been queued. However, you can associate each request with a private pointer. The interface incorporates two major parts:

KSI_AsyncService takes care of network transport. Added request does not launch the transfer automatically. To initiate processing of added requests you have to call KSI_AsyncService_run.
KSI_AsyncHandle is a request wrapper. It is possible to add multiple handles to the KSI_AsyncService at any time. A completed request (whether with a response, or an error status) can be accessed via KSI_AsyncService_run input parameter handle.

Typedef Documentation

◆ KSI_AsyncHandleState

typedef enum KSI_AsyncHandleState_en KSI_AsyncHandleState

Enum defining async handle state.

◆ KSI_AsyncOption

typedef enum KSI_AsyncOption_en KSI_AsyncOption

Enum defining async service options. Pay attention to the used parameter type.

See also: KSI_AsyncService_setOption for applying option values.; KSI_AsyncService_getOption for extracting option values.

Enumeration Type Documentation

◆ KSI_AsyncHandleState_en

enum KSI_AsyncHandleState_en

Enum defining async handle state.

Enumerator
KSI_ASYNC_STATE_UNDEFINED	The state of the request is undefined.
KSI_ASYNC_STATE_WAITING_FOR_DISPATCH	The request is cached in the output queue.
KSI_ASYNC_STATE_WAITING_FOR_RESPONSE	The request has been dispathed.
KSI_ASYNC_STATE_RESPONSE_RECEIVED	The response has been received and is ready to be read. This is the final state of a request. See also KSI_AsyncHandle_getAggregationResp for extracting aggregation response. KSI_AsyncHandle_getSignature for extracting KSI KSI Signature. KSI_AsyncHandle_free for cleaning up resources.
KSI_ASYNC_STATE_ERROR	An error has occured while the request was in process. This is the final state of a request. See also KSI_AsyncHandle_getError for reading the error code. KSI_AsyncHandle_free for cleaning up resources. KSI_AsyncService_addRequest for re-adding the request back into the request queue.

◆ KSI_AsyncOption_en

enum KSI_AsyncOption_en

Enum defining async service options. Pay attention to the used parameter type.

See also: KSI_AsyncService_setOption for applying option values.; KSI_AsyncService_getOption for extracting option values.

Enumerator

KSI_ASYNC_OPT_CON_TIMEOUT

Async connection timeout. Time interval between when network connection has been initiated and the point it has been established. Default setting is 10 sec.

Parameters

timeout Timeout in seconds. Paramer of type size_t.

See also: KSI_AsyncHandle_getState for the request state.; KSI_AsyncHandle_getError for the request error.

Note: In case of timeout, if there are any request that have not been responded yet, the request state will be set to KSI_ASYNC_STATE_ERROR and error KSI_NETWORK_CONNECTION_TIMEOUT.

KSI_ASYNC_OPT_RCV_TIMEOUT

Async request response receive timeout. Represents the time interval between when the request was sent out and a response has been received. Default setting is 10 sec.

Parameters

timeout Timeout in seconds. Paramer of type size_t.

See also: KSI_AsyncHandle_getState for the request state.; KSI_AsyncHandle_getError for the request error.

Note: In case of timeout the request state will be set to KSI_ASYNC_STATE_ERROR and error to KSI_NETWORK_RECIEVE_TIMEOUT.

KSI_ASYNC_OPT_SND_TIMEOUT

Async request send timeout. Represent the time interval between when the request has been added to the request queue and it has been sent out. Default setting is 10 sec.

Parameters

timeout Timeout in seconds. Paramer of type size_t.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

See also: KSI_AsyncHandle_getState for the request state.; KSI_AsyncHandle_getError for the request error.

Note: In case of timeout the request state will be set to KSI_ASYNC_STATE_ERROR and error to KSI_NETWORK_SEND_TIMEOUT.

KSI_ASYNC_OPT_REQUEST_CACHE_SIZE

Maximum parallel running request count. New value may not be less than the allready set value. Default setting is 1.

Parameters

count Paramer of type size_t.

See also: KSI_AsyncService_addRequest for adding asynchronous request to the output queue.

KSI_ASYNC_OPT_MAX_REQUEST_COUNT

Maximum number of request permitted per round. Default setting is 1.

Parameters

count Paramer of type size_t.

Note: In case the maximum number of request is allready sent out during a round interval, additional request will be buffered in intenal cache.

__KSI_ASYNC_OPT_COUNT

Function Documentation

◆ KSI_AbstractAsyncClient_new()

int KSI_AbstractAsyncClient_new	(	KSI_CTX *	ctx,
		KSI_AsyncClient **	c
	)

Construct an abstract async client object.

Parameters

[in]	ctx	KSI context.
[out]	c	Pointer to the receiving pointer.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_AsyncAggregationHandle_new()

int KSI_AsyncAggregationHandle_new	(	KSI_CTX *	ctx,
		KSI_AggregationReq *	req,
		KSI_AsyncHandle **	o
	)

Constructor for the async handle object.

Parameters

[in]	ctx	KSI context.
[in]	req	Aggregation request.
[out]	o	Pointer to the receiving pointer.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

Note: The handle takes ownership of the req resource, thus it may not be freed after a successful call to this function.

◆ KSI_AsyncClient_free()

void KSI_AsyncClient_free ( KSI_AsyncClient * c )

Free async client object.

Parameters

[in] c Async client object.

See also: KSI_TcpAsyncClient_new

Note: This will also handle termination of open network connection.

◆ KSI_AsyncHandle_free()

void KSI_AsyncHandle_free ( KSI_AsyncHandle * o )

Async handle object resource cleanup method.

Parameters

[in] o Instance to be freed.

◆ KSI_AsyncHandle_getAggregationReq()

int KSI_AsyncHandle_getAggregationReq	(	const KSI_AsyncHandle *	h,
		KSI_AggregationReq **	req
	)

Getter for the aggregation request.

Parameters

[in]	h	Async handle.
[out]	req	Pointer to the receiving pointer.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_AsyncHandle_getAggregationResp()

int KSI_AsyncHandle_getAggregationResp	(	const KSI_AsyncHandle *	h,
		KSI_AggregationResp **	resp
	)

Getter for the aggregation response.

Parameters

[in]	h	Async handle.
[out]	resp	Pointer to the receiving pointer.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

See also: KSI_SignatureBuilder_openFromAggregationResp for building a KSI Signature from aggregation response.; KSI_AsyncHandle_getSignature for getting a verified KSI Signature.

◆ KSI_AsyncHandle_getError()

int KSI_AsyncHandle_getError	(	const KSI_AsyncHandle *	h,
		int *	error
	)

Get the error code for the request which state is KSI_ASYNC_STATE_ERROR.

Parameters

[in]	h	Async handle.
[out]	error	Handle error KSI_StatusCode

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

See also: KSI_AsyncHandle_getState for getting the state of the request.

◆ KSI_AsyncHandle_getErrorMessage()

int KSI_AsyncHandle_getErrorMessage	(	const KSI_AsyncHandle *	h,
		KSI_Utf8String **	msg
	)

Get the error message for the request which state is KSI_ASYNC_STATE_ERROR.

Parameters

[in]	h	Async handle.
[out]	msg	Handle external error code.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

See also: KSI_AsyncHandle_getState for getting the state of the request.; KSI_Utf8String_cstr for message stringification.

◆ KSI_AsyncHandle_getExtError()

int KSI_AsyncHandle_getExtError	(	const KSI_AsyncHandle *	h,
		long *	ext
	)

Get the external error code for the request which state is KSI_ASYNC_STATE_ERROR.

Parameters

[in]	h	Async handle.
[out]	ext	Handle error message.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

See also: KSI_AsyncHandle_getState for getting the state of the request.

◆ KSI_AsyncHandle_getRequestCtx()

int KSI_AsyncHandle_getRequestCtx	(	const KSI_AsyncHandle *	o,
		const void **	reqCtx
	)

Getter for the request specific context.

Parameters

[in]	o	Async handle object.
[out]	reqCtx	Pointer to the receiving pointer.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_AsyncHandle_getRequestId()

int KSI_AsyncHandle_getRequestId	(	const KSI_AsyncHandle *	h,
		KSI_uint64_t *	id
	)

Get the request ID.

Parameters

[in]	h	Async handle.
[out]	id	Request ID.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

Note: The value is only valid after a successful call to KSI_AsyncService_addRequest.

See also: KSI_AsyncService_addRequest for adding asynchronous request to the output queue.

◆ KSI_AsyncHandle_getSignature()

int KSI_AsyncHandle_getSignature	(	const KSI_AsyncHandle *	h,
		KSI_Signature **	signature
	)

KSI signature getter. The returned signature is verified internally.

Parameters

[in]	h	Async handle.
[out]	signature	Pointer to the receiving pointer.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

Note: The returned resources must be freed by the caller.; The signature will only be returned if the handle state is KSI_ASYNC_STATE_RESPONSE_RECEIVED.

See also: KSI_AsyncHandle_getState for getting the state of the request.; KSI_Signature_free for cleaning up returned resources.

◆ KSI_AsyncHandle_getState()

int KSI_AsyncHandle_getState	(	const KSI_AsyncHandle *	h,
		int *	state
	)

Get the state of the request handle.

Parameters

[in]	h	Async handle.
[out]	state	Payload state KSI_AsyncHandleState

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

See also: KSI_AsyncHandle_getError for reading error code.; KSI_AsyncHandle_getSignature for getting KSI KSI Signature.

◆ KSI_AsyncHandle_ref()

KSI_AsyncHandle* KSI_AsyncHandle_ref ( KSI_AsyncHandle * o )

Increases the inner reference count of that object. *
Parameters

[in] o Pointer to KSI_AsyncHandle *

Returns
Returns the input pointer on success or NULL on error. *

See also
KSI_AsyncHandle_free

◆ KSI_AsyncHandle_setRequestCtx()

int KSI_AsyncHandle_setRequestCtx	(	KSI_AsyncHandle *	o,
		void *	reqCtx,
		void()(void )	reqCtx_free
	)

Setter for the request user private context.

Parameters

[in]	o	Async handle object.
[in]	reqCtx	Request context.
[in]	reqCtx_free	Pointer to the context cleanup method.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_AsyncService_addRequest()

int KSI_AsyncService_addRequest	(	KSI_AsyncService *	s,
		KSI_AsyncHandle *	handle
	)

Non-blocking aggregation request setter. All request are put into output queue untill, they are sent during KSI_AsyncService_run call.

Parameters

[in]	s	Async service instance.
[out]	handle	Async handle associated with the request.

Returns: KSI_OK, when operation succeeded;; KSI_ASYNC_REQUEST_CACHE_FULL, if the internal cache is full. In this case the caller should wait for responses, or process received responses;; otherwise an error code.

Note: The async service s takes ownership of req request on a successful call to this function, thus the caller may not clear the memory.

See also: KSI_SigningAsyncService_new for creating a new signing async service instance.; KSI_AsyncAggregationHandle_new for creating a new async request instance.; KSI_AsyncHandle_free for cleaning up resources in case of a failure.; KSI_AsyncService_run for handling communication towards service endpoint.; KSI_ASYNC_OPT_REQUEST_CACHE_SIZE for increasing the cache size.

◆ KSI_AsyncService_free()

void KSI_AsyncService_free ( KSI_AsyncService * service )

Free async service object.

Parameters

[in] service Async serivce object.

◆ KSI_AsyncService_getOption()

int KSI_AsyncService_getOption	(	const KSI_AsyncService *	s,
		const KSI_AsyncOption	option,
		void *	value
	)

Async service option getter.

Parameters

[in]	s	Async service instance.
[in]	option	Option to be updated from KSI_AsyncOption.
[out]	value	Option value as specified in KSI_AsyncOption.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

See also: KSI_AsyncOption defines supported options and parameter types.; KSI_AsyncService_setOption for applying option values.

◆ KSI_AsyncService_getPendingCount()

int KSI_AsyncService_getPendingCount	(	KSI_AsyncService *	s,
		size_t *	count
	)

Get the number of requests that have been sent or are still in send queue.

Parameters

[in]	s	Async service instance.
[out]	count	Pointer to the value.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_AsyncService_getReceivedCount()

int KSI_AsyncService_getReceivedCount	(	KSI_AsyncService *	s,
		size_t *	count
	)

Get the number of request that have received a response and are ready to be extracted from async service s.

Parameters

[in]	s	Async service instance.
[out]	count	Pointer to the value.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

See also: KSI_AsyncService_run for extracting received responses.

◆ KSI_AsyncService_run()

int KSI_AsyncService_run	(	KSI_AsyncService *	service,
		KSI_AsyncHandle **	handle,
		size_t *	waiting
	)

Non-blocking send/receive worker. The method will open a connection to remote service, dispatch cached requests and map the received responses. The method has to be called multiple times in order for all request to be processed.

Parameters

[in]	service	Async service instance.
[out]	handle	Async handle associated with a request.
[out]	waiting	Total number of requests in process.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

Note: The waiting count can be ignored by setting it to NULL.; The returned handle will be set to NULL if there is no response in queue.

See also: KSI_AsyncService_addRequest for adding asynchronous request to the output queue.; KSI_AsyncHandle_getState for getting the state of the request.; KSI_AsyncService_getPendingCount for requests in process.; KSI_AsyncService_getReceivedCount for received responses.

◆ KSI_AsyncService_setOption()

int KSI_AsyncService_setOption	(	KSI_AsyncService *	s,
		const KSI_AsyncOption	option,
		void *	value
	)

Async service option setter.

Parameters

[in]	s	Async service instance.
[in]	option	Option to be updated from KSI_AsyncOption.
[in]	value	Option value as specified in KSI_AsyncOption.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

See also: KSI_AsyncOption defines supported options and parameter types.; KSI_AsyncService_getOption for extracting option values.

◆ KSI_SigningAsyncService_new()

int KSI_SigningAsyncService_new	(	KSI_CTX *	ctx,
		KSI_AsyncService **	service
	)

Creates and initalizes a concrete async service object to be used to interract with aggregator endpoint.

Parameters

[in]	ctx	KSI context.
[out]	service	Pointer to the receiving pointer.

Returns: Status code (KSI_OK, when operation succeeded, otherwise an error code).

See also: KSI_AsyncService_free

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ KSI_AsyncHandleState

◆ KSI_AsyncOption

Enumeration Type Documentation

◆ KSI_AsyncHandleState_en

◆ KSI_AsyncOption_en

Function Documentation

◆ KSI_AbstractAsyncClient_new()

◆ KSI_AsyncAggregationHandle_new()

◆ KSI_AsyncClient_free()

◆ KSI_AsyncHandle_free()

◆ KSI_AsyncHandle_getAggregationReq()

◆ KSI_AsyncHandle_getAggregationResp()

◆ KSI_AsyncHandle_getError()

◆ KSI_AsyncHandle_getErrorMessage()

◆ KSI_AsyncHandle_getExtError()

◆ KSI_AsyncHandle_getRequestCtx()

◆ KSI_AsyncHandle_getRequestId()

◆ KSI_AsyncHandle_getSignature()

◆ KSI_AsyncHandle_getState()

◆ KSI_AsyncHandle_ref()

◆ KSI_AsyncHandle_setRequestCtx()

◆ KSI_AsyncService_addRequest()

◆ KSI_AsyncService_free()

◆ KSI_AsyncService_getOption()

◆ KSI_AsyncService_getPendingCount()

◆ KSI_AsyncService_getReceivedCount()

◆ KSI_AsyncService_run()

◆ KSI_AsyncService_setOption()

◆ KSI_SigningAsyncService_new()