xref: /curl/docs/libcurl/curl_mime_filedata.md (revision 5a488251) 
1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_mime_filedata
5Section: 3
6Source: libcurl
7See-also:
8  - curl_mime_addpart (3)
9  - curl_mime_data (3)
10  - curl_mime_filename (3)
11  - curl_mime_name (3)
12Protocol:
13  - HTTP
14  - IMAP
15  - SMTP
16Added-in: 7.56.0
17---
18
19# NAME
20
21curl_mime_filedata - set a mime part's body data from a file contents
22
23# SYNOPSIS
24
25~~~c
26#include <curl/curl.h>
27
28CURLcode curl_mime_filedata(curl_mimepart *part,
29                            const char *filename);
30~~~
31
32# DESCRIPTION
33
34curl_mime_filedata(3) sets a mime part's body content from the named
35file's contents. This is an alternative to curl_mime_data(3) for setting
36data to a mime part.
37
38*part* is the part's to assign contents to.
39
40*filename* points to the null-terminated file's path name. The pointer can
41be NULL to detach the previous part contents settings. Filename storage can
42be safely be reused after this call.
43
44As a side effect, the part's remote filename is set to the base name of the
45given *filename* if it is a valid named file. This can be undone or
46overridden by a subsequent call to curl_mime_filename(3).
47
48The contents of the file is read during the file transfer in a streaming
49manner to allow huge files to get transferred without using much memory. It
50therefore requires that the file is kept intact during the entire request.
51
52If the file size cannot be determined before actually reading it (such as for
53a character device or named pipe), the whole mime structure containing the
54part is transferred using chunks by HTTP but is rejected by IMAP.
55
56Setting a part's contents multiple times is valid: only the value set by the
57last call is retained.
58
59# %PROTOCOLS%
60
61# EXAMPLE
62
63~~~c
64int main(void)
65{
66  curl_mime *mime;
67  curl_mimepart *part;
68
69  CURL *curl = curl_easy_init();
70  if(curl) {
71    /* create a mime handle */
72    mime = curl_mime_init(curl);
73
74    /* add a part */
75    part = curl_mime_addpart(mime);
76
77    /* send data from this file */
78    curl_mime_filedata(part, "image.png");
79
80    /* set name */
81    curl_mime_name(part, "data");
82  }
83}
84~~~
85
86# %AVAILABILITY%
87
88# RETURN VALUE
89
90CURLE_OK or a CURL error code upon failure. CURLE_READ_ERROR is only an
91indication that the file is not yet readable: it can be safely ignored at
92this time, but the file must be made readable before the pertaining
93easy handle is performed.
94