Commit 86d25d49 authored by George Nash's avatar George Nash Committed by Kishen Maloor

Document random PIN and reset functions in oc_api.h

This adds doxygen documentation for:
 - oc_random_pin_cb_t - callback function
 - oc_set_random_pin_callback
 - oc_reset
 - oc_reset_device
Signed-off-by: George Nash's avatarGeorge Nash <george.nash@intel.com>
parent d0884c70
Pipeline #216 passed with stage
in 53 seconds
......@@ -454,8 +454,56 @@ int oc_init_platform(const char *mfg_name,
#define oc_set_custom_platform_property(prop, value) \
oc_rep_set_text_string(root, prop, value)
/**
* Callback invoked when an onboarding client requests device ownership via the
* Random PIN Ownership Transfer Method (OTM). The purpose of the callback is
* to allow the device to display the random PIN to the user onboarding the
* device.
*
* Example:
* ```
* #ifdef OC_SECURITY
* void random_pin_cb(const unsigned char *pin, size_t pin_len, void *data)
* {
* (void)data;
* PRINT("\n\nRandom PIN: %.*s\n\n", (int)pin_len, pin);
* }
* #endif // OC_SECURITY
*
* int main(void) {
* ...
* #ifdef OC_SECURITY
* oc_storage_config("./server_creds");
* oc_set_random_pin_callback(random_pin_cb, NULL);
* #endif // OC_SECURITY
* // handler code omitted from example code see oc_main_init
* oc_main_init(&handler)
* ...
* return 0;
* }
* ```
*
* @param[in] data context pointer that comes from the oc_init_platform()
* function
*
* @see oc_set_random_pin_callback
*/
typedef void (*oc_random_pin_cb_t)(const unsigned char *pin, size_t pin_len,
void *data);
/**
* Set the random pin callback for Random PIN Ownership Transfer Method (OTM)
*
* @note This should be set before invoking oc_main_init().
*
* @param[in] cb callback function invoked when client requests Random PIN OTM
* @param[in] data context pointer that is passed to the oc_random_pin_cb_t the
* context pointer must be a valid pointer as long as the device
* is in 'Ready For Ownership Transfer Method' (RFOTM) state.
*
* @see oc_random_pin_cb_t
* @see oc_main_init
*/
void oc_set_random_pin_callback(oc_random_pin_cb_t cb, void *data);
/**
......@@ -479,8 +527,37 @@ bool oc_get_con_res_announced(void);
*/
void oc_set_con_res_announced(bool announce);
/**
* Reset all logical devices to the RFOTM state
*
* All devices will be placed in the 'Ready For Ownership Transfer Mode'
* (RFOTM). This is the initial startup state for for all devices that have not
* yet been onboarded. After this call all devices will need to be onboarded
* and provisioned again.
*
* @note The function oc_reset() deals only with security and provisioning it
* does not reset any other device settings.
*
* @note Use of this function requires building with OC_SECURITY defined.
*/
void oc_reset();
/**
* Reset logical device to the RFOTM state
*
* The device will be placed in the 'Ready For Ownership Transfer Mode' (RFOTM).
* This is the initial state startup state for for all devices that have not yet
* been onboarded. After this call the device will need to be onboarded and
* provisioned again.
*
* @note The function oc_reset_device() deals only with security and
* provisioning it does not reset any other device settings.
*
* @note Use of this function requires building the stack with OC_SECURITY
* defined.
*
* @param[in] device index of the logical device to reset
*/
void oc_reset_device(size_t device);
/** Server side */
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment