Documentation

Peripheral Device

The following functions are used when OSDP is used in PD mode. The libraryreturns a single opaque pointer of type osdp_t where it maintains allinternal data. All applications consuming this library must pass this contextpointer to all API calls.

Device Lifecycle Management ​

typedefosdp_t
typedef void osdp_t

To 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.

functionosdp_pd_setup
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.

Parameters
channelPointer to channel ops used for this PD context.
infoPointer to info struct populated by application.
Returns
OSDPContext on success
NULLon errors
functionosdp_pd_refresh
void 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.

Parameters
ctxOSDP context
functionosdp_pd_teardown
void osdp_pd_teardown(osdp_t *ctx)

Cleanup all osdp resources. The context pointer is no longer valid after this call.

Parameters
ctxOSDP context

PD Capabilities ​

structosdp_pd_cap

PD capability structure. Each PD capability has a 3 byte representation.

Members
uint8_t function_code
Capability function code. See osdp_pd_cap_function_code_e
uint8_t compliance_level
A function_code dependent number that indicates what the PD can do with this capability.
uint8_t num_items
Number of such capability entities in PD
functionosdp_pd_set_capabilities
void osdp_pd_set_capabilities(osdp_t *ctx, const struct osdp_pd_cap *cap)

Set PD's capabilities.

Parameters
ctxOSDP context
cappointer to array of cap (struct osdp_pd_cap) terminated by a capability with cap->function_code set to 0.

Commands ​

typedefpd_command_callback_t
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.

Parameters
argpointer that will was passed to the arg param of osdp_pd_set_command_callback.
cmdpointer to the received command.
Returns
0if LibOSDP must send an osdp_ACK response.
-veif LibOSDP must send an osdp_NAK response.
+veis reserved.
functionosdp_pd_set_command_callback
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.

Parameters
ctxOSDP context
cbThe callback function's pointer
argA pointer that will be passed as the first argument of cb

Refer to the command structure document for moreinformation on how the cmd structure is framed.

Info

For CMD_MFG, callback return values use normal ACK/NAK behavior (negativereturn → NAK, non-negative return → ACK). Any manufacturer-specific replypayload must be sent asynchronously by submitting an OSDP_EVENT_MFGREP eventwith 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_eventto deliver it to the CP on the next osdp_POLL command.

functionosdp_pd_submit_event
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.

Parameters
ctxOSDP context
eventpointer to event struct. Must be filled by application.
Returns
0on success
-1on failure
functionosdp_pd_flush_events
int osdp_pd_flush_events(osdp_t *ctx)

Deletes all events from the PD's event queue.

Parameters
ctxOSDP context
Returns
intint Count of events dequeued.

Refer to the event structure document for moreinformation on how to populate the event structure.