Main API of IoTivity-Lite for client and server. More...

#include "messaging/coap/oc_coap.h"
#include "oc_buffer_settings.h"
#include "oc_cloud.h"
#include "oc_config.h"
#include "oc_export.h"
#include "oc_link.h"
#include "oc_rep.h"
#include "oc_ri.h"
#include "oc_role.h"
#include "oc_signal_event_loop.h"
#include "port/oc_storage.h"
#include "util/oc_compiler.h"
#include "util/oc_features.h"
#include "util/oc_process.h"
#include "oc_collection.h"
#include "oc_client_state.h"

Data Structures
struct	oc_connectivity_listening_ports_s
	The structure includes flags that can be used to disable listening on certain IP interfaces. More...

struct	oc_handler_t
	Call back handlers that are invoked in response to oc_main_init() More...

Macros
#define	oc_activate_interrupt_handler(name) (oc_process_start(&(name##_interrupt_x), 0))
	activate the interrupt handler More...

#define	oc_define_interrupt_handler(name)
	define the interrupt handler More...

#define	oc_set_custom_device_property(prop, value) oc_rep_set_text_string(root, prop, value)
	Set custom device property. More...

#define	oc_set_custom_platform_property(prop, value) oc_rep_set_text_string(root, prop, value)
	Set custom platform property. More...

#define	oc_signal_interrupt_handler(name)
	API for setting handlers for interrupts. More...

Typedefs
typedef void(*	oc_add_device_cb_t) (void *data)
	Callback invoked during oc_add_device(). More...

typedef struct oc_add_new_device_s	oc_add_new_device_t

typedef void(*	oc_con_write_cb_t) (size_t device_index, const oc_rep_t *rep)
	Callback for change notifications from the oic.wk.con resource. More...

typedef enum oc_connectivity_listening_port_flags_e	oc_connectivity_listening_port_flags_t

typedef struct oc_connectivity_listening_ports_s	oc_connectivity_listening_ports_t
	The structure includes flags that can be used to disable listening on certain IP interfaces. More...

typedef struct oc_connectivity_ports_s	oc_connectivity_ports_t

typedef void(*	oc_factory_presets_cb_t) (size_t device, void *data)
	Callback invoked by the stack initialization to perform any "factory settings", e.g., this may be used to load a manufacturer certificate. More...

typedef void(*	oc_init_platform_cb_t) (void *data)
	Callback invoked during oc_init_platform(). More...

typedef void(*	oc_ownership_status_cb_t) (const oc_uuid_t device_uuid, size_t device_index, bool owned, void user_data)
	Callback invoked when the "owned" property of the doxm is changed. More...

typedef void(*	oc_random_pin_cb_t) (const unsigned char pin, size_t pin_len, void data)
	Callback invoked when an onboarding client requests device ownership via the Random PIN Ownership Transfer Method (OTM). More...

typedef void(*	oc_select_oxms_cb_t) (size_t device_index, int oxms, int num_oxms, void *user_data)
	Callback to filter out unsupported ownership methods when they are evaluated. More...

typedef void(*	oc_send_response_cb_t) (oc_request_t *request, oc_status_t response_code)
	Callback function is triggered by oc_send_response before the response is set. More...

Enumerations
enum	oc_connectivity_listening_port_flags_e { OC_CONNECTIVITY_DISABLE_IPV6_PORT = 0x01 , OC_CONNECTIVITY_DISABLE_SECURE_IPV6_PORT = 0x04 , OC_CONNECTIVITY_DISABLE_ALL_PORTS = 0x0F }

Functions
int	oc_add_device (const char uri, const char rt, const char name, const char spec_version, const char data_model_version, oc_add_device_cb_t add_device_cb, void data)
	Add an ocf device to the the stack. More...

int	oc_add_device_v1 (oc_add_new_device_t cfg)
	Add an ocf device to the the stack. More...

void	oc_add_ownership_status_cb (oc_ownership_status_cb_t cb, void *user_data)
	Add callback that is invoked when the doxm "owned" property is changed. More...

bool	oc_add_resource (oc_resource_t *resource)
	Add a resource to the IoTivity stack. More...

void	oc_close_session (const oc_endpoint_t *endpoint)
	close the tls session on the indicated endpoint More...

void	oc_delayed_delete_resource (oc_resource_t *resource)
	Schedule a callback to remove a resource. More...

bool	oc_delete_resource (oc_resource_t *resource)
	Remove a resource from the IoTivity stack and delete the resource. More...

void	oc_device_bind_resource_type (size_t device, const char *type)
	Add a Resource Type "rt" property to the an `/oic/d` resource. More...

bool	oc_do_delete (const char uri, const oc_endpoint_t endpoint, const char query, oc_response_handler_t handler, oc_qos_t qos, void user_data)
	Issue a DELETE request to delete a resource. More...

bool	oc_do_delete_with_timeout (const char uri, const oc_endpoint_t endpoint, const char query, uint16_t timeout_seconds, oc_response_handler_t handler, oc_qos_t qos, void user_data)
	Issue a DELETE request to delete a resource. More...

bool	oc_do_get (const char uri, const oc_endpoint_t endpoint, const char query, oc_response_handler_t handler, oc_qos_t qos, void user_data)
	Issue a GET request to obtain the current value of all properties a resource. More...

bool	oc_do_get_with_timeout (const char uri, const oc_endpoint_t endpoint, const char query, uint16_t timeout_seconds, oc_response_handler_t handler, oc_qos_t qos, void user_data)
	Issue a GET request to obtain the current value of all properties a resource. More...

bool	oc_do_ip_discovery (const char rt, oc_discovery_handler_t handler, void user_data)
	Discover all servers that have a resource type. More...

bool	oc_do_ip_discovery_all (oc_discovery_all_handler_t handler, void *user_data)
	Discover all servers. More...

bool	oc_do_ip_discovery_all_at_endpoint (oc_discovery_all_handler_t handler, const oc_endpoint_t endpoint, void user_data)
	Discover all resources in a specific endpoint. More...

bool	oc_do_ip_discovery_at_endpoint (const char rt, oc_discovery_handler_t handler, const oc_endpoint_t endpoint, void *user_data)
	Discover resources in a specific endpoint. More...

bool	oc_do_ip_multicast (const char uri, const char query, oc_response_handler_t handler, void *user_data)
	invoke multicast discovery of devices More...

bool	oc_do_observe (const char uri, const oc_endpoint_t endpoint, const char query, oc_response_handler_t handler, oc_qos_t qos, void user_data)
	Dispatch a GET request with the CoAP Observe option to subscribe for notifications from a resource. More...

bool	oc_do_post (void)
	Dispatch the CoAP POST request. More...

bool	oc_do_post_with_timeout (uint16_t timeout_seconds)
	Dispatch the CoAP POST request. More...

bool	oc_do_put (void)
	Dispatch the CoAP PUT request. More...

bool	oc_do_put_with_timeout (uint16_t timeout_seconds)
	Dispatch the CoAP POST request. More...

bool	oc_do_realm_local_ipv6_discovery (const char rt, oc_discovery_handler_t handler, void user_data)
	Discover all servers that have a resource type using the realm-local scope. More...

bool	oc_do_realm_local_ipv6_discovery_all (oc_discovery_all_handler_t handler, void *user_data)
	Discover all servers using the realm-local scope. More...

bool	oc_do_realm_local_ipv6_multicast (const char uri, const char query, oc_response_handler_t handler, void *user_data)
	invoke multicast discovery of devices on IPV6 realm local scope More...

bool	oc_do_site_local_ipv6_discovery (const char rt, oc_discovery_handler_t handler, void user_data)
	Discover all servers that have a resource type using the site-local scope. More...

bool	oc_do_site_local_ipv6_discovery_all (oc_discovery_all_handler_t handler, void *user_data)
	Discover all servers using the realm-local scope. More...

bool	oc_do_site_local_ipv6_multicast (const char uri, const char query, oc_response_handler_t handler, void *user_data)
	invoke multicast discovery of devices on IPV6 site local scope More...

void	oc_free_server_endpoints (oc_endpoint_t *endpoint)
	Free a list of endpoints from the oc_endpoint_t. More...

bool	oc_get_con_res_announced (void)
	Returns whether the oic.wk.con resource is advertised. More...

bool	oc_get_diagnostic_message (const oc_client_response_t response, const char msg, size_t size)
	retrieve the diagnostic payload from a response More...

int	oc_get_query_value (const oc_request_t request, const char key, const char **value)
	Get a pointer to the start of the value in a URL query parameter key=value pair. More...

int	oc_get_query_value_v1 (const oc_request_t request, const char key, size_t key_len, const char **value)
	Get a pointer to the start of the value in a URL query parameter key=value pair. More...

bool	oc_get_request_payload_raw (const oc_request_t request, const uint8_t payload, size_t size, oc_content_format_t *content_format)
	retrieve the payload from the request, no processing More...

bool	oc_get_response_payload_raw (const oc_client_response_t response, const uint8_t payload, size_t size, oc_content_format_t *content_format)
	retrieve the response payload, without processing More...

bool	oc_has_delayed_callback (const void *cb_data, oc_trigger_t callback, bool ignore_cb_data)
	Check if given delayed callback has already been scheduled. More...

void	oc_ignore_request (oc_request_t *request)
	Ignore the request. More...

void	oc_indicate_separate_response (oc_request_t request, oc_separate_response_t response)
	Respond to an incoming request asynchronously. More...

int	oc_init_platform (const char mfg_name, oc_init_platform_cb_t init_platform_cb, void data)
	Initialize the platform. More...

bool	oc_init_post (const char uri, const oc_endpoint_t endpoint, const char query, oc_response_handler_t handler, oc_qos_t qos, void user_data)
	Prepare the stack to issue a POST request. More...

bool	oc_init_put (const char uri, const oc_endpoint_t endpoint, const char query, oc_response_handler_t handler, oc_qos_t qos, void user_data)
	Prepare the stack to issue a PUT request. More...

void	oc_init_query_iterator (void)
	This resets the query iterator to the start of the URI query parameter. More...

bool	oc_is_owned_device (size_t device_index)
	Get the ownership status of the logical device this is the value of the doxm "owned" property. More...

int	oc_iterate_query (const oc_request_t request, const char key, size_t key_len, const char *value, size_t value_len)
	Iterate through the URI query parameters and get each key=value pair. More...

bool	oc_iterate_query_get_values (const oc_request_t request, const char key, const char *value, int value_len)
	Iterate though the URI query parameters for a specific key. More...

bool	oc_iterate_query_get_values_v1 (const oc_request_t request, const char key, size_t key_len, const char *value, int value_len)
	Iterate though the URI query parameters for a specific key. More...

int	oc_main_init (const oc_handler_t *handler)
	Register and call handler functions responsible for controlling the IoTivity-lite stack. More...

bool	oc_main_needs_poll (void)
	Check if process polling was requested. More...

oc_clock_time_t	oc_main_poll (void)
	Poll to process tasks. More...

oc_clock_time_t	oc_main_poll_v1 (void)
	Poll to process tasks. More...

void	oc_main_shutdown (void)
	Shutdown and free all stack related resources. More...

oc_resource_t *	oc_new_resource (const char name, const char uri, uint8_t num_resource_types, size_t device)
	Allocate and populate a new oc_resource_t. More...

int	oc_notify_observers (oc_resource_t *resource)
	Notify all observers of a change to a given resource's property. More...

void	oc_notify_observers_delayed (oc_resource_t *resource, uint16_t seconds)
	Schedule notify all observers to invoke after a set number of seconds. More...

void	oc_notify_observers_delayed_ms (oc_resource_t *resource, uint16_t milliseconds)
	Schedule notify all observers to invoke after a set number of milliseconds. More...

void	oc_notify_resource_changed (oc_resource_t *resource)
	Notify all relevant mechanisms of a change to a given resource. More...

void	oc_process_baseline_interface (const oc_resource_t *resource)
	Helper function used when responding to a GET request to add Common Properties to a GET response. More...

int	oc_query_value_exists (const oc_request_t request, const char key)
	Checks if a query parameter 'key' exist in the URL query parameter. More...

bool	oc_query_value_exists_v1 (const oc_request_t request, const char key, size_t key_len)
	Checks if a query parameter 'key' exist in the URL query parameter. More...

void	oc_remove_delayed_callback (const void *cb_data, oc_trigger_t callback)
	Cancel a scheduled delayed callback. More...

void	oc_remove_delayed_callback_by_filter (oc_trigger_t cb, oc_ri_timed_event_filter_t filter, const void *filter_data, bool match_all, oc_ri_timed_event_on_delete_t on_delete)
	Cancel a scheduled delayed callback by matching it by the provided filtering function. More...

void	oc_remove_ownership_status_cb (oc_ownership_status_cb_t cb, const void *user_data)
	Remove the ownership changed callback. More...

void	oc_reset (void)
	Reset all logical devices to the RFOTM state and close all opened TLS connections immediately. More...

void	oc_reset_device (size_t device)
	Reset logical device to the RFOTM state and close all opened TLS connections immediately. More...

bool	oc_reset_device_v1 (size_t device, bool force)
	Reset logical device to the RFOTM state. More...

void	oc_reset_v1 (bool force)
	Reset all logical devices to the RFOTM state. More...

void	oc_resource_bind_resource_interface (oc_resource_t *resource, oc_interface_mask_t iface_mask)
	Add the supported interface(s) to the resource. More...

void	oc_resource_bind_resource_type (oc_resource_t resource, const char type)
	Add a Resource Type "rt" property to the resource. More...

void	oc_resource_make_public (oc_resource_t *resource)
	Expose unsecured coap:// endpoints (in addition to secured coaps:// endpoints) for this resource in /oic/res. More...

void	oc_resource_set_default_interface (oc_resource_t *resource, oc_interface_mask_t iface_mask)
	Select the default interface. More...

void	oc_resource_set_discoverable (oc_resource_t *resource, bool state)
	Specify if a resource can be found using OCF discover mechanisms. More...

void	oc_resource_set_observable (oc_resource_t *resource, bool state)
	Specify that a resource should notify clients when a property has been modified. More...

void	oc_resource_set_periodic_observable (oc_resource_t *resource, uint16_t seconds)
	The resource will periodically notify observing clients of is property values. More...

void	oc_resource_set_pushable (oc_resource_t *resource, bool state)
	Specify if a resource can be pushable. More...

void	oc_resource_set_request_handler (oc_resource_t resource, oc_method_t method, oc_request_callback_t callback, void user_data)
	Specify a request_callback for GET, PUT, POST, and DELETE methods. More...

void	oc_resource_tag_func_desc (oc_resource_t *resource, oc_enum_t func)
	Sets the tag value for the relatvie position "tag_func_rel" tag. More...

void	oc_resource_tag_locn (oc_resource_t *resource, oc_locn_t locn)
	sets the value of the "tag_locn" tag More...

void	oc_resource_tag_pos_desc (oc_resource_t *resource, oc_pos_description_t pos)
	Sets the tag value for tag "tag-pos-desc" on the resource. More...

void	oc_resource_tag_pos_rel (oc_resource_t *resource, double x, double y, double z)
	Sets the value for the relative position "tag-pos-rel" tag. More...

void	oc_send_diagnostic_message (oc_request_t request, const char msg, size_t msg_len, oc_status_t response_code)
	send a diagnostic payload More...

bool	oc_send_ping (bool custody, const oc_endpoint_t endpoint, uint16_t timeout_seconds, oc_response_handler_t handler, void user_data)
	send CoAP ping over the TCP connection More...

void	oc_send_response (oc_request_t *request, oc_status_t response_code)
	Called after the response to a GET, PUT, POST or DELETE call has been prepared completed. More...

void	oc_send_response_raw (oc_request_t request, const uint8_t payload, size_t size, oc_content_format_t content_format, oc_status_t response_code)
	send the request, no processing More...

void	oc_send_response_with_callback (oc_request_t *request, oc_status_t response_code, bool trigger_cb)
	Called after the response to a GET, PUT, POST or DELETE call has been prepared completed. More...

void	oc_send_separate_response (oc_separate_response_t *handle, oc_status_t response_code)
	Called to send the deferred response to a GET, PUT, POST or DELETE request. More...

void	oc_set_con_res_announced (bool announce)
	Sets whether the oic.wk.con resource is announced. More...

void	oc_set_con_write_cb (oc_con_write_cb_t callback)
	Sets the callback to receive change notifications for the `oic.wk.con` resource. More...

void	oc_set_delayed_callback (void *cb_data, oc_trigger_t callback, uint16_t seconds)
	Schedule a callback to be invoked after a set number of seconds. More...

void	oc_set_delayed_callback_ms (void *cb_data, oc_trigger_t callback, uint16_t milliseconds)
	Schedule a callback to be invoked after a set number of milliseconds. More...

void	oc_set_delayed_callback_ms_v1 (void *cb_data, oc_trigger_t callback, uint64_t milliseconds)
	Schedule a callback to be invoked after a set number of milliseconds. More...

void	oc_set_factory_presets_cb (oc_factory_presets_cb_t cb, void *data)
	Set the factory presets callback. More...

void	oc_set_immutable_device_identifier (size_t device, const oc_uuid_t *piid)
	Set the immutable device identifier. More...

void	oc_set_random_pin_callback (oc_random_pin_cb_t cb, void *data)
	Set the random pin callback for Random PIN Ownership Transfer Method (OTM) More...

void	oc_set_select_oxms_cb (oc_select_oxms_cb_t callback, void *user_data)
	Sets the callback to filter out unsupported ownership methods. More...

void	oc_set_send_response_callback (oc_send_response_cb_t cb)
	Set the send response callback function. More...

void	oc_set_separate_response_buffer (oc_separate_response_t *handle)
	Set a response buffer for holding the response payload. More...

void	oc_stop_multicast (oc_client_response_t *response)
	stop the multicast update (e.g. More...

bool	oc_stop_observe (const char uri, const oc_endpoint_t endpoint)
	Unsubscribe for notifications from a resource. More...

Detailed Description

Main API of IoTivity-Lite for client and server.

Macro Definition Documentation

◆ oc_set_custom_device_property

#define oc_set_custom_device_property	(	prop,
		value
	)	oc_rep_set_text_string(root, prop, value)

Set custom device property.

The purpose is to add additional device properties that are not supplied to oc_add_device() function call. This function will likely only be used inside the oc_add_device_cb_t().

Parameters

[in]	prop	the name of the custom property being added to the device
[in]	value	the value of the custom property being added to the device

See also: oc_add_device_cb_t for example code using this function; oc_add_device

◆ oc_set_custom_platform_property

#define oc_set_custom_platform_property	(	prop,
		value
	)	oc_rep_set_text_string(root, prop, value)

Set custom platform property.

The purpose is to add additional platfrom properties that are not supplied to oc_init_platform() function call. This function will likely only be used inside the oc_init_platform_cb_t().

Parameters

[in]	prop	the name of the custom property being added to the platform
[in]	value	the value of the custom property being added to the platform

See also: oc_init_platform_cb_t for example code using this function; oc_init_platform

Typedef Documentation

◆ oc_add_device_cb_t

typedef void(* oc_add_device_cb_t) (void *data)

Callback invoked during oc_add_device().

The purpose is to add any additional device properties that are not supplied to oc_add_device() function call.

Example:

static void set_device_custom_property(void *data)
{
  (void)data;
  oc_set_custom_device_property(purpose, "desk lamp");
}
 
static int app_init(void)
{
  int ret = oc_init_platform("My Platform", NULL, NULL);
  ret |= oc_add_device("/oic/d", "oic.d.light", "My light", "ocf.1.0.0",
                       "ocf.res.1.0.0", set_device_custom_property, NULL);
  return ret;
}

Parameters

[in] data context pointer that comes from the oc_init_platform() function

See also: oc_add_device; oc_set_custom_device_property

◆ oc_connectivity_listening_ports_t

typedef struct oc_connectivity_listening_ports_s oc_connectivity_listening_ports_t

The structure includes flags that can be used to disable listening on certain IP interfaces.

If a port is set to 0, the system will determine which port to open by default. On the other hand, if a port is specified, the stack will open that particular port.

◆ oc_factory_presets_cb_t

typedef void(* oc_factory_presets_cb_t) (size_t device, void *data)

Callback invoked by the stack initialization to perform any "factory settings", e.g., this may be used to load a manufacturer certificate.

The following example illustrates the method of loading a manufacturer certificate chain (end-entity certificate, intermediate CA certificate, and root CA certificate) using oc_pki_xxx APIs.

Example:

void factory_presets_cb(size_t device, void *data)
{
  (void)device;
  (void)data;
#if defined(OC_SECURITY) && defined(OC_PKI)
  char cert[8192];
  size_t cert_len = 8192;
  if (read_pem("pki_certs/ee.pem", cert, &cert_len) < 0) {
    OC_PRINTF("ERROR: unable to read certificates\n");
    return;
  }
 
  char key[4096];
  size_t key_len = 4096;
  if (read_pem("pki_certs/key.pem", key, &key_len) < 0) {
    OC_PRINTF("ERROR: unable to read private key");
    return;
  }
 
  int ee_credid = oc_pki_add_mfg_cert(0, (const unsigned char *)cert,
cert_len, (const unsigned char *)key, key_len);
 
  if (ee_credid < 0) {
    OC_PRINTF("ERROR installing manufacturer EE cert\n");
    return;
  }
 
  cert_len = 8192;
  if (read_pem("pki_certs/subca1.pem", cert, &cert_len) < 0) {
    OC_PRINTF("ERROR: unable to read certificates\n");
    return;
  }
 
  int subca_credid = oc_pki_add_mfg_intermediate_cert(
    0, ee_credid, (const unsigned char *)cert, cert_len);
 
  if (subca_credid < 0) {
    OC_PRINTF("ERROR installing intermediate CA cert\n");
    return;
  }
 
  cert_len = 8192;
  if (read_pem("pki_certs/rootca1.pem", cert, &cert_len) < 0) {
    OC_PRINTF("ERROR: unable to read certificates\n");
    return;
  }
 
  int rootca_credid =
    oc_pki_add_mfg_trust_anchor(0, (const unsigned char *)cert, cert_len);
  if (rootca_credid < 0) {
    OC_PRINTF("ERROR installing root cert\n");
    return;
  }
 
  oc_pki_set_security_profile(0, OC_SP_BLACK, OC_SP_BLACK, ee_credid);
#endif // OC_SECURITY && OC_PKI
}

Parameters

[in]	device	number of the device
[in]	data	context pointer that comes from the oc_set_factory_presets_cb() function

See also: oc_set_factory_presets_cb; oc_pki_add_mfg_cert; oc_pki_add_mfg_intermediate_cert; oc_pki_add_mfg_trust_anchor; oc_pki_set_security_profile

◆ oc_init_platform_cb_t

typedef void(* oc_init_platform_cb_t) (void *data)

Callback invoked during oc_init_platform().

The purpose is to add any additional platform properties that are not supplied to oc_init_platform() function call.

Example:

static void set_additional_platform_properties(void *data)
{
  (void)data;
  // Manufactures Details Link
  oc_set_custom_platform_property(mnml,
"http://www.example.com/manufacture");
  // Model Number
  oc_set_custom_platform_property(mnmo, "Model No1");
  // Date of Manufacture
  oc_set_custom_platform_property(mndt,"2020/01/17");
  //Serial Number
  oc_set_custom_platform_property(mnsel, "1234567890");
}
 
static int app_init(void)
{
  int ret = oc_init_platform("My Platform",
set_additional_platform_properties, NULL); ret |= oc_add_device("/oic/d",
"oic.d.light", "My light", "ocf.1.0.0", "ocf.res.1.0.0", NULL, NULL); return
ret;
}

Parameters

[in] data context pointer that comes from the oc_add_device() function

See also: oc_add_device; oc_set_custom_device_property

◆ oc_ownership_status_cb_t

typedef void(* oc_ownership_status_cb_t) (const oc_uuid_t *device_uuid, size_t device_index, bool owned, void *user_data)

Callback invoked when the "owned" property of the doxm is changed.

Parameters

[in]	device_uuid	the UUID of the device that change ownership
[in]	device_index	of the logical device that changed ownership
[in]	owned	if true the device has been claimed by an onboarding tool
[in]	user_data	context pointer

◆ oc_random_pin_cb_t

typedef void(* oc_random_pin_cb_t) (const unsigned char *pin, size_t pin_len, void *data)

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
static void random_pin_cb(const unsigned char *pin, size_t pin_len, void
*data)
{
 (void)data;
 OC_PRINTF("\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;
}

Parameters

[in]	pin	random pin
[in]	pin_len	length of the random pin
[in]	data	context pointer that comes from the oc_init_platform() function

See also: oc_set_random_pin_callback

◆ oc_select_oxms_cb_t

typedef void(* oc_select_oxms_cb_t) (size_t device_index, int *oxms, int *num_oxms, void *user_data)

Callback to filter out unsupported ownership methods when they are evaluated.

For example, if you want to support only the manufacturer certificate based owner transfer method, you will set oxms[0] to OC_OXMTYPE_MFG_CERT and *num_oxms to 1.

Parameters

[in]	device_index	of the logical device that changed ownership
[in,out]	oxms	array of supported ownership types(oc_sec_doxmtype_t). Filters out non-supported methods.
[in,out]	num_oxms	number of supported ownership methods.
[in]	user_data	context pointer

Enumeration Type Documentation

◆ oc_connectivity_listening_port_flags_e

enum oc_connectivity_listening_port_flags_e

Enumerator
OC_CONNECTIVITY_DISABLE_IPV6_PORT	Disable port on IPv6.
OC_CONNECTIVITY_DISABLE_SECURE_IPV6_PORT	Disable port on IPv6 for secure connections.
OC_CONNECTIVITY_DISABLE_ALL_PORTS	Disable all ports.

Function Documentation

◆ oc_add_device()

int oc_add_device	(	const char *	uri,
		const char *	rt,
		const char *	name,
		const char *	spec_version,
		const char *	data_model_version,
		oc_add_device_cb_t	add_device_cb,
		void *	data
	)

Add an ocf device to the the stack.

This function is typically called as part of the stack initialization process from inside the init callback handler.

The oc_add_device function may be called as many times as needed. Each call will add a new device to the stack with its own port address. Each device is automatically assigned a number starting with zero and incremented by one each time the function is called. This number is not returned therefore it is important to know the order devices are added.

Example:

//app_init is an instance of the `init` callback handler.
static int app_init(void)
{
  int ret = oc_init_platform("Refrigerator", NULL, NULL);
  ret |= oc_add_device("/oic/d", "oic.d.refrigeration", "My fridge",
                       "ocf.2.0.5", "ocf.res.1.0.0,ocf.sh.1.0.0",
                       NULL, NULL);
  ret |= oc_add_device("/oic/d", "oic.d.thermostat", "My thermostat",
                       "ocf.2.0.5", "ocf.res.1.0.0,ocf.sh.1.0.0",
                       NULL, NULL);
  return ret;
}

Parameters

[in]	uri	the The device URI. The wellknown default URI "/oic/d" is hosted by every server. Used to expose device specific information
[in]	rt	the resource type
[in]	name	the user readable name of the device
[in]	spec_version	The version of the OCF Server. This is the "icv" device property
[in]	data_model_version	Spec version of the resource and device specifications to which this device data model is implemtned. This is the "dmv" device property
[in]	add_device_cb	callback function invoked during oc_add_device(). The purpose is to add additional device properties that are not supplied to oc_add_device() function call.
[in]	data	context pointer that is passed to the oc_add_device_cb_t

Returns

0 on success
-1 on failure

See also: init

◆ oc_add_device_v1()

int oc_add_device_v1 ( oc_add_new_device_t cfg )

Add an ocf device to the the stack.

This function is typically called as part of the stack initialization process from inside the init callback handler.

The oc_add_device_v1 function may be called as many times as needed. Each call will add a new device to the stack with its own port address. Each device is automatically assigned a number starting with zero and incremented by one each time the function is called. This number is not returned therefore it is important to know the order devices are added.

Example:

//app_init is an instance of the `init` callback handler.
static int app_init(void)
{
  int ret = oc_init_platform("Refrigerator", NULL, NULL);
  ret |= oc_add_device_v1(device1);
  ret |= oc_add_device_v1(device2);
  return ret;
}

Parameters

[in] cfg the configuration of the new device

Returns

0 on success
-1 on failure

See also: init

◆ oc_add_ownership_status_cb()

void oc_add_ownership_status_cb	(	oc_ownership_status_cb_t	cb,
		void *	user_data
	)

Add callback that is invoked when the doxm "owned" property is changed.

If oc_add_ownership_status_cb is called before oc_main_init or inside one of the , the oc_handler_t callback funtions the oc_ownership_status_cb_t will be invoked when the stack is initilized giving the startup ownership value. If oc_add_ownership_status_cb is called after oc_main_init the oc_add_ownership_status_cb will not be invoked for the startup ownership value.

Note: Use of this function requires building the stack with OC_SECURITY defined.

Parameters

[in]	cb	callback function that will be invoked
[in]	user_data	context pointer passed to the oc_ownership_status_cb_t callback the pointer must remain valid till callback is removed.

◆ oc_get_con_res_announced()

bool oc_get_con_res_announced ( void )

Returns whether the oic.wk.con resource is advertised.

Returns

true if advertised (default)
false if not

See also: oc_set_con_res_announced; oc_set_con_write_cb

◆ oc_init_platform()

int oc_init_platform	(	const char *	mfg_name,
		oc_init_platform_cb_t	init_platform_cb,
		void *	data
	)

Initialize the platform.

This function is typically called as part of the stack initialization process from inside the init callback handler.

Parameters

[in]	mfg_name	the name of the platform manufacture
[in]	init_platform_cb	callback function invoked during oc_init_platform(). The purpose is to add additional device properties that are not supplied to oc_init_platform() function call.
[in]	data	context pointer that is passed to the oc_init_platform_cb_t

Returns

0 on success
-1 on failure

See also: init; oc_init_platform_cb_t

◆ oc_is_owned_device()

bool oc_is_owned_device ( size_t device_index )

Get the ownership status of the logical device this is the value of the doxm "owned" property.

If oc_is_owned_device() is called before oc_main_init() has completed it will always return false because stack security has not been initialized.

Note: Use of this function requires building the stack with OC_SECURITY defined.

Parameters

[in] device_index the index of the logical device

Returns: true if the device is owned by an onboarding tool

◆ oc_main_init()

int oc_main_init ( const oc_handler_t * handler )

Register and call handler functions responsible for controlling the IoTivity-lite stack.

This will initialize the IoTivity-lite stack.

Before initializing the stack, a few setup functions may need to be called before calling oc_main_init those functions are:

Not all of the listed functions must be called before calling oc_main_init.

Parameters

[in] handler struct containing pointers callback handler functions responsible for controlling the IoTivity-lite application

Returns

0 if stack has been initialized successfully
a negative number if there is an error in stack initialization

See also: oc_set_con_res_announced; oc_set_factory_presets_cb; oc_set_max_app_data_size; oc_set_random_pin_callback; oc_storage_config

◆ oc_main_needs_poll()

bool oc_main_needs_poll ( void )

Check if process polling was requested.

Returns: true A polling of processes was requested by a call to oc_process_poll and oc_main_poll_v1 should be called.; false Otherwise

See also: oc_main_poll; oc_process_poll

◆ oc_main_poll()

oc_clock_time_t oc_main_poll ( void )

Poll to process tasks.

Returns: Time for the next poll event in absolute time

Deprecated:: replaced by oc_main_poll_v1 in v2.2.5.6

◆ oc_main_poll_v1()

oc_clock_time_t oc_main_poll_v1 ( void )

Poll to process tasks.

Returns: Time for the next poll event in monotonic time

Note: The underlying implementation uses monotonic to keep track of time. To calculate the remaining time until the next poll event use oc_clock_time_monotonic().

See also: oc_clock_time_monotonic

◆ oc_main_shutdown()

void oc_main_shutdown ( void )

Shutdown and free all stack related resources.

◆ oc_remove_ownership_status_cb()

void oc_remove_ownership_status_cb	(	oc_ownership_status_cb_t	cb,
		const void *	user_data
	)

Remove the ownership changed callback.

Note: Use of this function requires building the stack with OC_SECURITY defined.

Parameters

[in]	cb	callback function to remove
[in]	user_data	the context pointer used when the callback was added

◆ oc_reset()

void oc_reset ( void )

Reset all logical devices to the RFOTM state and close all opened TLS connections immediately.

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.; Use of this function requires building with OC_SECURITY defined.; A device connected to a cloud is not unregistered from the cloud since the connection has been closed immediately.

◆ oc_reset_device()

void oc_reset_device ( size_t device )

Reset logical device to the RFOTM state and close all opened TLS connections immediately.

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.; Use of this function requires building the stack with OC_SECURITY defined.

Parameters

[in] device index of the logical device to reset

◆ oc_reset_device_v1()

bool oc_reset_device_v1	(	size_t	device,
		bool	force
	)

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.; Use of this function requires building the stack with OC_SECURITY defined.

Parameters

[in]	device	index of the logical device to reset
[in]	force	true to reset immediately, false to reset after the 2 second for terminate the connections (eg cloud unregistration)

◆ oc_reset_v1()

void oc_reset_v1 ( bool force )

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_v1() deals only with security and provisioning it does not reset any other device settings.; Use of this function requires building with OC_SECURITY defined.

Parameters

[in] force true to close all TLS connections immediately, false to close them after the 2 second delay. Set to false if the device is connected to a cloud and you want to unregister it.

◆ oc_set_con_res_announced()

void oc_set_con_res_announced ( bool announce )

Sets whether the oic.wk.con resource is announced.

Note: This should be set before invoking oc_main_init().

Parameters

[in] announce true to announce (default) or false if not

See also: oc_get_con_res_announced; oc_set_con_write_cb

◆ oc_set_factory_presets_cb()

void oc_set_factory_presets_cb	(	oc_factory_presets_cb_t	cb,
		void *	data
	)

Set the factory presets callback.

The factory presets callback is called by the stack to enable per-device presets.

Note: oc_set_factory_presets_cb() must be called before oc_main_init().

Parameters

[in]	cb	oc_factory_presets_cb_t function pointer to be called
[in]	data	context pointer that is passed to the oc_factory_presets_cb_t the pointer must be a valid pointer till after oc_main_init() call completes.

◆ oc_set_random_pin_callback()

void oc_set_random_pin_callback	(	oc_random_pin_cb_t	cb,
		void *	data
	)

Set the random pin callback for Random PIN Ownership Transfer Method (OTM)

Note: This should be set before invoking oc_main_init().

Parameters

[in]	cb	callback function invoked when client requests Random PIN OTM
[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 also: oc_random_pin_cb_t; oc_main_init

◆ oc_set_select_oxms_cb()

void oc_set_select_oxms_cb	(	oc_select_oxms_cb_t	callback,
		void *	user_data
	)

Sets the callback to filter out unsupported ownership methods.

The function can be used to set or unset the callback. For example, if you want to support only the manufacturer certificate based owner transfer method.

Parameters

	callback	The callback to register or NULL to unset it. If the function is invoked a second time, then the previously set callback is simply replaced.
[in]	user_data	context pointer

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ oc_set_custom_device_property

◆ oc_set_custom_platform_property

Typedef Documentation

◆ oc_add_device_cb_t

◆ oc_connectivity_listening_ports_t

◆ oc_factory_presets_cb_t

◆ oc_init_platform_cb_t

◆ oc_ownership_status_cb_t

◆ oc_random_pin_cb_t

◆ oc_select_oxms_cb_t

Enumeration Type Documentation

◆ oc_connectivity_listening_port_flags_e

Function Documentation

◆ oc_add_device()

◆ oc_add_device_v1()

◆ oc_add_ownership_status_cb()

◆ oc_get_con_res_announced()

◆ oc_init_platform()

◆ oc_is_owned_device()

◆ oc_main_init()

◆ oc_main_needs_poll()

◆ oc_main_poll()

◆ oc_main_poll_v1()

◆ oc_main_shutdown()

◆ oc_remove_ownership_status_cb()

◆ oc_reset()

◆ oc_reset_device()

◆ oc_reset_device_v1()

◆ oc_reset_v1()

◆ oc_set_con_res_announced()

◆ oc_set_factory_presets_cb()

◆ oc_set_random_pin_callback()

◆ oc_set_select_oxms_cb()