<doc>
  <legacy_id>1573</legacy_id>
  <name>libURLMultipartFormData</name>
  <type>function</type>
  <syntax>
    <example>libURLMultipartFormData(<i>form data, key_1, value_1, ..., key_n, value_n)</i></example>
    <example>libURLMultipartFormData(<i>form data, array)</i></example>
    <example>libURLMultipartFormData(<i>form data</i>)</example>
  </syntax>
  <library>Internet library</library>
  <objects>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
  </classification>
  <references>
    <command tag="post">post Command</command>
    <command tag="libURLSetExpect100">libURLSetExpect100 Command</command>
    <function tag="libURLMultipartFormAddPart">libURLMultipartFormAddPart Function</function>
    <function tag="libURLFormData">libURLFormData Function</function>
  </references>
  <history>
    <introduced version="2.5">Added.</introduced>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
    <web/>
  </classes>
  <security>
    <network/>
  </security>
  <summary><b>libURLMultipartFormData</b> formats data in the way described in rfc 1867.</summary>
  <examples>
    <example>put empty into tForm</p><p>put "http://www.someserver.com/cgi-bin/form.cgi" into tUrl</p><p>put "dave" into tName put "hello" into tMessage</p><p>put "&amp;lt;file&amp;gt;" &amp; "C:/myfile.txt" into tFile</p><p>if libURLMultipartFormData \</p><p> (tForm, "name", tName, "message", tMessage, "file", tFile) \</p><p> is not empty then</p><p> answer it ##error</p><p>else</p><p> set the httpHeaders to line 1 of tForm</p><p> post line 2 to -1 of tForm to url tUrl</p><p> ## check the result, etc., here</p><p> set the httpHeaders to empty</p><p>end if</example>
  </examples>
  <description>
    <p>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). </p><p/><p><b>Note:</b> 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;". </p><p/><p><b>Note:</b> 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. </p><p/><p>The standard way to call the function is with pairs of name/value parameters. </p><p/><p>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): </p><p/><p>put empty into tForm</p><p>put "dave" into tName</p><p>put "hello" into tMessage</p><p>put "&lt;file&gt;" &amp; "C:/myfile.txt" into tFile</p><p>put "name," &amp; tName into tArray[1]</p><p>put "message," &amp; tMessage into tArray[2]</p><p>put "file," &amp; tFile into tArray[3]</p><p>if libURLMultipartFormData(tForm, tArray) is not empty then</p><p>    answer it ##error</p><p>else</p><p>    set the httpHeaders to line 1 of tForm</p><p>    post line 2 to -1 of tForm to url </p><p>    ## check the result, etc., here</p><p>    set the httpHeaders to empty</p><p>end if</p><p/><p> 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 <function tag="libURLMultipartFormAddPart">libURLMultipartFormAddPart</function>. </p><p/><p><img src="202653"/> <b>Important!</b> The <b>libURLMultipartFormData</b> <glossary tag="function">function</glossary> is part of the <glossary tag="Internet library">Internet library</glossary>. To ensure that the <glossary tag="keyword">keyword</glossary> works in a <glossary tag="standalone application">standalone application</glossary>, you must include this <glossary tag="LiveCode custom library">custom library</glossary> when you create your <glossary tag="standalone application">standalone</glossary>. In the Inclusions section of the <glossary tag="Standalone Application Settings">Standalone Application Settings</glossary> window, make sure "Internet Library" is selected in the list of script libraries.</p><p/><p><b>Note:</b> When included in a <glossary tag="standalone application">standalone application</glossary>, the <glossary tag="Internet library">Internet library</glossary> is implemented as a hidden <command tag="group">group</command> and made available when the <command tag="group">group</command> receives its first <message tag="openBackground">openBackground</message> message. During the first part of the <glossary tag="application">application's</glossary> startup process, before this <keyword tag="message box">message</keyword> is sent, the <b>http</b> <glossary tag="keyword">keyword</glossary> is not yet available. This may affect attempts to use this <glossary tag="keyword">keyword</glossary> in <message tag="startup">startup</message>, <message tag="preOpenStack">preOpenStack</message>, <message tag="openStack">openStack</message>, or <message tag="preOpenCard">preOpenCard</message> <glossary tag="handler">handlers</glossary> in the <glossary tag="main stack">main stack</glossary>. Once the <glossary tag="application">application</glossary> has finished starting up, the <command tag="start using">library</command> is available and the <b>http</b> <glossary tag="keyword">keyword</glossary> can be used in any <glossary tag="handler">handler</glossary>.</p>
  </description>
</doc>