 |
BALTECH Docs |
C API for BALTECH SDK
|
|
|
BALTECH Docs |
C API for BALTECH SDK
|
|
Macros | |
| #define | BRP_ERR_AR_NOMESSAGE BRP_ERR_STATUS(0x0500, 0x01) |
| #define | BRP_ERR_AR_DISABLED BRP_ERR_STATUS(0x0500, 0x10) |
| #define | BRP_CMD_SYS_GETINFO_FWS_LEN 41 |
| maximum length of firmwarestring (see brp_exec_Sys_GetInfo()) More... | |
| #define | BRP_INFINITE 0xFFFFFFFF |
| is used if brp_time shall be infinite. More... | |
| #define | BRP_TIME_SUBTRACT(time, delta) |
| #define | BRP_FRAME_INVALID_SIZE ((size_t) -1) |
| #define | BRP_LOG_DIR_PREFIX "brp-logs-" |
| #define | BRP_PROTID_BRP 1 |
| identificator for BRP protocols (see brp_protocol.h) More... | |
| #define | BRP_PROTID_TCPIP 2 |
| identificator for TCP/IP protocol (see tcpip_protocol.h) More... | |
| #define | BRP_PROTID_PKI 3 |
| #define | BRP_PROTID_COMPOSITE 4 |
| identificator for composed protocols (see composite_protocol.h) More... | |
| #define | BRP_PROTID_DUMMY 5 |
| internal identificator for unused protocol layers in composed protocols (see composite_protocol.h). More... | |
| #define | BRP_PROTID_USB_HID 6 |
| identificator for USB HID protocols (see usb_hid_protocol.h) More... | |
| #define | BRP_PROTID_RS232 7 |
| identificator for RS232/Virtual Comport protocols (see usb_hid_protocol.h) More... | |
| #define | BRP_PROTID_SECURE_CHANNEL 8 |
| identificator for RS232 protocol (see rs232_protocol.h) More... | |
| #define | BRP_PROTID_MONITOR 9 |
| identificator for transparent BRP monitor protocol. More... | |
| #define | BRP_PROTID_CUSTOM(ndx) (0x80+(ndx)) |
| identificator for custom protocols (=not implemented by this library) More... | |
| #define | BRP_LAYERID_ANONYMOUS 0 |
| unnamed protocol layer More... | |
| #define | BRP_LAYERID_IO 1 |
| lowest protocol layer that forwards More... | |
| #define | BRP_LAYERID_BRP 3 |
| data to OS drivers More... | |
| #define | BRP_LAYERID_MONITOR 5 |
| monitoring layer More... | |
| #define | BRP_LAYERID_CRYPTO 4 |
| encryption layer More... | |
| #define | BRP_LAYERID_PLAIN_MONITOR 6 |
| monitoring layer for dencrypted cmds More... | |
| #define | BRP_AES_KEY_SIZE 16 |
| #define | BRP_AES_BLOCK_SIZE 16 |
| #define | BRP_MAX_SECURITY_LEVEL 3 |
| #define | BRP_DEFAULT_TCP_PORT 2939 |
| If a TCP/IP connection is created without specifying a portnr, this default value is used as portnr. More... | |
| #define | BRP_DEFAULT_TCPIP_ROUNDTRIP_TIMEOUT 1500 |
| This is the default time that will be assumed as worst case for a single roundtrip. More... | |
Typedefs | |
| typedef unsigned char * | brp_buf |
| represents a pointer to a protocol data buffer. More... | |
| typedef unsigned long | brp_time |
| absolute/relative timeout/delay in ms. More... | |
| typedef unsigned int | brp_errcode |
| This type is used library-wide for passing error codes in the return value of functions. More... | |
| typedef struct brp_mempool_object_t * | brp_mempool |
| mempool handle. More... | |
| typedef struct brp_protocol_t * | brp_protocol |
| This is a generic handle of a protocol. More... | |
| typedef int | brp_layer_id |
| identifies the layer of a composite protocol stack (see brp_create() or brp_create_composite(). More... | |
| typedef unsigned char | brp_sec_key[BRP_AES_KEY_SIZE] |
| A AES128 key, that is required for crypto operations. More... | |
| typedef unsigned char | brp_sec_iv[BRP_AES_BLOCK_SIZE] |
| A AES IV. More... | |
Functions | |
| BRP_LIB brp_errcode | brp_decode_base64_obj (char *obj_name, brp_frame encoded_frm, brp_frame decoded_frm) |
| This function decodes any BASE64-encoded frame and stores the decoded data in "decoded_frm". More... | |
| BRP_LIB brp_protocol | brp_create_brp (void) |
| Creates a new BRP protocol. More... | |
| BRP_LIB brp_errcode | brp_exec_cmd (brp_protocol protocol, int cmd_code, brp_buf param_buf, size_t param_len, brp_buf resp_buf, size_t max_resp_len, size_t *resp_len, brp_time cmd_timeout) |
| Runs a command on the BRP device connected via the assigned protocol. More... | |
| BRP_LIB brp_errcode | brp_send_cmd (brp_protocol protocol, int cmd_code, brp_buf param_buf, size_t param_len, brp_time cmd_timeout, int mode) |
| Sends a command frame via a BRP protocol. More... | |
| BRP_LIB brp_errcode | brp_recv_cmd (brp_protocol protocol, brp_buf resp_buf, size_t max_resp_len, size_t *resp_len, brp_time timeout) |
| Returns the response of a command runned on the BRP device connected via base_protocol. More... | |
| BRP_LIB brp_errcode | brp_break_cmd (brp_protocol protocol) |
| Stops a command that was run with brp_send_cmd() with the mode parameter set to in BRP_MODE_CONTINUOUS or BRP_MODE_REPEAT. More... | |
| BRP_LIB brp_errcode | brp_exec_Sys_GetInfo (brp_protocol protocol, char *fws) |
| Retrieves the firmware string. More... | |
| BRP_LIB brp_errcode | brp_exec_AR_GetMessage (brp_protocol protocol, int *msg_type, char *msg, size_t max_msg_len, size_t *msg_len) |
| Returns the last message read by device. More... | |
| BRP_LIB brp_errcode | brp_exec_Sys_CfgSetValue (brp_protocol protocol, int key, int value, brp_buf data, size_t data_len) |
| Modifies the devices (permanent) configuration. More... | |
| BRP_LIB brp_errcode | brp_exec_Sys_CfgGetValue (brp_protocol protocol, int key, int value, brp_buf data, size_t max_data_len, size_t *data_len) |
| Retrieves a configuration value from the device. More... | |
| BRP_LIB brp_protocol | brp_create_composite (void) |
| Creates an empty composite protocol. More... | |
| BRP_LIB brp_protocol | brp_create (void) |
| This is equivalent to the following call: More... | |
| BRP_LIB brp_errcode | brp_add_layer (brp_protocol composite_protocol, brp_layer_id layer_id) |
| Adds a protocol layer without assigning a protocol to it. More... | |
| BRP_LIB brp_errcode | brp_set_layer (brp_protocol composite_protocol, brp_layer_id layer_id, brp_protocol layer_protocol) |
| Adds/replaces a protocol layer to a composite protocol. More... | |
| BRP_LIB brp_protocol | brp_get_layer (brp_protocol composite_protocol, brp_layer_id layer_id) |
| Retrieves a protocol layer from a composite protocol. More... | |
| BRP_LIB brp_protocol | brp_detach_layer (brp_protocol composite_protocol, brp_layer_id layer_id) |
| Removes a protocol from a composite protocol stack without destroying. More... | |
| BRP_LIB brp_errcode | brp_set_io (brp_protocol protocol, brp_protocol io_protocol) |
| Assigns an I/O protocol to a composite protocol (protocol stack). More... | |
| BRP_LIB brp_errcode | brp_set_crypto (brp_protocol composite_protocol, brp_protocol crypto_protocol) |
| Assigns a crypto protocol to a composite protocol (protocol stack). More... | |
| BRP_LIB brp_errcode | brp_suppress_monitoring (brp_protocol protocol) |
| Disables the monitoring feature of this library. More... | |
| BRP_LIB void | brp_mempool_free (brp_mempool *mempool) |
| Releases the memory of a brp_mempool. More... | |
| BRP_LIB brp_protocol | brp_create_monitor (void) |
| Creates a new Monitor protocol layer. More... | |
| BRP_LIB char * | brp_map_errcode (brp_errcode errcode) |
| Retrieve name of errorcode. More... | |
| BRP_LIB char * | brp_map_errcode_to_desc (brp_errcode errcode) |
| Retrieve textual description of errorcode in english. More... | |
| BRP_LIB char * | brp_map_errcode_to_docurl (brp_errcode errcode) |
| Retrieve URL of the documentation describing the passed errcode. More... | |
| BRP_LIB char * | brp_map_cmdcode (unsigned cmd_code) |
| Retrieve the name of a (16bit) cmdcode as C string. More... | |
| BRP_LIB char * | brp_map_cmdcode_to_docurl (unsigned cmd_code) |
| Retrieve URL of the documentation describing the passed cmdcode. More... | |
| BRP_LIB brp_protocol | brp_create_pki (int security_level, brp_buf host_cert_chain, size_t host_cert_chain_len, brp_buf dev_ca_cert_chain, size_t dev_ca_cert_chain_len, brp_buf private_key, size_t private_key_len, brp_time session_timeout) |
| Creates a new PKI protocol layer. More... | |
| BRP_LIB brp_errcode | brp_append_host_certs (brp_protocol protocol, brp_buf host_cert_chain, size_t host_cert_chain_len) |
| Adds certificate(s) to the host certificate chain. More... | |
| BRP_LIB brp_errcode | brp_append_dev_ca_certs (brp_protocol protocol, brp_buf dev_ca_cert_chain, size_t dev_ca_cert_chain_len) |
| Adds certificate(s) to the devices CA certificate chain. More... | |
| BRP_LIB brp_errcode | brp_pki_save_session (brp_protocol protocol, brp_buf persistent_buf, size_t peristent_buf_size, size_t *persistent_buf_actlen) |
| This command stores the current PKI session state in a persistent storage for being continued later using brp_pki_restore_session(). More... | |
| BRP_LIB size_t | brp_pki_get_session_buf_size (brp_protocol protocol) |
| Returns the size of the buffer required to store the session state using brp_pki_save_session(). More... | |
| BRP_LIB brp_errcode | brp_pki_restore_session (brp_protocol protocol, brp_buf persistent_buf, size_t persistent_buf_size) |
| This command reloads the current PKI session that was stored by brp_pki_save_session(). More... | |
| BRP_LIB brp_errcode | brp_pki_get_dev_cert (brp_protocol protocol, brp_buf dev_cert_buf, size_t dev_cert_buf_size, size_t *dev_cert_len) |
| This command retrieves the certificate of the device which it created a PKI connection to. More... | |
| BRP_LIB brp_errcode | brp_open (brp_protocol protocol) |
| Set up a connection via this protocol. More... | |
| BRP_LIB brp_errcode | brp_close (brp_protocol protocol) |
| Closes protocol. More... | |
| BRP_LIB brp_errcode | brp_flush (brp_protocol) |
| Deletes all data that is waiting in input buffers for being read via brp_recv_frame() (or brp_recv_fix_frame() / brp_frecv_any_frame()). More... | |
| BRP_LIB brp_errcode | brp_get_io_id (brp_protocol protocol, char **intf_name, brp_frame instance_id) |
| Retrieves the instance name of the I/O-protocol of this protocol stack. More... | |
| BRP_LIB brp_errcode | brp_destroy (brp_protocol) |
| Closes a protocol if opened and frees all allocated resources thereafter. More... | |
| BRP_LIB brp_protocol | brp_create_rs232 (char *dev_name, unsigned baudrate, char parity) |
| Creates a protocol object for RS232/CDC interfaces from the device name. More... | |
| BRP_LIB brp_protocol | brp_create_secure_channel (int security_level, brp_sec_key key, int sec_mode) |
| Creates a new secured channel that allows you to establish an authenticated and encrypted connection over an insecure BRP channel. More... | |
| BRP_LIB brp_errcode | brp_mutual_authenticate (brp_protocol protocol, int security_level, brp_sec_key key, int *req_auth_modes, brp_sec_key session_key) |
| Does a mutual authentication and generates a session key. More... | |
| BRP_LIB brp_errcode | brp_secured_send_frm (brp_protocol protocol, int security_level, int sec_mode, brp_sec_key key, brp_sec_iv iv, int cmd_code, brp_buf param_buf, size_t param_len, brp_time cmd_timeout, int mode) |
| Sends an encrypted command. More... | |
| BRP_LIB brp_errcode | brp_secured_recv_frm (brp_protocol protocol, int sec_mode, brp_sec_key key, brp_sec_iv iv, int cmd_code, brp_frame resp_frm, brp_time timeout) |
| Sends an encrypted command. More... | |
| BRP_LIB brp_protocol | brp_create_tcpip (char *ipaddr) |
| Creates a TCP/IP protocol from an IP address. More... | |
| BRP_LIB brp_protocol | brp_create_tcpip_by_socket (int socket) |
| Creates a TCP/IP protocol from an OS-level socket that was created by the user of the BRP library. More... | |
| BRP_LIB char * | brp_get_tcpip_ipaddr (brp_protocol protocol) |
| Retrieves the ipaddr set in brp_create_tcpip(). More... | |
| BRP_LIB brp_errcode | brp_set_tcpip_roundtrip_timeout (brp_protocol protocol, brp_time timeout) |
| If the value of BRP_DEFAULT_TCPIP_ROUNDTRIP_TIMEOUT is not appropriate it can be finetuned for specific protocol instances via this function. More... | |
| BRP_LIB brp_time | brp_get_tcpip_roundtrip_timeout (brp_protocol protocol) |
| Retrieves the value of the roundtrip timeout set by the last brp_set_tcpip_roundtrip_timeout(). More... | |
| BRP_LIB brp_protocol | brp_create_usb_hid (long long snr) |
| Creates an (USB) HID protocol object from the connected baltech device with serialnumber 'snr'. More... | |
| BRP_LIB char * | brp_get_version (void) |
| Returns the version of the BRP Communication Libary. More... | |
BRP_MODE_XXX | |
| #define | BRP_MODE_STD 0x00 |
| Standard mode. More... | |
| #define | BRP_MODE_NONE BRP_MODE_STD |
| legacy define More... | |
| #define | BRP_MODE_CONTINUOUS 0x01 |
| Continous mode. More... | |
| #define | BRP_MODE_REPEAT 0x02 |
| Repeat mode. More... | |
| #define | BRP_MODE_BREAK 0x03 |
| Stop continuous / repeat mode. More... | |
BRP_MASK_XXX | |
Defines bitmasks for :brp_errcode. If a errcode is and'ed with one of the bitmasks the corresponding part of the error can be extracted. | |
| #define | BRP_ERRMASK_GROUP 0xFFFF0000 |
| #define | BRP_ERRMASK_CODE 0x0000FFFF |
BRP_ERRGRP_XXX | |
| #define | BRP_ERRGRP_DEVICE 0x00010000u |
| A command failed to execute due to a error on the device side which is not host communication related (card error, ...) More... | |
| #define | BRP_ERRGRP_COMM_UNSUPPORTED 0x00800000u |
| A command cannot be executed as the device does not support the requested feature. More... | |
| #define | BRP_ERRGRP_COMM_ACCESSDENIED 0x01000000u |
| A command cannot be executed as the device does not allow access this features in the current operations mode. More... | |
| #define | BRP_ERRGRP_COMM_TIMEOUT 0x02000000u |
| A the device or host exceeded the allowed time for sending a frame. More... | |
| #define | BRP_ERRGRP_COMM_FRAMEFORMAT 0x04000000u |
| The device or host send a frame that does not correspond the expected frame. More... | |
| #define | BRP_ERRGRP_COMM_UNDEFINED 0x08000000u |
| any device <-> host communication problem which is not categoriezed by one of the BRP_ERRGRP_COMM_* macros More... | |
| #define | BRP_ERRGRP_COMMUNICATION 0x0F800000u |
| Any kind of device <-> host communication problem. More... | |
| #define | BRP_ERRGRP_LIB_INVALIDCALL 0x10000000u |
| The libraries API was used in an invalid manner. More... | |
| #define | BRP_ERRGRP_LIB_NONRECOVERABLE 0x20000000u |
| A fatal error occured, which the library cannot recover from. More... | |
| #define | BRP_ERRGRP_LIB_OS 0x40000000u |
| A error in the operating system layer (i.e. More... | |
| #define | BRP_ERRGRP_LIB_UNDEFINED 0x80000000u |
| any library specific error which is not one of the BRP_ERRGRP_LIB_* macros. More... | |
| #define | BRP_ERRGRP_LIBRARY 0xF0000000u |
| Any error which occured in the library. More... | |
BRP_ERR_XXX | |
A list of standard error codes that required all over this library. | |
| #define | BRP_OK 0x00000000u |
| If a function of return type :brp_errcode runs properly, it returns this value. More... | |
| #define | BRP_ERR_INTERNAL (0x0001u | BRP_ERRGRP_LIB_NONRECOVERABLE) |
| This error must not be returned if the library operatares correctly. More... | |
| #define | BRP_ERR_CMD_TIMEOUT (0x0002u | BRP_ERRGRP_COMM_TIMEOUT) |
| A BRP command that was send by brp_send_frame() exceeded the specified timeout (see also brp_send_cmd() / brp_exec_cmd()). More... | |
| #define | BRP_ERR_FRAMEFORMAT (0x0003u | BRP_ERRGRP_COMM_FRAMEFORMAT) |
| The frame returned from the reader does not match the format expected by the BRP protocol. More... | |
| #define | BRP_ERR_INVALID_API_CALL (0x0004u | BRP_ERRGRP_LIB_INVALIDCALL) |
| Returned if the a parameter contains an invalid value. More... | |
| #define | BRP_ERR_OUT_OF_MEMORY (0x0005u | BRP_ERRGRP_LIB_NONRECOVERABLE) |
| The heap has not enough memory to allocate a buffer that is required for the wanted operation. More... | |
| #define | BRP_ERR_NOT_IMPLEMENTED (0x0006u | BRP_ERRGRP_LIB_INVALIDCALL) |
| The requested feature is not implemented yet. More... | |
| #define | BRP_ERR_BUSY (0x0007u | BRP_ERRGRP_LIB_INVALIDCALL) |
| The Library is not ready to send/receive data. More... | |
| #define | BRP_ERR_CLOSED (0x0008u | BRP_ERRGRP_LIB_INVALIDCALL) |
| The protocol/device is not opened. More... | |
| #define | BRP_ERR_BUFFER_OVERFLOW (0x0009u | BRP_ERRGRP_COMM_FRAMEFORMAT) |
| A Command's response is bigger than the buffer provided for the response. More... | |
| #define | BRP_ERR_OPEN_IO (0x000Au | BRP_ERRGRP_LIB_OS) |
| Failed to open the I/O connection. More... | |
| #define | BRP_ERR_WRITE_IO (0x000Bu | BRP_ERRGRP_LIB_OS) |
| Failed to send data via IO connection. More... | |
| #define | BRP_ERR_WAIT_IO (0x000Cu | BRP_ERRGRP_LIB_OS) |
| Failed to wait for data via IO connection. More... | |
| #define | BRP_ERR_READ_IO (0x000Du | BRP_ERRGRP_LIB_OS) |
| Failed to wait for data via IO connection. More... | |
| #define | BRP_ERR_CLOSE_IO (0x000Eu | BRP_ERRGRP_LIB_OS) |
| Failed to open the I/O connection. More... | |
| #define | BRP_ERR_PAYLOAD_FORMAT (0x000Fu | BRP_ERRGRP_COMM_FRAMEFORMAT) |
| The payload of a frame has invalid format. More... | |
| #define | BRP_ERR_CRYPTO_FORMAT (0x0010u | BRP_ERRGRP_COMM_FRAMEFORMAT) |
| The payload of a encrypted/PKI command or a PKI certificate had invalid format/response. More... | |
| #define | BRP_ERR_PKI_FORMAT BRP_ERR_CRYPTO_FORMAT |
| #define | BRP_ERR_DEV_CERT_FORMAT (0x0011u | BRP_ERRGRP_COMM_FRAMEFORMAT) |
| The devices PKI end-Certificate had invalid format. More... | |
| #define | BRP_ERR_HOST_CERT_FORMAT (0x00012u | BRP_ERRGRP_COMM_FRAMEFORMAT) |
| The hosts PKI Certificate or the devices CA certificates (which are stored on the host!) had invalid format. More... | |
| #define | BRP_ERR_PKI_OPERATION_FAILED (0x0013u | BRP_ERRGRP_LIB_NONRECOVERABLE) |
| A PKI operation cannot be executed. More... | |
| #define | BRP_ERR_DEV_CERT_INVALID_SIGNATURE (0x0014u | BRP_ERRGRP_COMM_ACCESSDENIED) |
| The ECC certificate of the device is invalid. More... | |
| #define | BRP_ERR_HOST_CERT_INVALID_SIGNATURE (0x0015u | BRP_ERRGRP_COMM_ACCESSDENIED) |
| The ECC certificate of the host is invalid or the devices CA certificates (which are stored on the host!) have invalid signature. More... | |
| #define | BRP_ERR_SEC_LEVEL_NOT_SUPPORTED (0x0016u | BRP_ERRGRP_COMM_ACCESSDENIED) |
| The given securitylevel is not supported. More... | |
| #define | BRP_ERR_SEQ_CTR_NOT_IN_SYNC (0x0017u | BRP_ERRGRP_COMM_ACCESSDENIED) |
| The sequence counter is not in sync any more. More... | |
| #define | BRP_ERR_INVALID_HMAC (0x0018u | BRP_ERRGRP_COMM_ACCESSDENIED) |
| The HMAC is invalid. More... | |
| #define | BRP_ERR_CRYPTO_RECV_DEV (0x0019u | BRP_ERRGRP_COMM_ACCESSDENIED) |
| device failed to decrypt PKI command successfully More... | |
| #define | BRP_ERR_UNSUPPORTED_COMMAND (0x0020u | BRP_ERRGRP_COMM_UNSUPPORTED) |
| The specified BRP command is not supported by the connected device. More... | |
| #define | BRP_ERR_COMMAND_DENIED (0x0021u |BRP_ERRGRP_COMM_ACCESSDENIED) |
| The BRP command is not allowed to be executed from the current security level. More... | |
| #define | BRP_ERR_UNEXPECTED_FRAME (0x0022u | BRP_ERRGRP_COMM_FRAMEFORMAT) |
| The received frame is a valid BRP frame but not expected in this protocol state. More... | |
| #define | BRP_ERR_TIMEOUT (0x0023u | BRP_ERRGRP_COMM_TIMEOUT) |
| The response to a brp_recv_frame() / brp_recv_any_frame() is not returned within the specified timeout. More... | |
| #define | BRP_ERR_CALLED_INVALID_FRAME (0x0024u | BRP_ERRGRP_LIB_INVALIDCALL) |
| Returned if the a frame passed to a function to be transferred to the device has invalid format. More... | |
| #define | BRP_ERR_EXISTING_LAYER (0x0025u | BRP_ERRGRP_LIB_INVALIDCALL) |
| The layer is tried to be added to a composite protocol (see brp_add_layer() / brp_set_layer()) although already added earliert. More... | |
| #define | BRP_ERR_GEN_RANDOM_DATA (0x0026u | BRP_ERRGRP_LIB_OS) |
| The OS failed to generate a random number. More... | |
| #define | BRP_ERR_INVALID_KEY (0x0027u | BRP_ERRGRP_COMM_ACCESSDENIED) |
| The readers KEY does not match the key of the host. More... | |
| #define | BRP_ERR_STATUS(cmd_code, statuscode) |
| Error codes that happen on the reader side are encoded by this macro. More... | |
BRP_SECMODE_ Security Modes | |
BRP_SECMODE_* specifies the level of security that shall be applied when establishing a secure channel. Internally this bitmask is translated to the authmode bitmask. | |
| #define | BRP_SECMODE_STD 0 |
| This is the recommended setting as it provides ideal security. More... | |
| #define | BRP_SECMODE_PLAIN 1 |
| Same as BRP_SECMODE_STD, except that encryption is disabled. More... | |
| #define | BRP_SECMODE_STATELESS 2 |
| Allows secured communication without session handling. More... | |