vici: Complete libvici doxygen comments
authorMartin Willi <martin@revosec.ch>
Thu, 1 May 2014 09:07:10 +0000 (11:07 +0200)
committerMartin Willi <martin@revosec.ch>
Wed, 7 May 2014 12:13:38 +0000 (14:13 +0200)
src/libcharon/plugins/vici/libvici.h

index 2689b39..04d8f4a 100644 (file)
@@ -28,8 +28,8 @@
  * - vici_connect(): Connect to a vici service
  * - vici_disconnect(): Disconnect from a vici service
  *
  * - vici_connect(): Connect to a vici service
  * - vici_disconnect(): Disconnect from a vici service
  *
- * Library initialization is basically required to set up libstrongswan and
- * a small thread pool. Initialize libstrongswan manually instead.
+ * Library initialization implicitly initializes libstrongswan and a small
+ * thread pool.
  *
  * Connecting requires an uri, which is currently either a UNIX socket path
  * prefixed with unix://, or a hostname:port touple prefixed with tcp://.
  *
  * Connecting requires an uri, which is currently either a UNIX socket path
  * prefixed with unix://, or a hostname:port touple prefixed with tcp://.
@@ -269,6 +269,8 @@ void vici_free_req(vici_req_t *req);
 /**
  * Dump a message text representation to a FILE stream.
  *
 /**
  * Dump a message text representation to a FILE stream.
  *
+ * On error, errno is set appropriately.
+ *
  * @param res          response message to dump
  * @param label                a label to print for this message
  * @param out          FILE to dump to
  * @param res          response message to dump
  * @param label                a label to print for this message
  * @param out          FILE to dump to
@@ -292,6 +294,8 @@ vici_parse_t vici_parse(vici_res_t *res);
  *
  * The string is valid until vici_free_res() is called.
  *
  *
  * The string is valid until vici_free_res() is called.
  *
+ * On error, errno is set appropriately.
+ *
  * @param res          response message to parse
  * @return                     name tag / key, NULL on error
  */
  * @param res          response message to parse
  * @return                     name tag / key, NULL on error
  */
@@ -314,7 +318,13 @@ int vici_parse_name_eq(vici_res_t *res, char *name);
  *
  * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
  * VICI_PARSE_LIST_ITEM.
  *
  * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
  * VICI_PARSE_LIST_ITEM.
+ *
  * The string is valid until vici_free_res() is called.
  * The string is valid until vici_free_res() is called.
+ *
+ * On error, errno is set appropriately.
+ *
+ * @param len          pointer receiving value length
+ * @return                     pointer to value, NULL on error
  */
 void* vici_parse_value(vici_res_t *res, int *len);
 
  */
 void* vici_parse_value(vici_res_t *res, int *len);
 
@@ -323,9 +333,12 @@ void* vici_parse_value(vici_res_t *res, int *len);
  *
  * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
  * VICI_PARSE_LIST_ITEM.
  *
  * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
  * VICI_PARSE_LIST_ITEM.
+ *
  * This call is successful only if the value contains no non-printable
  * characters. The string is valid until vici_free_res() is called.
  *
  * This call is successful only if the value contains no non-printable
  * characters. The string is valid until vici_free_res() is called.
  *
+ * On error, errno is set appropriately.
+ *
  * @param res          response message to parse
  * @return                     value as string, NULL on error
  */
  * @param res          response message to parse
  * @return                     value as string, NULL on error
  */
@@ -338,6 +351,8 @@ char* vici_parse_value_str(vici_res_t *res);
  * invoked for the current section level only. To descent into sections, call
  * vici_parse_cb() from within a section callback.
  *
  * invoked for the current section level only. To descent into sections, call
  * vici_parse_cb() from within a section callback.
  *
+ * On error, errno is set appropriately.
+ *
  * @param res          message to parse
  * @param section      callback invoked for each section
  * @param kv           callback invoked for key/value pairs
  * @param res          message to parse
  * @param section      callback invoked for each section
  * @param kv           callback invoked for key/value pairs