ON Semiconductor / mbed-os

Dependents:   mbed-TFT-example-NCS36510 mbed-Accelerometer-example-NCS36510 mbed-Accelerometer-example-NCS36510

Embed: (wiki syntax)

« Back to documentation index

sn_nsdl_lib.h File Reference

sn_nsdl_lib.h File Reference

NanoService Devices Library header file. More...

Go to the source code of this file.

Data Structures

struct  sn_nsdl_ep_parameters_
 Endpoint registration parameters. More...
struct  sn_nsdl_sent_messages_
 For internal use. More...
struct  sn_grs_resource_
 Includes resource path. More...
struct  sn_grs_resource_list_
 Table of created resources. More...
struct  sn_nsdl_resource_parameters_
 Resource registration parameters. More...
struct  sn_nsdl_resource_info_
 Defines parameters for the resource. More...
struct  sn_nsdl_oma_device_
 Defines OMA device object parameters. More...
struct  sn_nsdl_oma_server_info_
 Defines OMAlw server information. More...
struct  sn_nsdl_bs_ep_info_
 Defines endpoint parameters to OMA bootstrap. More...

Typedefs

typedef enum omalw_server_security_ omalw_server_security_t
 Received device server security.
typedef enum
sn_nsdl_oma_binding_and_mode_ 
sn_nsdl_oma_binding_and_mode_t
 Endpoint binding and mode.
typedef enum
sn_nsdl_registration_mode_ 
sn_nsdl_registration_mode_t
 Endpoint registration mode.
typedef struct
sn_nsdl_ep_parameters_ 
sn_nsdl_ep_parameters_s
 Endpoint registration parameters.
typedef struct
sn_nsdl_sent_messages_ 
sn_nsdl_sent_messages_s
 For internal use.
typedef struct sn_grs_resource_ sn_grs_resource_s
 Includes resource path.
typedef struct
sn_grs_resource_list_ 
sn_grs_resource_list_s
 Table of created resources.
typedef enum sn_grs_resource_acl_ sn_grs_resource_acl_e
 Resource access rights.
typedef enum sn_nsdl_resource_mode_ sn_nsdl_resource_mode_e
 Defines the resource mode.
typedef struct
sn_nsdl_resource_parameters_ 
sn_nsdl_resource_parameters_s
 Resource registration parameters.
typedef struct
sn_nsdl_resource_info_ 
sn_nsdl_resource_info_s
 Defines parameters for the resource.
typedef struct sn_nsdl_oma_device_ sn_nsdl_oma_device_t
 Defines OMA device object parameters.
typedef struct
sn_nsdl_oma_server_info_ 
sn_nsdl_oma_server_info_t
 Defines OMAlw server information.
typedef struct sn_nsdl_bs_ep_info_ sn_nsdl_bs_ep_info_t
 Defines endpoint parameters to OMA bootstrap.

Enumerations

enum  omalw_server_security_
 

Received device server security.

More...
enum  sn_nsdl_oma_binding_and_mode_
 

Endpoint binding and mode.

More...
enum  sn_nsdl_registration_mode_
 

Endpoint registration mode.

More...
enum  sn_grs_resource_acl_
 

Resource access rights.

More...
enum  sn_nsdl_resource_mode_ {
  SN_GRS_STATIC = 0, SN_GRS_DYNAMIC, SN_GRS_DIRECTORY, SN_GRS_STATIC = 0,
  SN_GRS_DYNAMIC, SN_GRS_DIRECTORY
}
 

Defines the resource mode.

More...

Functions

uint16_t sn_nsdl_register_endpoint (struct nsdl_s *handle, sn_nsdl_ep_parameters_s *endpoint_info_ptr)
 Registers endpoint to mbed Device Server.
uint16_t sn_nsdl_unregister_endpoint (struct nsdl_s *handle)
 Sends unregister-message to mbed Device Server.
uint16_t sn_nsdl_update_registration (struct nsdl_s *handle, uint8_t *lt_ptr, uint8_t lt_len)
 Update the registration with mbed Device Server.
int8_t sn_nsdl_set_endpoint_location (struct nsdl_s *handle, uint8_t *location_ptr, uint8_t location_len)
 Sets the location receievd from Device Server.
int8_t sn_nsdl_is_ep_registered (struct nsdl_s *handle)
 Checks if endpoint is registered.
void sn_nsdl_nsp_lost (struct nsdl_s *handle)
 A function to inform mbed Device C client library if application detects a fault in mbed Device Server registration.
uint16_t sn_nsdl_send_observation_notification (struct nsdl_s *handle, uint8_t *token_ptr, uint8_t token_len, uint8_t *payload_ptr, uint16_t payload_len, sn_coap_observe_e observe, sn_coap_msg_type_e message_type, sn_coap_content_format_e content_format)
 Sends observation message to mbed Device Server.
uint16_t sn_nsdl_send_observation_notification_with_uri_path (struct nsdl_s *handle, uint8_t *token_ptr, uint8_t token_len, uint8_t *payload_ptr, uint16_t payload_len, sn_coap_observe_e observe, sn_coap_msg_type_e message_type, uint8_t content_type, uint8_t *uri_path_ptr, uint16_t uri_path_len)
 Sends observation message to mbed Device Server with uri path.
char * sn_nsdl_get_version (void)
 Version query function.
int8_t sn_nsdl_process_coap (struct nsdl_s *handle, uint8_t *packet, uint16_t packet_len, sn_nsdl_addr_s *src)
 To push CoAP packet to mbed Device C Client library.
int8_t sn_nsdl_exec (struct nsdl_s *handle, uint32_t time)
 CoAP retransmission function.
int8_t sn_nsdl_create_resource (struct nsdl_s *handle, sn_nsdl_resource_info_s *res)
 Resource creating function.
int8_t sn_nsdl_put_resource (struct nsdl_s *handle, sn_nsdl_resource_info_s *res)
 Resource putting function.
sn_nsdl_resource_info_ssn_nsdl_get_resource (struct nsdl_s *handle, uint16_t pathlen, uint8_t *path)
 Resource get function.
sn_grs_resource_list_ssn_nsdl_list_resource (struct nsdl_s *handle, uint16_t pathlen, uint8_t *path)
 Resource list function.
void sn_nsdl_free_resource_list (struct nsdl_s *handle, sn_grs_resource_list_s *list)
 Free a resource list obtained from sn_nsdl_list_resource()
int8_t sn_nsdl_send_coap_message (struct nsdl_s *handle, sn_nsdl_addr_s *address_ptr, sn_coap_hdr_s *coap_hdr_ptr)
 Send an outgoing CoAP request.
int8_t set_NSP_address (struct nsdl_s *handle, uint8_t *NSP_address, uint16_t port, sn_nsdl_addr_type_e address_type)
 This function is used to set the mbed Device Server address given by an application.
int8_t sn_nsdl_destroy (struct nsdl_s *handle)
 This function releases all allocated memory in mbed Device C Client library.
uint16_t sn_nsdl_oma_bootstrap (struct nsdl_s *handle, sn_nsdl_addr_s *bootstrap_address_ptr, sn_nsdl_ep_parameters_s *endpoint_info_ptr, sn_nsdl_bs_ep_info_t *bootstrap_endpoint_info_ptr)
 Starts OMA bootstrap process.
omalw_certificate_list_t * sn_nsdl_get_certificates (struct nsdl_s *handle)
 Get pointer to received device server certificates.
int8_t sn_nsdl_update_certificates (struct nsdl_s *handle, omalw_certificate_list_t *certificate_ptr, uint8_t certificate_chain)
 Updates certificate pointers to resource server.
int8_t sn_nsdl_create_oma_device_object (struct nsdl_s *handle, sn_nsdl_oma_device_t *device_object_ptr)
 Creates new device object resource.
sn_coap_hdr_ssn_nsdl_build_response (struct nsdl_s *handle, sn_coap_hdr_s *coap_packet_ptr, uint8_t msg_code)
 Prepares generic response packet from a request packet.
sn_coap_options_list_ssn_nsdl_alloc_options_list (struct nsdl_s *handle, sn_coap_hdr_s *coap_msg_ptr)
 Allocates and initializes options list structure.
void sn_nsdl_release_allocated_coap_msg_mem (struct nsdl_s *handle, sn_coap_hdr_s *freed_coap_msg_ptr)
 Releases memory of given CoAP message.
int8_t sn_nsdl_set_retransmission_parameters (struct nsdl_s *handle, uint8_t resending_count, uint8_t resending_interval)
 If re-transmissions are enabled, this function changes resending count and interval.
int8_t sn_nsdl_set_retransmission_buffer (struct nsdl_s *handle, uint8_t buffer_size_messages, uint16_t buffer_size_bytes)
 If re-transmissions are enabled, this function changes message retransmission queue size.
int8_t sn_nsdl_set_block_size (struct nsdl_s *handle, uint16_t block_size)
 If block transfer is enabled, this function changes the block size.
int8_t sn_nsdl_set_duplicate_buffer_size (struct nsdl_s *handle, uint8_t message_count)
 If dublicate message detection is enabled, this function changes buffer size.
void * sn_nsdl_get_context (const struct nsdl_s *const handle)
 Get the application defined context parameter for given handle.

Detailed Description

NanoService Devices Library header file.

Definition in file sn_nsdl_lib.h.


Typedef Documentation

Received device server security.

Resource access rights.

Table of created resources.

Includes resource path.

Defines endpoint parameters to OMA bootstrap.

Endpoint registration parameters.

Defines OMA device object parameters.

Defines OMAlw server information.

Endpoint registration mode.

If REGISTER_WITH_RESOURCES, endpoint sends list of all resources during registration. If REGISTER_WITH_TEMPLATE, endpoint sends registration without resource list. Device server must have correctly configured template.

Defines parameters for the resource.

Defines the resource mode.

Resource registration parameters.

For internal use.


Enumeration Type Documentation

Received device server security.

Definition at line 49 of file sn_nsdl_lib.h.

Resource access rights.

Definition at line 135 of file sn_nsdl_lib.h.

Endpoint binding and mode.

Definition at line 60 of file sn_nsdl_lib.h.

Endpoint registration mode.

If REGISTER_WITH_RESOURCES, endpoint sends list of all resources during registration. If REGISTER_WITH_TEMPLATE, endpoint sends registration without resource list. Device server must have correctly configured template.

Definition at line 73 of file sn_nsdl_lib.h.

Defines the resource mode.

Enumerator:
SN_GRS_STATIC 

Static resources have some value that doesn't change.

SN_GRS_DYNAMIC 

Dynamic resources are handled in application.

Therefore one must give function callback pointer to them

SN_GRS_DIRECTORY 

Directory resources are unused and unsupported.

Definition at line 158 of file sn_nsdl_lib.h.


Function Documentation

int8_t set_NSP_address ( struct nsdl_s *  handle,
uint8_t *  NSP_address,
uint16_t  port,
sn_nsdl_addr_type_e  address_type 
)

This function is used to set the mbed Device Server address given by an application.

Parameters:
*handlePointer to nsdl-library handle
Returns:
0 Success
-1 Failed to indicate that internal address pointer is not allocated (call nsdl_init() first).

Definition at line 1824 of file sn_nsdl.c.

sn_coap_options_list_s* sn_nsdl_alloc_options_list ( struct nsdl_s *  handle,
sn_coap_hdr_s coap_msg_ptr 
)

Allocates and initializes options list structure.

Parameters:
*handlePointer to library handle
*coap_msg_ptris pointer to CoAP message that will contain the options

If the message already has a pointer to an option structure, that pointer is returned, rather than a new structure being allocated.

Returns:
Return value is pointer to the CoAP options structure.
In following failure cases NULL is returned:
-Failure in given pointer (= NULL)
-Failure in memory allocation (malloc() returns NULL)

Definition at line 2525 of file sn_nsdl.c.

sn_coap_hdr_s * sn_nsdl_build_response ( struct nsdl_s *  handle,
sn_coap_hdr_s coap_packet_ptr,
uint8_t  msg_code 
)

Prepares generic response packet from a request packet.

This function allocates memory for the resulting sn_coap_hdr_s

Parameters:
*handlePointer to library handle
*coap_packet_ptrThe request packet pointer
msg_coderesponse messages code
Returns:
*coap_packet_ptr The allocated and pre-filled response packet pointer NULL Error in parsing the request

Definition at line 2516 of file sn_nsdl.c.

int8_t sn_nsdl_create_oma_device_object ( struct nsdl_s *  handle,
sn_nsdl_oma_device_t device_object_ptr 
)

Creates new device object resource.

Parameters:
*handlePointer to nsdl-library handle

Definition at line 777 of file sn_nsdl.c.

int8_t sn_nsdl_create_resource ( struct nsdl_s *  handle,
sn_nsdl_resource_info_s res 
)

Resource creating function.

Used to create a static or dynamic CoAP resource.

Parameters:
*resPointer to a structure of type sn_nsdl_resource_info_t that contains the information about the resource.
Returns:
0 Success
-1 Failure
-2 Resource already exists
-3 Invalid path
-4 List adding failure

Definition at line 2469 of file sn_nsdl.c.

int8_t sn_nsdl_destroy ( struct nsdl_s *  handle )

This function releases all allocated memory in mbed Device C Client library.

Parameters:
*handlePointer to nsdl-library handle

Definition at line 115 of file sn_nsdl.c.

int8_t sn_nsdl_exec ( struct nsdl_s *  handle,
uint32_t  time 
)

CoAP retransmission function.

Used to give execution time for the mbed Device C Client library for retransmissions.

Parameters:
*handlePointer to nsdl-library handle
timeTime in seconds.
Returns:
0 Success
-1 Failure

Definition at line 1022 of file sn_nsdl.c.

void sn_nsdl_free_resource_list ( struct nsdl_s *  handle,
sn_grs_resource_list_s list 
)

Free a resource list obtained from sn_nsdl_list_resource()

Parameters:
listThe list to free, or NULL.

Definition at line 2439 of file sn_nsdl.c.

omalw_certificate_list_t * sn_nsdl_get_certificates ( struct nsdl_s *  handle )

Get pointer to received device server certificates.

Parameters:
*handlePointer to nsdl-library handle

Definition at line 681 of file sn_nsdl.c.

void * sn_nsdl_get_context ( const struct nsdl_s *const  handle )

Get the application defined context parameter for given handle.

This is useful for example when interfacing with c++ objects where a pointer to object is set as the context, and in the callback functions the context pointer can be used to call methods for the correct instance of the c++ object.

Parameters:
*handlePointer to library handle
Returns:
Pointer to the application defined context

Definition at line 2602 of file sn_nsdl.c.

sn_nsdl_dynamic_resource_parameters_s * sn_nsdl_get_resource ( struct nsdl_s *  handle,
uint16_t  pathlen,
uint8_t *  path 
)

Resource get function.

Used to get a resource.

Parameters:
*handlePointer to nsdl-library handle
pathlenContains the length of the path that is to be returned (excluding possible trailing '\0').
*pathA pointer to an array containing the path.
Returns:
!NULL Success, pointer to a sn_nsdl_resource_info_s that contains the resource information
NULL Failure

Used to get a resource.

Parameters:
*handlePointer to nsdl-library handle
pathlenContains the length of the path that is to be returned (excluding possible trailing '\0').
*pathA pointer to an array containing the path.
Returns:
!NULL Success, pointer to a sn_nsdl_dynamic_resource_parameters_s that contains the resource information
NULL Failure

Definition at line 1031 of file sn_nsdl.c.

uint32_t sn_nsdl_get_version ( void   )

Version query function.

Used to retrieve the version information from the mbed Device C Client library.

Returns:
Pointer to library version string

Definition at line 860 of file sn_nsdl.c.

int8_t sn_nsdl_is_ep_registered ( struct nsdl_s *  handle )

Checks if endpoint is registered.

Parameters:
*handlePointer to nsdl-library handle
Returns:
1 Endpoint registration is done successfully
0 Endpoint is not registered

Definition at line 509 of file sn_nsdl.c.

sn_grs_resource_list_s * sn_nsdl_list_resource ( struct nsdl_s *  handle,
uint16_t  pathlen,
uint8_t *  path 
)

Resource list function.

Parameters:
*handlePointer to nsdl-library handle
pathlenContains the length of the target path (excluding possible trailing '\0'). The length value is not examined if the path itself is a NULL pointer.
*pathA pointer to an array containing the path or a NULL pointer.
Returns:
!NULL A pointer to a sn_grs_resource_list_s structure containing the resource listing.
NULL Failure with an unspecified error

Definition at line 2429 of file sn_nsdl.c.

void sn_nsdl_nsp_lost ( struct nsdl_s *  handle )

A function to inform mbed Device C client library if application detects a fault in mbed Device Server registration.

Parameters:
*handlePointer to nsdl-library handle

After calling this function sn_nsdl_is_ep_registered() will return "not registered".

Definition at line 499 of file sn_nsdl.c.

uint16_t sn_nsdl_oma_bootstrap ( struct nsdl_s *  handle,
sn_nsdl_addr_s bootstrap_address_ptr,
sn_nsdl_ep_parameters_s endpoint_info_ptr,
sn_nsdl_bs_ep_info_t bootstrap_endpoint_info_ptr 
)

Starts OMA bootstrap process.

Parameters:
*handlePointer to nsdl-library handle
Returns:
bootstrap message ID, 0 if failed

Definition at line 605 of file sn_nsdl.c.

int8_t sn_nsdl_process_coap ( struct nsdl_s *  handle,
uint8_t *  packet,
uint16_t  packet_len,
sn_nsdl_addr_s src 
)

To push CoAP packet to mbed Device C Client library.

Used to push an CoAP packet to mbed Device C Client library for processing.

Parameters:
*handlePointer to nsdl-library handle
*packetPointer to a uint8_t array containing the packet (including the CoAP headers). After successful execution this array may contain the response packet.
*packet_lenPointer to length of the packet. After successful execution this array may contain the length of the response packet.
*srcPointer to packet source address information. After successful execution this array may contain the destination address of the response packet.
Returns:
0 Success
-1 Failure

Definition at line 872 of file sn_nsdl.c.

int8_t sn_nsdl_put_resource ( struct nsdl_s *  handle,
sn_nsdl_resource_info_s res 
)

Resource putting function.

Used to put a static or dynamic CoAP resource without creating copy of it. NOTE: Remember that only resource will be owned, not data that it contains

Parameters:
*resPointer to a structure of type sn_nsdl_resource_info_t that contains the information about the resource.
Returns:
0 Success
-1 Failure
-2 Resource already exists
-3 Invalid path
-4 List adding failure

Definition at line 2479 of file sn_nsdl.c.

uint16_t sn_nsdl_register_endpoint ( struct nsdl_s *  handle,
sn_nsdl_ep_parameters_s endpoint_info_ptr 
)

Registers endpoint to mbed Device Server.

Parameters:
*handlePointer to nsdl-library handle
*endpoint_info_ptrContains endpoint information.
Returns:
registration message ID, 0 if failed

Definition at line 233 of file sn_nsdl.c.

void sn_nsdl_release_allocated_coap_msg_mem ( struct nsdl_s *  handle,
sn_coap_hdr_s freed_coap_msg_ptr 
)

Releases memory of given CoAP message.

Note!!! Does not release Payload part

Parameters:
*handlePointer to library handle
*freed_coap_msg_ptris pointer to released CoAP message

Definition at line 2533 of file sn_nsdl.c.

int8_t sn_nsdl_send_coap_message ( struct nsdl_s *  handle,
sn_nsdl_addr_s address_ptr,
sn_coap_hdr_s coap_hdr_ptr 
)

Send an outgoing CoAP request.

Parameters:
*handlePointer to nsdl-library handle
*address_ptrPointer to source address struct
*coap_hdr_ptrPointer to CoAP message to be sent
Returns:
0 Success
-1 Failure

Definition at line 2459 of file sn_nsdl.c.

uint16_t sn_nsdl_send_observation_notification ( struct nsdl_s *  handle,
uint8_t *  token_ptr,
uint8_t  token_len,
uint8_t *  payload_ptr,
uint16_t  payload_len,
sn_coap_observe_e  observe,
sn_coap_msg_type_e  message_type,
sn_coap_content_format_e  content_format 
)

Sends observation message to mbed Device Server.

Parameters:
*handlePointer to nsdl-library handle
*token_ptrPointer to token to be used
token_lenToken length
*payload_ptrPointer to payload to be sent
payload_lenPayload length
observeObserve option value to be sent
message_typeObservation message type (confirmable or non-confirmable)
content_formatObservation message payload content format
Returns:
!0 Success, observation messages message ID
0 Failure

Definition at line 519 of file sn_nsdl.c.

uint16_t sn_nsdl_send_observation_notification_with_uri_path ( struct nsdl_s *  handle,
uint8_t *  token_ptr,
uint8_t  token_len,
uint8_t *  payload_ptr,
uint16_t  payload_len,
sn_coap_observe_e  observe,
sn_coap_msg_type_e  message_type,
uint8_t  content_type,
uint8_t *  uri_path_ptr,
uint16_t  uri_path_len 
)

Sends observation message to mbed Device Server with uri path.

Parameters:
*handlePointer to nsdl-library handle
*token_ptrPointer to token to be used
token_lenToken length
*payload_ptrPointer to payload to be sent
payload_lenPayload length
observeObserve option value to be sent
message_typeObservation message type (confirmable or non-confirmable)
content_typeObservation message payload contetnt type
uri_path_ptrPointer to uri path to be sent
uri_path_lenUri path len
Returns:
!0 Success, observation messages message ID
0 Failure

Definition at line 536 of file sn_nsdl.c.

int8_t sn_nsdl_set_block_size ( struct nsdl_s *  handle,
uint16_t  block_size 
)

If block transfer is enabled, this function changes the block size.

Parameters:
*handlePointer to library handle
uint16_tblock_size maximum size of CoAP payload. Valid sizes are 16, 32, 64, 128, 256, 512 and 1024 bytes
Returns:
0 = success, -1 = failure

Definition at line 2562 of file sn_nsdl.c.

int8_t sn_nsdl_set_duplicate_buffer_size ( struct nsdl_s *  handle,
uint8_t  message_count 
)

If dublicate message detection is enabled, this function changes buffer size.

Parameters:
*handlePointer to library handle
uint8_tmessage_count max number of messages saved for duplicate control
Returns:
0 = success, -1 = failure

Definition at line 2570 of file sn_nsdl.c.

int8_t sn_nsdl_set_endpoint_location ( struct nsdl_s *  handle,
uint8_t *  location_ptr,
uint8_t  location_len 
)

Sets the location receievd from Device Server.

Parameters:
*handlePointer to nsdl-library handle
*lt_ptrPointer to location value string , eg. "s322j4k"
lt_lenLength of the location string
Returns:
success, 0 if failed -1

Definition at line 485 of file sn_nsdl.c.

int8_t sn_nsdl_set_retransmission_buffer ( struct nsdl_s *  handle,
uint8_t  buffer_size_messages,
uint16_t  buffer_size_bytes 
)

If re-transmissions are enabled, this function changes message retransmission queue size.

Set size to '0' to disable feature. If both are set to '0', then re-sendings are disabled.

Parameters:
*handlePointer to library handle
uint8_tbuffer_size_messages queue size - maximum number of messages to be saved to queue
uint8_tbuffer_size_bytes queue size - maximum size of messages saved to queue
Returns:
0 = success, -1 = failure

Definition at line 2552 of file sn_nsdl.c.

int8_t sn_nsdl_set_retransmission_parameters ( struct nsdl_s *  handle,
uint8_t  resending_count,
uint8_t  resending_intervall 
)

If re-transmissions are enabled, this function changes resending count and interval.

Parameters:
*handlePointer to library handle
uint8_tresending_count max number of resendings for message
uint8_tresending_intervall message resending intervall in seconds
Returns:
0 = success, -1 = failure

Definition at line 2542 of file sn_nsdl.c.

uint16_t sn_nsdl_unregister_endpoint ( struct nsdl_s *  handle )

Sends unregister-message to mbed Device Server.

Parameters:
*handlePointer to nsdl-library handle
Returns:
unregistration message ID, 0 if failed

Definition at line 314 of file sn_nsdl.c.

int8_t sn_nsdl_update_certificates ( struct nsdl_s *  handle,
omalw_certificate_list_t *  certificate_ptr,
uint8_t  certificate_chain 
)

Updates certificate pointers to resource server.

Parameters:
*handlePointer to nsdl-library handle

Definition at line 732 of file sn_nsdl.c.

uint16_t sn_nsdl_update_registration ( struct nsdl_s *  handle,
uint8_t *  lt_ptr,
uint8_t  lt_len 
)

Update the registration with mbed Device Server.

Parameters:
*handlePointer to nsdl-library handle
*lt_ptrPointer to lifetime value string in ascii form, eg. "1200"
lt_lenLength of the lifetime string
Returns:
registration update message ID, 0 if failed

Definition at line 384 of file sn_nsdl.c.