From 59b2abf2065135965da51932f5a25bced61140d2 Mon Sep 17 00:00:00 2001 From: Siddharth Chandrasekaran Date: Tue, 12 Mar 2024 21:20:29 +0100 Subject: [PATCH] api: Fix doxygen comments style all over osdp.h Signed-off-by: Siddharth Chandrasekaran --- README.md | 4 +- doc/index.rst | 43 ++- include/osdp.h | 804 +++++++++++++++++++++++++++---------------------- 3 files changed, 489 insertions(+), 362 deletions(-) diff --git a/README.md b/README.md index 98925d37..203aa512 100644 --- a/README.md +++ b/README.md @@ -62,11 +62,11 @@ app must call this method at least once every 50ms. After this point, the CP context can, - send commands to any one of the PDs (to control LEDs, Buzzers, etc.,) - - register a closure for events that are sent from a PD + - register a callback for events that are sent from a PD and the PD context can, - notify it's controlling CP about an event (card read, key press, etc.,) - - register a closure for commands issued by the CP + - register a callback for commands issued by the CP ## Language Support diff --git a/doc/index.rst b/doc/index.rst index 49b417c6..9d7122f6 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -32,7 +32,9 @@ This protocol is developed and maintained by `Security Industry Association`_ Salient Features of LibOSDP --------------------------- - - Supports secure channel communication (AES-128) + - Supports secure channel communication (AES-128) by default and provides a + custom init-time flag to enforce a higher level of security not mandated by + the specification - Can be used to setup a PD or CP mode of operation - Exposes a well defined contract though a single header file - Cross-platform; runs on bare-metal, Linux, Mac, and even Windows @@ -45,6 +47,44 @@ Salient Features of LibOSDP to ensure higher quality of releases. - Built-in, sophisticated, debugging infrastructure and tools ([see][14]). +Usage Overview +-------------- + +A device complying with OSDP can either be a CP or a PD. There can be only one +CP on a bus which can talk to multiple PDs. LibOSDP allows your application to +work either as a CP or a PD so depending on what you want to do you have to do +some things differently. + +LibOSDP creates the following constructs which allow interactions between +devices on the OSDP bus. These should not be confused with the protocol +specified terminologies that may use the same names. They are: + +- Channel - Something that allows two OSDP devices to talk to each other +- Commands - A call for action from a CP to one of its PDs +- Events - A call for action from a PD to its CP + +You start by implementing the `osdp_channel` interface; this allows LibOSDP to +communicate with other osdp devices on the bus. Then you describe the PD you +are + +- talking to on the bus (in case of CP mode of operation) or, +- going to behave as on the bus (in case of PD mode of operation) + +by using the `osdp_pd_info_t` struct. + +You can use `osdp_pd_info_t` struct (or an array of it in case of CP) to create +a `osdp_t` context. Then your app needs to call the `osdp_cp/pd_refresh()` as +frequently as possible. To meet the OSDP specified timing requirements, your +app must call this method at least once every 50ms. + +After this point, the CP context can, + - send commands to any one of the PDs (to control LEDs, Buzzers, etc.,) + - register a callback for events that are sent from a PD + +and the PD context can, + - notify it's controlling CP about an event (card read, key press, etc.,) + - register a callback for commands issued by the CP + Supported Commands and Replies ------------------------------ @@ -64,6 +104,7 @@ of the protocol support only the most common among them. You can see a libosdp/secure-channel libosdp/debugging libosdp/compatibility + libosdp/production-usage .. toctree:: :caption: Protocol diff --git a/include/osdp.h b/include/osdp.h index 2b2c738c..c83e39c1 100644 --- a/include/osdp.h +++ b/include/osdp.h @@ -4,6 +4,11 @@ * SPDX-License-Identifier: Apache-2.0 */ +/** + * @file + * @brief Open Supervised Device Protocol (OSDP) public API header file. + */ + #ifndef _OSDP_H_ #define _OSDP_H_ @@ -51,187 +56,156 @@ extern "C" { */ enum osdp_pd_cap_function_code_e { /** - * @brief Dummy. + * Dummy. */ OSDP_PD_CAP_UNUSED, /** - * @brief This function indicates the ability to monitor the status of a - * switch using a two-wire electrical connection between the PD and the - * switch. The on/off position of the switch indicates the state of an - * external device. + * This function indicates the ability to monitor the status of a switch + * using a two-wire electrical connection between the PD and the switch. + * The on/off position of the switch indicates the state of an external + * device. * * The PD may simply resolve all circuit states to an open/closed - * status, or it may implement supervision of the monitoring circuit. - * A supervised circuit is able to indicate circuit fault status in + * status, or it may implement supervision of the monitoring circuit. A + * supervised circuit is able to indicate circuit fault status in * addition to open/closed status. */ OSDP_PD_CAP_CONTACT_STATUS_MONITORING, /** - * @brief This function provides a switched output, typically in the - * form of a relay. The Output has two states: active or inactive. The - * Control Panel (CP) can directly set the Output's state, or, if the PD + * This function provides a switched output, typically in the form of a + * relay. The Output has two states: active or inactive. The Control + * Panel (CP) can directly set the Output's state, or, if the PD * supports timed operations, the CP can specify a time period for the * activation of the Output. */ OSDP_PD_CAP_OUTPUT_CONTROL, /** - * @brief This capability indicates the form of the card data is - * presented to the Control Panel. + * This capability indicates the form of the card data is presented to + * the Control Panel. */ OSDP_PD_CAP_CARD_DATA_FORMAT, /** - * @brief This capability indicates the presence of and type of LEDs. + * This capability indicates the presence of and type of LEDs. */ OSDP_PD_CAP_READER_LED_CONTROL, /** - * @brief This capability indicates the presence of and type of an - * Audible Annunciator (buzzer or similar tone generator) + * This capability indicates the presence of and type of an Audible + * Annunciator (buzzer or similar tone generator) */ OSDP_PD_CAP_READER_AUDIBLE_OUTPUT, /** - * @brief This capability indicates that the PD supports a text display + * This capability indicates that the PD supports a text display * emulating character-based display terminals. */ OSDP_PD_CAP_READER_TEXT_OUTPUT, /** - * @brief This capability indicates that the type of date and time - * awareness or time keeping ability of the PD. + * This capability indicates that the type of date and time awareness + * or time keeping ability of the PD. */ OSDP_PD_CAP_TIME_KEEPING, /** - * @brief All PDs must be able to support the checksum mode. This - * capability indicates if the PD is capable of supporting CRC mode. + * All PDs must be able to support the checksum mode. This capability + * indicates if the PD is capable of supporting CRC mode. */ OSDP_PD_CAP_CHECK_CHARACTER_SUPPORT, /** - * @brief This capability indicates the extent to which the PD supports + * This capability indicates the extent to which the PD supports * communication security (Secure Channel Communication) */ OSDP_PD_CAP_COMMUNICATION_SECURITY, /** - * @brief This capability indicates the maximum size single message the - * PD can receive. + * This capability indicates the maximum size single message the PD can + * receive. */ OSDP_PD_CAP_RECEIVE_BUFFERSIZE, /** - * @brief This capability indicates the maximum size multi-part message - * which the PD can handle. + * This capability indicates the maximum size multi-part message which + * the PD can handle. */ OSDP_PD_CAP_LARGEST_COMBINED_MESSAGE_SIZE, /** - * @brief This capability indicates whether the PD supports the - * transparent mode used for communicating directly with a smart card. + * This capability indicates whether the PD supports the transparent + * mode used for communicating directly with a smart card. */ OSDP_PD_CAP_SMART_CARD_SUPPORT, /** - * @brief This capability indicates the number of credential reader - * devices present. Compliance levels are bit fields to be assigned as - * needed. + * This capability indicates the number of credential reader devices + * present. Compliance levels are bit fields to be assigned as needed. */ OSDP_PD_CAP_READERS, /** - * @brief This capability indicates the ability of the reader to handle + * This capability indicates the ability of the reader to handle * biometric input */ OSDP_PD_CAP_BIOMETRICS, /** - * @brief Capability Sentinel + * Capability Sentinel */ OSDP_PD_CAP_SENTINEL }; +/** + * @brief OSDP specified NAK codes + */ enum osdp_pd_nak_code_e { - /** - * @brief Dummy - */ - OSDP_PD_NAK_NONE, - /** - * @brief Message check character(s) error (bad cksum/crc) - */ - OSDP_PD_NAK_MSG_CHK, - /** - * @brief Command length error - */ - OSDP_PD_NAK_CMD_LEN, - /** - * @brief Unknown Command Code – Command not implemented by PD - */ - OSDP_PD_NAK_CMD_UNKNOWN, - /** - * @brief Sequence number error - */ - OSDP_PD_NAK_SEQ_NUM, - /** - * @brief Secure Channel is not supported by PD - */ - OSDP_PD_NAK_SC_UNSUP, - /** - * @brief unsupported security block or security conditions not met - */ - OSDP_PD_NAK_SC_COND, - /** - * @brief BIO_TYPE not supported - */ - OSDP_PD_NAK_BIO_TYPE, - /** - * @brief BIO_FORMAT not supported - */ - OSDP_PD_NAK_BIO_FMT, - /** - * @brief Unable to process command record - */ - OSDP_PD_NAK_RECORD, - /** - * @brief NAK codes max value - */ - OSDP_PD_NAK_SENTINEL + OSDP_PD_NAK_NONE, /**< No error */ + OSDP_PD_NAK_MSG_CHK, /**< Message check character(s) error (bad cksum/crc) */ + OSDP_PD_NAK_CMD_LEN, /**< Command length error */ + OSDP_PD_NAK_CMD_UNKNOWN, /**< Unknown Command Code – Command not implemented by PD */ + OSDP_PD_NAK_SEQ_NUM, /**< Sequence number error */ + OSDP_PD_NAK_SC_UNSUP, /**< Secure Channel is not supported by PD */ + OSDP_PD_NAK_SC_COND, /**< unsupported security block or security conditions not met */ + OSDP_PD_NAK_BIO_TYPE, /**< BIO_TYPE not supported */ + OSDP_PD_NAK_BIO_FMT, /**< BIO_FORMAT not supported */ + OSDP_PD_NAK_RECORD, /**< Unable to process command record */ + OSDP_PD_NAK_SENTINEL /**< NAK codes max value */ }; /** * @brief PD capability structure. Each PD capability has a 3 byte * representation. * - * @param function_code One of enum osdp_pd_cap_function_code_e. - * @param compliance_level A function_code dependent number that indicates what - * the PD can do with this capability. + * @param function_code . + * @param compliance_level * @param num_items Number of such capability entities in PD. */ struct osdp_pd_cap { + /** + * Capability function code. See @ref osdp_pd_cap_function_code_e + */ uint8_t function_code; + /** + * A function_code dependent number that indicates what the PD can do + * with this capability. + */ uint8_t compliance_level; uint8_t num_items; }; /** * @brief PD ID information advertised by the PD. - * - * @param version 1-Byte Manufacturer's version number - * @param model 1-byte Manufacturer's model number - * @param vendor_code 3-bytes IEEE assigned OUI - * @param serial_number 4-byte serial number for the PD - * @param firmware_version 3-byte version (major, minor, build) */ struct osdp_pd_id { - int version; - int model; - uint32_t vendor_code; - uint32_t serial_number; - uint32_t firmware_version; + int version; /**< 1-Byte Manufacturer's version number */ + int model; /**< 1-byte Manufacturer's model number */ + uint32_t vendor_code; /**< 3-bytes IEEE assigned OUI */ + uint32_t serial_number; /**< 4-byte serial number for the PD */ + uint32_t firmware_version; /**< 3-byte version (major, minor, build) */ }; /** @@ -240,7 +214,7 @@ struct osdp_pd_id { * * @param data for use by underlying layers. osdp_channel::data is passed * @param buf byte array copy incoming data - * @param len sizeof `buf`. Can copy utmost `len` bytes into `buf` + * @param maxlen sizeof `buf`. Can copy utmost `maxlen` bytes into `buf` * * @retval +ve: number of bytes copied on to `buf`. Must be <= `len` * @retval -ve on errors @@ -271,52 +245,77 @@ typedef void (*osdp_flush_fn_t)(void *data); /** * @brief User defined communication channel abstraction for OSDP devices. * The methods for read/write/flush are expected to be non-blocking. - * - * @param data pointer to a block of memory that will be passed to the - * send/receive/flush method. This is optional (can be set to NULL) - * @param id on multi-drop networks, more than one PD can share the same - * channel (read/write/flush pointers). On such networks, the - * channel_id is used to lock a PD to a channel. On multi-drop - * networks, this `id` must non-zero and be unique for each bus. - * @param recv Pointer to function used to receive osdp packet data - * @param send Pointer to function used to send osdp packet data - * @param flush Pointer to function used to flush the channel (optional) */ struct osdp_channel { + /** + * pointer to a block of memory that will be passed to the + * send/receive/flush method. This is optional (can be set to NULL) + */ void *data; + /** + * channel_id; On multi-drop networks, more than one PD can share the + * same channel (read/write/flush pointers). On such networks, the + * channel_id is used to lock a PD to a channel. On multi-drop + * networks, this `id` must non-zero and be unique for each bus. + */ int id; + /** + * Pointer to function used to receive osdp packet data + */ osdp_read_fn_t recv; + /** + * Pointer to function used to send osdp packet data + */ osdp_write_fn_t send; + /** + * Pointer to function used to flush the channel (optional) + */ osdp_flush_fn_t flush; }; /** * @brief OSDP PD Information. This struct is used to describe a PD to LibOSDP. - * - * @param name User provided name for this PD (log messages include this name) - * @param baud_rate Can be one of 9600/19200/38400/57600/115200/230400 - * @param address 7 bit PD address. the rest of the bits are ignored. The - * special address 0x7F is used for broadcast. So there can be 2^7-1 - * devices on a multi-drop channel - * @param flags Used to modify the way the context is setup. See `OSDP_FLAG_XXX` - * @param id Static information that the PD reports to the CP when it received a - * `CMD_ID`. These information must be populated by a PD application. - * @param cap This is a pointer to an array of structures containing the PD' - * capabilities. Use { -1, 0, 0 } to terminate the array. This is used - * only PD mode of operation - * @param channel Communication channel ops structure, containing send/recv - * function pointers. - * @param scbk Pointer to 16 bytes of Secure Channel Base Key for the PD. If - * non-null, this is used to set-up the secure channel. */ typedef struct { + /** + * User provided name for this PD (log messages include this name) + */ const char *name; + /** + * Can be one of 9600/19200/38400/57600/115200/230400 + */ int baud_rate; + /** + * 7 bit PD address. the rest of the bits are ignored. The special + * address 0x7F is used for broadcast. So there can be 2^7-1 devices on + * a multi-drop channel + */ int address; + /** + * Used to modify the way the context is setup. See `OSDP_FLAG_*` + * macros. + */ int flags; + /** + * Static information that the PD reports to the CP when it received a + * `CMD_ID`. These information must be populated by a PD application. + */ struct osdp_pd_id id; + /** + * This is a pointer to an array of structures containing the PD' + * capabilities. Use { -1, 0, 0 } to terminate the array. This is used + * only PD mode of operation + */ const struct osdp_pd_cap *cap; + /** + * Communication channel ops structure, containing send/recv function + * pointers + */ struct osdp_channel channel; + /** + * Pointer to 16 bytes of Secure Channel Base Key for the PD. If + * non-null, this is used to set-up the secure channel. + */ const uint8_t *scbk; } osdp_pd_info_t; @@ -329,6 +328,9 @@ typedef struct { */ typedef void osdp_t; +/** + * @brief OSDP Status report types + */ enum osdp_status_report_type { /** * @brief Status report of the inputs attached the PD @@ -355,12 +357,12 @@ enum osdp_status_report_type { }; /** - * @brief 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 PR responds back with this structure. + * @brief 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 PR responds back with this structure. * - * This can is used by the PD to indicate various status change reports. Upto - * a maximum of 32 statuses can be reported using this API. + * This can is used by the PD to indicate various status change reports. Upto a + * maximum of 32 statuses can be reported using this API. * * @param type The kind of event to report see `enum osdp_event_status_type_e` * @param nr_entries Number of valid bits in `status` @@ -387,13 +389,13 @@ struct osdp_status_report { * * @param output_no 0 = First Output, 1 = Second Output, etc. * @param control_code One of the following: - * 0 - NOP – do not alter this output - * 1 - set the permanent state to OFF, abort timed operation (if any) - * 2 - set the permanent state to ON, abort timed operation (if any) - * 3 - set the permanent state to OFF, allow timed operation to complete - * 4 - set the permanent state to ON, allow timed operation to complete - * 5 - set the temporary state to ON, resume perm state on timeout - * 6 - set the temporary state to OFF, resume permanent state on timeout + * 0 - NOP – do not alter this output + * 1 - set the permanent state to OFF, abort timed operation (if any) + * 2 - set the permanent state to ON, abort timed operation (if any) + * 3 - set the permanent state to OFF, allow timed operation to complete + * 4 - set the permanent state to ON, allow timed operation to complete + * 5 - set the temporary state to ON, resume perm state on timeout + * 6 - set the temporary state to OFF, resume permanent state on timeout * @param timer_count Time in units of 100 ms */ struct osdp_cmd_output { @@ -403,114 +405,164 @@ struct osdp_cmd_output { }; /** - * @brief LED Colors as specified in OSDP for the on_color/off_color parameters. + * @brief LED Colors as specified in OSDP for the on_color/off_color + * parameters. */ enum osdp_led_color_e { - OSDP_LED_COLOR_NONE, - OSDP_LED_COLOR_RED, - OSDP_LED_COLOR_GREEN, - OSDP_LED_COLOR_AMBER, - OSDP_LED_COLOR_BLUE, - OSDP_LED_COLOR_MAGENTA, - OSDP_LED_COLOR_CYAN, - OSDP_LED_COLOR_WHITE, - OSDP_LED_COLOR_SENTINEL + OSDP_LED_COLOR_NONE, /**< No color */ + OSDP_LED_COLOR_RED, /**< Red */ + OSDP_LED_COLOR_GREEN, /**< Green */ + OSDP_LED_COLOR_AMBER, /**< Amber */ + OSDP_LED_COLOR_BLUE, /**< Blue */ + OSDP_LED_COLOR_MAGENTA, /**< Magenta */ + OSDP_LED_COLOR_CYAN, /**< Cyan */ + OSDP_LED_COLOR_WHITE, /**< White */ + OSDP_LED_COLOR_SENTINEL /**< Max value */ }; /** - * @brief LED params sub-structure. Part of LED command. See struct osdp_cmd_led - * - * @param control_code One of the following: - * Temporary Control Code: - * 0 - NOP - do not alter this LED's temporary settings - * 1 - Cancel any temporary operation and display this LED's permanent - * state immediately - * 2 - Set the temporary state as given and start timer immediately - * Permanent Control Code: - * 0 - NOP - do not alter this LED's permanent settings - * 1 - Set the permanent state as given - * @param on_count The ON duration of the flash, in units of 100 ms - * @param off_count The OFF duration of the flash, in units of 100 ms - * @param on_color Color to set during the ON timer (enum osdp_led_color_e) - * @param off_color Color to set during the OFF timer (enum osdp_led_color_e) - * @param timer_count Time in units of 100 ms (only for temporary mode) + * @brief LED params sub-structure. Part of LED command. See @ref osdp_cmd_led. */ struct osdp_cmd_led_params { + /** Control code. + * + * Temporary Control Code: + * - 0 - NOP - do not alter this LED's temporary settings. + * - 1 - Cancel any temporary operation and display this LED's + * permanent state immediately. + * - 2 - Set the temporary state as given and start timer immediately. + * + * Permanent Control Code: + * - 0 - NOP - do not alter this LED's permanent settings. + * - 1 - Set the permanent state as given. + */ uint8_t control_code; + /** + * The ON duration of the flash, in units of 100 ms. + */ uint8_t on_count; + /** + * The OFF duration of the flash, in units of 100 ms. + */ uint8_t off_count; + /** + * Color to set during the ON timer (see @ref osdp_led_color_e). + */ uint8_t on_color; + /** + * Color to set during the OFF timer (see @ref osdp_led_color_e). + */ uint8_t off_color; + /** + * Time in units of 100 ms (only for temporary mode). + */ uint16_t timer_count; }; /** * @brief Sent from CP to PD to control the behaviour of it's on-board LEDs - * - * @param reader 0 = First Reader, 1 = Second Reader, etc. - * @param led_number 0 = first LED, 1 = second LED, etc. - * @param temporary ephemeral LED status descriptor - * @param permanent permanent LED status descriptor */ struct osdp_cmd_led { + /** + * Reader number. 0 = First Reader, 1 = Second Reader, etc. + */ uint8_t reader; + /** + * LED number. 0 = first LED, 1 = second LED, etc. + */ uint8_t led_number; + /** + * Ephemeral LED status descriptor. + */ struct osdp_cmd_led_params temporary; + /** + * Permanent LED status descriptor. + */ struct osdp_cmd_led_params permanent; }; /** * @brief Sent from CP to control the behaviour of a buzzer in the PD. - * - * @param reader 0 = First Reader, 1 = Second Reader, etc. - * @param control_code 0: no tone, 1: off, 2: default tone, 3+ is TBD. - * @param on_count The ON duration of the flash, in units of 100 ms - * @param off_count The OFF duration of the flash, in units of 100 ms - * @param rep_count The number of times to repeat the ON/OFF cycle; 0: forever */ struct osdp_cmd_buzzer { + /** + * Reader number. 0 = First Reader, 1 = Second Reader, etc. + */ uint8_t reader; + /** + * Control code. + * - 0 - no tone + * - 1 - off + * - 2 - default tone + * - 3+ - TBD + */ uint8_t control_code; + /** + * The ON duration of the sound, in units of 100 ms. + */ uint8_t on_count; + /** + * The OFF duration of the sound, in units of 100 ms. + */ uint8_t off_count; + /** + * The number of times to repeat the ON/OFF cycle; 0: forever. + */ uint8_t rep_count; }; /** * @brief Command to manipulate any display units that the PD supports. - * - * @param reader 0 = First Reader, 1 = Second Reader, etc. - * @param control_code One of the following: - * 1 - permanent text, no wrap - * 2 - permanent text, with wrap - * 3 - temp text, no wrap - * 4 - temp text, with wrap - * @param temp_time duration to display temporary text, in seconds - * @param offset_row row to display the first character (1 indexed) - * @param offset_col column to display the first character (1 indexed) - * @param length Number of characters in the string - * @param data The string to display */ struct osdp_cmd_text { + /** + * Reader number. 0 = First Reader, 1 = Second Reader, etc. + */ uint8_t reader; + /** + * Control code. + * - 1 - permanent text, no wrap + * - 2 - permanent text, with wrap + * - 3 - temp text, no wrap + * - 4 - temp text, with wrap + */ uint8_t control_code; + /** + * Duration to display temporary text, in seconds + */ uint8_t temp_time; + /** + * Row to display the first character (1-indexed) + */ uint8_t offset_row; + /** + * Column to display the first character (1-indexed) + */ uint8_t offset_col; + /** + * Number of characters in the string + */ uint8_t length; + /** + * The string to display + */ uint8_t data[OSDP_CMD_TEXT_MAX_LEN]; }; /** * @brief Sent in response to a COMSET command. Set communication parameters to * PD. Must be stored in PD non-volatile memory. - * - * @param address Unit ID to which this PD will respond after the change takes - * effect. - * @param baud_rate baud rate value 9600/19200/38400/57600/115200/230400 */ struct osdp_cmd_comset { + /** + * Unit ID to which this PD will respond after the change takes effect. + */ uint8_t address; + /** + * Baud rate. + * + * Valid values: 9600, 19200, 38400, 115200, 230400. + */ uint32_t baud_rate; }; @@ -523,8 +575,18 @@ struct osdp_cmd_comset { * @param data Key data */ struct osdp_cmd_keyset { + /** + * Type of keys: + * - 0x01 – Secure Channel Base Key + */ uint8_t type; + /** + * Number of bytes of key data - (Key Length in bits + 7) / 8 + */ uint8_t length; + /** + * Key data + */ uint8_t data[OSDP_CMD_KEYSET_KEY_MAX_LEN]; }; @@ -546,15 +608,18 @@ struct osdp_cmd_mfg { /** * @brief File transfer start command - * - * @param id Pre-agreed file ID between CP and PD. - * @param flags Reserved and set to zero by OSDP spec; - * - * Note: flags upper bits are used by libosdp as: - * bit-31 - OSDP_CMD_FILE_TX_FLAG_CANCEL: cancel an ongoing transfer */ struct osdp_cmd_file_tx { + /** + * Pre-agreed file ID between CP and PD + */ int id; + /** + * Reserved and set to zero by OSDP spec. + * + * Note: The upper bits are used by libosdp as: + * bit-31 - OSDP_CMD_FILE_TX_FLAG_CANCEL: cancel an ongoing transfer + */ uint32_t flags; }; @@ -562,42 +627,38 @@ struct osdp_cmd_file_tx { * @brief OSDP application exposed commands */ enum osdp_cmd_e { - OSDP_CMD_OUTPUT = 1, - OSDP_CMD_LED, - OSDP_CMD_BUZZER, - OSDP_CMD_TEXT, - OSDP_CMD_KEYSET, - OSDP_CMD_COMSET, - OSDP_CMD_MFG, - OSDP_CMD_FILE_TX, - OSDP_CMD_STATUS, - OSDP_CMD_SENTINEL + OSDP_CMD_OUTPUT = 1, /**< Output control command */ + OSDP_CMD_LED, /**< Reader LED control command */ + OSDP_CMD_BUZZER, /**< Reader buzzer control command */ + OSDP_CMD_TEXT, /**< Reader text output command */ + OSDP_CMD_KEYSET, /**< Encryption Key Set Command */ + OSDP_CMD_COMSET, /**< PD communication configuration command */ + OSDP_CMD_MFG, /**< Manufacturer specific command */ + OSDP_CMD_FILE_TX, /**< File transfer comand */ + OSDP_CMD_STATUS, /**< Status report eommand */ + OSDP_CMD_SENTINEL /**< Max command value */ }; /** * @brief OSDP Command Structure. This is a wrapper for all individual OSDP * commands. - * - * @param id used to select specific commands in union. Type: enum osdp_cmd_e - * @param led LED command structure - * @param buzzer buzzer command structure - * @param text text command structure - * @param output output command structure - * @param comset comset command structure - * @param keyset keyset command structure */ struct osdp_cmd { + /** + * Command ID. Used to select specific commands in union. + */ enum osdp_cmd_e id; + /** Command */ union { - struct osdp_cmd_led led; - struct osdp_cmd_buzzer buzzer; - struct osdp_cmd_text text; - struct osdp_cmd_output output; - struct osdp_cmd_comset comset; - struct osdp_cmd_keyset keyset; - struct osdp_cmd_mfg mfg; - struct osdp_cmd_file_tx file_tx; - struct osdp_status_report status; + struct osdp_cmd_led led; /**< LED command structure */ + struct osdp_cmd_buzzer buzzer; /**< Buzzer command structure */ + struct osdp_cmd_text text; /**< Text command structure */ + struct osdp_cmd_output output; /**< Output command structure */ + struct osdp_cmd_comset comset; /**< Comset command structure */ + struct osdp_cmd_keyset keyset; /**< Keyset command structure */ + struct osdp_cmd_mfg mfg; /**< Manufacturer specific command structure */ + struct osdp_cmd_file_tx file_tx; /**< File transfer command structure */ + struct osdp_status_report status; /**< Status report command structure */ }; }; @@ -614,49 +675,62 @@ struct osdp_cmd { * when a PD must report a card read. */ enum osdp_event_cardread_format_e { - OSDP_CARD_FMT_RAW_UNSPECIFIED, - OSDP_CARD_FMT_RAW_WIEGAND, - OSDP_CARD_FMT_ASCII, - OSDP_CARD_FMT_SENTINEL + OSDP_CARD_FMT_RAW_UNSPECIFIED, /**< Unspecified card format */ + OSDP_CARD_FMT_RAW_WIEGAND, /**< Wiegand card format */ + OSDP_CARD_FMT_ASCII, /**< ASCII card format */ + OSDP_CARD_FMT_SENTINEL /**< Max card format value */ }; /** * @brief OSDP event cardread * - * @param reader_no In context of readers attached to current PD, this number - * indicated this number. This is not supported by LibOSDP. - * @param format Format of the card being read. - * see `enum osdp_event_cardread_format_e` - * @param direction Card read direction of PD 0 - Forward; 1 - Backward - * @param length Length of card data in bytes or bits depending on `format` - * (see note). - * @param data Card data of `length` bytes or bits depending on `format` - * (see note). - * - * @note When `format` is set to OSDP_CARD_FMT_RAW_UNSPECIFIED or + * @note When @a format is set to OSDP_CARD_FMT_RAW_UNSPECIFIED or * OSDP_CARD_FMT_RAW_WIEGAND, the length is expressed in bits. OTOH, when it is * set to OSDP_CARD_FMT_ASCII, the length is in bytes. The number of bytes to - * read from the `data` field must be interpreted accordingly. + * read from the @a data field must be interpreted accordingly. */ struct osdp_event_cardread { + /** + * Reader number. 0 = First Reader, 1 = Second Reader, etc. + */ int reader_no; + /** + * Format of the card being read. + */ enum osdp_event_cardread_format_e format; + /** + * Direction of data in @a data array. + * - 0 - Forward + * - 1 - Backward + */ int direction; + /** + * Length of card data in bytes or bits depending on @a format + */ int length; + /** + * Card data of @a length bytes or bits bits depending on @a format + */ uint8_t data[OSDP_EVENT_CARDREAD_MAX_DATALEN]; }; /** * @brief OSDP Event Keypad - * - * @param reader_no In context of readers attached to current PD, this number - * indicated this number. This is not supported by LibOSDP. - * @param length Length of keypress data in bytes - * @param data keypress data of `length` bytes */ struct osdp_event_keypress { + /** + * Reader number in context of sub-readers attached to current PD; this + * number indicates the number of that reader. This is not supported by + * LibOSDP. + */ int reader_no; + /** + * Length of keypress data in bytes + */ int length; + /** + * Keypress data of @a length bytes + */ uint8_t data[OSDP_EVENT_KEYPRESS_MAX_DATALEN]; }; @@ -664,19 +738,26 @@ struct osdp_event_keypress { * @brief OSDP Event Manufacturer Specific Command * * Note: OSDP spec v2.2 makes this structure fixed at 4 bytes. LibOSDP allows - * for some additional data to be passed in this command using the data and - * length fields. To be fully compliant with the specification, set the length - * field to 0. - * - * @param vendor_code 3-bytes IEEE assigned OUI of manufacturer - * @param command 1-byte reply code - * @param length Length of manufacturer data in bytes (optional) - * @param data manufacturer data of `length` bytes (optional) + * for some additional data to be passed in this command using the @a data and + * @a length fields. To be fully compliant with the specification, set @a + * length to 0. */ struct osdp_event_mfgrep { + /** + * 3-bytes IEEE assigned OUI of manufacturer + */ uint32_t vendor_code; + /** + * 1-byte reply code + */ uint8_t command; + /** + * Length of manufacturer data in bytes (optional) + */ uint8_t length; + /** + * Manufacturer data of `length` bytes (optional) + */ uint8_t data[OSDP_EVENT_MFGREP_MAX_DATALEN]; }; @@ -684,43 +765,28 @@ struct osdp_event_mfgrep { * @brief OSDP PD Events */ enum osdp_event_type { - /** - * @brief Card read event - */ - OSDP_EVENT_CARDREAD = 1, - /** - * @brief Key press event - */ - OSDP_EVENT_KEYPRESS, - /** - * @brief Manufacturer specific reply event - */ - OSDP_EVENT_MFGREP, - /** - * @brief Status event - */ - OSDP_EVENT_STATUS, - /** - * @brief Event maximum - */ - OSDP_EVENT_SENTINEL + OSDP_EVENT_CARDREAD = 0, /**< Card read event */ + OSDP_EVENT_KEYPRESS, /**< Keypad press event */ + OSDP_EVENT_MFGREP, /**< Manufacturer specific reply event */ + OSDP_EVENT_STATUS, /**< Status event */ + OSDP_EVENT_SENTINEL /**< Max event value */ }; /** * @brief OSDP Event structure. - * - * @param id used to select specific event in union. See: enum osdp_event_type - * @param keypress keypress event structure - * @param cardread cardread event structure - * @param mfgrep mfgrep event structure */ struct osdp_event { + /** + * Event type. + * Used to select specific event in union. + */ enum osdp_event_type type; + /** Event */ union { - struct osdp_event_keypress keypress; - struct osdp_event_cardread cardread; - struct osdp_event_mfgrep mfgrep; - struct osdp_status_report status; + struct osdp_event_keypress keypress; /**< Keypress event structure */ + struct osdp_event_cardread cardread; /**< Card read event structure */ + struct osdp_event_mfgrep mfgrep; /**< Manufacturer spefific response event struture */ + struct osdp_status_report status; /**< Status report event strcture */ }; }; @@ -735,20 +801,21 @@ struct osdp_event { * * @retval 0 if LibOSDP must send a `osdp_ACK` response * @retval -ve if LibOSDP must send a `osdp_NAK` response - * @retval +ve and modify the passed `struct osdp_cmd *cmd` if LibOSDP must send - * a specific response. This is useful for sending manufacturer specific - * reply ``osdp_MFGREP``. + * @retval +ve and modify the passed `struct osdp_cmd *cmd` if LibOSDP must + * send a specific response. This is useful for sending manufacturer specific + * reply `osdp_MFGREP`. */ typedef int (*pd_command_callback_t)(void *arg, struct osdp_cmd *cmd); /** - * @brief Callback for CP event notifications. After is has been registered with - * `osdp_cp_set_event_callback`, this method is invoked when the CP receives an - * event from the PD. - * - * @param arg pointer that will was passed to the arg param of - * `osdp_cp_set_event_callback`. - * @param pd PD offset number as in `pd_info_t *`. + * @brief Callback for CP event notifications. After it has been registered + * with `osdp_cp_set_event_callback`, this method is invoked when the CP + * receives an event from the PD. + * + * @param arg Opaque pointer provided by the application during callback + * registration. + * @param pd PD offset (0-indexed) of this PD in `osdp_pd_info_t *` passed to + * osdp_cp_setup() * @param ev pointer to osdp_event struct (filled by libosdp). * * @retval 0 on handling the event successfully. @@ -866,7 +933,8 @@ void osdp_cp_teardown(osdp_t *ctx); * @brief Generic command enqueue API. * * @param ctx OSDP context - * @param pd PD offset number as in `pd_info_t *`. + * @param pd PD offset (0-indexed) of this PD in `osdp_pd_info_t *` passed to + * osdp_cp_setup() * @param cmd command pointer. Must be filled by application. * * @retval 0 on success @@ -883,7 +951,8 @@ int osdp_cp_send_command(osdp_t *ctx, int pd, const struct osdp_cmd *cmd); * invalid/stale results. * * @param ctx OSDP context - * @param pd PD offset number as in `pd_info_t *`. + * @param pd PD offset (0-indexed) of this PD in `osdp_pd_info_t *` passed to + * osdp_cp_setup() * @param id A pointer to struct osdp_pd_id that will be filled with the * PD ID information that the PD last returned. * @@ -898,7 +967,8 @@ int osdp_cp_get_pd_id(const osdp_t *ctx, int pd, struct osdp_pd_id *id); * had a the chance to get this information will return invalid/stale results. * * @param ctx OSDP context - * @param pd PD offset number as in `pd_info_t *`. + * @param pd PD offset (0-indexed) of this PD in `osdp_pd_info_t *` passed to + * osdp_cp_setup() * @param cap in/out; struct osdp_pd_cap pointer with osdp_pd_cap::function_code * set to the function code to get data for. * @@ -921,7 +991,8 @@ void osdp_cp_set_event_callback(osdp_t *ctx, cp_event_callback_t cb, void *arg); * @brief Set or clear OSDP public flags * * @param ctx OSDP context - * @param pd_idx PD offset number as in `pd_info_t *`. + * @param pd PD offset (0-indexed) of this PD in `osdp_pd_info_t *` passed to + * osdp_cp_setup() * @param flags One or more of the public flags (OSDP_FLAG_XXX) exported from * osdp.h. Any other bits will cause this method to fail. * @param do_set when true: set `flags` in ctx; when false: clear `flags` in ctx @@ -932,7 +1003,7 @@ void osdp_cp_set_event_callback(osdp_t *ctx, cp_event_callback_t cb, void *arg); * @note It doesn't make sense to call some initialization time flags during * runtime. This method is for dynamic flags that can be turned on/off at runtime. */ -int osdp_cp_modify_flag(osdp_t *ctx, int pd_idx, uint32_t flags, bool do_set); +int osdp_cp_modify_flag(osdp_t *ctx, int pd, uint32_t flags, bool do_set); /* ------------------------------- */ /* Common Methods */ @@ -943,15 +1014,15 @@ int osdp_cp_modify_flag(osdp_t *ctx, int pd_idx, uint32_t flags, bool do_set); * with LOG_EMERG being most critical to LOG_DEBUG being the least. */ enum osdp_log_level_e { - OSDP_LOG_EMERG, - OSDP_LOG_ALERT, - OSDP_LOG_CRIT, - OSDP_LOG_ERROR, - OSDP_LOG_WARNING, - OSDP_LOG_NOTICE, - OSDP_LOG_INFO, - OSDP_LOG_DEBUG, - OSDP_LOG_MAX_LEVEL + 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 */ }; /** @@ -979,12 +1050,12 @@ typedef void (*osdp_log_callback_fn_t)(int log_level, const char *file, * * @param name A soft name for this module; will appear in all the log lines. * @param log_level OSDP log levels of type `enum osdp_log_level_e`. Default is - * LOG_INFO. + * LOG_INFO. * @param puts_fn A 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. + * 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. * * Note: This function has to be called before osdp_{cp,pd}_setup(). Otherwise * it will be ignored. @@ -994,9 +1065,9 @@ void osdp_logger_init(const char *name, int log_level, /** * @brief A callback function that gets called when LibOSDP wants to emit a log - * line. All messages (of all log levels) are passed on to this callback - * without any log formatting. This API is for users who may already have - * a logger configured in their application. + * line. All messages (of all log levels) are passed on to this callback + * without any log formatting. This API is for users who may already have a + * logger configured in their application. * * @param cb The callback function. See `osdp_log_callback_fn_t` for more * details. @@ -1015,8 +1086,8 @@ const char *osdp_get_version(); /** * @brief 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. + * info about the source tree from which this version of LibOSDP was built. + * Used in diagnostics. * * @retval source identifier string */ @@ -1041,6 +1112,69 @@ void osdp_get_status_mask(const osdp_t *ctx, uint8_t *bitmask); */ void osdp_get_sc_status_mask(const osdp_t *ctx, uint8_t *bitmask); +/** + * @brief Open a pre-agreed file + * + * @param arg Opaque pointer that was provided in @ref osdp_file_ops when the + * ops struct was registered. + * @param file_id File ID of pre-agreed file between this CP and PD + * @param size Size of the file that was opened (filled by application) + * + * @retval 0 on success + * @retval -1 on errors + */ +typedef int (*osdp_file_open_fn_t)(void *arg, int file_id, int *size); + +/** + * @brief Read a chunk of file data into buffer + * + * @param arg Opaque pointer that was provided in @ref osdp_file_ops when the + * ops struct was registered. + * @param buf Buffer to store file data read + * @param size Number of bytes to read from file into buffer + * @param offset Number of bytes from the beginning of the file to + * start reading from. + * + * @retval Number of bytes read + * @retval 0 on EOF + * @retval -ve on errors. + * + * @note LibOSDP will guarantee that size and offset params are always + * positive and size is always greater than or equal to offset. + */ +typedef int (*osdp_file_read_fn_t)(void *arg, void *buf, int size, int offset); + +/** + * @brief Write a chunk of file data from buffer to disk. + * + * @param arg Opaque pointer that was provided in @ref osdp_file_ops when the + * ops struct was registered. + * @param buf Buffer with file data to be stored to disk + * @param size Number of bytes to write to disk + * @param offset Number of bytes from the beginning of the file to + * start writing too. + * + * @retval Number of bytes written + * @retval 0 on EOF + * @retval -ve on errors. + * + * @note LibOSDP will guarantee that size and offset params are always + * positive and size is always greater than or equal to offset. + */ +typedef int (*osdp_file_write_fn_t)(void *arg, const void *buf, + int size, int offset); + +/** + * @brief Close file that corresponds to a given file descriptor + * + * @param arg Opaque pointer that was provided in @ref osdp_file_ops when the + * ops struct was registered. + * + * @retval 0 on success + * @retval -1 on errors. + */ +typedef int (*osdp_file_close_fn_t)(void *arg); + /** * @brief OSDP File operations struct that needs to be filled by the CP/PD * application and registered with LibOSDP using osdp_file_register_ops() @@ -1054,58 +1188,10 @@ struct osdp_file_ops { * such as the open file descriptors or any other private data here. */ void *arg; - - /** - * @brief Open a pre-agreed file - * - * @param arg Opaque pointer to private data passed though by libosdp - * @param file_id File ID of pre-agreed file between this CP and PD - * @param size Size of the file that was opened (filled by application) - * - * @retval 0 on success. -1 on errors. - */ - int (*open)(void *arg, int file_id, int *size); - - /** - * @brief Read a chunk of file data into buffer - * - * @param arg Opaque pointer to private data passed though by libosdp - * @param buf Buffer to store file data read - * @param size Number of bytes to read from file into buffer - * @param offset Number of bytes from the beginning of the file to - * start reading from. - * - * @retval Number of bytes read, 0 on EOF, -ve on errors. - * - * @note LibOSDP will guarantee that size and offset params are always - * positive and size is always greater than or equal to offset. - */ - int (*read)(void *arg, void *buf, int size, int offset); - - /** - * @brief Write a chunk of file data from buffer to disk. - * - * @param arg Opaque pointer to private data passed though by libosdp - * @param buf Buffer with file data to be stored to disk - * @param size Number of bytes to write to disk - * @param offset Number of bytes from the beginning of the file to - * start writing too. - * - * @retval Number of bytes read, 0 on EOF, -ve on errors. - * - * @note LibOSDP will guarantee that size and offset params are always - * positive and size is always greater than or equal to offset. - */ - int (*write)(void *arg, const void *buf, int size, int offset); - - /** - * @brief Close file that corresponds to a given file descriptor - * - * @param arg Opaque pointer to private data passed though by libosdp - * - * @retval 0 on success. -1 on errors. - */ - int (*close)(void *arg); + 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 */ }; /**