mirror of
https://github.com/curl/curl.git
synced 2024-12-09 06:30:06 +08:00
eb559c8056
Deprecation and removal of codeset conversion support from the library have released the strict need for an early binding of mime structures to an easy handle (https://github.com/curl/curl/commit/2610142). This constraint currently forces to create the handle before the mime structure and the latter cannot be attached to another handle once created (see https://curl.se/mail/lib-2022-08/0027.html). This commit removes the handle pointers from the mime structures allowing more flexibility on their use. When an easy handle is duplicated, bound mime structures must however still be duplicated too as their components hold send-time dynamic information. Closes #9927
74 lines
2.7 KiB
Groff
74 lines
2.7 KiB
Groff
.\" **************************************************************************
|
|
.\" * _ _ ____ _
|
|
.\" * Project ___| | | | _ \| |
|
|
.\" * / __| | | | |_) | |
|
|
.\" * | (__| |_| | _ <| |___
|
|
.\" * \___|\___/|_| \_\_____|
|
|
.\" *
|
|
.\" * Copyright (C) 1998 - 2022, Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
.\" *
|
|
.\" * This software is licensed as described in the file COPYING, which
|
|
.\" * you should have received as part of this distribution. The terms
|
|
.\" * are also available at https://curl.se/docs/copyright.html.
|
|
.\" *
|
|
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
|
.\" * copies of the Software, and permit persons to whom the Software is
|
|
.\" * furnished to do so, under the terms of the COPYING file.
|
|
.\" *
|
|
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
|
.\" * KIND, either express or implied.
|
|
.\" *
|
|
.\" * SPDX-License-Identifier: curl
|
|
.\" *
|
|
.\" **************************************************************************
|
|
.TH curl_mime_init 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual"
|
|
.SH NAME
|
|
curl_mime_init - create a mime handle
|
|
.SH SYNOPSIS
|
|
.nf
|
|
#include <curl/curl.h>
|
|
|
|
curl_mime *curl_mime_init(CURL *easy_handle);
|
|
.fi
|
|
.SH DESCRIPTION
|
|
\fIcurl_mime_init(3)\fP creates a handle to a new empty mime structure,
|
|
This mime structure can be subsequently filled using the mime API, then
|
|
attached to some easy handle using option \fICURLOPT_MIMEPOST(3)\fP within
|
|
a \fIcurl_easy_setopt(3)\fP call or added as a multipart in another mime
|
|
handle's part using \fIcurl_mime_subparts(3)\fP.
|
|
|
|
\fIeasy_handle\fP is used for part separator randomization and error
|
|
reporting. It does not need to be the final target handle.
|
|
|
|
Using a mime handle is the recommended way to post an HTTP form, format and
|
|
send a multi-part email with SMTP or upload such an email to an IMAP server.
|
|
.SH EXAMPLE
|
|
.nf
|
|
CURL *easy = curl_easy_init();
|
|
curl_mime *mime;
|
|
curl_mimepart *part;
|
|
|
|
/* Build an HTTP form with a single field named "data", */
|
|
mime = curl_mime_init(easy);
|
|
part = curl_mime_addpart(mime);
|
|
curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED);
|
|
curl_mime_name(part, "data");
|
|
|
|
/* Post and send it. */
|
|
curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime);
|
|
curl_easy_setopt(easy, CURLOPT_URL, "https://example.com");
|
|
curl_easy_perform(easy);
|
|
|
|
/* Clean-up. */
|
|
curl_easy_cleanup(easy);
|
|
curl_mime_free(mime);
|
|
.SH AVAILABILITY
|
|
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
|
|
.SH RETURN VALUE
|
|
A mime struct handle, or NULL upon failure.
|
|
.SH "SEE ALSO"
|
|
.BR curl_mime_addpart "(3),"
|
|
.BR curl_mime_subparts "(3),"
|
|
.BR curl_mime_free "(3),"
|
|
.BR CURLOPT_MIMEPOST "(3)"
|