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