Documentation

Application Events

LibOSDP exposes the following structures through osdp.h. All events are carried in a single union wrapper:

structosdp_event

OSDP Event structure.

Members
osdp_queue_node_t _node
Reserved: internal queue linkage
enum osdp_event_type type
Event type. Used to select specific event in union
uint32_t flags
Flags; reserved, set to zero
struct osdp_event_keypress keypress
Keypress event structure
struct osdp_event_cardread cardread
Card read event structure
struct osdp_event_mfgrep mfgrep
Manufacturer specific response event struture
struct osdp_event_mfgstat mfgstatr
Manufacturer specific status reply event structure
struct osdp_event_mfgstat mfgerrr
Manufacturer specific error reply event structure
struct osdp_event_bioreadr bioreadr
Biometric read reply event structure
struct osdp_event_biomatchr biomatchr
Biometric match reply event structure
struct osdp_event_piv_reply piv_reply
Smartcard/PIV reply event structure
struct osdp_status_report status
Status report event structure
struct osdp_notification notif
LibOSDP notification (CP mode)
union osdp_event::@4 @5
Event

The type field selects the active union member and is one of osdp_event_type:

enumosdp_event_type

OSDP PD Events.

Values
OSDP_EVENT_CARDREAD
Card read event
OSDP_EVENT_KEYPRESS
Keypad press event
OSDP_EVENT_MFGREP
Manufacturer specific reply event
OSDP_EVENT_STATUS
Status event
OSDP_EVENT_NOTIFICATION
LibOSDP notification event
OSDP_EVENT_MFGSTATR
Manufacturer specific status reply event
OSDP_EVENT_MFGERRR
Manufacturer specific error reply event
OSDP_EVENT_BIOREADR
Scan and send biometric data event
OSDP_EVENT_BIOMATCHR
Scan and match biometric template event
OSDP_EVENT_PIVDATAR
PIV data reply event
OSDP_EVENT_GENAUTHR
General authenticate reply event
OSDP_EVENT_CRAUTHR
Challenge/response authenticate reply event
OSDP_EVENT_SENTINEL
Max event value

Below are the structures for each event type. They are delivered to the CP with osdp_pd_submit_event.

Key Press Event ​

structosdp_event_keypress

OSDP Event Keypad.

Members
int reader_no
Target reader: 0 is this PD, 1 the first attached reader, and so on. Must fit within the PD's OSDP_PD_CAP_READERS capability.
int length
Length of keypress data in bytes
uint8_t data
Keypress data of length bytes
defineOSDP_EVENT_KEYPRESS_MAX_DATALEN
64

Max keypress data, in bytes, that a keypad event can carry. One byte per key, so this bounds the number of keys a PD can report in one event.

Card Read Event ​

structosdp_event_cardread

OSDP event cardread.

Members
int reader_no
Target reader: 0 is this PD, 1 the first attached reader, and so on. Must fit within the PD's OSDP_PD_CAP_READERS capability.
enum osdp_event_cardread_format_e format
Format of the card being read.
int direction
Direction of data in data array. - 0 - Forward - 1 - Backward
uint16_t length
Length of card data in bits. Carried as a 16-bit value on the wire.
uint8_t data
Card data of length bytes or bits bits depending on format
enumosdp_event_cardread_format_e

Various card formats that a PD can support. This is sent to CP when a PD must report a card read.

Values
OSDP_CARD_FMT_RAW_UNSPECIFIED
Unspecified card format
OSDP_CARD_FMT_RAW_WIEGAND
Wiegand card format
OSDP_CARD_FMT_ASCII
ASCII card format (deprecated; don't use)
OSDP_CARD_FMT_SENTINEL
Max card format value
defineOSDP_EVENT_CARDREAD_MAX_DATALEN
64

Max card data, in bytes, that a card read event can carry. Note that the event's length field is in bits or bytes depending on the card format, but this bound is always in bytes.

Manufacturer Specific Reply Event ​

structosdp_event_mfgrep

OSDP Event Manufacturer Specific Command.

Members
uint32_t vendor_code
3-bytes IEEE assigned OUI of manufacturer
uint8_t length
Length of manufacturer data in bytes (optional)
uint8_t data
Manufacturer data of length bytes (optional)
defineOSDP_EVENT_MFGREP_MAX_DATALEN
128

Max vendor defined data, in bytes, that a manufacturer specific reply can carry.

Manufacturer Specific Status Event ​

structosdp_event_mfgstat

OSDP Event Manufacturer Specific Status/Error Reply.

Members
uint8_t length
Length of manufacturer data in bytes
uint8_t data
Manufacturer data of length bytes
defineOSDP_EVENT_MFGSTAT_MAX_DATALEN
128

Max vendor defined data, in bytes, that a manufacturer specific status or error reply can carry.

Biometric Events ​

structosdp_event_bioreadr

OSDP Event Scan and Send Biometric Data.

Members
uint8_t reader
Target reader: 0 is this PD, 1 the first attached reader, and so on. Must fit within the PD's OSDP_PD_CAP_READERS capability.
enum osdp_biometric_status_e status
Outcome of the scan. See osdp_biometric_status_e. The remaining fields are valid only when this is OSDP_BIO_STATUS_SUCCESS.
enum osdp_biometric_type_e type
Body part that was scanned. See osdp_biometric_type_e Note: The OSDP spec carries no format field in this reply.
uint8_t quality
Scan quality; 0x00 is worst, 0xFF is best
uint16_t length
Length of the template in data
uint8_t data
The scanned image or template
structosdp_event_biomatchr

OSDP Event Scan and Match Biometric Template.

Members
uint8_t reader
Target reader: 0 is this PD, 1 the first attached reader, and so on. Must fit within the PD's OSDP_PD_CAP_READERS capability.
enum osdp_biometric_status_e status
Outcome of the scan. See osdp_biometric_status_e. score is valid only when this is OSDP_BIO_STATUS_SUCCESS.
uint8_t score
Result of the biometric match; 0x00 is no match, 0xFF is best match
defineOSDP_EVENT_BIOREADR_MAX_TEMPLATE_LEN
256

Max biometric template carried in a BIOREADR reply.

A REPLY_BIOREADR template normally has to fit in one packet. Setting OSDP_FLAG_BIOREADR_MULTIPART on both roles lets LibOSDP split a larger template across fragments — a non-conforming, opt-in extension. See Multi-part Messages.

Status Report Request Event ​

structosdp_status_report

Status report structure. Used by OSDP_CMD_STATUS and OSDP_EVENT_STATUS. In case of command, it is used to send a query to the PD while in the case of events, the PD responds back with this structure.

Members
enum osdp_status_report_type type
The kind of event to report see enum osdp_event_status_type_e
int nr_entries
Number of valid entries in report
uint8_t report
Status report; one byte per entry
enumosdp_status_report_type

OSDP Status report types.

Values
OSDP_STATUS_REPORT_INPUT
Status report of the inputs attached the PD.
OSDP_STATUS_REPORT_OUTPUT
Status report of the output attached the PD.
OSDP_STATUS_REPORT_LOCAL
Local tamper and power status report.
OSDP_STATUS_REPORT_READER
Reader tamper status report.

Notifications ​

When enabled with OSDP_FLAG_ENABLE_NOTIFICATION, LibOSDP reports internal state changes to the application through these structures.

structosdp_notification

LibOSDP notification payload.

Members
enum osdp_notification_type type
Notification type
struct osdp_notification_command command
COMMAND
struct osdp_notification_sc_status sc_status
SC_STATUS
struct osdp_notification_pd_status pd_status
PD_STATUS
struct osdp_mp_notification mp
MP_*
struct osdp_pd_id pd_id
PD_ID
union osdp_notification::@0 @1
enumosdp_notification_type

LibOSDP notification type.

Values
OSDP_NOTIFICATION_COMMAND
Application command outcome report. Payload: command (osdp_notification_command).
OSDP_NOTIFICATION_SC_STATUS
Secure Channel state change. Payload: sc_status (osdp_notification_sc_status). Fires on both CP and PD. In CP mode it reports the state of the SC session with the addressed PD; in PD mode it reports the state of the SC session with the CP.
OSDP_NOTIFICATION_PD_STATUS
Peer link state change. Payload: pd_status (osdp_notification_pd_status). In CP mode: the addressed PD has gone online or offline. In PD mode: the CP has become reachable (inbound traffic observed) or unreachable (no CP activity for OSDP_PD_ONLINE_TOUT_MS).
OSDP_NOTIFICATION_MP_START
Multipart transfer opened. mp carries mp_type/object_id/total.
OSDP_NOTIFICATION_MP_PROGRESS
Multipart fragment committed. mp.offset/mp.total advance.
OSDP_NOTIFICATION_MP_DONE
Multipart transfer terminated. mp.outcome is set.
OSDP_NOTIFICATION_PD_ID
PD ID collected (CP mode). Payload: pd_id (osdp_pd_id). Fires when the CP reads a PD's identity (osdp_PDID) during the INIT handshake and it differs from the last one seen for that PD: on first contact, or if the device answering an address changed. A reconnect that reports the same identity is silent.