Documentation
Peripheral Device
The following functions are used when OSDP is used in PD mode. The library returns a single opaque pointer of type osdp_t where it maintains all internal data. All applications consuming this library must pass this context pointer to all API calls.
Device Lifecycle Management
The PD is described to osdp_pd_setup with an osdp_pd_info_t structure.
typedef void osdp_tTo keep the OSDP internal data structures from polluting the exposed headers, they are typedefed to void before sending them to the upper layers. This level of abstraction looked reasonable as technically no one should attempt to modify it outside of the LibOSDP and their definition may change at any time.
osdp_t * osdp_pd_setup(struct osdp_channel *channel, const osdp_pd_info_t *info)This method is used to setup a device in PD mode. Application must store the returned context pointer and pass it back to all OSDP functions intact.
channelPointer to channel ops used for this PD context.infoPointer to info struct populated by application.OSDPContext on successNULLon errorsvoid osdp_pd_refresh(osdp_t *ctx)Periodic refresh method. Must be called by the application at least once every 50ms to meet OSDP timing requirements.
ctxOSDP contextvoid osdp_pd_teardown(osdp_t *ctx)Cleanup all osdp resources. The context pointer is no longer valid after this call.
ctxOSDP contextPD Capabilities
See PD capabilities for the full list of function codes and compliance levels a PD can advertise.
PD capability structure. Each PD capability has a 3 byte representation.
enum osdp_pd_cap_function_code_e function_codeuint8_t compliance_leveluint8_t num_itemsVarious PD capability function codes.
OSDP_PD_CAP_UNUSEDOSDP_PD_CAP_CONTACT_STATUS_MONITORINGOSDP_PD_CAP_OUTPUT_CONTROLOSDP_PD_CAP_CARD_DATA_FORMATOSDP_PD_CAP_READER_LED_CONTROLOSDP_PD_CAP_READER_AUDIBLE_OUTPUTOSDP_PD_CAP_READER_TEXT_OUTPUTOSDP_PD_CAP_TIME_KEEPINGOSDP_PD_CAP_CHECK_CHARACTER_SUPPORTOSDP_PD_CAP_COMMUNICATION_SECURITYOSDP_PD_CAP_RECEIVE_BUFFERSIZEOSDP_PD_CAP_LARGEST_COMBINED_MESSAGE_SIZEOSDP_PD_CAP_SMART_CARD_SUPPORTOSDP_PD_CAP_READERSOSDP_PD_CAP_BIOMETRICSOSDP_PD_CAP_SECURE_PIN_ENTRYOSDP_PD_CAP_OSDP_VERSIONOSDP_PD_CAP_SENTINELvoid osdp_pd_set_capabilities(osdp_t *ctx, const struct osdp_pd_cap *cap)Set PD's capabilities.
ctxOSDP contextcappointer to array of cap (struct osdp_pd_cap) terminated by a capability with cap->function_code set to OSDP_PD_CAP_SENTINEL.Commands
typedef int(* pd_command_callback_t) (void *arg, struct osdp_cmd *cmd)Callback for PD command notifications. After it has been registered with osdp_pd_set_command_callback, this method is invoked when the PD receives a command from the CP.
argpointer that will was passed to the arg param of osdp_pd_set_command_callback.cmdpointer to the received command.0if LibOSDP must send an osdp_ACK response.-veif LibOSDP must send an osdp_NAK response.+veis reserved.void osdp_pd_set_command_callback(osdp_t *ctx, pd_command_callback_t cb, void *arg)Set callback method for PD command notification. This callback is invoked when the PD receives a command from the CP.
ctxOSDP contextcbThe callback function's pointerargA pointer that will be passed as the first argument of cbRefer to the command structure document for more information on how the cmd structure is framed.
For CMD_MFG, callback return values use normal ACK/NAK behavior (negative return → NAK, non-negative return → ACK). Any manufacturer-specific reply payload must be sent asynchronously by submitting an OSDP_EVENT_MFGREP event with osdp_pd_submit_event.
Events
When a PD app has an event (card read, key press, etc.) to report to the CP, it creates the corresponding event structure and calls osdp_pd_submit_event to deliver it to the CP on the next osdp_POLL command.
int osdp_pd_submit_event(osdp_t *ctx, const struct osdp_event *event)Submit PD events to CP. These events are delivered to the CP as a response to a future POLL command. A successful return does not mean CP received it, it only means LibOSDP accepted this submission.
ctxOSDP contexteventpointer to event struct. Must be filled by application.0on success-1on failureAn accepted event is queued by reference; LibOSDP does not copy it. The event you pass must stay alive and unmodified from a successful submission until the library is done with it. An event that lives on the stack of a function that returns (a command callback, say), or one reused for a second submission while the first is still queued, corrupts the queue.
Ownership returns to your application when the event completion callback fires for that pointer (register it with osdp_pd_set_event_completion_callback). Every accepted event is reported exactly once — including those dropped by osdp_pd_flush_events (OSDP_COMPLETION_FLUSHED) and osdp_pd_teardown (OSDP_COMPLETION_ABORTED) — so a heap-allocated event should be freed in that callback. On a -1 return the event was never queued and is yours to reuse at once.
int osdp_pd_flush_events(osdp_t *ctx)Deletes all events from the PD's event queue.
ctxOSDP contextintint Count of events dequeued.Event Completion
Register a completion callback to learn when each submitted event leaves your ownership. The outcome is reported as an osdp_completion_status.
typedef void(* pd_event_completion_callback_t) (void *arg, const struct osdp_event *ev, enum osdp_completion_status status)Callback for PD event completion notifications.
void osdp_pd_set_event_completion_callback(osdp_t *ctx, pd_event_completion_callback_t cb, void *arg)Set callback method for PD event completion.
ctxOSDP contextcbCallback function pointerargOpaque pointer passed as first callback argumentRefer to the event structure document for more information on how to populate the event structure.
Deprecated
osdp_pd_notify_event is retained for backward compatibility; new code should use osdp_pd_submit_event instead.
int osdp_pd_notify_event(osdp_t *ctx, const struct osdp_event *event)API to notify PD events to CP. These events are sent to the CP as an alternate response to a POLL command.
ctxOSDP contexteventpointer to event struct. Must be filled by application.0on success-1on failure