Every external interface method uses the same signature. This signature is defined by Utimaco, and is the signature that the cmds module will expect as it calls through a function pointer to the sub-function.
The external-method method signature is a symbol name that takes three parameters: a pointer to the current context, as well as parameters for the length-of-the-payload, and for the payload itself. The return value is an integer, either 0x0 for no-error, or non-0x0 to indicate an error was found.
On the CryptoServer, certain sub-functions take no data, or the single parameter takes up the entire p_cmd field. When the serialized p_cmd data is more complex, a target structure may be provided for use by cmds_scanf, and (if used) is generally implemented as a C struct, by convention named `cmd` (as in the example provided above).
int exmp_ext_echo (T_CMDS_HANDLE *p_hdl, int l_cmd, unsigned char *p_cmd);
Because structure packing is not strongly defined by the C language, cross-platform hosting environments that may have different processors, operating systems, programming languages, as well as endianness issues and a lack of automation, it is currently necessary to manually serialize the data to send, and deserialize the data on receipt for each host application, on each platform, for each sub-function and its response.
When a complex structure (cmd) is sent, it may include different fields which can represent integers, strings (fixed length character arrays), and/or variable-length byte arrays, or can include something that mimics a switch/case over a union of different structs.
The return interface may be a structure that is as simple, or as complicated, as the input struct described above.
Manually serializing and deserializing data, while straightforward, is repetitive and prone to error. Engineers who have been using the tools provided, often, and repeatedly, may not believe that automation for these steps is of any benefit. For engineers new to the process, or who only use it rarely, automation is a suitable time saver.
Of the four times you will marshal the data -- serialization on the host, deserialization on the CryptoServer, and serialization of the response on the CryptoServer for deserialization on the host, two of these must be done manually. The third and fourth, deserialization of the p_cmd buffer, into the cmd struct within an SFC, and deserialization of the response buffer into a similar struct on the host, can benefit from using cmds_scanf() (or cs_scanp).
Use of cmds_scanf() is covered below.
Use of cs_scanp (For C and C++ host applications only) is similar, see the relevant documentation for the differences.
In general, the automation provided by the pattern processing tools described here bypasses the use of cs_scanp, by giving you direct access to auto-generated object classes, based on the cmds_scanf patterns, where needed.