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