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