commit ca9ecfd24ad7dba6d529fc8acb2fc8e9edcbd247
parent 3f3f5d875ae78698a874540e184a8cf49837ecce
Author: Marcello Stanisci <stanisci.m@gmail.com>
Date: Tue, 29 May 2018 17:26:35 +0200
Commenting the "twister API" header file
Diffstat:
2 files changed, 68 insertions(+), 53 deletions(-)
diff --git a/src/include/taler_twister_service.h b/src/include/taler_twister_service.h
@@ -1,22 +1,21 @@
/*
- This file is part of Taler
- Copyright (C) 2018 Taler Systems SA
+ This file is part of Taler
+ Copyright (C) 2018 Taler Systems SA
- Taler is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as
- published by the Free Software Foundation; either version 3,
- or (at your option) any later version.
+ Taler is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as
+ published by the Free Software Foundation; either version 3,
+ or (at your option) any later version.
- Taler is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
- the GNU General Public License for more details.
+ Taler is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
+ the GNU General Public License for more details.
- You should have received a copy of the GNU General Public
- License along with Taler; see the file COPYING. If not,
- write to the Free Software Foundation, Inc., 51 Franklin
- Street, Fifth Floor, Boston, MA 02110-1301, USA.
- */
+ You should have received a copy of the GNU General Public
+ License along with Taler; see the file COPYING. If not,
+ write to the Free Software Foundation, Inc., 51 Franklin
+ Street, Fifth Floor, Boston, MA 02110-1301, USA. */
#ifndef TALER_TWISTER_SERVICE_H_
#define TALER_TWISTER_SERVICE_H_
@@ -80,9 +79,8 @@ struct TALER_TWISTER_Operation;
* @a modify_value.
*
* @param h twister instance to control
- * @param modify_path object-like notation path to the object to
- * modify
- * @param modify_value value to use for @a modify_path
+ * @param path object-like notation path to the object to modify
+ * @param value value to use for @a modify_path
* @param cb callback to call once twister gets this instruction.
* @param cb_cls closure for @a cb_callback
*
@@ -95,6 +93,19 @@ TALER_TWISTER_modify_path_dl (struct TALER_TWISTER_Handle *h,
GNUNET_SCHEDULER_TaskCallback cb,
void *cb_cls);
+
+/**
+ * Change the JSON field pointed by @a path to the new @a value.
+ * It only applies to upload objects.
+ *
+ * @param h twister instance to control
+ * @param path object-like notation path to the object to modify
+ * @param value value to use for @a modify_path
+ * @param cb callback to call once twister gets this instruction.
+ * @param cb_cls closure for @a cb_callback
+ *
+ * @return operation handle.
+ */
struct TALER_TWISTER_Operation *
TALER_TWISTER_modify_path_ul (struct TALER_TWISTER_Handle *h,
const char *path,
@@ -102,13 +113,15 @@ TALER_TWISTER_modify_path_ul (struct TALER_TWISTER_Handle *h,
GNUNET_SCHEDULER_TaskCallback cb,
void *cb_cls);
/**
- * Randomly flip a character into the JSON string
- * object pointed to by @a path.
+ * Instruct the twister to flip a character into
+ * the string JSON field that belongs to the object
+ * being returned to the HTTP client.
*
* @param h twister instance to control
* @param path object-like notation to point the string
* object where we seek a character to flip.
- * @param cb function to call once twister is ready
+ * @param cb function to call once twister has processed this
+ * request
* @param cb_cls closure for @a cb
* @return operation handle (to possibly abort)
*/
@@ -120,13 +133,15 @@ TALER_TWISTER_flip_download
void *cb_cls);
/**
- * Randomly flip a character into the JSON string
- * object pointed to by @a path.
+ * Instruct the twister to flip a character into
+ * the string JSON field that belongs to the object
+ * being uploaded to the proxied service.
*
* @param h twister instance to control
* @param path object-like notation to point the string
* object where we seek a character to flip.
- * @param cb function to call once twister is ready
+ * @param cb function to call once twister has batched this
+ * request
* @param cb_cls closure for @a cb
* @return operation handle (to possibly abort)
*/
@@ -157,7 +172,8 @@ TALER_TWISTER_change_response_code
* Randomly truncate the response.
*
* @param h twister instance to control
- * @param cb function to call once twister is ready
+ * @param cb function to call once twister has processed this
+ * request.
* @param cb_cls closure for @a cb
* @return operation handle (to possibly abort)
*/
@@ -171,7 +187,8 @@ TALER_TWISTER_malform
* Randomly truncate the request.
*
* @param h twister instance to control
- * @param cb function to call once twister is ready
+ * @param cb function to call once twister is ready; tipically
+ * a acknowledge function.
* @param cb_cls closure for @a cb
* @return operation handle (to possibly abort)
*/
@@ -182,7 +199,8 @@ TALER_TWISTER_malform_upload
void *cb_cls);
/**
- * Delete the object pointed to by @a path.
+ * Delete the object pointed to by @a path. Note, this
+ * object belongs to the JSON response object.
*
* @param h twister instance to control
* @param path object-like notation to point the object to be
@@ -204,8 +222,8 @@ TALER_TWISTER_delete_path
* changes requested by the operation, or not! Must be called
* before the operations callback was invoked.
*
- * @param op operation to cancel, operation's callback will not
- * be called
+ * @param op operation to cancel,
+ * operation's callback will not be called
*/
void
TALER_TWISTER_cancel (struct TALER_TWISTER_Operation *op);
@@ -221,11 +239,10 @@ TALER_TWISTER_cancel (struct TALER_TWISTER_Operation *op);
/** @} */ /* end of group nse */
/**
- * Prepare execution of twister service:
- * mainly check if port is available
+ * Prepare twister for execution; mainly checks whether the
+ * HTTP port is available and construct the base URL based on it.
*
* @param config_filename configuration file name.
- *
* @return twister base URL, NULL upon errors.
*/
char *
@@ -235,7 +252,6 @@ TALER_TESTING_prepare_twister (const char *config_filename);
* Run the twister service.
*
* @param config_filename configuration file name.
- *
* @return twister process handle, NULL upon errors.
*/
struct GNUNET_OS_Process *
diff --git a/src/twister/twister_api.c b/src/twister/twister_api.c
@@ -1,23 +1,22 @@
/*
- This file is part of Taler.
- Copyright (C) 2009, 2010, 2011, 2016 GNUnet e.V.
- Copyright (C) 2018 Taler Systems SA
-
- Taler is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as
- published by the Free Software Foundation; either version 3,
- or (at your option) any later version.
-
- Taler is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public
- License along with Taler; see the file COPYING. If not,
- write to the Free Software Foundation, Inc., 51 Franklin
- Street, Fifth Floor, Boston, MA 02110-1301, USA.
-*/
+ This file is part of Taler.
+ Copyright (C) 2009, 2010, 2011, 2016 GNUnet e.V.
+ Copyright (C) 2018 Taler Systems SA
+
+ Taler is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as
+ published by the Free Software Foundation; either version 3,
+ or (at your option) any later version.
+
+ Taler is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public
+ License along with Taler; see the file COPYING. If not,
+ write to the Free Software Foundation, Inc., 51 Franklin
+ Street, Fifth Floor, Boston, MA 02110-1301, USA. */
/**
* @file twister_api.c
@@ -146,7 +145,7 @@ handle_acknowledgement (void *cls,
* Connect to the twister service.
*
* @param cfg the configuration to use
- * @return handle to use
+ * @return handle to use in #TALER_TWISTER_disconnect to disconnect
*/
struct TALER_TWISTER_Handle *
TALER_TWISTER_connect
