NSDL C library
Dependents: NSDL_HelloWorld_WiFi UbloxModemNanoServiceClient IOT-NSDL_HelloWorld LWM2M_NanoService_Ethernet ... more
Fork of nsdl_lib by
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_
Generated on Tue Jul 12 2022 18:09:19 by 1.7.2