sn_nsdl_lib.h

00001 /**
00002  * \file sn_nsdl_lib.h
00003  *
00004  * \brief NanoService Devices Library header file
00005  *
00006  *  Created on: Aug 23, 2011
00007  *      Author: tero
00008  *
00009  */
00010 
00011 #ifdef __cplusplus
00012 extern "C" {
00013 #endif
00014 
00015 #define SN_NSDL_CONST_MEMORY_ATTRIBUTE
00016 
00017 #define SN_NSDL_ENDPOINT_NOT_REGISTERED  0
00018 #define SN_NSDL_ENDPOINT_IS_REGISTERED   1
00019 
00020 /**
00021  * \brief Endpoint registration parameters
00022  */
00023 typedef struct sn_nsdl_ep_parameters_
00024 {
00025     uint8_t     *endpoint_name_ptr;     /**< Endpoint name */
00026     uint8_t     endpoint_name_len;
00027 
00028     uint8_t     *domain_name_ptr;       /**< Domain to register. If null, NSP uses default domain */
00029     uint8_t     domain_name_len;
00030 
00031     uint8_t     *type_ptr;              /**< Endpoint type */
00032     uint8_t     type_len;
00033 
00034     uint8_t     *lifetime_ptr;          /**< Endpoint lifetime in seconds. eg. "1200" = 1200 seconds */
00035     uint8_t     lifetime_len;
00036 
00037 } sn_nsdl_ep_parameters_s;
00038 
00039 /**
00040  * \brief For internal use
00041  */
00042 typedef struct sn_nsdl_sent_messages_
00043 {
00044     uint16_t    msg_id_number;
00045     uint8_t     message_type;
00046 } sn_nsdl_sent_messages_s;
00047 
00048 /**
00049  * \brief Function pointers used for memory allocation and freeing
00050  */
00051 typedef struct sn_nsdl_mem_
00052 {
00053     void *(*sn_nsdl_alloc)(uint16_t);
00054     void (*sn_nsdl_free)(void *);
00055 } sn_nsdl_mem_s;
00056 
00057 /**
00058  * \brief Includes resource path
00059  */
00060 typedef struct sn_grs_resource_
00061 {
00062     uint8_t pathlen;
00063     uint8_t *path;
00064 } sn_grs_resource_s;
00065 
00066 /**
00067  * \brief Table of created resources
00068  */
00069 typedef struct sn_grs_resource_list_
00070 {
00071     uint8_t res_count;                  /**< Number of resources */
00072     sn_grs_resource_s *res;
00073 } sn_grs_resource_list_s;
00074 
00075 /**
00076  * \brief Resource access rights
00077  */
00078 typedef enum sn_grs_resource_acl_
00079 {
00080     SN_GRS_GET_ALLOWED  = 0x01 ,
00081     SN_GRS_PUT_ALLOWED  = 0x02,
00082     SN_GRS_POST_ALLOWED = 0x04,
00083     SN_GRS_DELETE_ALLOWED   = 0x08
00084 } sn_grs_resource_acl_e;
00085 
00086 /**
00087  * \brief Used protocol
00088  */
00089 typedef struct sn_proto_info_
00090 {
00091     sn_nsdl_capab_e proto;              /**< Only COAP is supported */
00092 } sn_proto_info_s;
00093 
00094 /**
00095  * \brief Defines the resource mode
00096  */
00097 typedef enum sn_nsdl_resource_mode_
00098 {
00099     SN_GRS_STATIC,                      /**< Static resources have some value that doesn't change */
00100     SN_GRS_DYNAMIC,                     /**< Dynamic resources are handled in application. Therefore one must give function callback pointer to them */
00101     SN_GRS_DIRECTORY                    /**< Directory resources are unused and unsupported */
00102 } sn_nsdl_resource_mode_e;
00103 
00104 /**
00105  * \brief Resource registration parameters
00106  */
00107 typedef struct sn_nsdl_resource_parameters_
00108 {
00109     uint8_t     *resource_type_ptr;
00110     uint16_t    resource_type_len;
00111 
00112     uint8_t     *interface_description_ptr;
00113     uint16_t    interface_description_len;
00114 
00115     uint8_t     coap_content_type;
00116 
00117     uint8_t     mime_content_type;
00118 
00119     uint8_t     observable;
00120 
00121     uint8_t     registered;
00122 
00123 }sn_nsdl_resource_parameters_s;
00124 
00125 /**
00126  * \brief Defines parameters for the resource.
00127  */
00128 typedef struct sn_nsdl_resource_info_
00129 {
00130     sn_nsdl_resource_parameters_s   *resource_parameters_ptr;
00131 
00132     sn_nsdl_resource_mode_e         mode;                       /**< STATIC etc.. */
00133 
00134     uint16_t                        pathlen;                    /**< Address */
00135     uint8_t                         *path;
00136 
00137     uint16_t                        resourcelen;                /**< 0 if dynamic resource, resource information in static resource */
00138     uint8_t                         *resource;                  /**< NULL if dynamic resource */
00139 
00140     sn_grs_resource_acl_e           access;
00141 
00142     uint8_t (*sn_grs_dyn_res_callback)(sn_coap_hdr_s *, sn_nsdl_addr_s *, sn_proto_info_s *);
00143 
00144 } sn_nsdl_resource_info_s;
00145 
00146 /**
00147  * \fn extern int8_t sn_nsdl_init   (uint8_t (*sn_nsdl_tx_cb)(sn_nsdl_capab_e , uint8_t *, uint16_t, sn_nsdl_addr_s *),
00148  *                          uint8_t (*sn_nsdl_rx_cb)(sn_coap_hdr_s *, sn_nsdl_addr_s *),
00149  *                          sn_nsdl_mem_s *sn_memory)
00150  *
00151  * \brief Initialization function for NSDL library. Initializes NSDL, GRS, HTTP and CoAP.
00152  *
00153  * \param *sn_nsdl_tx_callback  A callback function for sending messages.
00154  *
00155  * \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
00156  *                              reply for some NSDL message (register message etc.), rx callback will be called.
00157  *
00158  * \param *sn_memory            Memory structure which includes function pointers to the allocation and free functions.
00159  *
00160  * \return  0   Success
00161  * \return  -1  Failure
00162  */
00163 extern int8_t sn_nsdl_init(uint8_t (*sn_nsdl_tx_cb)(sn_nsdl_capab_e , uint8_t *, uint16_t, sn_nsdl_addr_s *),
00164                             uint8_t (*sn_nsdl_rx_cb)(sn_coap_hdr_s *, sn_nsdl_addr_s *),
00165                             sn_nsdl_mem_s *sn_memory);
00166 
00167 /**
00168  * \fn extern uint8_t sn_nsdl_register_endpoint(sn_nsdl_ep_parameters_s *endpoint_info_ptr)
00169  *
00170  * \brief Registers endpoint to NSP server.
00171  *
00172  * \param *endpoint_info_ptr    Contains endpoint information.
00173  *
00174  * \return  0   Success
00175  * \return  -1  Failure
00176  */
00177 extern int8_t sn_nsdl_register_endpoint(sn_nsdl_ep_parameters_s *endpoint_info_ptr);
00178 
00179 /**
00180  * \fn extern int8_t sn_nsdl_unregister_endpoint(void)
00181  *
00182  * \brief Sends unregister-message to NSP server.
00183  *
00184  * \return  0   Success
00185  * \return  -1  Failure
00186  */
00187 extern int8_t sn_nsdl_unregister_endpoint(void);
00188 
00189 /**
00190  * \fn extern int8_t sn_nsdl_update_registration(sn_nsdl_ep_parameters_s *endpoint_parameters_ptr);
00191  *
00192  * \brief Update the registration with NSP.
00193  *
00194  * \param *endpoint_info_ptr    Contains endpoint information.
00195  *
00196  * \return  0   Success
00197  * \return  -1  Failure
00198  */
00199 extern int8_t sn_nsdl_update_registration(sn_nsdl_ep_parameters_s *endpoint_parameters_ptr);
00200 
00201 /**
00202  * \fn extern int8_t sn_nsdl_is_ep_registered(void)
00203  *
00204  * \brief Checks if endpoint is registered.
00205  *
00206  * \return 1 Endpoint registration is done successfully
00207  * \return 0 Endpoint is not registered
00208  */
00209 extern int8_t sn_nsdl_is_ep_registered(void);
00210 
00211 /**
00212  * \fn extern void sn_nsdl_nsp_lost(void);
00213  *
00214  * \brief A function to inform NSDL-C library if application detects a fault in NSP registration.
00215  *
00216  * After calling this function sn_nsdl_is_ep_registered() will return "not registered".
00217  */
00218 extern void sn_nsdl_nsp_lost(void);
00219 
00220 /**
00221  * \fn extern uint16_t sn_nsdl_send_observation_notification(uint8_t *token_ptr, uint8_t token_len,
00222  *                                                  uint8_t *payload_ptr, uint16_t payload_len,
00223  *                                                  uint8_t *observe_ptr, uint8_t observe_len,
00224  *                                                  sn_coap_msg_type_e message_type, uint8_t content_type)
00225  *
00226  *
00227  * \brief Sends observation message to NSP server
00228  *
00229  * \param   *token_ptr      Pointer to token to be used
00230  * \param   token_len       Token length
00231  * \param   *payload_ptr    Pointer to payload to be sent
00232  * \param   payload_len     Payload length
00233  * \param   *observe_ptr    Pointer to observe number to be sent
00234  * \param   observe_len     Observe number len
00235  * \param   message_type    Observation message type (confirmable or non-confirmable)
00236  * \param   contetnt_type   Observation message payload contetnt type
00237  *
00238  * \return  !0  Success, observation messages message ID
00239  * \return  0   Failure
00240  */
00241 extern uint16_t sn_nsdl_send_observation_notification(uint8_t *token_ptr, uint8_t token_len,
00242                                                     uint8_t *payload_ptr, uint16_t payload_len,
00243                                                     uint8_t *observe_ptr, uint8_t observe_len,
00244                                                     sn_coap_msg_type_e message_type, uint8_t content_type);
00245 
00246 /**
00247  * \fn extern int16_t sn_nsdl_get_capability(void)
00248  *
00249  * \brief Capability query function.
00250  *
00251  * Used to retrieve the list of supported protocols from the NSDL module.
00252  *
00253  * \return  >0  Success, supported capabilities reported using bitmask with definitions from sn_nsdl_capab_t
00254  * \return  0   Success, no supported capabilities
00255  */
00256 extern int16_t sn_nsdl_get_capability(void);
00257 
00258 /**
00259  * \fn extern uint32_t sn_nsdl_get_version(void)
00260  *
00261  * \brief Version query function.
00262  *
00263  * Used to retrieve the version information structure from the NSDL library.
00264  *
00265  * \return  !0  MSB 2 bytes major version, LSB 2 bytes minor version.
00266  * \return  0   Failure
00267 */
00268 extern uint32_t sn_nsdl_get_version(void);
00269 
00270 /**
00271  * \fn extern int8_t sn_nsdl_process_http(uint8_t *packet, uint16_t *packet_len, sn_nsdl_addr_s *src)
00272  *
00273  * \brief Currently HTTP is not supported
00274  *
00275  * \return  -1  Failure
00276  */
00277 extern int8_t sn_nsdl_process_http(uint8_t *packet, uint16_t *packet_len, sn_nsdl_addr_s *src);
00278 
00279 /**
00280  * \fn extern int8_t sn_nsdl_process_coap(uint8_t *packet, uint16_t packet_len, sn_nsdl_addr_s *src)
00281  *
00282  * \brief To push CoAP packet to NSDL library
00283  *
00284  * Used to push an CoAP packet to NSDL library for processing.
00285  *
00286  * \param   *packet  Pointer to a uint8_t array containing the packet (including the CoAP headers).
00287  *      After successful execution this array may contain the response packet.
00288  *
00289  * \param   *packet_len Pointer to length of the packet. After successful execution this array may contain the length
00290  *      of the response packet.
00291  *
00292  * \param   *src    Pointer to packet source address information. After successful execution this array may contain
00293  *      the destination address of the response packet.
00294  *
00295  * \return  0   Success
00296  * \return  -1  Failure
00297  */
00298 extern int8_t sn_nsdl_process_coap(uint8_t *packet, uint16_t packet_len, sn_nsdl_addr_s *src);
00299 
00300 /**
00301  * \fn extern int8_t sn_nsdl_exec(uint32_t time);
00302  *
00303  * \brief CoAP retransmission function.
00304  *
00305  * Used to give execution time for the NSDL (CoAP) library for retransmissions. The NSDL library
00306  * will call the exec functions of all enabled protocol modules.
00307  *
00308  * \param  time Time in seconds.
00309  *
00310  * \return  0   Success
00311  * \return  -1  Failure
00312  */
00313 extern int8_t sn_nsdl_exec(uint32_t time);
00314 
00315 /**
00316  * \fn  extern int8_t sn_nsdl_create_resource(sn_nsdl_resource_info_s *res)
00317  *
00318  * \brief Resource creating function.
00319  *
00320  * Used to create a static or dynamic HTTP(S) or CoAP resource.
00321  *
00322  * \param   *res    Pointer to a structure of type sn_nsdl_resource_info_t that contains the information
00323  *     about the resource.
00324  *
00325  * \return  0   Success
00326  * \return  -1  Failure
00327  * \return  -2  Resource already exists
00328  * \return  -3  Invalid path
00329  * \return  -4  List adding failure
00330  */
00331 extern int8_t sn_nsdl_create_resource(sn_nsdl_resource_info_s *res);
00332 
00333 /**
00334  * \fn extern int8_t sn_nsdl_update_resource(sn_nsdl_resource_info_s *res)
00335  *
00336  * \brief Resource updating function.
00337  *
00338  * Used to update the direct value of a static resource, the callback function pointer of a dynamic resource
00339  * and access rights of the recource.
00340  *
00341  * \param   *res    Pointer to a structure of type sn_nsdl_resource_info_t that contains the information
00342  *     about the resource. Only the pathlen and path elements are evaluated along with
00343  *     either resourcelen and resource or the function pointer.
00344  *
00345  * \return  0   Success
00346  * \return  -1  Failure
00347  */
00348 extern int8_t sn_nsdl_update_resource(sn_nsdl_resource_info_s *res);
00349 
00350 /**
00351  * \fn extern int8_t sn_nsdl_delete_resource(uint8_t pathlen, uint8_t *path)
00352  *
00353  * \brief Resource delete function.
00354  *
00355  * Used to delete a resource. If resource has a subresources, these all must also be removed.
00356  *
00357  * \param   pathlen     Contains the length of the path that is to be deleted (excluding possible trailing "\0").
00358  *
00359  * \param   *path_ptr   A pointer to an array containing the path.
00360  *
00361  * \return  0   Success
00362  * \return  -1  Failure (No such resource)
00363  */
00364 extern int8_t sn_nsdl_delete_resource(uint8_t pathlen, uint8_t *path);
00365 
00366 /**
00367  * \fn extern sn_nsdl_resource_info_s *sn_nsdl_get_resource(uint16_t pathlen, uint8_t *path)
00368  *
00369  * \brief Resource get function.
00370  *
00371  * Used to get a resource.
00372  *
00373  * \param   pathlen Contains the length of the path that is to be returned (excluding possible trailing '\0').
00374  *
00375  * \param   *path   A pointer to an array containing the path.
00376  *
00377  * \return  !NULL   Success, pointer to a sn_nsdl_resource_info_s that contains the resource information\n
00378  * \return  NULL    Failure
00379  */
00380 extern sn_nsdl_resource_info_s *sn_nsdl_get_resource(uint16_t pathlen, uint8_t *path);
00381 
00382 /**
00383  * \fn extern sn_grs_resource_list_s *sn_nsdl_list_resource(uint16_t pathlen, uint8_t *path)
00384  *
00385  * \brief Resource list function.
00386  *
00387  * \param   pathlen Contains the length of the target path (excluding possible trailing '\0').
00388  *     The length value is not examined if the path itself is a NULL pointer.
00389  *
00390  * \param   *path   A pointer to an array containing the path or a NULL pointer.
00391  *
00392  * \return  !NULL   A pointer to a sn_grs_resource_list_s structure containing the resource listing.
00393  * \return  NULL    Failure with an unspecified error
00394  */
00395 extern sn_grs_resource_list_s *sn_nsdl_list_resource(uint16_t pathlen, uint8_t *path);
00396 
00397 /**
00398  * \fn extern int8_t sn_nsdl_send_coap_message(sn_nsdl_addr_s *address_ptr, sn_coap_hdr_s *coap_hdr_ptr);
00399  *
00400  * \brief Send an outgoing CoAP request.
00401  *
00402  * \param   *address_ptr    Pointer to source address struct
00403  *
00404  * \param   *coap_hdr_ptr   Pointer to CoAP message to be sent
00405  *
00406  * \return  0   Success
00407  * \return  -1  Failure
00408  */
00409 extern int8_t sn_nsdl_send_coap_message(sn_nsdl_addr_s *address_ptr, sn_coap_hdr_s *coap_hdr_ptr);
00410 
00411 /**
00412  * \fn extern int8_t set_NSP_address(uint8_t *NSP_address, uint16_t port, sn_nsdl_addr_type_e address_type);
00413  *
00414  * \brief This function is used to set the NSP address given by an application.
00415  *
00416  * \return  0   Success
00417  * \return  -1  Failed to indicate that NSDL internal address pointer is not allocated (call nsdl_init() first).
00418  */
00419 extern int8_t set_NSP_address(uint8_t *NSP_address, uint16_t port, sn_nsdl_addr_type_e address_type);
00420 
00421 /**
00422  * \fn extern int8_t sn_nsdl_destroy(void);
00423  *
00424  * \brief This function releases all allocated memory in nsdl and grs modules.
00425  */
00426 extern int8_t sn_nsdl_destroy(void);
00427 
00428 #ifdef __cplusplus
00429 }
00430 #endif
00431