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