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