xref: /aosp_15_r20/external/curl/docs/libcurl/curl_mime_encoder.md (revision 6236dae45794135f37c4eb022389c904c8b0090d)
1*6236dae4SAndroid Build Coastguard Worker---
2*6236dae4SAndroid Build Coastguard Workerc: Copyright (C) Daniel Stenberg, <[email protected]>, et al.
3*6236dae4SAndroid Build Coastguard WorkerSPDX-License-Identifier: curl
4*6236dae4SAndroid Build Coastguard WorkerTitle: curl_mime_encoder
5*6236dae4SAndroid Build Coastguard WorkerSection: 3
6*6236dae4SAndroid Build Coastguard WorkerSource: libcurl
7*6236dae4SAndroid Build Coastguard WorkerSee-also:
8*6236dae4SAndroid Build Coastguard Worker  - curl_mime_addpart (3)
9*6236dae4SAndroid Build Coastguard Worker  - curl_mime_headers (3)
10*6236dae4SAndroid Build Coastguard Worker  - curl_mime_subparts (3)
11*6236dae4SAndroid Build Coastguard WorkerProtocol:
12*6236dae4SAndroid Build Coastguard Worker  - HTTP
13*6236dae4SAndroid Build Coastguard Worker  - IMAP
14*6236dae4SAndroid Build Coastguard Worker  - SMTP
15*6236dae4SAndroid Build Coastguard WorkerAdded-in: 7.56.0
16*6236dae4SAndroid Build Coastguard Worker---
17*6236dae4SAndroid Build Coastguard Worker
18*6236dae4SAndroid Build Coastguard Worker# NAME
19*6236dae4SAndroid Build Coastguard Worker
20*6236dae4SAndroid Build Coastguard Workercurl_mime_encoder - set a mime part's encoder and content transfer encoding
21*6236dae4SAndroid Build Coastguard Worker
22*6236dae4SAndroid Build Coastguard Worker# SYNOPSIS
23*6236dae4SAndroid Build Coastguard Worker
24*6236dae4SAndroid Build Coastguard Worker~~~c
25*6236dae4SAndroid Build Coastguard Worker#include <curl/curl.h>
26*6236dae4SAndroid Build Coastguard Worker
27*6236dae4SAndroid Build Coastguard WorkerCURLcode curl_mime_encoder(curl_mimepart *part, const char *encoding);
28*6236dae4SAndroid Build Coastguard Worker~~~
29*6236dae4SAndroid Build Coastguard Worker
30*6236dae4SAndroid Build Coastguard Worker# DESCRIPTION
31*6236dae4SAndroid Build Coastguard Worker
32*6236dae4SAndroid Build Coastguard Workercurl_mime_encoder() requests a mime part's content to be encoded before being
33*6236dae4SAndroid Build Coastguard Workertransmitted.
34*6236dae4SAndroid Build Coastguard Worker
35*6236dae4SAndroid Build Coastguard Worker*part* is the part's handle to assign an encoder.
36*6236dae4SAndroid Build Coastguard Worker*encoding* is a pointer to a null-terminated encoding scheme. It may be
37*6236dae4SAndroid Build Coastguard Workerset to NULL to disable an encoder previously attached to the part. The encoding
38*6236dae4SAndroid Build Coastguard Workerscheme storage may safely be reused after this function returns.
39*6236dae4SAndroid Build Coastguard Worker
40*6236dae4SAndroid Build Coastguard WorkerSetting a part's encoder multiple times is valid: only the value set by the
41*6236dae4SAndroid Build Coastguard Workerlast call is retained.
42*6236dae4SAndroid Build Coastguard Worker
43*6236dae4SAndroid Build Coastguard WorkerUpon multipart rendering, the part's content is encoded according to the
44*6236dae4SAndroid Build Coastguard Workerpertaining scheme and a corresponding *"Content-Transfer-Encoding"* header
45*6236dae4SAndroid Build Coastguard Workeris added to the part.
46*6236dae4SAndroid Build Coastguard Worker
47*6236dae4SAndroid Build Coastguard WorkerSupported encoding schemes are:
48*6236dae4SAndroid Build Coastguard Worker
49*6236dae4SAndroid Build Coastguard Worker"*binary*": the data is left unchanged, the header is added.
50*6236dae4SAndroid Build Coastguard Worker
51*6236dae4SAndroid Build Coastguard Worker"*8bit*": header added, no data change.
52*6236dae4SAndroid Build Coastguard Worker
53*6236dae4SAndroid Build Coastguard Worker"*7bit*": the data is unchanged, but is each byte is checked
54*6236dae4SAndroid Build Coastguard Workerto be a 7-bit value; if not, a read error occurs.
55*6236dae4SAndroid Build Coastguard Worker
56*6236dae4SAndroid Build Coastguard Worker"*base64*": Data is converted to base64 encoding, then split in
57*6236dae4SAndroid Build Coastguard WorkerCRLF-terminated lines of at most 76 characters.
58*6236dae4SAndroid Build Coastguard Worker
59*6236dae4SAndroid Build Coastguard Worker"*quoted-printable*": data is encoded in quoted printable lines of
60*6236dae4SAndroid Build Coastguard Workerat most 76 characters. Since the resulting size of the final data cannot be
61*6236dae4SAndroid Build Coastguard Workerdetermined prior to reading the original data, it is left as unknown, causing
62*6236dae4SAndroid Build Coastguard Workerchunked transfer in HTTP. For the same reason, this encoder may not be used
63*6236dae4SAndroid Build Coastguard Workerwith IMAP. This encoder targets text data that is mostly ASCII and should
64*6236dae4SAndroid Build Coastguard Workernot be used with other types of data.
65*6236dae4SAndroid Build Coastguard Worker
66*6236dae4SAndroid Build Coastguard WorkerIf the original data is already encoded in such a scheme, a custom
67*6236dae4SAndroid Build Coastguard Worker*Content-Transfer-Encoding* header should be added with
68*6236dae4SAndroid Build Coastguard Workercurl_mime_headers(3) instead of setting a part encoder.
69*6236dae4SAndroid Build Coastguard Worker
70*6236dae4SAndroid Build Coastguard WorkerEncoding should not be applied to multiparts, thus the use of this function on
71*6236dae4SAndroid Build Coastguard Workera part with content set with curl_mime_subparts(3) is strongly
72*6236dae4SAndroid Build Coastguard Workerdiscouraged.
73*6236dae4SAndroid Build Coastguard Worker
74*6236dae4SAndroid Build Coastguard Worker# %PROTOCOLS%
75*6236dae4SAndroid Build Coastguard Worker
76*6236dae4SAndroid Build Coastguard Worker# EXAMPLE
77*6236dae4SAndroid Build Coastguard Worker
78*6236dae4SAndroid Build Coastguard Worker~~~c
79*6236dae4SAndroid Build Coastguard Workerint main(void)
80*6236dae4SAndroid Build Coastguard Worker{
81*6236dae4SAndroid Build Coastguard Worker  curl_mime *mime;
82*6236dae4SAndroid Build Coastguard Worker  curl_mimepart *part;
83*6236dae4SAndroid Build Coastguard Worker
84*6236dae4SAndroid Build Coastguard Worker  CURL *curl = curl_easy_init();
85*6236dae4SAndroid Build Coastguard Worker  if(curl) {
86*6236dae4SAndroid Build Coastguard Worker    /* create a mime handle */
87*6236dae4SAndroid Build Coastguard Worker    mime = curl_mime_init(curl);
88*6236dae4SAndroid Build Coastguard Worker
89*6236dae4SAndroid Build Coastguard Worker    /* add a part */
90*6236dae4SAndroid Build Coastguard Worker    part = curl_mime_addpart(mime);
91*6236dae4SAndroid Build Coastguard Worker
92*6236dae4SAndroid Build Coastguard Worker    /* send a file */
93*6236dae4SAndroid Build Coastguard Worker    curl_mime_filedata(part, "image.png");
94*6236dae4SAndroid Build Coastguard Worker
95*6236dae4SAndroid Build Coastguard Worker    /* encode file data in base64 for transfer */
96*6236dae4SAndroid Build Coastguard Worker    curl_mime_encoder(part, "base64");
97*6236dae4SAndroid Build Coastguard Worker  }
98*6236dae4SAndroid Build Coastguard Worker}
99*6236dae4SAndroid Build Coastguard Worker~~~
100*6236dae4SAndroid Build Coastguard Worker
101*6236dae4SAndroid Build Coastguard Worker# %AVAILABILITY%
102*6236dae4SAndroid Build Coastguard Worker
103*6236dae4SAndroid Build Coastguard Worker# RETURN VALUE
104*6236dae4SAndroid Build Coastguard Worker
105*6236dae4SAndroid Build Coastguard WorkerCURLE_OK or a CURL error code upon failure.
106