[plc4x] 02/02: - Added the write-request functions - Added comments

[cd...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

cdutz pushed a commit to branch feature/c-api-read-support-no-promises
in repository https://gitbox.apache.org/repos/asf/plc4x.git

commit 8449ef3f1d047965ed0b6ec2684cf481344cc8c6
Author: Christofer Dutz <ch...@c-ware.de>
AuthorDate: Mon Apr 27 22:07:56 2020 +0200

    - Added the write-request functions
    - Added comments
---
 sandbox/plc4c/api/include/plc4c/connection.h | 43 +++++++++++++++++-----------
 sandbox/plc4c/api/include/plc4c/read.h       | 28 ++++++++++++++++++
 sandbox/plc4c/api/include/plc4c/types.h      | 23 +++++++++------
 sandbox/plc4c/api/include/plc4c/write.h      | 39 +++++++++++++++++++++++++
 4 files changed, 108 insertions(+), 25 deletions(-)

diff --git a/sandbox/plc4c/api/include/plc4c/connection.h b/sandbox/plc4c/api/include/plc4c/connection.h
index 5743b83..5efd841 100644
--- a/sandbox/plc4c/api/include/plc4c/connection.h
+++ b/sandbox/plc4c/api/include/plc4c/connection.h
@@ -26,19 +26,19 @@ extern "C" {
 #include "types.h"
 
 /**
- * CONNECTION CALLBACKS
- */
-
-/**
- * OTHER FUNCTION DEFS FOR CONNECTION
+ * Check if the connection is established successfully.
+ *
+ * @param connection the connection.
+ * @return true if the connection is established.
  */
+bool plc4c_connection_is_connected(plc4c_connection *connection);
 
 /**
- * CONNECTION FUNCTIONS
+ * Check if an error occurred while connecting.
+ *
+ * @param connection the connection.
+ * @return true if an error occurred while connecting.
  */
-
-bool plc4c_connection_is_connected(plc4c_connection *connection);
-
 bool plc4c_connection_has_error(plc4c_connection *connection);
 
 /**
@@ -49,6 +49,11 @@ bool plc4c_connection_has_error(plc4c_connection *connection);
  */
 return_code plc4c_connection_disconnect(plc4c_connection *connection);
 
+/**
+ * Destrop a previously created connection.
+ *
+ * @param connection
+ */
 void plc4c_connection_destroy(plc4c_connection *connection);
 
 /**
@@ -58,13 +63,15 @@ char *plc4c_connection_get_connection_string(plc4c_connection *connection);
 
 /**
  * Check if the current connection supports read operations.
+ *
  * @param connection reference to the connection
  * @return true if the connection supports reading, false otherwise
  */
 bool plc4c_connection_supports_reading(plc4c_connection *connection);
 
 /**
- * Initializes an empty read-request
+ * Initializes an empty read-request.
+ *
  * @param connection connection that this read-request will be executed on.
  * @param num_items number of items we want to read.
  * @param addresses array of address strings.
@@ -78,13 +85,15 @@ return_code plc4c_connection_create_read_request(plc4c_connection *connection,
 
 /**
  * Check if the current connection supports write operations.
+ *
  * @param connection reference to the connection
  * @return true if the connection supports writing, false otherwise
  */
 bool plc4c_connection_supports_writing(plc4c_connection *connection);
 
 /**
- * Initializes an empty write-request
+ * Initializes an empty write-request.
+ *
  * @param connection connection that this write-request will be executed on.
  * @param num_items number of items we want to write.
  * @param addresses array of address strings.
@@ -92,15 +101,15 @@ bool plc4c_connection_supports_writing(plc4c_connection *connection);
  * @param write_request pointer to the write-request
  * @param return_code
  */
-return_code
-plc4c_connection_create_write_request(plc4c_connection *connection,
-                                      int num_items,
-                                      char *addresses[],
-                                      void *values[],
-                                      plc4c_write_request **write_request);
+return_code plc4c_connection_create_write_request(plc4c_connection *connection,
+                                                  int num_items,
+                                                  char *addresses[],
+                                                  void *values[],
+                                                  plc4c_write_request **write_request);
 
 /**
  * Check if the current connection supports subscriptions.
+ *
  * @param connection reference to the connection
  * @return true if the connection supports subscriptions, false otherwise
  */
diff --git a/sandbox/plc4c/api/include/plc4c/read.h b/sandbox/plc4c/api/include/plc4c/read.h
index 4eb4f09..6f455a1 100644
--- a/sandbox/plc4c/api/include/plc4c/read.h
+++ b/sandbox/plc4c/api/include/plc4c/read.h
@@ -35,14 +35,42 @@ return_code plc4c_read_request_execute(plc4c_connection *connection,
                                        plc4c_read_request *read_request,
                                        plc4c_read_request_execution **read_request_execution);
 
+/**
+ * Check if the read-request is completed successfully.
+ *
+ * @param read_request_execution the read-request execution.
+ * @return true if the read-request is completed successfully.
+ */
 bool plc4c_read_request_finished_successfully(plc4c_read_request_execution *read_request_execution);
 
+/**
+ * Check if the read-request is completed unsuccessfully.
+ *
+ * @param read_request_execution the read-request execution.
+ * @return true if the read-request is completed with an error.
+ */
 bool plc4c_read_request_has_error(plc4c_read_request_execution *read_request_execution);
 
+/**
+ * Retrieve the read-response from a given read-request execution.
+ *
+ * @param read_request_execution the read-request execution.
+ * @return the read-response.
+ */
 plc4c_read_response *plc4c_read_request_get_response(plc4c_read_request_execution *read_request_execution);
 
+/**
+ * Destroys a given read-request.
+ *
+ * @param read_request the read-request.
+ */
 void plc4c_read_request_destroy(plc4c_read_request *read_request);
 
+/**
+ * Destroys a given read-request execution.
+ *
+ * @param read_request_execution the read-request execution.
+ */
 void plc4c_read_request_execution_destroy(plc4c_read_request_execution *read_request_execution);
 
 #ifdef __cplusplus
diff --git a/sandbox/plc4c/api/include/plc4c/types.h b/sandbox/plc4c/api/include/plc4c/types.h
index b63ba6d..2ef112b 100644
--- a/sandbox/plc4c/api/include/plc4c/types.h
+++ b/sandbox/plc4c/api/include/plc4c/types.h
@@ -26,7 +26,6 @@ extern "C" {
 #endif
 
 /**
- *
  * PLC4C error codes
 */
 typedef enum return_code {
@@ -49,42 +48,50 @@ typedef enum return_code {
 char *plc4c_return_code_to_message(return_code err);
 
 /**
- * the plc4c system
+ * The plc4c system.
  */
 typedef struct plc4c_system_t plc4c_system;
 
 /**
- * the plc4c_driver
+ * The plc4c_driver.
  */
 typedef struct plc4c_driver_t plc4c_driver;
 
 /**
- * the plc4c_connection
+ * The plc4c_connection.
  */
 typedef struct plc4c_connection_t plc4c_connection;
 
 /**
- * a plc4c read-request
+ * A plc4c read-request.
  */
 typedef struct plc4c_read_request_t plc4c_read_request;
 
 /**
- * a plc4c read-request-execution
+ * A plc4c read-request-execution.
  */
 typedef struct plc4c_read_request_execution_t plc4c_read_request_execution;
 
+/**
+ * A plc4c read-request response.
+ */
 typedef struct plc4c_read_response_t plc4c_read_response;
 
 /**
- * a plc4c write-request
+ * A plc4c write-request.
  */
 typedef struct plc4c_write_request_t plc4c_write_request;
 
 /**
- * a plc4c write-request-execution
+ * A plc4c write-request-execution.
  */
 typedef struct plc4c_write_request_execution_t plc4c_write_request_execution;
 
+/**
+ * A plc4c write-request response.
+ */
+typedef struct plc4c_write_response_t plc4c_write_response;
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/sandbox/plc4c/api/include/plc4c/write.h b/sandbox/plc4c/api/include/plc4c/write.h
index ad0167a..2b1b51e 100644
--- a/sandbox/plc4c/api/include/plc4c/write.h
+++ b/sandbox/plc4c/api/include/plc4c/write.h
@@ -26,6 +26,7 @@ extern "C" {
 
 /**
  * Actually executes the write-request.
+ *
  * @param connection connection this write-request will be executed on.
  * @param write_request the write-request object.
  * @param write_request_execution pointer to a data-structure handling one execution of the write-request.
@@ -35,6 +36,44 @@ return_code plc4c_write_request_execute(plc4c_connection *connection,
                                         plc4c_write_request *write_reques,
                                         plc4c_write_request_execution **write_request_execution);
 
+/**
+ * Check if the write-request is completed successfully.
+ *
+ * @param write_request_execution the write-request execution.
+ * @return true if the write-request is completed successfully.
+ */
+bool plc4c_write_request_finished_successfully(plc4c_write_request_execution *write_request_execution);
+
+/**
+ * Check if the write-request is completed unsuccessfully.
+ *
+ * @param write_request_execution the write-request execution.
+ * @return true if the write-request is completed with an error.
+ */
+bool plc4c_write_request_has_error(plc4c_write_request_execution *write_request_execution);
+
+/**
+ * Retrieve the write-response from a given write-request execution.
+ *
+ * @param write_request_execution the write-request execution.
+ * @return the write-response.
+ */
+plc4c_write_response *plc4c_write_request_get_response(plc4c_write_request_execution *write_request_execution);
+
+/**
+ * Destroys a given write-request.
+ *
+ * @param write_request the write-request.
+ */
+void plc4c_write_request_destroy(plc4c_write_request *write_request);
+
+/**
+ * Destroys a given write-request execution.
+ *
+ * @param write_request_execution the write-request execution.
+ */
+void plc4c_write_request_execution_destroy(plc4c_write_request_execution *write_request_execution);
+
 #ifdef __cplusplus
 }
 #endif