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