Diff: sn_nsdl_lib.h

Revision:

2:ab50a2ab6ec9

Parent:

1:01d723824294

Child:

3:d8cb1afd7285

--- a/sn_nsdl_lib.h	Wed Oct 09 14:18:21 2013 +0000
+++ b/sn_nsdl_lib.h	Wed Oct 09 14:57:33 2013 +0000
@@ -1,3 +1,13 @@
+/**
+ * \file sn_nsdl_lib.h
+ *
+ * \brief NanoService Devices Library header file
+ *
+ *  Created on: Aug 23, 2011
+ *      Author: tero
+ *
+ */
+ 
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -87,7 +97,7 @@
 
 typedef struct sn_grs_resource_list_
 {
-	uint8_t res_count;				/* Number of resources */
+	uint8_t res_count;				/**< Number of resources */
 	sn_grs_resource_s *res;
 }sn_grs_resource_list_s;
 
@@ -141,13 +151,13 @@
 {
 	sn_nsdl_resource_parameters_s 	*resource_parameters_ptr;
 
-	sn_nsdl_resource_mode_e			mode;						// STATIC etc..
+	sn_nsdl_resource_mode_e			mode;						//< STATIC etc..
 
-	uint16_t 						pathlen;					// Address
+	uint16_t 						pathlen;					//< Address
 	uint8_t 						*path;
 
-	uint16_t 						resourcelen;				// 0 if dynamic resource, resource information in static resource
-	uint8_t 						*resource;					// NULL if dynamic resource
+	uint16_t 						resourcelen;				//< 0 if dynamic resource, resource information in static resource
+	uint8_t 						*resource;					//< NULL if dynamic resource
 
 	sn_grs_resource_acl_e 			access;
 
@@ -160,7 +170,6 @@
  *							uint8_t (*sn_nsdl_rx_cb)(sn_coap_hdr_s *, sn_nsdl_addr_s *),
  *							sn_nsdl_mem_s *sn_memory)
  *
- *
  * \brief Initialization function for NSDL library. Initializes NSDL, GRS, HTTP and CoAP.
  *
  * \param *sn_nsdl_tx_callback 	A callback function for sending messages.
@@ -170,7 +179,8 @@
  *
  * \param *sn_memory			Memory structure which includes function pointers to the allocation and free functions.
  *
- * \return						SN_NSDL_SUCCESS = 0, Failed = -1
+ * \return Success = 0
+ * \return Failed = -1
  */
 int8_t sn_nsdl_init	(uint8_t (*sn_nsdl_tx_cb)(sn_nsdl_capab_e , uint8_t *, uint16_t, sn_nsdl_addr_s *),
 							uint8_t (*sn_nsdl_rx_cb)(sn_coap_hdr_s *, sn_nsdl_addr_s *),
@@ -179,43 +189,53 @@
 /**
  * \fn extern uint8_t sn_nsdl_register_endpoint(sn_nsdl_ep_parameters_s *endpoint_info_ptr)
  *
- *
  * \brief Registers endpoint to NSP server.
  *
  * \param *endpoint_info_ptr	Contains endpoint information.
  *
- * \return						SN_NSDL_SUCCESS = 0, Failed = -1
+ * \return Success = 0
+ * \return Failed = -1
  */
 int8_t sn_nsdl_register_endpoint(sn_nsdl_ep_parameters_s *endpoint_info_ptr);
 
 /**
  * \fn extern int8_t sn_nsdl_unregister_endpoint(void)
  *
- *
  * \brief Sends unregister-message to NSP server.
  *
- * \return		SN_NSDL_SUCCESS = 0, Failed = -1
+ * \return Success = 0
+ * \return Failed = -1
  */
 int8_t sn_nsdl_unregister_endpoint(void);
+
+/**
+ * Update the registration with NSP.
+ */
 int8_t sn_nsdl_update_registration (sn_nsdl_ep_parameters_s *endpoint_parameters_ptr);
+
+/**
+ *
+ */
 int8_t sn_nsdl_send_eventing_message (uint8_t *event_name_ptr, uint16_t event_name_len, uint8_t *message_body_ptr, uint16_t message_body_len);
 
 /**
  * \fn extern int8_t sn_nsdl_is_ep_registered(void)
  *
- *
  * \brief Checks if endpoint is registered.
  *
- * \return 1 if endpointi registration is done SN_NSDL_SUCCESSfully, 0 if endpoint is not registered
+ * \return 1 if endpointi registration is done successfully
+ * \return 0 if endpoint is not registered
  */
 int8_t sn_nsdl_is_ep_registered(void);
 
 /**
- * A function to inform NSDL-C library if application detects a fault in NSP registration. After calling this function
+ * \fn void sn_nsdl_nsp_lost(void);
+ *
+ * \brief A function to inform NSDL-C library if application detects a fault in NSP registration. After calling this function
  * , sn_nsdl_is_ep_registered() will return "not registered".
  */
- 
-void sn_nsdl_nsp_lost(void);
+ void sn_nsdl_nsp_lost(void);
+
 /**
  * \fn extern int8_t sn_nsdl_send_observation_notification(uint8_t *token_ptr, uint8_t token_len,
  *															uint8_t *payload_ptr, uint16_t payload_len,
@@ -231,34 +251,72 @@
  * \param *observe_ptr	Pointer to observe number to be sent
  * \param observe_len	Observe number len
  *
- * \return		SN_NSDL_SUCCESS = 0, Failed = -1
+ * \return Success = 0
+ * \return Failed = -1
  */
 extern uint16_t sn_nsdl_send_observation_notification(uint8_t *token_ptr, uint8_t token_len, uint8_t *payload_ptr, uint16_t payload_len, uint8_t *observe_ptr, uint8_t observe_len, sn_coap_msg_type_e message_type, uint8_t content_type);
+
 int16_t sn_nsdl_get_capability(void);
 uint32_t sn_nsdl_get_version(void);
 int8_t sn_nsdl_process_http(uint8_t *packet, uint16_t *packet_len, sn_nsdl_addr_s *src);
+
+/**
+ * Process an incoming CoAP message.
+ */
 int8_t sn_nsdl_process_coap(uint8_t *packet, uint16_t packet_len, sn_nsdl_addr_s *src);
+
+/**
+ * Must be called periodically for the library to update retransmissions.
+ */
 int8_t sn_nsdl_exec(uint32_t time);
+
+/**
+ * Adds a resource to the server.
+ */
 int8_t sn_nsdl_create_resource(sn_nsdl_resource_info_s *res);
+
+/**
+ * Updates a resource on the server.
+ */
 int8_t sn_nsdl_update_resource(sn_nsdl_resource_info_s *res);
+
+/**
+ * Removes a resource from the resource server.
+ */
 int8_t sn_nsdl_delete_resource(uint8_t pathlen, uint8_t *path);
+
+
 sn_nsdl_resource_info_s *sn_nsdl_get_resource(uint8_t pathlen, uint8_t *path);
 sn_grs_resource_list_s *sn_nsdl_list_resource(uint8_t pathlen, uint8_t *path);
+
+/**
+ * Send an outgoing CoAP request.
+ */
 int8_t sn_nsdl_send_coap_message(sn_nsdl_addr_s *address_ptr, sn_coap_hdr_s *coap_hdr_ptr);
+
 /**
+ * \fn int8_t set_NSP_address(uint8_t *NSP_address, uint16_t port, sn_nsdl_addr_type_e address_type);
+ *
  * \brief This function is used to set the NSP address given by an application.
- * @return 0 on success, -1 on false to indicate that NSDL internal address pointer is not allocated (call nsdl_init() first).
+ *
+ * \return 0 on success,
+ * \return -1 on false to indicate that NSDL internal address pointer is not allocated (call nsdl_init() first).
  */
 int8_t set_NSP_address(uint8_t *NSP_address, uint16_t port, sn_nsdl_addr_type_e address_type);
 
 /**
+ * \fn extern int8_t sn_nsdl_destroy(void);
+ *
  * \brief This function releases all allocated memory in nsdl and grs modules.
  */
 extern int8_t sn_nsdl_destroy(void);
 
 /*
+ * \fn extern const char __code * sn_nsdl_get_library_version_info(void);
+ *
  * \brief A function to request SN internal version information out of NSDL library in case of "error reporting" or similar.
- * @return A string with \0 in the end. A human readable format. Please deliver this item to Sensinode in case if you're to report of errors.
+ *
+ * \return A string with \0 in the end. A human readable format. Please deliver this item to Sensinode in case if you're to report of errors.
  */
 //extern const char __code * sn_nsdl_get_library_version_info(void);