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