sn_nsdl_lib.h

00001 /*
00002  * Copyright (c) 2011-2015 ARM Limited. All rights reserved.
00003  * SPDX-License-Identifier: Apache-2.0
00004  * Licensed under the Apache License, Version 2.0 (the License); you may
00005  * not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
00012  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 /**
00018 * \file sn_nsdl_lib.h
00019 *
00020 * \brief NanoService Devices Library header file
00021 *
00022 *
00023 */
00024 
00025 #ifndef SN_NSDL_LIB_H_
00026 #define SN_NSDL_LIB_H_
00027 
00028 #include "ns_list.h"
00029 #include "sn_client_config.h"
00030 
00031 #ifdef __cplusplus
00032 extern "C" {
00033 #endif
00034 
00035 #define SN_NSDL_ENDPOINT_NOT_REGISTERED  0
00036 #define SN_NSDL_ENDPOINT_IS_REGISTERED   1
00037 
00038 #define MAX_TOKEN_SIZE 8
00039 #define MAX_URI_QUERY_LEN 255
00040 
00041 #if defined MBED_CONF_MBED_CLIENT_DISABLE_INTERFACE_DESCRIPTION
00042 #define DISABLE_INTERFACE_DESCRIPTION MBED_CONF_MBED_CLIENT_DISABLE_INTERFACE_DESCRIPTION
00043 #endif
00044 
00045 #if defined MBED_CONF_MBED_CLIENT_DISABLE_RESOURCE_TYPE
00046 #define DISABLE_RESOURCE_TYPE MBED_CONF_MBED_CLIENT_DISABLE_RESOURCE_TYPE
00047 #endif
00048 
00049 /* Handle structure */
00050 struct nsdl_s;
00051 
00052 /**
00053  * \brief Received device server security
00054  */
00055 typedef enum omalw_server_security_ {
00056     SEC_NOT_SET = -1,
00057     PSK = 0,
00058     RPK = 1,
00059     CERTIFICATE = 2,
00060     NO_SEC = 3
00061 } omalw_server_security_t;
00062 
00063 /**
00064  * \brief Endpoint binding and mode
00065  */
00066 typedef enum sn_nsdl_oma_binding_and_mode_ {
00067     BINDING_MODE_NOT_SET = 0,
00068     BINDING_MODE_U = 0x01,
00069     BINDING_MODE_Q = 0x02,
00070     BINDING_MODE_S = 0x04
00071 } sn_nsdl_oma_binding_and_mode_t;
00072 
00073 //#define RESOURCE_ATTRIBUTES_LIST
00074 #ifdef RESOURCE_ATTRIBUTES_LIST
00075 /*
00076  * \brief Resource attributes types
00077  */
00078 typedef enum sn_nsdl_resource_attribute_ {
00079     ATTR_RESOURCE_TYPE,
00080     ATTR_INTERFACE_DESCRIPTION,
00081     ATTR_ENDPOINT_NAME,
00082     ATTR_QUEUE_MODE,
00083     ATTR_LIFETIME,
00084     ATTR_NOP,
00085     ATTR_END
00086 } sn_nsdl_resource_attribute_t;
00087 
00088 typedef struct sn_nsdl_attribute_item_ {
00089     sn_nsdl_resource_attribute_t attribute_name;
00090     char *value;
00091 } sn_nsdl_attribute_item_s;
00092 
00093 #endif
00094 
00095 /**
00096  * \brief Endpoint registration mode.
00097  *      If REGISTER_WITH_RESOURCES, endpoint sends list of all resources during registration.
00098  *      If REGISTER_WITH_TEMPLATE, endpoint sends registration without resource list. Device server must have
00099  *      correctly configured template.
00100  */
00101 typedef enum sn_nsdl_registration_mode_ {
00102     REGISTER_WITH_RESOURCES = 0,
00103     REGISTER_WITH_TEMPLATE
00104 } sn_nsdl_registration_mode_t;
00105 
00106 /**
00107  * \brief Endpoint registration parameters
00108  */
00109 typedef struct sn_nsdl_ep_parameters_ {
00110     uint8_t     endpoint_name_len;
00111     uint8_t     domain_name_len;
00112     uint8_t     type_len;
00113     uint8_t     lifetime_len;
00114     uint8_t     location_len;
00115 
00116     sn_nsdl_registration_mode_t ds_register_mode;       /**< Defines registration mode */
00117     sn_nsdl_oma_binding_and_mode_t binding_and_mode;    /**< Defines endpoints binding and mode */
00118 
00119     uint8_t     *endpoint_name_ptr;                     /**< Endpoint name */
00120     uint8_t     *domain_name_ptr;                       /**< Domain to register. If null, NSP uses default domain */
00121     uint8_t     *type_ptr;                              /**< Endpoint type */
00122     uint8_t     *lifetime_ptr;                          /**< Endpoint lifetime in seconds. eg. "1200" = 1200 seconds */
00123     uint8_t     *location_ptr;                          /**< Endpoint location in server, optional parameter,default is NULL */
00124 } sn_nsdl_ep_parameters_s;
00125 
00126 /**
00127  * \brief Resource access rights
00128  */
00129 typedef enum sn_grs_resource_acl_ {
00130     SN_GRS_GET_ALLOWED  = 0x01 ,
00131     SN_GRS_PUT_ALLOWED  = 0x02,
00132     SN_GRS_POST_ALLOWED = 0x04,
00133     SN_GRS_DELETE_ALLOWED   = 0x08
00134 } sn_grs_resource_acl_e;
00135 
00136 /**
00137  * \brief Defines the resource mode
00138  */
00139 typedef enum sn_nsdl_resource_mode_ {
00140     SN_GRS_STATIC = 0,                  /**< Static resources have some value that doesn't change */
00141     SN_GRS_DYNAMIC,                     /**< Dynamic resources are handled in application. Therefore one must give function callback pointer to them */
00142     SN_GRS_DIRECTORY                    /**< Directory resources are unused and unsupported */
00143 } sn_nsdl_resource_mode_e;
00144 
00145 /**
00146  * Enum defining an status codes that can happen when
00147  * sending notification
00148 */
00149 typedef enum {
00150     NOTIFICATION_STATUS_INIT = 0,           // Initial state.
00151     NOTIFICATION_STATUS_BUILD_ERROR,        // CoAP message building fails.
00152     NOTIFICATION_STATUS_RESEND_QUEUE_FULL,  // CoAP resend queue full.
00153     NOTIFICATION_STATUS_SENT,               // Notification sent to the server but ACK not yet received.
00154     NOTIFICATION_STATUS_DELIVERED,          // Received ACK from server.
00155     NOTIFICATION_STATUS_SEND_FAILED,        // Message sending failed (retransmission completed).
00156     NOTIFICATION_STATUS_SUBSCRIBED,         // Server has started the observation
00157     NOTIFICATION_STATUS_UNSUBSCRIBED        // Server has stopped the observation (RESET message or GET with observe 1)
00158 } NotificationDeliveryStatus;
00159 
00160 /**
00161  * Enum defining an different download types.
00162  * This is used for 'uri-path' when sending a GET request.
00163 */
00164 typedef enum {
00165     FIRMWARE_DOWNLOAD = 0,
00166     GENERIC_DOWNLOAD
00167 } DownloadType;
00168 
00169 /** Dummy alias to maintain compatibility with older version which had a typo in the enum name. */
00170 typedef NotificationDeliveryStatus NoticationDeliveryStatus;
00171 
00172 
00173 /**
00174  * \brief Defines static parameters for the resource.
00175  */
00176 typedef struct sn_nsdl_static_resource_parameters_ {
00177 #ifndef RESOURCE_ATTRIBUTES_LIST
00178 #ifndef DISABLE_RESOURCE_TYPE
00179     char        *resource_type_ptr;         /**< Type of the resource */
00180 #endif
00181 #ifndef DISABLE_INTERFACE_DESCRIPTION
00182     char        *interface_description_ptr; /**< Interface description */
00183 #endif
00184 #else
00185     sn_nsdl_attribute_item_s *attributes_ptr;
00186 #endif
00187     char        *path;                      /**< Resource path */
00188     bool        external_memory_block:1;    /**< 0 means block messages are handled inside this library,
00189                                                  otherwise block messages are passed to application */
00190     unsigned    mode:2;                     /**< STATIC etc.. */
00191     bool        free_on_delete:1;           /**< 1 if struct is dynamic allocted --> to be freed */
00192 } sn_nsdl_static_resource_parameters_s;
00193 
00194 /**
00195  * \brief Defines dynamic parameters for the resource.
00196  */
00197 typedef struct sn_nsdl_resource_parameters_ {
00198     uint8_t                                     (*sn_grs_dyn_res_callback)(struct nsdl_s *,
00199                                                                        sn_coap_hdr_s *,
00200                                                                        sn_nsdl_addr_s *,
00201                                                                        sn_nsdl_capab_e);
00202 #ifdef MEMORY_OPTIMIZED_API
00203     const sn_nsdl_static_resource_parameters_s  *static_resource_parameters;
00204 #else
00205     sn_nsdl_static_resource_parameters_s        *static_resource_parameters;
00206 #endif
00207     uint8_t                                     *resource;           /**< NULL if dynamic resource */
00208     ns_list_link_t                              link;
00209     uint16_t                                    resource_len;        /**< 0 if dynamic resource, resource information in static resource */
00210     uint16_t                                    coap_content_type;   /**< CoAP content type */
00211     unsigned                                    access:4;            /**< Allowed operation mode, GET, PUT, etc,
00212                                                                          TODO! This should be in static struct but current
00213                                                                          mbed-client implementation requires this to be changed at runtime */
00214     unsigned                                    registered:2;        /**< Is resource registered or not */
00215     bool                                        publish_uri:1;       /**< 1 if resource to be published to server */
00216     bool                                        free_on_delete:1;    /**< 1 if struct is dynamic allocted --> to be freed */
00217     bool                                        observable:1;        /**< Is resource observable or not */
00218     bool                                        auto_observable:1;   /**< Is resource auto observable or not */
00219     bool                                        always_publish:1;    /**< 1 if resource should always be published in registration or registration update **/
00220     unsigned                                    publish_value:2;     /**< 0 for non-publishing,1 if resource value to be published in registration message,
00221                                                                          2 if resource value to be published in Base64 encoded format */
00222 } sn_nsdl_dynamic_resource_parameters_s;
00223 
00224 
00225 /**
00226  * \fn struct nsdl_s *sn_nsdl_init  (uint8_t (*sn_nsdl_tx_cb)(sn_nsdl_capab_e , uint8_t *, uint16_t, sn_nsdl_addr_s *),
00227  *                          uint8_t (*sn_nsdl_rx_cb)(sn_coap_hdr_s *, sn_nsdl_addr_s *),
00228  *                          sn_nsdl_mem_s *sn_memory)
00229  *
00230  * \brief Initialization function for NSDL library. Initializes NSDL, GRS, HTTP and CoAP.
00231  *
00232  * \param *sn_nsdl_tx_callback  A callback function for sending messages.
00233  *
00234  * \param *sn_nsdl_rx_callback  A callback function for parsed messages. If received message is not CoAP protocol message (eg. ACK), message for GRS (GET, PUT, POST, DELETE) or
00235  *                              reply for some DS messages (register message etc.), rx callback will be called.
00236  *
00237  * \param *sn_memory            Memory structure which includes function pointers to the allocation and free functions.
00238  *
00239  * \return  pointer to created handle structure. NULL if failed
00240  */
00241 struct nsdl_s *sn_nsdl_init(uint8_t (*sn_nsdl_tx_cb)(struct nsdl_s *, sn_nsdl_capab_e , uint8_t *, uint16_t, sn_nsdl_addr_s *),
00242                             uint8_t (*sn_nsdl_rx_cb)(struct nsdl_s *, sn_coap_hdr_s *, sn_nsdl_addr_s *),
00243                             void *(*sn_nsdl_alloc)(uint16_t), void (*sn_nsdl_free)(void *),
00244                             uint8_t (*sn_nsdl_auto_obs_token_cb)(struct nsdl_s *, const char *, uint8_t *));
00245 
00246 /**
00247  * \fn extern uint16_t sn_nsdl_register_endpoint(struct nsdl_s *handle, sn_nsdl_ep_parameters_s *endpoint_info_ptr, const char *uri_query_parameters);
00248  *
00249  * \brief Registers endpoint to mbed Device Server.
00250  * \param *handle               Pointer to nsdl-library handle
00251  * \param *endpoint_info_ptr    Contains endpoint information.
00252  * \param *uri_query_parameters Uri query parameters.
00253  *
00254  * \return registration message ID, 0 if failed
00255  */
00256 extern uint16_t sn_nsdl_register_endpoint(struct nsdl_s *handle,
00257                                           sn_nsdl_ep_parameters_s *endpoint_info_ptr,
00258                                           const char *uri_query_parameters);
00259 
00260 /**
00261  * \fn extern int32_t sn_nsdl_unregister_endpoint(struct nsdl_s *handle)
00262  *
00263  * \brief Sends unregister-message to mbed Device Server.
00264  *
00265  * \param *handle               Pointer to nsdl-library handle
00266  *
00267  * \return  unregistration message ID, 0 if failed
00268  */
00269 extern int32_t sn_nsdl_unregister_endpoint(struct nsdl_s *handle);
00270 
00271 /**
00272  * \fn extern int32_t sn_nsdl_update_registration(struct nsdl_s *handle, uint8_t *lt_ptr, uint8_t lt_len);
00273  *
00274  * \brief Update the registration with mbed Device Server.
00275  *
00276  * \param *handle   Pointer to nsdl-library handle
00277  * \param *lt_ptr   Pointer to lifetime value string in ascii form, eg. "1200"
00278  * \param lt_len    Length of the lifetime string
00279  *
00280  * \return  registration update message ID, <0 if failed
00281  */
00282 extern int32_t sn_nsdl_update_registration(struct nsdl_s *handle, uint8_t *lt_ptr, uint8_t lt_len);
00283 
00284 /**
00285  * \fn extern int8_t sn_nsdl_set_endpoint_location(struct nsdl_s *handle, uint8_t *location_ptr, uint8_t location_len);
00286  *
00287  * \brief Sets the location receievd from Device Server.
00288  *
00289  * \param *handle   Pointer to nsdl-library handle
00290  * \param *lt_ptr   Pointer to location value string , eg. "s322j4k"
00291  * \param lt_len    Length of the location string
00292  *
00293  * \return  success, <0 if failed
00294  */
00295 extern int8_t sn_nsdl_set_endpoint_location(struct nsdl_s *handle, uint8_t *location_ptr, uint8_t location_len);
00296 
00297 /**
00298  * \fn extern int8_t sn_nsdl_is_ep_registered(struct nsdl_s *handle)
00299  *
00300  * \brief Checks if endpoint is registered.
00301  *
00302  * \param *handle   Pointer to nsdl-library handle
00303  *
00304  * \return 1 Endpoint registration is done successfully
00305  * \return 0 Endpoint is not registered
00306  */
00307 extern int8_t sn_nsdl_is_ep_registered(struct nsdl_s *handle);
00308 
00309 /**
00310  * \fn extern void sn_nsdl_nsp_lost(struct nsdl_s *handle);
00311  *
00312  * \brief A function to inform mbed Device C client library if application detects a fault in mbed Device Server registration.
00313  *
00314  * \param *handle   Pointer to nsdl-library handle
00315  *
00316  * After calling this function sn_nsdl_is_ep_registered() will return "not registered".
00317  */
00318 extern void sn_nsdl_nsp_lost(struct nsdl_s *handle);
00319 
00320 /**
00321  * \fn extern uint16_t sn_nsdl_send_observation_notification(struct nsdl_s *handle, uint8_t *token_ptr, uint8_t token_len,
00322  *                                                  uint8_t *payload_ptr, uint16_t payload_len,
00323  *                                                  sn_coap_observe_e observe,
00324  *                                                  sn_coap_msg_type_e message_type, sn_coap_content_format_e content_format)
00325  *
00326  *
00327  * \brief Sends observation message to mbed Device Server
00328  *
00329  * \param   *handle         Pointer to nsdl-library handle
00330  * \param   *token_ptr      Pointer to token to be used
00331  * \param   token_len       Token length
00332  * \param   *payload_ptr    Pointer to payload to be sent
00333  * \param   payload_len     Payload length
00334  * \param   observe         Observe option value to be sent
00335  * \param   message_type    Observation message type (confirmable or non-confirmable)
00336  * \param   content_format  Observation message payload content format
00337  * \param   message_id      -1 means stored value to be used otherwise new one is generated
00338  *
00339  * \return  >0  Success, observation messages message ID
00340  * \return  <=0   Failure
00341  */
00342 extern int32_t sn_nsdl_send_observation_notification(struct nsdl_s *handle, uint8_t *token_ptr, uint8_t token_len,
00343         uint8_t *payload_ptr, uint16_t payload_len,
00344         sn_coap_observe_e observe,
00345         sn_coap_msg_type_e message_type,
00346         sn_coap_content_format_e content_format,
00347         const int32_t message_id);
00348 
00349 /**
00350  * \fn extern uint32_t sn_nsdl_get_version(void)
00351  *
00352  * \brief Version query function.
00353  *
00354  * Used to retrieve the version information from the mbed Device C Client library.
00355  *
00356  * \return Pointer to library version string
00357 */
00358 extern char *sn_nsdl_get_version(void);
00359 
00360 /**
00361  * \fn extern int8_t sn_nsdl_process_coap(struct nsdl_s *handle, uint8_t *packet, uint16_t packet_len, sn_nsdl_addr_s *src)
00362  *
00363  * \brief To push CoAP packet to mbed Device C Client library
00364  *
00365  * Used to push an CoAP packet to mbed Device C Client library for processing.
00366  *
00367  * \param   *handle     Pointer to nsdl-library handle
00368  *
00369  * \param   *packet     Pointer to a uint8_t array containing the packet (including the CoAP headers).
00370  *      After successful execution this array may contain the response packet.
00371  *
00372  * \param   *packet_len Pointer to length of the packet. After successful execution this array may contain the length
00373  *      of the response packet.
00374  *
00375  * \param   *src        Pointer to packet source address information. After successful execution this array may contain
00376  *      the destination address of the response packet.
00377  *
00378  * \return  0   Success
00379  * \return  -1  Failure
00380  */
00381 extern int8_t sn_nsdl_process_coap(struct nsdl_s *handle, uint8_t *packet, uint16_t packet_len, sn_nsdl_addr_s *src);
00382 
00383 /**
00384  * \fn extern int8_t sn_nsdl_exec(struct nsdl_s *handle, uint32_t time);
00385  *
00386  * \brief CoAP retransmission function.
00387  *
00388  * Used to give execution time for the mbed Device C Client library for retransmissions.
00389  *
00390  * \param   *handle Pointer to nsdl-library handle
00391  *
00392  * \param  time Time in seconds.
00393  *
00394  * \return  0   Success
00395  * \return  -1  Failure
00396  */
00397 extern int8_t sn_nsdl_exec(struct nsdl_s *handle, uint32_t time);
00398 
00399 /**
00400  * \fn  extern int8_t sn_nsdl_put_resource(struct nsdl_s *handle, const sn_nsdl_dynamic_resource_parameters_s *res);
00401  *
00402  * \brief Resource putting function.
00403  *
00404  * Used to put a static or dynamic CoAP resource without creating copy of it.
00405  * NOTE: Remember that only resource will be owned, not data that it contains
00406  * NOTE: The resource may be removed from list by sn_nsdl_pop_resource().
00407  *
00408  * \param   *res    Pointer to a structure of type sn_nsdl_dynamic_resource_parameters_s that contains the information
00409  *     about the resource.
00410  *
00411  * \return  0   Success
00412  * \return  -1  Failure
00413  * \return  -2  Resource already exists
00414  * \return  -3  Invalid path
00415  * \return  -4  List adding failure
00416  */
00417 extern int8_t sn_nsdl_put_resource(struct nsdl_s *handle, sn_nsdl_dynamic_resource_parameters_s *res);
00418 
00419 /**
00420  * \fn  extern int8_t sn_nsdl_pop_resource(struct nsdl_s *handle, const sn_nsdl_dynamic_resource_parameters_s *res);
00421  *
00422  * \brief Resource popping function.
00423  *
00424  * Used to remove a static or dynamic CoAP resource from lists without deleting it.
00425  * NOTE: This function is a counterpart of sn_nsdl_put_resource().
00426  *
00427  * \param   *res    Pointer to a structure of type sn_nsdl_dynamic_resource_parameters_s that contains the information
00428  *     about the resource.
00429  *
00430  * \return  0   Success
00431  * \return  -1  Failure
00432  * \return  -3  Invalid path
00433  */
00434 extern int8_t sn_nsdl_pop_resource(struct nsdl_s *handle, sn_nsdl_dynamic_resource_parameters_s *res);
00435 
00436 /**
00437  * \fn extern int8_t sn_nsdl_delete_resource(struct nsdl_s *handle, char *path)
00438  *
00439  * \brief Resource delete function.
00440  *
00441  * Used to delete a resource. If resource has a subresources, these all must also be removed.
00442  *
00443  * \param   *handle     Pointer to nsdl-library handle
00444  * \param   *path_ptr   A pointer to an array containing the path.
00445  *
00446  * \return  0   Success
00447  * \return  -1  Failure (No such resource)
00448  */
00449 extern int8_t sn_nsdl_delete_resource(struct nsdl_s *handle, const char *path);
00450 
00451 /**
00452  * \fn extern sn_nsdl_dynamic_resource_parameters_s *sn_nsdl_get_resource(struct nsdl_s *handle, char *path)
00453  *
00454  * \brief Resource get function.
00455  *
00456  * Used to get a resource.
00457  *
00458  * \param   *handle     Pointer to nsdl-library handle
00459   * \param   *path   A pointer to an array containing the path.
00460  *
00461  * \return  !NULL   Success, pointer to a sn_nsdl_dynamic_resource_parameters_s that contains the resource information\n
00462  * \return  NULL    Failure
00463  */
00464 extern sn_nsdl_dynamic_resource_parameters_s *sn_nsdl_get_resource(struct nsdl_s *handle, const char *path);
00465 
00466 /**
00467  * \fn extern int8_t sn_nsdl_send_coap_message(struct nsdl_s *handle, sn_nsdl_addr_s *address_ptr, sn_coap_hdr_s *coap_hdr_ptr);
00468  *
00469  * \brief Send an outgoing CoAP request.
00470  *
00471  * \param   *handle Pointer to nsdl-library handle
00472  * \param   *address_ptr    Pointer to source address struct
00473  * \param   *coap_hdr_ptr   Pointer to CoAP message to be sent
00474  *
00475  * \return  0   Success
00476  * \return  -1  Failure
00477  */
00478 extern int8_t sn_nsdl_send_coap_message(struct nsdl_s *handle, sn_nsdl_addr_s *address_ptr, sn_coap_hdr_s *coap_hdr_ptr);
00479 
00480 /**
00481  * \fn extern int32_t sn_nsdl_send_request(struct nsdl_s *handle, sn_coap_msg_code_e msg_code, const char *uri_path, const uint32_t token, const size_t offset, const uint16_t payload_len, const uint8_t* payload_ptr);
00482  *
00483  * \brief Send an outgoing CoAP request.
00484  *
00485  * \param   *handle       Pointer to nsdl-library handle
00486  * \param   msg-code      CoAP message code to use for request
00487  * \param   *uri_path     Path to the data
00488  * \param   *token        Message token
00489  * \param   offset        Offset within response body to request
00490  * \param   payload_len   Message payload length, can be 0 for no payload
00491  * \param   *payload_ptr  Message payload pointer, can be NULL for no payload
00492  * \param   type          Type of the download
00493  *
00494  * \Return  > 0 Success else Failure
00495  */
00496 extern int32_t sn_nsdl_send_request(struct nsdl_s *handle,
00497                                     sn_coap_msg_code_e msg_code,
00498                                     const char *uri_path,
00499                                     const uint32_t token,
00500                                     const size_t offset,
00501                                     const uint16_t payload_len,
00502                                     uint8_t* payload_ptr,
00503                                     DownloadType type);
00504 
00505 /**
00506  * \fn extern int8_t set_NSP_address(struct nsdl_s *handle, uint8_t *NSP_address, uint8_t address_length, uint16_t port, sn_nsdl_addr_type_e address_type);
00507  *
00508  * \brief This function is used to set the mbed Device Server address given by an application.
00509  *
00510  * \param   *handle Pointer to nsdl-library handle
00511  * \return  0   Success
00512  * \return  -1  Failed to indicate that internal address pointer is not allocated (call nsdl_init() first).
00513  */
00514 extern int8_t set_NSP_address(struct nsdl_s *handle, uint8_t *NSP_address, uint8_t address_length, uint16_t port, sn_nsdl_addr_type_e address_type);
00515 
00516 /**
00517  * \fn extern int8_t sn_nsdl_destroy(struct nsdl_s *handle);
00518  *
00519  * \param   *handle Pointer to nsdl-library handle
00520  * \brief This function releases all allocated memory in mbed Device C Client library.
00521  */
00522 extern int8_t sn_nsdl_destroy(struct nsdl_s *handle);
00523 
00524 /**
00525  * \fn extern 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);
00526  *
00527  * \brief Starts OMA bootstrap process
00528  *
00529  * \param   *handle Pointer to nsdl-library handle
00530  *
00531  * \return bootstrap message ID, 0 if failed
00532  */
00533 extern uint16_t sn_nsdl_oma_bootstrap(struct nsdl_s *handle,
00534                                       sn_nsdl_addr_s *bootstrap_address_ptr,
00535                                       sn_nsdl_ep_parameters_s *endpoint_info_ptr,
00536                                       const char *uri_query_parameters);
00537 
00538 /**
00539  * \fn sn_coap_hdr_s *sn_nsdl_build_response(struct nsdl_s *handle, sn_coap_hdr_s *coap_packet_ptr, uint8_t msg_code)
00540  *
00541  * \brief Prepares generic response packet from a request packet. This function allocates memory for the resulting sn_coap_hdr_s
00542  *
00543  * \param *handle Pointer to library handle
00544  * \param *coap_packet_ptr The request packet pointer
00545  * \param msg_code response messages code
00546  *
00547  * \return *coap_packet_ptr The allocated and pre-filled response packet pointer
00548  *          NULL    Error in parsing the request
00549  *
00550  */
00551 extern sn_coap_hdr_s *sn_nsdl_build_response(struct nsdl_s *handle, sn_coap_hdr_s *coap_packet_ptr, uint8_t msg_code);
00552 
00553 /**
00554  * \brief Allocates and initializes options list structure
00555  *
00556  * \param *handle Pointer to library handle
00557  * \param *coap_msg_ptr is pointer to CoAP message that will contain the options
00558  *
00559  * If the message already has a pointer to an option structure, that pointer
00560  * is returned, rather than a new structure being allocated.
00561  *
00562  * \return Return value is pointer to the CoAP options structure.\n
00563  *         In following failure cases NULL is returned:\n
00564  *          -Failure in given pointer (= NULL)\n
00565  *          -Failure in memory allocation (malloc() returns NULL)
00566  */
00567 extern sn_coap_options_list_s *sn_nsdl_alloc_options_list(struct nsdl_s *handle, sn_coap_hdr_s *coap_msg_ptr);
00568 
00569 /**
00570  * \fn void sn_nsdl_release_allocated_coap_msg_mem(struct nsdl_s *handle, sn_coap_hdr_s *freed_coap_msg_ptr)
00571  *
00572  * \brief Releases memory of given CoAP message
00573  *
00574  *        Note!!! Does not release Payload part
00575  *
00576  * \param *handle Pointer to library handle
00577  *
00578  * \param *freed_coap_msg_ptr is pointer to released CoAP message
00579  */
00580 extern void sn_nsdl_release_allocated_coap_msg_mem(struct nsdl_s *handle, sn_coap_hdr_s *freed_coap_msg_ptr);
00581 
00582 /**
00583  * \fn int8_t sn_nsdl_set_retransmission_parameters(struct nsdl_s *handle, uint8_t resending_count, uint8_t resending_intervall)
00584  *
00585  * \brief  If re-transmissions are enabled, this function changes resending count and interval.
00586  *
00587  * \param *handle Pointer to library handle
00588  * \param uint8_t resending_count max number of resendings for message
00589  * \param uint8_t resending_intervall message resending intervall in seconds
00590  * \return  0 = success, -1 = failure
00591  */
00592 extern int8_t sn_nsdl_set_retransmission_parameters(struct nsdl_s *handle, uint8_t resending_count, uint8_t resending_interval);
00593 
00594 /**
00595  * \fn int8_t sn_nsdl_set_retransmission_buffer(struct nsdl_s *handle, uint8_t buffer_size_messages, uint16_t buffer_size_bytes)
00596  *
00597  * \brief If re-transmissions are enabled, this function changes message retransmission queue size.
00598  *  Set size to '0' to disable feature. If both are set to '0', then re-sendings are disabled.
00599  *
00600  * \param *handle Pointer to library handle
00601  * \param uint8_t buffer_size_messages queue size - maximum number of messages to be saved to queue
00602  * \param uint8_t buffer_size_bytes queue size - maximum size of messages saved to queue
00603  * \return  0 = success, -1 = failure
00604  */
00605 extern int8_t sn_nsdl_set_retransmission_buffer(struct nsdl_s *handle,
00606         uint8_t buffer_size_messages, uint16_t buffer_size_bytes);
00607 
00608 /**
00609  * \fn int8_t sn_nsdl_set_block_size(struct nsdl_s *handle, uint16_t block_size)
00610  *
00611  * \brief If block transfer is enabled, this function changes the block size.
00612  *
00613  * \param *handle Pointer to library handle
00614  * \param uint16_t block_size maximum size of CoAP payload. Valid sizes are 16, 32, 64, 128, 256, 512 and 1024 bytes
00615  * \return  0 = success, -1 = failure
00616  */
00617 extern int8_t sn_nsdl_set_block_size(struct nsdl_s *handle, uint16_t block_size);
00618 
00619 /**
00620  * \fn int8_t sn_nsdl_set_duplicate_buffer_size(struct nsdl_s *handle,uint8_t message_count)
00621  *
00622  * \brief If dublicate message detection is enabled, this function changes buffer size.
00623  *
00624  * \param *handle Pointer to library handle
00625  * \param uint8_t message_count max number of messages saved for duplicate control
00626  * \return  0 = success, -1 = failure
00627  */
00628 extern int8_t sn_nsdl_set_duplicate_buffer_size(struct nsdl_s *handle, uint8_t message_count);
00629 
00630 /**
00631  * \fn void *sn_nsdl_set_context(const struct nsdl_s *handle, void *context)
00632  *
00633  * \brief Set the application defined context parameter for given handle.
00634  *        This is useful for example when interfacing with c++ objects where a
00635  *        pointer to object is set as the context, and in the callback functions
00636  *        the context pointer can be used to call methods for the correct instance
00637  *        of the c++ object.
00638  *
00639  * \param *handle Pointer to library handle
00640  * \param *context Pointer to the application defined context
00641  * \return 0 = success, -1 = failure
00642  */
00643 extern int8_t sn_nsdl_set_context(struct nsdl_s * const handle, void * const context);
00644 
00645 /**
00646  * \fn void *sn_nsdl_get_context(const struct nsdl_s *handle)
00647  *
00648  * \brief Get the application defined context parameter for given handle.
00649  *        This is useful for example when interfacing with c++ objects where a
00650  *        pointer to object is set as the context, and in the callback functions
00651  *        the context pointer can be used to call methods for the correct instance
00652  *        of the c++ object.
00653  *
00654  * \param *handle Pointer to library handle
00655  * \return Pointer to the application defined context
00656  */
00657 extern void *sn_nsdl_get_context(const struct nsdl_s * const handle);
00658 
00659 /**
00660  * \fn int8_t sn_nsdl_clear_coap_resending_queue(struct nsdl_s *handle)
00661  *
00662  * \brief Clean confirmable message list.
00663  *
00664  * \param *handle Pointer to library handle
00665  * \return  0 = success, -1 = failure
00666  */
00667 extern int8_t sn_nsdl_clear_coap_resending_queue(struct nsdl_s *handle);
00668 
00669 /**
00670  * \fn int8_t sn_nsdl_clear_coap_sent_blockwise_messages(struct nsdl_s *handle)
00671  *
00672  * \brief Clears the sent blockwise messages from the linked list.
00673  *
00674  * \param *handle Pointer to library handle
00675  * \return  0 = success, -1 = failure
00676  */
00677 extern int8_t sn_nsdl_clear_coap_sent_blockwise_messages(struct nsdl_s *handle);
00678 
00679 /**
00680  * \fn int8_t sn_nsdl_clear_coap_received_blockwise_messages(struct nsdl_s *handle)
00681  *
00682  * \brief Clears the received blockwise messages from the linked list.
00683  *
00684  * \param *handle Pointer to library handle
00685  * \return  0 = success, -1 = failure
00686  */
00687 extern int8_t sn_nsdl_clear_coap_received_blockwise_messages(struct nsdl_s *handle);
00688 
00689 /**
00690  * \fn int8_t sn_nsdl_remove_msg_from_retransmission(struct nsdl_s *handle)
00691  *
00692  * \brief Clears item from the resend queue.
00693  *
00694  * \param *handle Pointer to library handle
00695  * \param *token Token to be removed
00696  * \param token_len Length of the token
00697  * \return  0 = success, -1 = failure
00698  */
00699 extern int8_t sn_nsdl_remove_msg_from_retransmission(struct nsdl_s *handle, uint8_t *token, uint8_t token_len);
00700 
00701 /**
00702  * \fn int8_t sn_nsdl_handle_block2_response_internally(struct nsdl_s *handle, uint8_t handle_response)
00703  *
00704  * \brief This function change the state whether CoAP library sends the block 2 response automatically or not.
00705  *
00706  * \param *handle Pointer to NSDL library handle
00707  * \param handle_response 1 if CoAP library handles the response sending otherwise 0.
00708  *
00709  * \return  0 = success, -1 = failure
00710  */
00711 extern int8_t sn_nsdl_handle_block2_response_internally(struct nsdl_s *handle, uint8_t handle_response);
00712 
00713 #ifdef RESOURCE_ATTRIBUTES_LIST
00714 /**
00715  * \fn int8_t sn_nsdl_free_resource_attributes_list(struct nsdl_s *handle, sn_nsdl_static_resource_parameters_s *params)
00716  *
00717  * \brief Free resource attributes list if free_on_delete is true for params. This will also free all attributes values
00718  * if they are pointer types.
00719  *
00720  * \param *params Pointer to resource static parameters
00721  */
00722 extern void sn_nsdl_free_resource_attributes_list(sn_nsdl_static_resource_parameters_s *params);
00723 
00724 /*
00725  * \fn bool sn_nsdl_set_resource_attribute(sn_nsdl_static_resource_parameters_s *params, sn_nsdl_attribute_item_s attribute)
00726  *
00727  * \brief Set resource link-format attribute value, create if it doesn't exist yet.
00728  *
00729  * \param *params Pointer to resource static parameters
00730  * \param attribute sn_nsdl_attribute_item_s structure containing attribute to set
00731  * \return True if successful, false on error
00732  */
00733 extern bool sn_nsdl_set_resource_attribute(sn_nsdl_static_resource_parameters_s *params, const sn_nsdl_attribute_item_s *attribute);
00734 
00735 /*
00736  * \fn bool sn_nsdl_get_resource_attribute(sn_nsdl_static_resource_parameters_s *params, sn_nsdl_resource_attribute_t attribute)
00737  *
00738  * \brief Get resource link-format attribute value
00739  *
00740  * \param *params Pointer to resource static parameters
00741  * \param attribute sn_nsdl_resource_attribute_t enum value for attribute to get
00742  * \return Pointer to value or null if attribute did not exist or had no value
00743  */
00744 extern const char* sn_nsdl_get_resource_attribute(const sn_nsdl_static_resource_parameters_s *params, sn_nsdl_resource_attribute_t attribute);
00745 
00746 /*
00747  * \fn bool sn_nsdl_remove_resource_attribute(sn_nsdl_static_resource_parameters_s *params, sn_nsdl_resource_attribute_t attribute)
00748  *
00749  * \brief Remove resource link-format attribute value
00750  *
00751  * \param *params Pointer to resource static parameters
00752  * \param attribute sn_nsdl_resource_attribute_t enum value for attribute to remove
00753  */
00754 extern bool sn_nsdl_remove_resource_attribute(sn_nsdl_static_resource_parameters_s *params, sn_nsdl_resource_attribute_t attribute);
00755 #endif
00756 
00757 /**
00758  * \fn bool sn_nsdl_print_coap_data(sn_coap_hdr_s *coap_header_ptr, bool outgoing)
00759  *
00760  * \brief Utility function to print all the CoAP header parameters
00761  *
00762  * \param *coap_header_ptr CoAP header
00763  * \param outgoing If True, package is going to be sent to server otherwise receiving
00764  */
00765 extern void sn_nsdl_print_coap_data(sn_coap_hdr_s *coap_header_ptr, bool outgoing);
00766 
00767 /**
00768  * \fn uint16_t sn_nsdl_get_block_size(struct nsdl_s *handle)
00769  *
00770  * \brief Get CoAP block size
00771  *
00772  * \param *handle Pointer to library handle
00773  * \return  block size
00774  */
00775 extern uint16_t sn_nsdl_get_block_size(const struct nsdl_s *handle);
00776 
00777 /**
00778  * \fn uint8_t sn_nsdl_get_retransmission_count(struct nsdl_s *handle)
00779  *
00780  * \brief  Returns retransmission coint
00781  *
00782  * \param *handle Pointer to library handle
00783  * \return  Retransmission count
00784  */
00785 extern uint8_t sn_nsdl_get_retransmission_count(struct nsdl_s *handle);
00786 
00787 /**
00788  * \fn extern int32_t sn_nsdl_send_coap_ping(struct nsdl_s *handle);
00789  *
00790  * \brief Send confirmable CoAP ping message.
00791  *
00792  * \param   *handle Pointer to nsdl-library handle
00793  *
00794  * \return message ID, 0 if failed
00795  */
00796 extern int32_t sn_nsdl_send_coap_ping(struct nsdl_s *handle);
00797 
00798 #ifdef __cplusplus
00799 }
00800 #endif
00801 
00802 #endif /* SN_NSDL_LIB_H_ */