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