Revision 2:ab50a2ab6ec9, committed 2013-10-09

Comitter:

screamer

Date:

Wed Oct 09 14:57:33 2013 +0000

Parent:

1:01d723824294

Child:

3:d8cb1afd7285

Commit message:

Added doxygen markup #2

Changed in this revision

--- a/sn_coap_header.h	Wed Oct 09 14:18:21 2013 +0000
+++ b/sn_coap_header.h	Wed Oct 09 14:57:33 2013 +0000
@@ -242,13 +242,44 @@
 /* * * * EXTERNAL FUNCTION PROTOTYPES  * * * */
 /* * * * * * * * * * * * * * * * * * * * * * */
 
+/**
+ * This function sets the memory allocation and deallocation functions the library will use, and must be called first.
+ */
 extern void           sn_coap_builder_and_parser_init(void* (*used_malloc_func_ptr)(uint16_t), void (*used_free_func_ptr)(void*));
+
+/**
+ * Use to parse an incoming message buffer to a CoAP header structure.
+ */
 extern sn_coap_hdr_s *sn_coap_parser(uint16_t packet_data_len, uint8_t *packet_data_ptr, coap_version_e *coap_version_ptr);
+
+/**
+ * This function releases any memory allocated by a CoAP message structure.
+ */
+extern void           sn_coap_parser_release_allocated_coap_msg_mem(sn_coap_hdr_s *freed_coap_msg_ptr);
+
+/**
+ * Use to build an outgoing message buffer from a CoAP header structure.
+ */
 extern int16_t        sn_coap_builder(uint8_t *dst_packet_data_ptr, sn_coap_hdr_s *src_coap_msg_ptr);
+
+/**
+ * Use to calculate the needed message buffer size from a CoAP message structure.
+ */
 extern uint16_t       sn_coap_builder_calc_needed_packet_data_size(sn_coap_hdr_s *src_coap_msg_ptr);
+
+/**
+ * This function releases any memory allocated in sn_nsdl_transmit_s
+ */
 extern void           sn_coap_builder_release_allocated_send_msg_mem(sn_nsdl_transmit_s *freed_send_msg_ptr);
+
+/**
+ * Use to automate the building of a response to an incoming request.
+ */
 extern sn_coap_hdr_s *sn_coap_build_response(sn_coap_hdr_s *coap_packet_ptr, uint8_t msg_code);
-extern void           sn_coap_parser_release_allocated_coap_msg_mem(sn_coap_hdr_s *freed_coap_msg_ptr);
+
+/**
+ * CoAP packet debugging. 
+ */
 extern void 		  sn_coap_packet_debug(sn_coap_hdr_s *coap_packet_ptr);
 
 #endif /* SN_COAP_HEADER_H_ */

--- a/sn_coap_protocol.h	Wed Oct 09 14:18:21 2013 +0000
+++ b/sn_coap_protocol.h	Wed Oct 09 14:57:33 2013 +0000
@@ -69,19 +69,61 @@
 /* * * * EXTERNAL FUNCTION PROTOTYPES  * * * */
 /* * * * * * * * * * * * * * * * * * * * * * */
 
+/**
+ * This function sets the memory allocation and deallocation functions the library will use, and must be called first.
+ */
 extern int8_t 			   sn_coap_protocol_init(void* (*used_malloc_func_ptr)(uint16_t), void (*used_free_func_ptr)(void*),
 										uint8_t (*used_tx_callback_ptr)(sn_nsdl_capab_e , uint8_t *, uint16_t, sn_nsdl_addr_s *));
+
+/**
+ * Frees all allocated memory in libCoap protocol part.
+ */
 extern int8_t 			   sn_coap_protocol_destroy(void);
+
+/**
+ * Use to build an outgoing message buffer from a CoAP header structure.
+ */
 extern int16_t             sn_coap_protocol_build(sn_nsdl_addr_s *dst_addr_ptr, uint8_t *dst_packet_data_ptr, sn_coap_hdr_s *src_coap_msg_ptr);
+
+/**
+ * Use to parse an incoming message buffer to a CoAP header structure.
+ */
 extern sn_coap_hdr_s      *sn_coap_protocol_parse(sn_nsdl_addr_s *src_addr_ptr, uint16_t packet_data_len, uint8_t *packet_data_ptr);
+
+/**
+ * Called periodically to allow the protocol to update retransmission timers and destroy unneeded data.
+ */
 extern int8_t 			   sn_coap_protocol_exec(uint32_t current_time);
+
+/**
+ * If block transfer is enabled, this function changes the block size.
+ */
 extern int8_t 			   sn_coap_protocol_set_block_size(uint16_t block_size);
+
+/**
+ * If dublicate message detection is enabled, this function changes buffer size.
+ */
 extern int8_t 			   sn_coap_protocol_set_duplicate_buffer_size(uint8_t message_count);
+
+/**
+ * If re-transmissions are enabled, this function changes resending count and buffer size.
+ */
 extern int8_t 			   sn_coap_protocol_set_retransmission(uint8_t resending_count, uint8_t buffer_size);
 
 /* NSP registration functions */
+/**
+ * Create an NSP registration message.
+ */
 extern int8_t 			   sn_coap_register(sn_coap_hdr_s *coap_hdr_ptr, registration_info_t *endpoint_info_ptr);
+
+/**
+ * Create an NSP update message.
+ */
 extern int8_t 			   sn_coap_register_update(sn_coap_hdr_s *coap_hdr_ptr, uint8_t *location, uint8_t length);
+
+/**
+ * Create an NSP de-registration message.
+ */
 extern int8_t 			   sn_coap_deregister(sn_coap_hdr_s *coap_hdr_ptr, uint8_t *location, uint8_t length);
 
 #endif /* SN_COAP_PROTOCOL_H_ */

--- 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);