- some doc updates
authorMartin Willi <martin@strongswan.org>
Mon, 5 Dec 2005 16:30:53 +0000 (16:30 -0000)
committerMartin Willi <martin@strongswan.org>
Mon, 5 Dec 2005 16:30:53 +0000 (16:30 -0000)
Source/charon/utils/identification.c
Source/charon/utils/identification.h
Source/charon/utils/iterator.h
Source/charon/utils/linked_list.h
Source/charon/utils/logger_manager.h

index 2e594dd..b2dc299 100644 (file)
@@ -125,7 +125,7 @@ static void destroy(private_identification_t *this)
        allocator_free(this);   
 }
 
-/**
+/*
  * Generic constructor used for the other twos
  */
 static private_identification_t *identification_create()
@@ -240,7 +240,9 @@ identification_t *identification_create_from_encoding(id_type_t type, chunk_t en
                }
        }                       
        
-       /* build string, must be cloned */
+       /* build string, must be cloned since 
+        * inet_ntoa points to a subsequently 
+        * overwritten buffer */
        this->string = allocator_alloc(strlen(string)+1);
        strcpy(this->string, string);
        
index bc28897..02a5a2e 100644 (file)
 typedef enum id_type_t id_type_t;
 
 /**
- * ID Types of a ID payload.
+ * @brief ID Types of a ID payload.
+ * 
+ * @see identification_t
  * 
  * @ingroup utils
  */
 enum id_type_t {
+       
        /**
         * ID data is a single four (4) octet IPv4 address.
         */
@@ -79,6 +82,9 @@ enum id_type_t {
        ID_KEY_ID = 11
 };
 
+/**
+ * string amppings for id_type_t
+ */
 extern mapping_t id_type_m[];
 
 typedef struct identification_t identification_t;
@@ -87,14 +93,20 @@ typedef struct identification_t identification_t;
  * @brief Generic identification, such as used in ID payload.
  * 
  * The following types are possible:
- * 
  * - ID_IPV4_ADDR 
- * - ID_FQDN (not implemented)
- * - ID_RFC822_ADDR  (not implemented)
- * - ID_IPV6_ADDR (not implemented)
- * - ID_DER_ASN1_DN  (not implemented)
- * - ID_DER_ASN1_GN (not implemented)
- * - ID_KEY_ID (not implemented)
+ * - ID_FQDN*
+ * - ID_RFC822_ADDR*
+ * - ID_IPV6_ADDR*
+ * - ID_DER_ASN1_DN*
+ * - ID_DER_ASN1_GN*
+ * - ID_KEY_ID*
+ * (* = string conversion not supported)
+ * 
+ * @b Constructors:
+ * - identification_create_from_string()
+ * - identification_create_from_encoding()
+ * 
+ * @todo Implement other types. 
  *
  * @ingroup utils
  */
@@ -134,7 +146,7 @@ struct identification_t {
         * 
         * @param this          the identification_t_object
         * @param other         other identification_t_object
-        * @return                      string
+        * @return                      TRUE if the IDs are equal
         */
        bool (*equals) (identification_t *this,identification_t *other);
 
@@ -142,7 +154,7 @@ struct identification_t {
        /**
         * @brief Destroys a identification_t object.
         *
-        * @param this                          identification_t object
+        * @param this          identification_t object
         */
        void (*destroy) (identification_t *this);
 };
@@ -150,7 +162,7 @@ struct identification_t {
 /**
  * @brief Creates an identification_t object from a string.
  * 
- * @param type         type of this id, such as ID_IPV4_ADDR or ID_RFC822_ADDR
+ * @param type         type of this id, such as ID_IPV4_ADDR
  * @param string       input string, which will be converted
  * @return
  *                                     - created identification_t object, or
@@ -164,7 +176,7 @@ identification_t * identification_create_from_string(id_type_t type, char *strin
 /**
  * @brief Creates an identification_t object from an encoded chunk.
  * 
- * @param type         type of this id, such as ID_IPV4_ADDR or ID_RFC822_ADDR
+ * @param type         type of this id, such as ID_IPV4_ADDR
  * @param encoded      encoded bytes, such as from identification_t.get_encoding
  * @return                     created identification_t object
  * 
index f0e66a0..55d1c5d 100644 (file)
@@ -31,12 +31,21 @@ typedef struct iterator_t iterator_t;
  * iterator_t defines an interface for iterating over collections.
  * It allows searching, deleting, updating and inserting.
  * 
+ * @b Constructors:
+ * - via linked_list_t.create_iterator, or
+ * - any other class which supports this interface
+ * 
+ * @see linked_list_t
+ * 
  * @ingroup utils 
  */
 struct iterator_t {
 
        /**
-        * Moves to the next element, if available.
+        * @brief Moves to the next element, if available.
+        * 
+        * A newly created iterator doesn't point to any item,
+        * call has_next first to point it to the first item.
         * 
         * @param this                  calling object
         * @return
@@ -46,7 +55,7 @@ struct iterator_t {
        bool (*has_next) (iterator_t *this);
 
        /**
-        * Returns the current value at the iterator position.
+        * @brief Returns the current value at the iterator position.
         * 
         * @param this                  calling object
         * @param[out] value    value is set to the current value at iterator position
@@ -57,7 +66,7 @@ struct iterator_t {
        status_t (*current) (iterator_t *this, void **value);
        
        /**
-        * Inserts a new item before the given iterator position.
+        * @biref Inserts a new item before the given iterator position.
         * 
         * The iterator position is not changed after inserting
         * 
@@ -92,7 +101,7 @@ struct iterator_t {
        status_t (*replace) (iterator_t *this, void **old_item, void *new_item);
 
        /**
-        * @brief removes an element from list at the given iterator position.
+        * @brief Removes an element from list at the given iterator position.
         * 
         * The position of the iterator is set in the following order:
         * - to the item before, if available
index 779252e..e01b7c1 100644 (file)
@@ -34,6 +34,9 @@ typedef struct linked_list_t linked_list_t;
  *
  * @warning Access to an object of this type is not thread-save.
  * 
+ * @b Costructors:
+ * - linked_list_create()
+ * 
  * @see job_queue_t, event_queue_t, send_queue_t
  * 
  * @ingroup utils
@@ -43,8 +46,8 @@ struct linked_list_t {
        /**
         * @brief Gets the count of items in the list.
         * 
-        * @param linked_list           calling object
-        * @return                                      number of items in list
+        * @param linked_list   calling object
+        * @return                              number of items in list
         */
        int (*get_count) (linked_list_t *linked_list);
        
@@ -53,9 +56,9 @@ struct linked_list_t {
         * 
         * @warning Created iterator_t object has to get destroyed by the caller.
         * 
-        * @param linked_list           calling object
-        * @param[in] forward           iterator direction (TRUE: front to end)
-        * @return                                      new iterator_t object
+        * @param linked_list   calling object
+        * @param[in] forward   iterator direction (TRUE: front to end)
+        * @return                              new iterator_t object
         */
        iterator_t * (*create_iterator) (linked_list_t *linked_list, bool forward);
 
index 7658e42..63b043f 100644 (file)
@@ -30,7 +30,7 @@
 typedef enum logger_context_t logger_context_t;
 
 /**
- * @brief Context of a specific logger 
+ * @brief Context of a specific logger.
  * 
  * @ingroup utils
  */
@@ -56,7 +56,16 @@ enum logger_context_t {
 typedef struct logger_manager_t logger_manager_t;
 
 /**
- * Class to manage logger_t objects.
+ * @brief Class to manage logger_t objects.
+ * 
+ * The logger manager stores all loggers in a list and
+ * allows their manipulation. Via a logger_context_t, the loglevel
+ * of a specific logging type can be adjusted at runtime.
+ * 
+ * @b Constructors:
+ * - logger_manager_create()
+ * 
+ * @see logger_t
  * 
  * @ingroup utils
  */