s3:libsmb: add comments for cli_write_send/cli_push_send

Added a code comment highlighting this 2 APIs do similar jobs, and tried
to explain why you might want to use one over the other.

BUG: https://bugzilla.samba.org/show_bug.cgi?id=7113
BUG: https://bugzilla.samba.org/show_bug.cgi?id=11892
BUG: https://bugzilla.samba.org/show_bug.cgi?id=13676

Signed-off-by: Tim Beale <timbeale@catalyst.net.nz>
Reviewed-by: Andrew Bartlett <abartlet@samba.org>

diff --git a/source3/libsmb/clireadwrite.c b/source3/libsmb/clireadwrite.c
index 6d47ccd872ac01e6086a7381a78082d7d063daab..e953fa5e22860af95d1456f8f94bfafcaf861f8e 100644 (file)
--- a/source3/libsmb/clireadwrite.c
+++ b/source3/libsmb/clireadwrite.c
@@ -1072,6 +1072,14 @@ struct cli_write_state {
 
 static void cli_write_done(struct tevent_req *subreq);
 
+/*
+ * Used to write to a file remotely.
+ * This is similar in functionality to cli_push_send(), except this is a more
+ * finer-grain API. For example, if the data we want to write exceeds the max
+ * write size of the underlying connection, then it's the caller's
+ * responsibility to handle this.
+ * For writing a small amount of data to file, this is a simpler API to use.
+ */
 struct tevent_req *cli_write_send(TALLOC_CTX *mem_ctx,
                                  struct tevent_context *ev,
                                  struct cli_state *cli, uint16_t fnum,
@@ -1455,6 +1463,16 @@ static void cli_push_setup_chunks(struct tevent_req *req);
 static void cli_push_chunk_ship(struct cli_push_chunk *chunk);
 static void cli_push_chunk_done(struct tevent_req *subreq);
 
+/*
+ * Used to write to a file remotely.
+ * This is similar in functionality to cli_write_send(), except this API
+ * handles writing a large file by breaking the data into chunks (so we don't
+ * exceed the max write size of the underlying connection). To do this, the
+ * (*source) callback handles copying the underlying file data into a message
+ * buffer, one chunk at a time.
+ * This API is recommended when writing a potentially large amount of data,
+ * e.g. when copying a file (or doing a 'put').
+ */
 struct tevent_req *cli_push_send(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
                                 struct cli_state *cli,
                                 uint16_t fnum, uint16_t mode,