> For the complete documentation index, see [llms.txt](https://sandbox-docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sandbox-docs.verifone.com/adk-5.0-programmers-guide/readme/files/dir_9ae62d232e1f8555f5337bbbbe2033a3/dir_a8642344d1890ac34080367e6f4e78c5/engine__keyservice_8h.md). # engine\_keyservice.h [Data Structures](#nested-classes) | [Macros](#define-members) | [Typedefs](#typedef-members) `#include ` Include dependency graph for engine\_keyservice.h: ![](/files/rAUUuwPNZ1RVMBUQNJrK) [Go to the source code of this file.](/adk-5.0-programmers-guide/engine__keyservice_8h_source.md) | | | | --------------- | ---------------------------------------- | | Data Structures | | | struct | [KS\_IOBuffer](#struct_k_s___i_o_buffer) | | | | | ------- | ---------------------------------------------------------------------------------------- | | Macros | | | #define | [KS\_CMD\_READ\_CERT](#a80a221065e023789a8866527b148810c) (ENGINE\_CMD\_BASE+0x10) | | #define | [KS\_CMD\_SET\_ERROR\_CB](#aaaa9216415bce126aae64a64e1be6efa) (ENGINE\_CMD\_BASE+0x11) | | #define | [KS\_CMD\_SET\_DEBUG\_CB](#a2968c2cff33a9788809e328fb5c6294c) (ENGINE\_CMD\_BASE+0x12) | | | | | --------------- | --------------------------------------------------------------------------------------------------------------- | | Typedefs | | | typedef void(\* | [ks\_trace\_callback](#afcf7437404424f6e27c15778b5b2af10)) (const char \*file, unsigned line, const char \*str) | *** ### DataStructure Documentation ### KS\_IOBuffer struct KS\_IOBuffer I/O buffer used for the keyservice to pass/read data to/from the keyservice engine | | | | | ------------- | ---------- | ---------------------------------- | | Data Fields | | | | unsigned char | buffer\[0] | pointer to data buffer | | unsigned | maxsize | allocated size for the data buffer | | unsigned | size | size of stored data in the buffer | ### MacroDefinition Documentation ### KS\_CMD\_READ\_CERT \#define KS\_CMD\_READ\_CERT (ENGINE\_CMD\_BASE+0x10) Control command to read the certificate from the keyservice engine. The command uses struct [KS\_IOBuffer](#struct_k_s___i_o_buffer) to pass the key reference name to the keyservice, for which the related certificate shall be read. The [KS\_IOBuffer](#struct_k_s___i_o_buffer) should be reserved with malloc() and sufficient buffer size (recommended is at least 8k). As input value the buffer gets the key reference name `key_name`, as output the same buffer is used by the keyservice engine to store the certificate. Example code to read the certificate for key reference `key_name` (C-string): ```cpp KS_IOBuffer *buf=(KS_IOBuffer *)malloc(sizeof(KS_IOBuffer)+8192); buf->maxsize=8192; buf->size=strlen(key_name); memcpy(buf->buffer,key_name,buf->size); if(ENGINE_ctrl(engine,KS_CMD_READ_CERT,0,buf,0)) { // success memcpy(certbuf,buf->buffer,buf->size); } free(buf); ``` {% hint style="info" %} If the read certificate length exceeds the allocated buffer size of the provided buffer, ENGINE\_ctrl() fails and the keyservice returns the required buffer size in buf->size, so that the caller can re-allocate the buffer to the required buffer size. {% endhint %} ### KS\_CMD\_SET\_DEBUG\_CB \#define KS\_CMD\_SET\_DEBUG\_CB (ENGINE\_CMD\_BASE+0x12) If supported by the keyservice engine, the application can use this control command to set a trace callback (see ks\_trace\_callback), which will be invoked for logging of informational debug-level events. ### KS\_CMD\_SET\_ERROR\_CB \#define KS\_CMD\_SET\_ERROR\_CB (ENGINE\_CMD\_BASE+0x11) If supported by the keyservice engine, the application can use this control command to set a trace callback (see ks\_trace\_callback), which will be invoked for logging of error conditions. ### TypedefDocumentation ### ks\_trace\_callback typedef void(\\\* ks\_trace\_callback) (const char \\\*file, unsigned line, const char \\\*str) callback trace function invoked, if keyservice engine calls the internal logging function to trace out debug information. This function can eiter be set by engine control command KS\_CMD\_SET\_ERROR\_CB to trace error conditions or by KS\_CMD\_SET\_DEBUG\_CB to trace informational debug-level messages. {% hint style="info" %} Only process flow information is logged, key contents are never logged. {% endhint %} \*\*Parameters\*\* \[in] **file** filename of the module containing the trace point \[in] **line** source line of the module containing the trace point \[in] **str** logging information as zero-terminated string --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://sandbox-docs.verifone.com/adk-5.0-programmers-guide/readme/files/dir_9ae62d232e1f8555f5337bbbbe2033a3/dir_a8642344d1890ac34080367e6f4e78c5/engine__keyservice_8h.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.