IMAP: add CURLOPT_UPLOAD_FLAGS and --upload-flags

Set properties on the uploaded resource.

Test 3209 and 3210 verify.

Closes #15970

docs/TODO

@@ -92,7 +92,6 @@
 
  9. IMAP
  9.1 Enhanced capability support
- 9.2 upload unread
 
  10. LDAP
  10.1 SASL based authentication mechanisms
@@ -721,12 +720,6 @@
  Add the ability, for an application that uses libcurl, to obtain the list of
  capabilities returned from the CAPABILITY command.
 
-9.2 upload unread
-
- Uploads over IMAP currently always set the email as "read" (or "seen"). It
- would be good to offer a way for users to select for uploads to remain
- unread.
-
 10. LDAP
 
 10.1 SASL based authentication mechanisms

docs/cmdline-opts/Makefile.inc

@@ -301,6 +301,7 @@ DPAGES = \
   trace.md \
   unix-socket.md \
   upload-file.md \
+  upload-flags.md \
   url.md \
   url-query.md \
   use-ascii.md \

docs/cmdline-opts/upload-file.md

@@ -31,7 +31,7 @@ filename or curl thinks that your last directory name is the remote filename
 to use.
 
 When putting the local filename at the end of the URL, curl ignores what is on
-the left side of any slash (/) or backslash (\) used in the filename and only
+the left side of any slash (/) or backslash (\\) used in the filename and only
 appends what is on the right side of the rightmost such character.
 
 Use the filename `-` (a single dash) to use stdin instead of a given file.

docs/cmdline-opts/upload-flags.md

@@ -0,0 +1,24 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
+SPDX-License-Identifier: curl
+Long: upload-flags
+Arg: <flags>
+Help: IMAP upload behavior
+Category: curl output
+Added: 8.13.0
+Multi: single
+See-also:
+  - upload-file
+Example:
+  - --upload-flags Flagged,!Seen --upload-file local/dir/file $URL
+---
+
+# `--upload-flags`
+
+Specify additional behavior to apply to uploaded files. Flags are
+specified as either a single flag value or a comma-separated list
+of flag values. These values are case-sensitive and may be negated
+by prepending them with a '-' character. Currently the following
+flag values are accepted: answered, deleted, draft, flagged, and
+seen. The currently-accepted flag values are used to set flags on
+IMAP uploads.

docs/internals/STRPARSE.md

@@ -81,7 +81,7 @@ int Curl_str_quotedword(char **linep, struct Curl_str *out, const size_t max);
 ~~~
 
 Get a "quoted" word. This means everything that is provided within a leading
-and an ending double character. No escaping possible.
+and an ending double quote character. No escaping possible.
 
 `max` is the longest accepted word, or it returns error.
 

docs/libcurl/curl_easy_setopt.md

@@ -1273,6 +1273,10 @@ Upload data. See CURLOPT_UPLOAD(3)
 
 Set upload buffer size. See CURLOPT_UPLOAD_BUFFERSIZE(3)
 
+## CURLOPT_UPLOAD_FLAGS
+
+Set upload flags. See CURLOPT_UPLOAD_FLAGS(3)
+
 ## CURLOPT_URL
 
 URL to work on. See CURLOPT_URL(3)

docs/libcurl/opts/CURLOPT_UPLOAD_FLAGS.md

@@ -0,0 +1,100 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: CURLOPT_UPLOAD_FLAGS
+Section: 3
+Source: libcurl
+See-also:
+  - CURLOPT_UPLOAD (3)
+Protocol:
+  - IMAP
+  - IMAPS
+Added-in: 8.13.0
+---
+
+# NAME
+
+CURLOPT_UPLOAD_FLAGS - upload flags for IMAP
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UPLOAD_FLAGS, long bitmask);
+~~~
+
+# DESCRIPTION
+
+Pass a long as parameter, which is set to a bitmask, to tell libcurl which
+flags to send the server relating to uploaded files. The current supported
+flags are **CURLULFLAG_ANSWERED**, which sets the **Answered** flag for IMAP
+uploads, **CURLULFLAG_DELETED**, which sets the **Deleted** flag for IMAP
+uploads, **CURLULFLAG_DRAFT**, which sets the **Draft** flag for IMAP uploads,
+**CURLULFLAG_FLAGGED**, which sets the **Flagged** flag for IMAP uploads, and
+**CURLULFLAG_SEEN**, which sets the **Seen** flag for IMAP uploads.
+
+# DEFAULT
+
+A bitmask with only the **CURLULFLAG_SEEN** flag set.
+
+# %PROTOCOLS%
+
+# EXAMPLE
+
+~~~c
+static size_t read_cb(char *ptr, size_t size, size_t nmemb, void *userdata)
+{
+  FILE *src = userdata;
+  /* copy as much data as possible into the 'ptr' buffer, but no more than
+     'size' * 'nmemb' bytes */
+  size_t retcode = fread(ptr, size, nmemb, src);
+
+  return retcode;
+}
+
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    FILE *src = fopen("local-file", "r");
+    curl_off_t fsize; /* set this to the size of the input file */
+
+    /* we want to use our own read function */
+    curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb);
+
+    /* enable uploading */
+    curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
+
+    /* specify target */
+    curl_easy_setopt(curl, CURLOPT_URL, "imap://example.com:993/mailbox");
+
+    /* provide username */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user@example.com");
+
+    /* provide password */
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "password");
+
+    /* specify that uploaded mail should be considered flagged */
+    curl_easy_setopt(curl, CURLOPT_UPLOAD_FLAGS, CURLULFLAG_FLAGGED);
+
+    /* now specify which pointer to pass to our callback */
+    curl_easy_setopt(curl, CURLOPT_READDATA, src);
+
+    /* Set the size of the file to upload */
+    curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize);
+
+    /* perform the upload */
+    curl_easy_perform(curl);
+  }
+}
+~~~
+
+# %AVAILABILITY%
+
+# RETURN VALUE
+
+curl_easy_setopt(3) returns a CURLcode indicating success or error.
+
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).

docs/libcurl/opts/Makefile.inc

@@ -411,6 +411,7 @@ man_MANS =                                      \
   CURLOPT_UPKEEP_INTERVAL_MS.3                  \
   CURLOPT_UPLOAD.3                              \
   CURLOPT_UPLOAD_BUFFERSIZE.3                   \
+  CURLOPT_UPLOAD_FLAGS.3                        \
   CURLOPT_URL.3                                 \
   CURLOPT_USE_SSL.3                             \
   CURLOPT_USERAGENT.3                           \

docs/libcurl/symbols-in-versions

@@ -895,6 +895,7 @@ CURLOPT_UNRESTRICTED_AUTH       7.10.4
 CURLOPT_UPKEEP_INTERVAL_MS      7.62.0
 CURLOPT_UPLOAD                  7.1
 CURLOPT_UPLOAD_BUFFERSIZE       7.62.0
+CURLOPT_UPLOAD_FLAGS            8.13.0
 CURLOPT_URL                     7.1
 CURLOPT_USE_SSL                 7.17.0
 CURLOPT_USERAGENT               7.1
@@ -1128,6 +1129,11 @@ CURLUPART_SCHEME                7.62.0
 CURLUPART_URL                   7.62.0
 CURLUPART_USER                  7.62.0
 CURLUPART_ZONEID                7.65.0
+CURLULFLAG_ANSWERED             8.13.0
+CURLULFLAG_DELETED              8.13.0
+CURLULFLAG_DRAFT                8.13.0
+CURLULFLAG_FLAGGED              8.13.0
+CURLULFLAG_SEEN                 8.13.0
 CURLUSESSL_ALL                  7.17.0
 CURLUSESSL_CONTROL              7.17.0
 CURLUSESSL_NONE                 7.17.0

docs/options-in-versions

@@ -266,6 +266,7 @@
 --trace-time                         7.14.0
 --unix-socket                        7.40.0
 --upload-file (-T)                   4.0
+--upload-flags                       8.13.0
 --url                                7.5
 --url-query                          7.87.0
 --use-ascii (-B)                     5.0