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_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 "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, 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_resource_free_instance_t) (oc_resource_t *)
	Callback invoked to delete an resource. More...

typedef oc_resource_t (	oc_resource_get_instance_t) (const char , oc_string_array_t , oc_resource_properties_t, oc_interface_mask_t, size_t)
	Callback invoked to retrieve an resource. 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
OC_API void	oc_add_collection (oc_resource_t *collection)
	Adds a collection to the list of collections. More...

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

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

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

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

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

OC_API void	oc_collection_add_link (oc_resource_t collection, oc_link_t link)
	Adds the link to the collection. More...

OC_API bool	oc_collection_add_mandatory_rt (oc_resource_t collection, const char rt)
	Add a mandatory Resource Type to a collection. More...

OC_API bool	oc_collection_add_supported_rt (oc_resource_t collection, const char rt)
	Add a supported Resource Type to a collection. More...

OC_API oc_resource_t *	oc_collection_get_collections (void)
	Gets all known collections. More...

OC_API oc_link_t *	oc_collection_get_links (oc_resource_t *collection)
	Returns the list of links belonging to this collection. More...

OC_API void	oc_collection_remove_link (oc_resource_t collection, oc_link_t link)
	Removes a link from the collection. More...

OC_API bool	oc_collections_add_rt_factory (const char *rt, oc_resource_get_instance_t get_instance, oc_resource_free_instance_t free_instance)
	adds the resource type factory More...

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

OC_API void	oc_delete_collection (oc_resource_t *collection)
	Deletes the specified collection. More...

OC_API void	oc_delete_link (oc_link_t *link)
	Deletes the link. More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

OC_API void	oc_link_add_link_param (oc_link_t link, const char key, const char *value)
	Adds a link parameter with specified key and value. More...

OC_API void	oc_link_add_rel (oc_link_t link, const char rel)
	Adds a relation to the link. More...

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

OC_API oc_clock_time_t	oc_main_poll (void)
	poll to process tasks More...

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

OC_API oc_resource_t *	oc_new_collection (const char name, const char uri, uint8_t num_resource_types, size_t device)
	Creates a new empty collection. More...

OC_API oc_link_t *	oc_new_link (oc_resource_t *resource)
	Creates a new link for collections with the specified resource. More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

OC_API void	oc_resource_set_properties_cbs (oc_resource_t resource, oc_get_properties_cb_t get_properties, void get_props_user_data, oc_set_properties_cb_t set_properties, void *set_props_user_data)
	sets the callback properties for set properties and get properties More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

OC_API void	oc_set_delayed_callback_ms (void *cb_data, oc_trigger_t callback, uint16_t milliseconds) OC_DEPRECATED("replaced by oc_set_delayed_callback_ms_v1 in v2.2.5.4")
	Schedule a callback to be invoked after a set number of milliseconds. More...

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

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

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

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

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

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

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

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

OC_API 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) {
    PRINT("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) {
    PRINT("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) {
    PRINT("ERROR installing manufacturer EE cert\n");
    return;
  }
 
  cert_len = 8192;
  if (read_pem("pki_certs/subca1.pem", cert, &cert_len) < 0) {
    PRINT("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) {
    PRINT("ERROR installing intermediate CA cert\n");
    return;
  }
 
  cert_len = 8192;
  if (read_pem("pki_certs/rootca1.pem", cert, &cert_len) < 0) {
    PRINT("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) {
    PRINT("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;
 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;
}

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()

OC_API 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()

OC_API 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()

OC_API 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()

OC_API 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()

OC_API 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()

OC_API 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()

OC_API 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_poll()

OC_API oc_clock_time_t oc_main_poll ( void )

poll to process tasks

Returns

time for the next poll event

◆ oc_main_shutdown()

OC_API void oc_main_shutdown ( void )

Shutdown and free all stack related resources.

◆ oc_remove_ownership_status_cb()

OC_API void oc_remove_ownership_status_cb	(	oc_ownership_status_cb_t	cb,
		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()

OC_API 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()

OC_API 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()

OC_API bool oc_reset_device_v1	(	size_t	device,
		bool	close_all_tls_connections_immediately
	)

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]	close_all_tls_connections_immediately	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_reset_v1()

OC_API void oc_reset_v1 ( bool close_all_tls_connections_immediately )

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] close_all_tls_connections_immediately 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()

OC_API 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()

OC_API 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()

OC_API 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()

OC_API 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_poll()

◆ 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()