Guardtime KSI c SDK
|
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 |
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:
handle
. typedef enum KSI_AsyncHandleState_en KSI_AsyncHandleState |
Enum defining async handle state.
typedef enum KSI_AsyncOption_en KSI_AsyncOption |
Enum defining async service options. Pay attention to the used parameter type.
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.
[in] | ctx | KSI context object. |
[in] | id | Unique async service id. |
[in] | userp | Contains whatever user-defined value set using the KSI_ASYNC_OPT_CALLBACK_USERDATA. |
[in,out] | haConfig | Configuration instance where the new value should be merged into. |
[in] | respConfig | Sub-service configuration response. |
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.
[in] | ctx | KSI context object. |
[in] | id | Unique async service id (useful in case of HA service). |
[in] | userp | Contains whatever user-defined value set using the KSI_ASYNC_OPT_CALLBACK_USERDATA. |
[in] | connected | Boolean value indication connection state. |
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.
|
KSI_ASYNC_STATE_PUSH_CONFIG_RECEIVED |
Configuration has been received from the server.
|
KSI_ASYNC_STATE_ERROR |
An error has occured while the request was in process.
|
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:
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:
|
enum KSI_AsyncOption_en |
Enum defining async service options. Pay attention to the used parameter type.
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.
| |||
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.
| |||
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.
| |||
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.
| |||
KSI_ASYNC_OPT_MAX_REQUEST_COUNT |
Maximum number of request permitted per round. Default setting is 1.
| |||
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.
| |||
KSI_ASYNC_OPT_CONF_CONSOLIDATE_CALLBACK |
Enables the user to define a alternative method for consolidating high availability sub-service configuration responses.
| |||
KSI_ASYNC_OPT_HA_SUBSERVICE_LIST |
Get the list of high availability service subservices.
| |||
KSI_ASYNC_OPT_CONNECTION_STATE_CALLBACK |
The callback is invoked when the network connection state to a server has changed.
| |||
KSI_ASYNC_OPT_CALLBACK_USERDATA |
Custom pointer to be passed to callbacks. The pointer nor its data is processed internally.
| |||
KSI_ASYNC_OPT_HMAC_ALGORITHM |
HMAC algorithm to be used for securing transactions. In not set, the KSI_CTX default HMAC algorithm is used.
| |||
__KSI_ASYNC_OPT_COUNT |
int KSI_AbstractAsyncClient_new | ( | KSI_CTX * | ctx, |
KSI_AsyncClient ** | c | ||
) |
Construct an abstract async client object.
[in] | ctx | KSI context. |
[out] | c | Pointer to the receiving pointer. |
int KSI_AbstractAsyncHandle_new | ( | KSI_CTX * | ctx, |
KSI_AsyncHandle ** | o | ||
) |
Constructor for the abstract async handle.
[in] | ctx | KSI context. |
[out] | o | Abstract async handle. |
int KSI_AsyncAggregationHandle_new | ( | KSI_CTX * | ctx, |
KSI_AggregationReq * | req, | ||
KSI_AsyncHandle ** | o | ||
) |
Constructor for the async handle object.
[in] | ctx | KSI context. |
[in] | req | Aggregation request. |
[out] | o | Pointer to the receiving pointer. |
req
resource, thus it may not be freed after a successful call to this function. rootHash
Data Hashing value. void KSI_AsyncClient_free | ( | KSI_AsyncClient * | c | ) |
Free async client object.
[in] | c | Async client object. |
int KSI_AsyncExtendHandle_new | ( | KSI_CTX * | ctx, |
KSI_ExtendReq * | req, | ||
KSI_AsyncHandle ** | o | ||
) |
Constructor for the async handle object.
[in] | ctx | KSI context. |
[in] | req | Extend request. |
[out] | o | Pointer to the receiving pointer. |
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.
[in] | ctx | KSI context. |
[in] | sig | KSI signature to be extended. |
[in] | pubRec | Publication record (optional). |
[out] | o | Pointer to the receiving pointer. |
o
will make copies of the resources, thus it is users responsibility to clean up input resources after a successful call to this function. void KSI_AsyncHandle_free | ( | KSI_AsyncHandle * | o | ) |
Async handle object resource cleanup method.
[in] | o | Instance to be freed. |
int KSI_AsyncHandle_getAggregationReq | ( | const KSI_AsyncHandle * | h, |
KSI_AggregationReq ** | req | ||
) |
Getter for the aggregation request.
[in] | h | Async handle. |
[out] | req | Pointer to the receiving pointer. |
int KSI_AsyncHandle_getAggregationResp | ( | const KSI_AsyncHandle * | h, |
KSI_AggregationResp ** | resp | ||
) |
Getter for the aggregation response.
[in] | h | Async handle. |
[out] | resp | Pointer to the receiving pointer. |
int KSI_AsyncHandle_getConfig | ( | const KSI_AsyncHandle * | h, |
KSI_Config ** | config | ||
) |
Server push configuration getter.
[in] | h | Async handle. |
[out] | config | Pointer to the receiving pointer. |
int KSI_AsyncHandle_getError | ( | const KSI_AsyncHandle * | h, |
int * | error | ||
) |
Get the error code for the request which state is KSI_ASYNC_STATE_ERROR.
[in] | h | Async handle. |
[out] | error | Handle error KSI_StatusCode |
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.
[in] | h | Async handle. |
[out] | msg | Handle external error code. |
int KSI_AsyncHandle_getExtendReq | ( | const KSI_AsyncHandle * | h, |
KSI_ExtendReq ** | req | ||
) |
Getter for the extend request.
[in] | h | Async handle. |
[out] | req | Pointer to the receiving pointer. |
int KSI_AsyncHandle_getExtendResp | ( | const KSI_AsyncHandle * | h, |
KSI_ExtendResp ** | resp | ||
) |
Getter for the extend response.
[in] | h | Async handle. |
[out] | resp | Pointer to the receiving pointer. |
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.
[in] | h | Async handle. |
[out] | ext | Handle error message. |
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.
[in] | h | Async handle. |
[out] | parentId | Unique async service id. |
int KSI_AsyncHandle_getRequestCtx | ( | const KSI_AsyncHandle * | o, |
const void ** | reqCtx | ||
) |
Getter for the request specific context.
[in] | o | Async handle object. |
[out] | reqCtx | Pointer to the receiving pointer. |
int KSI_AsyncHandle_getRequestId | ( | const KSI_AsyncHandle * | h, |
KSI_uint64_t * | id | ||
) |
Get the request ID.
[in] | h | Async handle. |
[out] | id | Request ID. |
int KSI_AsyncHandle_getSignature | ( | const KSI_AsyncHandle * | h, |
KSI_Signature ** | signature | ||
) |
KSI signature getter. The returned signature is verified internally.
[in] | h | Async handle. |
[out] | signature | Pointer to the receiving pointer. |
int KSI_AsyncHandle_getState | ( | const KSI_AsyncHandle * | h, |
int * | state | ||
) |
Get the state of the request handle.
[in] | h | Async handle. |
[out] | state | Payload state KSI_AsyncHandleState |
KSI_AsyncHandle* KSI_AsyncHandle_ref | ( | KSI_AsyncHandle * | o | ) |
[in] | o | Pointer to KSI_AsyncHandle * |
NULL
on error. * int KSI_AsyncHandle_setRequestCtx | ( | KSI_AsyncHandle * | o, |
void * | reqCtx, | ||
void(*)(void *) | reqCtx_free | ||
) |
Setter for the request user private context.
[in] | o | Async handle object. |
[in] | reqCtx | Request context. |
[in] | reqCtx_free | Pointer to the context cleanup method. |
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.
[in] | service | Pointer to the async service. |
[in] | uri | Host name. |
[in] | loginId | User name. |
[in] | key | HMAC shared secret. |
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.
[in] | service | Async service instance. |
[out] | handle | Async handle associated with the request. |
s
takes ownership of req
request on a successful call to this function, thus the caller may not clear the memory. void KSI_AsyncService_free | ( | KSI_AsyncService * | service | ) |
Free async service object.
[in] | service | Async serivce object. |
int KSI_AsyncService_getOption | ( | const KSI_AsyncService * | s, |
const int | option, | ||
void * | value | ||
) |
Async service option getter.
[in] | s | Async service instance. |
[in] | option | Option to be updated from KSI_AsyncOption. |
[out] | value | Option value as specified in KSI_AsyncOption. |
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.
[in] | s | Async service instance. |
[out] | count | Pointer to the value. |
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
.
[in] | s | Async service instance. |
[out] | count | Pointer to the value. |
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.
[in] | service | Async service instance. |
[out] | handle | Async handle associated with a request. |
[out] | waiting | Total number of requests in process. |
waiting
count can be ignored by setting it to NULL. handle
will be set to NULL if there is no response in queue. int KSI_AsyncService_setEndpoint | ( | KSI_AsyncService * | service, |
const char * | uri, | ||
const char * | loginId, | ||
const char * | key | ||
) |
Setter for the service endpoint.
[in] | service | Pointer to the async service. |
[in] | uri | Host name. |
[in] | loginId | User name. |
[in] | key | HMAC shared secret. |
int KSI_AsyncService_setOption | ( | KSI_AsyncService * | s, |
const int | option, | ||
void * | value | ||
) |
Async service option setter.
[in] | s | Async service instance. |
[in] | option | Option to be updated from KSI_AsyncOption. |
[in] | value | Option value as specified in KSI_AsyncOption. |
int KSI_AsyncSigningHandle_new | ( | KSI_CTX * | ctx, |
KSI_DataHash * | rootHash, | ||
KSI_uint64_t | rootLevel, | ||
KSI_AsyncHandle ** | o | ||
) |
Constructor for the async signing handle object.
[in] | ctx | KSI context. |
[in] | rootHash | Root value of the hash tree. If rootLevel is nil, it is the document hash. |
[in] | rootLevel | Level of the root node (0 =< x <= 0xff). |
[out] | o | Pointer to the receiving pointer. |
rootHash
resource, thus it may not be freed after a successful call to this function. rootHash
Data Hashing value. 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.
[in] | ctx | KSI context. |
[out] | service | Pointer to the receiving pointer. |
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.
[in] | ctx | KSI context. |
[out] | service | Pointer to the receiving pointer. |
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.
[in] | ctx | KSI context. |
[out] | service | Pointer to the receiving pointer. |
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.
[in] | ctx | KSI context. |
[out] | service | Pointer to the receiving pointer. |