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