Name: libURLMultipartFormData

Type: function

Syntax: libURLMultipartFormData(form data, key_1, value_1, ..., key_n, value_n)

Syntax: libURLMultipartFormData(form data, array)

Syntax: libURLMultipartFormData(<form data>)

Summary: <libURLMultipartFormData> formats data in the way described in rfc 1867.

Introduced: 2.5

OS: mac,windows,linux

Platforms: desktop,server,web

Security: network

Example:
put empty into tForm
put "http://www.someserver.com/cgi-bin/form.cgi" into tUrl
put "dave" into tName put "hello" into tMessage
put "&lt;file&gt;" & "C:/myfile.txt" into tFile
if libURLMultipartFormData \
 (tForm, "name", tName, "message", tMessage, "file", tFile) \
 is not empty then
 answer it ##error
else
 set the httpHeaders to line 1 of tForm
 post line 2 to -1 of tForm to url tUrl
 ## check the result, etc., here
 set the httpHeaders to empty
end if

The result: ## check the result, etc., here.

Description:
The function can be called in a number of ways depending on the parameters passed. In all cases, the first parameter must be a variable which will be filled with the form data. The function will return empty if successful, or an error message if it fails (for example, if it couldn't open a file). 

>*Note:* When you need to supply a file as the value of a parameter, you must pass the file name preceeded by the text "&lt;file&gt;". 

>*Note:* In all cases, the first line of the data returned in the form data variable is the Content-Type header that must be included in the httpHeaders of the url request. Lines 2 to the end of the data is the data that must be posted to the url. 

The standard way to call the function is with pairs of name/value parameters. 

You can also pass in an array instead of pairs of parameters. This could be useful if there are many parts to a form. The array must be numerically indexed, and each element should contain the part name and part value, separated by a comma. So (using the above example): 

put empty into tForm
put "dave" into tName
put "hello" into tMessage
put "&lt;file&gt;" & "C:/myfile.txt" into tFile
put "name," & tName into tArray[1]
put "message," & tMessage into tArray[2]
put "file," & tFile into tArray[3]
if libURLMultipartFormData(tForm, tArray) is not empty then
    answer it ##error
else
    set the httpHeaders to line 1 of tForm
    post line 2 to -1 of tForm to url 
    set the httpHeaders to empty
end if

 You can also call the function with no arguments except the form data. This will return an "empty" form. Basically, line 1 is the header, and line 2 is the final boundary mark of the form. It is of no use by itself, but it can be used with <libURLMultipartFormAddPart>. 

>*Important:*  The <libURLMultipartFormData> <function> is part of the <Internet library>. To ensure that the <keyword> works in a <standalone application>, you must include this <Revolution custom library|custom library> when you create your <standalone application|standalone>. In the Inclusions section of the <Standalone Application Settings> window, make sure "Internet Library" is selected in the list of script libraries.

>*Note:* When included in a <standalone application>, the <Internet library> is implemented as a hidden <group> and made available when the <group> receives its first <openBackground> message. During the first part of the <application|application's> startup process, before this <message> is sent, the http <keyword> is not yet available. This may affect attempts to use this <keyword> in <startup>, <preOpenStack>, <openStack>, or <preOpenCard> <handler|handlers> in the <main stack>. Once the <application> has finished starting up, the <library> is available and the http <keyword> can be used in any <handler>.

References: startup (message), openBackground (message), preOpenStack (message), openStack (message), preOpenCard (message), post (command), libURLSetExpect100 (command), libURLMultipartFormAddPart (function), libURLFormData (function), Internet library (library), Revolution custom library (library), library (library), main stack (glossary), handler (glossary), Standalone Application Settings (glossary), message (glossary), group (glossary), standalone application (glossary), keyword (glossary), function (glossary), application (glossary)
