Xuanwo commented on code in PR #3259:
URL:
https://github.com/apache/incubator-opendal/pull/3259#discussion_r1355933321
##########
bindings/c/include/opendal.h:
##########
@@ -524,6 +524,53 @@ enum opendal_code opendal_operator_blocking_write(const
struct opendal_operator_
struct opendal_result_read opendal_operator_blocking_read(const struct
opendal_operator_ptr *ptr,
const char *path);
+/**
+ * \brief Blockingly read the data from `path`.
+ *
+ * Read the data out from `path` blockingly by operator, returns
+ * an opendal_result_read with error code.
+ *
+ * @param ptr The opendal_operator_ptr created previously
+ * @param path The path you want to read the data out
+ * @param buffer The buffer you want to read the data into
+ * @param buffer_len The length of the buffer
+ * @see opendal_operator_ptr
+ * @see opendal_result_read
+ * @see opendal_code
+ * @return Returns opendal_code
+ *
+ * \note If the read operation succeeds, the returned opendal_bytes is newly
allocated on heap.
+ * After your usage of that, please call opendal_bytes_free() to free the
space.
+ *
+ * # Example
+ *
+ * Following is an example
+ * ```C
+ * // ... you have write "Hello, World!" to path "/testpath"
+ *
+ * int length = 13;
+ * unsigned char buffer[length];
+ * opendal_code r = opendal_operator_blocking_read_with_buffer(ptr,
"testpath", buffer, length);
+ * assert(r == OPENDAL_OK);
+ * // assert buffer == "Hello, World!"
+ *
+ * ```
+ *
+ * # Safety
+ *
+ * It is **safe** under the cases below
+ * * The memory pointed to by `path` must contain a valid nul terminator at
the end of
+ * the string.
+ *
+ * # Panic
+ *
+ * * If the `path` points to NULL, this function panics, i.e. exits with
information
+ */
+enum opendal_code opendal_operator_blocking_read_with_buffer(const struct
opendal_operator_ptr *ptr,
Review Comment:
I dislike the `read_with_buffer` API as it may conflict with
`read_with("path").buffer(4096)`.
What if we expose `opendal_operator_blocking_reader` that returns an
`opendal_reader_ptr` instead? Users can directly call `read`/`seek` on the
reader. I think this API will provide more power and control to users over the
data reading logic.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
