form:AddFile(name, path[, type, filename, headers])
form:AddFile()
is used to append a file upload section when building a multipart/formdata HTTP POST
(sometimes referred to as RFC 2388-style posts). Once you've added all the sections you want included,
pass the form handle as parameter to #CURLOPT_HTTPPOST
. See easy:SetOpt_HTTPPost for details.
You must call form:Free() after the form post has been done to free the resources.
Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header
with #CURLOPT_HTTPHEADER
as usual.
First, there are some basics you need to understand about multipart/formdata posts. Each part consists of
at least a NAME
and a CONTENTS
part. If the part is made for file upload, there are also a stored
CONTENT-TYPE
and a FILENAME
. Below, we'll discuss what options you use to get these properties
in the parts you want to add to your post.
The name
argument must be a string which provides the name of this part. The name is not allowed to contain
zero-valued bytes.
The path
argument must be get to the path of a filename to be uploaded. Libcurl sets the filename field
to the basename of the provided filename, it reads the contents of the file and passes them as data and sets
the content-type if the given file match one of the internally known file extensions. The given upload file has
to exist in its full in the file system already when the upload starts, as libcurl needs to read the correct file size beforehand.
The specified file needs to kept around until the associated transfer is done.
The optional argument type
can be used to get the content-type for the part. The optional filename
argument can
be used to use a different file name than the one derived from path
for the upload. The optional argument headers
can be used to specify extra headers for the form POST section. This takes a table containing a list and appends
the list of headers to those libcurl automatically generates.