Guardtime KSI c SDK
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Typedefs | Enumerations | Functions
Network Interface (Asynchronous)

Typedefs

typedef enum
KSI_AsyncHandleState_en 
KSI_AsyncHandleState
 
typedef int(* KSI_AsyncServiceCallback_ConnectState )(KSI_CTX *ctx, size_t id, void *userp, const char *host, int connected)
 
typedef int(* KSI_AsyncServiceCallback_configConsolidate )(KSI_CTX *ctx, size_t id, void *userp, KSI_Config *haConfig, KSI_Config *respConfig)
 
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_PUSH_CONFIG_RECEIVED, KSI_ASYNC_STATE_ERROR, KSI_ASYNC_STATE_ERROR_NOTICE
}
 
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_PUSH_CONF_CALLBACK, KSI_ASYNC_OPT_CONF_CONSOLIDATE_CALLBACK, KSI_ASYNC_OPT_HA_SUBSERVICE_LIST,
  KSI_ASYNC_OPT_CONNECTION_STATE_CALLBACK, KSI_ASYNC_OPT_CALLBACK_USERDATA, __KSI_ASYNC_OPT_COUNT
}
 

Functions

void KSI_AsyncHandle_free (KSI_AsyncHandle *o)
 
int KSI_AbstractAsyncHandle_new (KSI_CTX *ctx, KSI_AsyncHandle **o)
 
int KSI_AsyncAggregationHandle_new (KSI_CTX *ctx, KSI_AggregationReq *req, KSI_AsyncHandle **o)
 
int KSI_AsyncSigningHandle_new (KSI_CTX *ctx, KSI_DataHash *rootHash, KSI_uint64_t rootLevel, KSI_AsyncHandle **o)
 
int KSI_AsyncExtendHandle_new (KSI_CTX *ctx, KSI_ExtendReq *req, KSI_AsyncHandle **o)
 
int KSI_AsyncExtendingHandle_new (KSI_CTX *ctx, const KSI_Signature *sig, const KSI_PublicationRecord *pubRec, KSI_AsyncHandle **o)
 
KSI_AsyncHandleKSI_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_getParentId (const KSI_AsyncHandle *h, size_t *parentId)
 
int KSI_AsyncHandle_getAggregationReq (const KSI_AsyncHandle *h, KSI_AggregationReq **req)
 
int KSI_AsyncHandle_getExtendReq (const KSI_AsyncHandle *h, KSI_ExtendReq **req)
 
int KSI_AsyncHandle_getAggregationResp (const KSI_AsyncHandle *h, KSI_AggregationResp **resp)
 
int KSI_AsyncHandle_getExtendResp (const KSI_AsyncHandle *h, KSI_ExtendResp **resp)
 
int KSI_AsyncHandle_getSignature (const KSI_AsyncHandle *h, KSI_Signature **signature)
 
int KSI_AsyncHandle_getConfig (const KSI_AsyncHandle *h, KSI_Config **config)
 
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_ExtendingAsyncService_new (KSI_CTX *ctx, KSI_AsyncService **service)
 
int KSI_AsyncService_addRequest (KSI_AsyncService *service, 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 int option, void *value)
 
int KSI_AsyncService_getOption (const KSI_AsyncService *s, const int option, void *value)
 
int KSI_AsyncService_setEndpoint (KSI_AsyncService *service, const char *uri, const char *loginId, const char *key)
 
int KSI_AsyncService_addEndpoint (KSI_AsyncService *service, const char *uri, const char *loginId, const char *key)
 
int KSI_SigningHighAvailabilityService_new (KSI_CTX *ctx, KSI_AsyncService **service)
 
int KSI_ExtendingHighAvailabilityService_new (KSI_CTX *ctx, KSI_AsyncService **service)
 
void KSI_HighAvailabilityRequest_free (KSI_HighAvailabilityRequest *o)
 
int KSI_HighAvailabilityRequest_new (KSI_CTX *ctx, KSI_AsyncHandle *asyncHandle, KSI_HighAvailabilityRequest **o)
 

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:

Typedef Documentation

Enum defining async handle state.

Note
User must process only those handles that have reached there final states.

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.
typedef int(* KSI_AsyncServiceCallback_configConsolidate)(KSI_CTX *ctx, size_t id, void *userp, KSI_Config *haConfig, KSI_Config *respConfig)

High availability KSI_AsyncService configuration consolidation callback.

Parameters
[in]ctxKSI context object.
[in]idUnique async service id.
[in]userpContains whatever user-defined value set using the KSI_ASYNC_OPT_CALLBACK_USERDATA.
[in,out]haConfigConfiguration instance where the new value should be merged into.
[in]respConfigSub-service configuration response.
Returns
Implementation must return status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_ASYNC_OPT_CONF_CONSOLIDATE_CALLBACK for setting up the callback.
typedef int(* KSI_AsyncServiceCallback_ConnectState)(KSI_CTX *ctx, size_t id, void *userp, const char *host, int connected)

Async service network connection establishment listener callback.

Parameters
[in]ctxKSI context object.
[in]idUnique async service id (useful in case of HA service).
[in]userpContains whatever user-defined value set using the KSI_ASYNC_OPT_CALLBACK_USERDATA.
[in]connectedBoolean value indication connection state.
Returns
Implementation must return status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_ASYNC_OPT_CONNECTION_STATE_CALLBACK for setting up the callback.

Enumeration Type Documentation

Enum defining async handle state.

Note
User must process only those handles that have reached there final states.
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.

See also
KSI_AsyncHandle_getAggregationResp for extracting aggregation response.
KSI_AsyncHandle_getExtendResp for extracting extening response.
KSI_AsyncHandle_getSignature for extracting KSI KSI Signature.
KSI_AsyncHandle_free for cleaning up resources.
Note
This is the final state of a request.
KSI_ASYNC_STATE_PUSH_CONFIG_RECEIVED 

Configuration has been received from the server.

See also
KSI_AsyncHandle_getConfig for extracting server configuration response.
KSI_AsyncHandle_free for cleaning up resources.
Note
This is the final state of a request.
KSI_ASYNC_STATE_ERROR 

An error has occured while the request was in process.

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.
Note
This is the final state of a request.
KSI_ASYNC_STATE_ERROR_NOTICE 

An error has occured while a request is/was processed. As such, it is not an error response, however, it is an indication that not all sub systems are functioning errorless. There are following scenarious when the error cound have occured:

  • while the request is waiting for a valid response, any of the underlying enpoint services could have encountered eg. network connection issues;
  • a valid response has been already returned to the user with a handle in KSI_ASYNC_STATE_RESPONSE_RECEIVED, or KSI_ASYNC_STATE_PUSH_CONFIG_RECEIVED state from any unterlying endpoint. Meanwhile, other endpoint(s) could have been waiting for receive timeout.

The difference between KSI_ASYNC_STATE_ERROR is that a handle is set into the state when no valid response can be returned to the user.

The handle in current state contains only the error information and a reference to the original request:

See also
KSI_AsyncHandle_getError for reading the error code.
KSI_AsyncHandle_getRequestCtx for extracting the original request handle.
KSI_AsyncHandle_free for cleaning up resources.
Note
This is the final state for a handle.
KSI_AsyncService_addRequest can not be used direcly on a request this state references to. However, the original handle can be used for this purpose.
The attached request handle (returned via KSI_AsyncHandle_getRequestCtx) is owned by the handle returned in currect state, thus it may not be freed by the user. In order to keep a refecence of a handle use KSI_AsyncHandle_ref.

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
timeoutTimeout 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
timeoutTimeout 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
timeoutTimeout 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
countParamer 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
countParamer 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_PUSH_CONF_CALLBACK 

If configured, on reception of KSI_Config the callback is invoked instead of returning the configuration via KSI_AsyncHandle with the state KSI_ASYNC_STATE_PUSH_CONFIG_RECEIVED.

Parameters
p_funcParamer of type KSI_Config_Callback.
Note
For reading the stored value via KSI_AsyncService_getOption a parameter of type size_t should be used, and casted to KSI_Config_Callback before use.
The KSI_CTX push config callback configuration will be overriden by current setting.
See also
KSI_OPT_AGGR_CONF_RECEIVED_CALLBACK and KSI_OPT_EXT_CONF_RECEIVED_CALLBACK for KSI_CTX callback configuration.
KSI_ASYNC_OPT_CONF_CONSOLIDATE_CALLBACK 

Enables the user to define a alternative method for consolidating high availability sub-service configuration responses.

Parameters
p_funcParamer of type KSI_AsyncServiceCallback_configConsolidate.
Note
For reading the stored value via KSI_AsyncService_getOption a parameter of type size_t should be used, and casted to KSI_AsyncServiceCallback_configConsolidate before use.
The default consolidation handling will be disabled.
Only applicable to a high availability KSI_AsyncService created via KSI_SigningHighAvailabilityService_new or KSI_ExtendingHighAvailabilityService_new.
KSI_ASYNC_OPT_HA_SUBSERVICE_LIST 

Get the list of high availability service subservices.

Parameters
[out]p_listParamer of type KSI_AsyncServiceList.
Note
Only functioning as option getter on a high availability service.
For reading the stored value via KSI_AsyncService_getOption a parameter of type size_t should be used, and casted to KSI_AsyncServiceList before use.
See also
KSI_AsyncService_addEndpoint for adding a subservice to the high availability service.
KSI_ASYNC_OPT_CONNECTION_STATE_CALLBACK 

The callback is invoked when the network connection state to a server has changed.

Parameters
p_funcParamer of type #KSI_AsyncServiceConnectState_Callback.
Note
Only applicable in case of TCP client.
For reading the stored value via KSI_AsyncService_getOption a parameter of type size_t should be used, and casted to #KSI_AsyncServiceConnectState_Callback before use.
KSI_ASYNC_OPT_CALLBACK_USERDATA 

Custom pointer to be passed to callbacks. The pointer nor its data is processed internally.

Parameters
pdataParamer of type void*.
__KSI_ASYNC_OPT_COUNT 

Function Documentation

int KSI_AbstractAsyncClient_new ( KSI_CTX ctx,
KSI_AsyncClient **  c 
)

Construct an abstract async client object.

Parameters
[in]ctxKSI context.
[out]cPointer to the receiving pointer.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_AbstractAsyncHandle_new ( KSI_CTX ctx,
KSI_AsyncHandle **  o 
)

Constructor for the abstract async handle.

Parameters
[in]ctxKSI context.
[out]oAbstract async handle.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_AsyncAggregationHandle_new ( KSI_CTX ctx,
KSI_AggregationReq req,
KSI_AsyncHandle **  o 
)

Constructor for the async handle object.

Parameters
[in]ctxKSI context.
[in]reqAggregation request.
[out]oPointer 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.
See also
KSI_AsyncService_addRequest for adding asynchronous request to the output queue.
KSI_AsyncHandle_getAggregationResp for retrieving aggregation response.
KSI_AsyncHandle_getSignature for retrieving KSI KSI Signature fot the rootHash Data Hashing value.
void KSI_AsyncClient_free ( KSI_AsyncClient c)

Free async client object.

Parameters
[in]cAsync client object.
Note
This will also handle termination of opened network connection.
See also
KSI_TcpAsyncClient_new
KSI_HttpAsyncClient_new
int KSI_AsyncExtendHandle_new ( KSI_CTX ctx,
KSI_ExtendReq req,
KSI_AsyncHandle **  o 
)

Constructor for the async handle object.

Parameters
[in]ctxKSI context.
[in]reqExtend request.
[out]oPointer to the receiving pointer.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The handle takes ownership of the provided request resource, thus they may not be freed after a successful call to this function.
See also
KSI_AsyncService_addRequest for adding asynchronous request to the output queue.
KSI_AsyncHandle_getExtendResp for retrieving extend response.
KSI_SignatureBuilder_applyCalendarHashChain for constructing a KSI KSI Signature from extending response.
int KSI_AsyncExtendingHandle_new ( KSI_CTX ctx,
const KSI_Signature sig,
const KSI_PublicationRecord pubRec,
KSI_AsyncHandle **  o 
)

Constructor for the async handle object for extending provided KSI signature.

Parameters
[in]ctxKSI context.
[in]sigKSI signature to be extended.
[in]pubRecPublication record (optional).
[out]oPointer to the receiving pointer.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The handle o will make copies of the resources, thus it is users responsibility to clean up input resources after a successful call to this function.
See also
KSI_AsyncService_addRequest for adding asynchronous request to the output queue.
KSI_AsyncHandle_getExtendResp for retrieving extend response.
KSI_AsyncHandle_getSignature for retrieving an extended KSI KSI Signature.
void KSI_AsyncHandle_free ( KSI_AsyncHandle o)

Async handle object resource cleanup method.

Parameters
[in]oInstance to be freed.
int KSI_AsyncHandle_getAggregationReq ( const KSI_AsyncHandle h,
KSI_AggregationReq **  req 
)

Getter for the aggregation request.

Parameters
[in]hAsync handle.
[out]reqPointer to the receiving pointer.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_AsyncHandle_getAggregationResp ( const KSI_AsyncHandle h,
KSI_AggregationResp **  resp 
)

Getter for the aggregation response.

Parameters
[in]hAsync handle.
[out]respPointer 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.
int KSI_AsyncHandle_getConfig ( const KSI_AsyncHandle h,
KSI_Config **  config 
)

Server push configuration getter.

Parameters
[in]hAsync handle.
[out]configPointer to the receiving pointer.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
A valid configuration will only be returned if the handle state is KSI_ASYNC_STATE_PUSH_CONFIG_RECEIVED.
See also
KSI_AsyncHandle_getState for getting the state of the request.
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]hAsync handle.
[out]errorHandle 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.
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]hAsync handle.
[out]msgHandle 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.
int KSI_AsyncHandle_getExtendReq ( const KSI_AsyncHandle h,
KSI_ExtendReq **  req 
)

Getter for the extend request.

Parameters
[in]hAsync handle.
[out]reqPointer to the receiving pointer.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_AsyncHandle_getExtendResp ( const KSI_AsyncHandle h,
KSI_ExtendResp **  resp 
)

Getter for the extend response.

Parameters
[in]hAsync handle.
[out]respPointer to the receiving pointer.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_AsyncHandle_getSignature for getting a verified KSI Signature.
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]hAsync handle.
[out]extHandle 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.
int KSI_AsyncHandle_getParentId ( const KSI_AsyncHandle h,
size_t *  parentId 
)

Get the request handler ID. This is the unique async service id that is provided also to the configured callbacks (see KSI_AsyncServiceCallback) and seen in the logs.

Parameters
[in]hAsync handle.
[out]parentIdUnique async service 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.
int KSI_AsyncHandle_getRequestCtx ( const KSI_AsyncHandle o,
const void **  reqCtx 
)

Getter for the request specific context.

Parameters
[in]oAsync handle object.
[out]reqCtxPointer to the receiving pointer.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_AsyncHandle_getRequestId ( const KSI_AsyncHandle h,
KSI_uint64_t id 
)

Get the request ID.

Parameters
[in]hAsync handle.
[out]idRequest 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.
int KSI_AsyncHandle_getSignature ( const KSI_AsyncHandle h,
KSI_Signature **  signature 
)

KSI signature getter. The returned signature is verified internally.

Parameters
[in]hAsync handle.
[out]signaturePointer 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.
int KSI_AsyncHandle_getState ( const KSI_AsyncHandle h,
int *  state 
)

Get the state of the request handle.

Parameters
[in]hAsync handle.
[out]statePayload 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* KSI_AsyncHandle_ref ( KSI_AsyncHandle o)
  • Increases the inner reference count of that object. *
    Parameters
    [in]oPointer to KSI_AsyncHandle *
    Returns
    Returns the input pointer on success or NULL on error. *
    See also
    KSI_AsyncHandle_free
int KSI_AsyncHandle_setRequestCtx ( KSI_AsyncHandle o,
void *  reqCtx,
void(*)(void *)  reqCtx_free 
)

Setter for the request user private context.

Parameters
[in]oAsync handle object.
[in]reqCtxRequest context.
[in]reqCtx_freePointer to the context cleanup method.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_AsyncService_addEndpoint ( KSI_AsyncService service,
const char *  uri,
const char *  loginId,
const char *  key 
)

Subservice endpoint adder. In order to setup multiple subservices, the method has to be called repeteadly.

Parameters
[in]servicePointer to the async service.
[in]uriHost name.
[in]loginIdUser name.
[in]keyHMAC shared secret.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_SigningHighAvailabilityService_new or KSI_ExtendingHighAvailabilityService_new for constucting high availability async service.
KSI_AsyncService_free
KSI_OPT_HA_SAFEGUARD for the maximum number of high availability subservices.
Note
Acts as KSI_AsyncService_setEndpoint if used with a service constructed via KSI_SigningAsyncService_new or KSI_ExtendingAsyncService_new.
int KSI_AsyncService_addRequest ( KSI_AsyncService service,
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]serviceAsync service instance.
[out]handleAsync 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.
void KSI_AsyncService_free ( KSI_AsyncService service)

Free async service object.

Parameters
[in]serviceAsync serivce object.
int KSI_AsyncService_getOption ( const KSI_AsyncService s,
const int  option,
void *  value 
)

Async service option getter.

Parameters
[in]sAsync service instance.
[in]optionOption to be updated from KSI_AsyncOption.
[out]valueOption 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.
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]sAsync service instance.
[out]countPointer to the value.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
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]sAsync service instance.
[out]countPointer to the value.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_AsyncService_run for extracting received responses.
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]serviceAsync service instance.
[out]handleAsync handle associated with a request.
[out]waitingTotal 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.
int KSI_AsyncService_setEndpoint ( KSI_AsyncService service,
const char *  uri,
const char *  loginId,
const char *  key 
)

Setter for the service endpoint.

Parameters
[in]servicePointer to the async service.
[in]uriHost name.
[in]loginIdUser name.
[in]keyHMAC shared secret.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
On repetitive invocation KSI_INVALID_STATE error is returned.
See also
KSI_SigningAsyncService_new or KSI_ExtendingAsyncService_new for constucting async service.
KSI_AsyncService_free
KSI_AsyncService_addEndpoint for adding subservices to high availability service.
Note
As a special case when used with high availability KSI_AsyncService, the invocation of endpoint setter will reset already configured endpoints (also invalidate provided requests) and call KSI_AsyncService_addEndpoint.
int KSI_AsyncService_setOption ( KSI_AsyncService s,
const int  option,
void *  value 
)

Async service option setter.

Parameters
[in]sAsync service instance.
[in]optionOption to be updated from KSI_AsyncOption.
[in]valueOption 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.
Note
Before appling any options the service endpoint has to be configured.
Pay attention to the service type the option is intended to be used with. If not stated explicitly, there are no limitation. However, if used wrongly KSI_INVALID_ARGUMENT will be returned.
int KSI_AsyncSigningHandle_new ( KSI_CTX ctx,
KSI_DataHash rootHash,
KSI_uint64_t  rootLevel,
KSI_AsyncHandle **  o 
)

Constructor for the async signing handle object.

Parameters
[in]ctxKSI context.
[in]rootHashRoot value of the hash tree. If rootLevel is nil, it is the document hash.
[in]rootLevelLevel of the root node (0 =< x <= 0xff).
[out]oPointer to the receiving pointer.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The handle takes ownership of the rootHash resource, thus it may not be freed after a successful call to this function.
See also
KSI_AsyncService_addRequest for adding asynchronous request to the output queue.
KSI_AsyncHandle_getAggregationResp for retrieving aggregation response.
KSI_AsyncHandle_getSignature for retrieving KSI KSI Signature fot the rootHash Data Hashing value.
KSI_DataHash_ref for keeping a reference to the rootHash.
int KSI_ExtendingAsyncService_new ( KSI_CTX ctx,
KSI_AsyncService **  service 
)

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

Parameters
[in]ctxKSI context.
[out]servicePointer to the receiving pointer.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_AsyncService_free
KSI_AsyncService_setEndpoint for setting up an endpoint.
int KSI_ExtendingHighAvailabilityService_new ( KSI_CTX ctx,
KSI_AsyncService **  service 
)

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

Parameters
[in]ctxKSI context.
[out]servicePointer to the receiving pointer.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_AsyncService_addEndpoint for adding subservices.
KSI_AsyncService_free
void KSI_HighAvailabilityRequest_free ( KSI_HighAvailabilityRequest o)
int KSI_HighAvailabilityRequest_new ( KSI_CTX ctx,
KSI_AsyncHandle asyncHandle,
KSI_HighAvailabilityRequest **  o 
)
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]ctxKSI context.
[out]servicePointer to the receiving pointer.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_AsyncService_free
KSI_AsyncService_setEndpoint for setting up an endpoint.
int KSI_SigningHighAvailabilityService_new ( KSI_CTX ctx,
KSI_AsyncService **  service 
)

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

Parameters
[in]ctxKSI context.
[out]servicePointer to the receiving pointer.
Returns
Status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_AsyncService_addEndpoint for adding subservices.
KSI_AsyncService_free