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 90This function returns a CURLcode indicating success or error. 91 92CURLE_OK (0) means everything was OK, non-zero means an error occurred, see 93libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3) 94there can be an error message stored in the error buffer when non-zero is 95returned. 96 97CURLE_READ_ERROR is only an indication that the file is not yet readable: it 98can be safely ignored at this time, but the file must be made readable before 99the pertaining easy handle is performed. 100
