Documentation

Miscellaneous

Debugging and Diagnostics ​

For how to configure the logger and capture packet/data traces, see the Debugging guide.

enumosdp_log_level_e

Different levels of log messages; based on importance of the message with LOG_EMERG being most critical to LOG_DEBUG being the least.

Values
OSDP_LOG_EMERG
Log level Emergency
OSDP_LOG_ALERT
Log level Alert
OSDP_LOG_CRIT
Log level Critical
OSDP_LOG_ERROR
Log level Error
OSDP_LOG_WARNING
Log level Warning
OSDP_LOG_NOTICE
Log level Notice
OSDP_LOG_INFO
Log level Info
OSDP_LOG_DEBUG
Log level Debug
OSDP_LOG_MAX_LEVEL
Log level max value
functionosdp_logger_init
void osdp_logger_init(const char *name, int log_level, osdp_log_puts_fn_t puts_fn)

Configure OSDP Logging.

Parameters
nameA soft name for this module; will appear in all the log lines.
log_levelOSDP log levels of type enum osdp_log_level_e. Default is LOG_INFO.
puts_fnA puts() like function that will be invoked to write the log buffer. Can be handy if you want to log to file on a UART device without putchar redirection. See osdp_log_puts_fn_t definition to see the behavioral expectations. When this is set to NULL, LibOSDP will log to stderr.

The logger can route output either through a simple puts-style sink or a richer structured callback.

typedefosdp_log_puts_fn_t
typedef int(* osdp_log_puts_fn_t) (const char *msg)

Puts a string to the logging medium.

Parameters
msga null-terminated char buffer.
Returns
0on success; -ve on errors
typedefosdp_log_callback_fn_t
typedef void(* osdp_log_callback_fn_t) (int pd, int log_level, const char *msg, const char *file, unsigned long line)

A callback function to be used with external loggers.

Parameters
pdAddress of PD associated with this message; -1 for non-PD/system logs
log_levelA syslog style log level. See enum osdp_log_level_e
msgThe log message
fileRelative path to file which produced the log message
lineLine number in file which produced the log message
functionosdp_set_log_callback
void osdp_set_log_callback(osdp_log_callback_fn_t cb)

Set logging callback for LibOSDP.

Parameters
cbThe callback function. See osdp_log_callback_fn_t for more details.
functionosdp_get_version
const char * osdp_get_version()

Get LibOSDP version as a const char *. Used in diagnostics.

Returns
versionstring
functionosdp_get_source_info
const char * osdp_get_source_info()

Get LibOSDP source identifier as a const char *. This string has info about the source tree from which this version of LibOSDP was built. Used in diagnostics.

Returns
sourceidentifier string

Status and Metrics ​

functionosdp_get_status_mask
void osdp_get_status_mask(const osdp_t *ctx, uint8_t *bitmask)

Get a bit mask of number of PD that are online currently.

Parameters
ctxOSDP context
bitmaskpointer to an array of bytes. must be as large as (num_pds + 7 / 8).
functionosdp_get_sc_status_mask
void osdp_get_sc_status_mask(const osdp_t *ctx, uint8_t *bitmask)

Get a bit mask of number of PD that are online and have an active secure channel currently.

Parameters
ctxOSDP context
bitmaskpointer to an array of bytes. must be as large as (num_pds + 7 / 8).
structosdp_metrics

Link/protocol health counters accumulated since the last osdp_get_metrics() call.

Members
uint32_t packets_sent
Packets transmitted successfully on the wire. Counted once per packet handed to the channel driver with its full payload.
uint32_t packets_received
Packets received with a well-formed frame. Frames that failed the CRC/checksum integrity check are still counted here; only frames rejected earlier (bad SOM, bad length, bad direction bit, etc.) are excluded.
uint32_t packet_check_errors
Inbound frames rejected at the integrity-check stage. Merged counter across CRC-16 and single-byte checksum failures — the check used is implicit in the negotiated capability.
uint32_t nak_count
REPLY_NAK packets observed on this context. On a PD-mode context these are NAKs transmitted; on a CP-mode context these are NAKs received. Direction is implicit from the role.
uint32_t sc_handshake_count
Successful secure-channel activations (post-SCRYPT).
uint32_t sc_failure_count
Secure-channel tear-downs of a previously active session.
uint32_t command_count
Commands processed at the application callback boundary.
uint32_t event_count
Events dispatched to the application callback.
functionosdp_get_metrics
int osdp_get_metrics(osdp_t *ctx, int pd_idx, struct osdp_metrics *out)

Read and reset link/protocol health counters for one PD slot.

Parameters
ctxOSDP context
pd_idxPD index to snapshot (0..NUM_PD-1)
outDestination struct filled with the current counter values. The counters for this PD are then cleared to zero.
Returns
0on success, -1 on invalid arguments.

File Operations ​

Register a set of file callbacks so LibOSDP can drive an OSDP file transfer against storage your application controls.

typedefosdp_file_open_fn_t
typedef int(* osdp_file_open_fn_t) (void *arg, int file_id, uint32_t *size)

Open a pre-agreed file.

Parameters
argOpaque pointer that was provided in osdp_file_ops when the ops struct was registered.
file_idFile ID of pre-agreed file between this CP and PD
sizeSize of the file that was opened (to be populated by sender). In case of receiver, this value is just just input to indicate the incoming file size.
Returns
0on success
-1on errors
typedefosdp_file_read_fn_t
typedef int(* osdp_file_read_fn_t) (void *arg, void *buf, uint32_t size, uint32_t offset)

Read a chunk of file data into buffer.

Parameters
argOpaque pointer that was provided in osdp_file_ops when the ops struct was registered.
bufBuffer to store file data read
sizeNumber of bytes to read from file into buffer
offsetNumber of bytes from the beginning of the file to start reading from.
Returns
Numberof bytes read
0on EOF
-veon errors.
typedefosdp_file_write_fn_t
typedef int(* osdp_file_write_fn_t) (void *arg, const void *buf, uint32_t size, uint32_t offset)

Write a chunk of file data from buffer to disk.

Parameters
argOpaque pointer that was provided in osdp_file_ops when the ops struct was registered.
bufBuffer with file data to be stored to disk
sizeNumber of bytes to write to disk
offsetNumber of bytes from the beginning of the file to start writing too.
Returns
Numberof bytes written
0on EOF
-veon errors.
typedefosdp_file_close_fn_t
typedef int(* osdp_file_close_fn_t) (void *arg)

Close file that corresponds to a given file descriptor.

Parameters
argOpaque pointer that was provided in osdp_file_ops when the ops struct was registered.
Returns
0on success
-1on errors.
structosdp_file_ops

OSDP File operations struct that needs to be filled by the CP/PD application and registered with LibOSDP using osdp_file_register_ops() before a file transfer command can be initiated.

Members
void * arg
A opaque pointer to private data that can be filled by the application which will be passed as the first argument for each of the below functions. Applications can keep their file context info such as the open file descriptors or any other private data here.
osdp_file_open_fn_t open
open handler function
osdp_file_read_fn_t read
read handler function
osdp_file_write_fn_t write
write handler function
osdp_file_close_fn_t close
close handler function
functionosdp_file_register_ops
int osdp_file_register_ops(osdp_t *ctx, int pd, const struct osdp_file_ops *ops)

Register a global file operations struct with OSDP. Both CP and PD modes should have done so already before CP can sending a OSDP_CMD_FILE_TX.

Parameters
ctxOSDP context
pdPD number in case of CP. This param is ignored in PD mode
opsPopulated file operations struct
Returns
0on success. -1 on errors.
Doxygen entry not found: enum::osdp_file_tx_outcome
functionosdp_get_file_tx_status
int osdp_get_file_tx_status(const osdp_t *ctx, int pd, uint32_t *size, uint32_t *offset)

Query file transfer status if one is in progress. Calling this method when there is no file transfer progressing will return error.

Parameters
ctxOSDP context
pdPD number in case of CP. This param is ignored in PD mode
sizeTotal size of the file (as obtained from file_ops->open())
offsetOffset into the file that has been sent/received (CP/PD)
Returns
0on success. -1 on errors.