 |
KNX IoT
KNX IoT Point API stack implementation
|
|
KNX IoT
KNX IoT Point API stack implementation
|
Main API of the stack for client and server. More...
#include "messaging/coap/oc_coap.h"#include "oc_buffer_settings.h"#include "oc_knx.h"#include "oc_rep.h"#include "oc_ri.h"#include "oc_client_state.h"#include "oc_signal_event_loop.h"#include "port/oc_storage.h"#include "api/oc_knx_client.h"#include "api/oc_knx_swu.h"#include "oc_programming_mode.h"Go to the source code of this file.
Data Structures | |
| 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_MAX_URL_LENGTH (30) |
| maximum URL length (as specified by KNX) 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 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_hostname_cb_t) (size_t device, oc_string_t host_name, void *data) |
| Callback invoked by the stack to set the host name. More... | |
| typedef void(* | oc_init_platform_cb_t) (void *data) |
| Callback invoked during oc_init_platform(). More... | |
| typedef void(* | oc_programming_mode_cb_t) (size_t device, bool programming_mode, void *data) |
| Set the programming mode callback NOTE: It is the responsibility of this callback (if registered), to set the programming mode of the device via a call to oc_knx_device_set_programming_mode();. More... | |
| typedef void(* | oc_reset_cb_t) (size_t device, int reset_value, void *data) |
| Callback invoked by the stack initialization to perform any application reset. More... | |
| typedef void(* | oc_restart_cb_t) (size_t device, void *data) |
| Callback invoked by the stack to invoke a restart. More... | |
Functions | |
| int | oc_add_device (const char *name, const char *version, const char *base, const char *serial_number, oc_add_device_cb_t add_device_cb, void *data) |
| Add an a device to the stack. More... | |
| bool | oc_add_resource (oc_resource_t *resource) |
| Add a resource to the stack. More... | |
| void | oc_close_session (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 stack and delete the resource. More... | |
| bool | oc_do_delete (const char *uri, 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_get (const char *uri, oc_endpoint_t *endpoint, const char *query, oc_response_handler_t handler, oc_qos_t qos, void *user_data) |
| issues a get request with accept-content CBOR More... | |
| bool | oc_do_get_ex (const char *uri, oc_endpoint_t *endpoint, const char *query, oc_response_handler_t handler, oc_qos_t qos, oc_content_format_t content, oc_content_format_t accept, void *user_data) |
| Issue a GET request to obtain the current value of all properties a resource. More... | |
| bool | oc_do_multicast_update (void) |
| initiate the multi-cast update More... | |
| bool | oc_do_observe (const char *uri, 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 wiht content type and accept type CBOR. More... | |
| bool | oc_do_post_ex (oc_content_format_t content, oc_content_format_t accept) |
| Dispatch the CoAP POST request. More... | |
| bool | oc_do_put (void) |
| Dispatch the CoAP PUT request wiht content type and accept type CBOR. More... | |
| bool | oc_do_put_ex (oc_content_format_t content, oc_content_format_t accept) |
| Dispatch the CoAP PUT request. More... | |
| bool | oc_do_wk_discovery_all (const char *uri_query, int scope, oc_discovery_all_handler_t handler, void *user_data) |
| Discover all servers that have a resource type using the 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_diagnostic_message (oc_client_response_t *response, const char **msg, size_t *size) |
| retrieve the diagnostic payload from a response More... | |
| int | oc_get_query_value (oc_request_t *request, const char *key, 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 (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 (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... | |
| 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... | |
| bool | oc_init_multicast_update (oc_endpoint_t *mcast, const char *uri, const char *query) |
| initialize the multicast update 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, 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, 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... | |
| int | oc_iterate_query (oc_request_t *request, char **key, size_t *key_len, 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 (oc_request_t *request, const char *key, char **value, int *value_len) |
| Iterate though the URI query parameters for a specific key. More... | |
| int | oc_lf_get_entry_param (const char *payload, int payload_len, int entry, const char *param, const char **p_out, int *p_len) |
| link format parser, retrieve a parameter value More... | |
| int | oc_lf_get_entry_uri (const char *payload, int payload_len, int entry, const char **uri, int *uri_len) |
| link format parser, retrieve the URL of an entry. More... | |
| int | oc_lf_number_of_entries (const char *payload, int payload_len) |
| link format parser, retrieve the number of entries in a response More... | |
| int | oc_main_init (const oc_handler_t *handler) |
| Register and call handler functions responsible for controlling the stack. More... | |
| oc_clock_time_t | oc_main_poll (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 (const oc_resource_t *resource) |
| Notify all observers of a change to a given resource's property. More... | |
| int | oc_query_value_exists (oc_request_t *request, const char *key) |
| Checks if a query parameter 'key' exist in the URL query parameter. More... | |
| bool | oc_query_values_available (oc_request_t *request) |
| Checks if a query parameter are available. More... | |
| void | oc_remove_delayed_callback (void *cb_data, oc_trigger_t callback) |
| used to cancel a delayed callback More... | |
| void | oc_resource_bind_content_type (oc_resource_t *resource, oc_content_format_t content_type) |
| set the content type on the resource More... | |
| void | oc_resource_bind_dpt (oc_resource_t *resource, const char *dpt) |
| Add a Data Point Type "dpt" property to the resource. 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 /well-known/core. More... | |
| void | oc_resource_set_discoverable (oc_resource_t *resource, bool state) |
| Specify if a resource can be found using .well-known/core discover mechanisms. More... | |
| void | oc_resource_set_function_block_instance (oc_resource_t *resource, uint8_t instance) |
| set a resource to a specific function block instance default is instance 0, if there is just 1 instance of the function block this function does not have to be called. 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_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... | |
| 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_send_cbor_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_cbor_response_with_payload_size (oc_request_t *request, oc_status_t response_code, size_t payload_size) |
| Called after the response to a GET, PUT, POST or DELETE call has been prepared completed. 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... | |
| void | oc_send_empty_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, with an empty payload. More... | |
| void | oc_send_json_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_linkformat_response (oc_request_t *request, oc_status_t response_code, size_t response_length) |
| Called after the response to a GET, PUT, POST or DELETE call has been prepared completed. More... | |
| bool | oc_send_ping (bool custody, 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, will respond with CBOR. More... | |
| void | oc_send_response_no_format (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_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_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 miliseconds) |
| Schedule a callback to be invoked after a set number of miliseconds. More... | |
| void | oc_set_factory_presets_cb (oc_factory_presets_cb_t cb, void *data) |
| Set the factory presets callback. More... | |
| void | oc_set_hostname_cb (oc_hostname_cb_t cb, void *data) |
| Set the host name callback. More... | |
| void | oc_set_programming_mode_cb (oc_programming_mode_cb_t cb, void *data) |
| Set the programming mode callback. More... | |
| void | oc_set_reset_cb (oc_reset_cb_t cb, void *data) |
| Set the reset callback. More... | |
| void | oc_set_restart_cb (oc_restart_cb_t cb, void *data) |
| Set the restart callback. 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, oc_endpoint_t *endpoint) |
| Unsubscribe for notifications from a resource. More... | |
Main API of the stack for client and server.
Definition in file oc_api.h.
| #define OC_MAX_URL_LENGTH (30) |
| #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().
| [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 |
| #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 platform 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().
| [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 |
| 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:
| [in] | data | context pointer that comes from the oc_init_platform() function |
| typedef void(* oc_factory_presets_cb_t) (size_t device, void *data) |
| typedef void(* oc_hostname_cb_t) (size_t device, oc_string_t host_name, void *data) |
| 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:
| [in] | data | context pointer that comes from the oc_add_device() function |
| typedef void(* oc_programming_mode_cb_t) (size_t device, bool programming_mode, void *data) |
Set the programming mode callback NOTE: It is the responsibility of this callback (if registered), to set the programming mode of the device via a call to oc_knx_device_set_programming_mode();.
| [in] | device | the device index |
| [in] | programming_mode | whether to set the programming mode to true or false |
| [in] | data | the user supplied data |
| typedef void(* oc_reset_cb_t) (size_t device, int reset_value, void *data) |
| typedef void(* oc_restart_cb_t) (size_t device, void *data) |
| int oc_add_device | ( | const char * | name, |
| const char * | version, | ||
| const char * | base, | ||
| const char * | serial_number, | ||
| oc_add_device_cb_t | add_device_cb, | ||
| void * | data | ||
| ) |
Add an a device to 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:
| [in] | name | the user readable name of the device |
| [in] | version | The api version e.g. "1.0.0" |
| [in] | base | the base url e.g. "/" |
| [in] | serial_number | the serial number of the device |
| [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 |
0 on success-1 on failureReferenced by app_init().
| 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.
| [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 |
0 on success-1 on failureReferenced by app_init().
| int oc_main_init | ( | const oc_handler_t * | handler | ) |
Register and call handler functions responsible for controlling the stack.
This will initialize the 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.
| [in] | handler | struct containing pointers callback handler functions responsible for controlling the application |
0 if stack has been initialized successfully| oc_clock_time_t oc_main_poll | ( | void | ) |
poll to process tasks
| void oc_main_shutdown | ( | void | ) |
Shutdown and free all stack related resources.
| 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.
| [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. |
| void oc_set_hostname_cb | ( | oc_hostname_cb_t | cb, |
| void * | data | ||
| ) |
Set the host name callback.
The host name callback is called by the stack when the host name needs to be set
| [in] | cb | oc_hostname_cb_t function pointer to be called |
| [in] | data | context pointer that is passed to the oc_restart_cb_t the pointer must be a valid pointer till after oc_main_init() call completes. |
| void oc_set_programming_mode_cb | ( | oc_programming_mode_cb_t | cb, |
| void * | data | ||
| ) |
Set the programming mode callback.
The programming mode callback is called by the stack to enable per-device setting of the programming mode on application level.
| [in] | cb | oc_programming_mode_cb_t function pointer to be called |
| [in] | data | context pointer that is passed to the oc_programming_mode_cb_t the pointer must be a valid pointer till after oc_main_init() call completes. |
| void oc_set_reset_cb | ( | oc_reset_cb_t | cb, |
| void * | data | ||
| ) |
Set the reset callback.
The reset callback is called by the stack to enable per-device reset on application level.
| [in] | cb | oc_reset_cb_t function pointer to be called |
| [in] | data | context pointer that is passed to the oc_reset_cb_t the pointer must be a valid pointer till after oc_main_init() call completes. |
| void oc_set_restart_cb | ( | oc_restart_cb_t | cb, |
| void * | data | ||
| ) |
Set the restart callback.
The restart callback is called by the stack to enable per-device reset on application level.
Implemented by the stack:
| [in] | cb | oc_restart_cb_t function pointer to be called |
| [in] | data | context pointer that is passed to the oc_restart_cb_t the pointer must be a valid pointer till after oc_main_init() call completes. |
1.9.1