Skip to content

Commit

Permalink
Documentation for Multipart parser
Browse files Browse the repository at this point in the history 
Also added multipart.parse as a convenience function
  • Loading branch information
@felixge @ry
felixge authored and ry committed Oct 3, 2009
1 parent 602f9db commit eeaa267
Show file tree
Hide file tree
Showing 5 changed files with 444 additions and 6 deletions.
112 changes: 111 additions & 1 deletion doc/api.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1516,6 +1516,116 @@ <h4 id="_tt_http_clientresponse_tt"><tt>http.ClientResponse</tt></h4>
</p>
</dd>
</dl></div>
<h3 id="_multipart_parsing">Multipart Parsing</h3><div style="clear:left"></div>
<div class="paragraph"><p>A library to parse HTTP requests with <tt>multipart/form-data</tt> is included with
Node. To use it, <tt>require("/multipart.js")</tt>.</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
<tt>multipart.parse(options)</tt>
</dt>
<dd>
<div class="ulist"><ul>
<li>
<p>
on success: Returns an object where each key holds the value of one part of
the stream. <tt>options</tt> can either be an instance of
<tt>http.ServerRequest</tt> or an object containing a <em>boundary</em> and a
<em>data</em> key.
</p>
</li>
<li>
<p>
on error: no parameters.
</p>
</li>
</ul></div>
</dd>
</dl></div>
<h4 id="_tt_multipart_stream_tt"><tt>multipart.Stream</tt></h4>
<div class="paragraph"><p>Here is an example for parsing a <tt>multipart/form-data</tt> request:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>var multipart = require('/multipart.js');
var stream = new multipart.Stream(options);
var parts = {};

stream.addListener('part', function (part) {
var name = part.headers['Content-Disposition'].name;
var buffer = '';

part.addListener('body', function(chunk) {
buffer = buffer + chunk;
});

part.addListener('complete', function() {
parts[name] = buffer;
});
});

stream.addListener('complete', function() {
// The parts object now contains all parts and data
});</tt></pre>
</div></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="7%" />
<col width="15%" />
<col width="76%" />
<thead>
<tr>
<th align="left" valign="top">Event </th>
<th align="left" valign="top"> Parameters </th>
<th align="left" valign="top"> Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><tt>"part"</tt></p></td>
<td align="left" valign="top"><p class="table"><tt>part</tt></p></td>
<td align="left" valign="top"><p class="table">Emitted when a new part is found in the stream.
<tt>part</tt> is an instance of <tt>multipart.Part</tt>.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><tt>"complete"</tt></p></td>
<td align="left" valign="top"><p class="table"></p></td>
<td align="left" valign="top"><p class="table">Emitted when the end of the stream is reached.</p></td>
</tr>
</tbody>
</table>
</div>
<h4 id="_tt_multipart_part_tt"><tt>multipart.Part</tt></h4>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="7%" />
<col width="15%" />
<col width="76%" />
<thead>
<tr>
<th align="left" valign="top">Event </th>
<th align="left" valign="top"> Parameters </th>
<th align="left" valign="top"> Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><tt>"body"</tt></p></td>
<td align="left" valign="top"><p class="table"><tt>chunk</tt></p></td>
<td align="left" valign="top"><p class="table">Emitted when a chunk of body is read.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><tt>"complete"</tt></p></td>
<td align="left" valign="top"><p class="table"></p></td>
<td align="left" valign="top"><p class="table">Emitted when the end of the part is reached.</p></td>
</tr>
</tbody>
</table>
</div>
<h3 id="_tcp">TCP</h3><div style="clear:left"></div>
<div class="paragraph"><p>To use the TCP server and client one must <tt>require("/tcp.js")</tt> or
<tt>include("/tcp.js")</tt>.</p></div>
Expand Down Expand Up @@ -2029,7 +2139,7 @@ <h2 id="_extension_api">Extension API</h2>
<div id="footer">
<div id="footer-text">
Version 0.1.13<br />
Last updated 2009-09-30 23:15:59 CEST
Last updated 2009-10-03 18:02:36 CEST
</div>
</div>
</body>
Expand Down
58 changes: 56 additions & 2 deletions doc/api.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -565,8 +565,6 @@ Objects returned from +node.fs.stat()+ are of this type.

+stats.isSocket()+:: ...



=== HTTP

To use the HTTP server and client one must +require("/http.js")+ or
Expand Down Expand Up @@ -942,6 +940,62 @@ After emitted no other events will be emitted on the response.
+response.client+ ::
A reference to the +http.Client+ that this response belongs to.

=== Multipart Parsing

A library to parse HTTP requests with +multipart/form-data+ is included with
Node. To use it, +require("/multipart.js")+.

+multipart.parse(options)+ ::
- on success: Returns an object where each key holds the value of one part of
the stream. +options+ can either be an instance of
+http.ServerRequest+ or an object containing a 'boundary' and a
'data' key.
- on error: no parameters.

==== +multipart.Stream+

Here is an example for parsing a +multipart/form-data+ request:

----------------------------------------
var multipart = require('/multipart.js');
var stream = new multipart.Stream(options);
var parts = {};
stream.addListener('part', function (part) {
var name = part.headers['Content-Disposition'].name;
var buffer = '';
part.addListener('body', function(chunk) {
buffer = buffer + chunk;
});
part.addListener('complete', function() {
parts[name] = buffer;
});
});
stream.addListener('complete', function() {
// The parts object now contains all parts and data
});
----------------------------------------


[cols="1,2,10",options="header"]
|=========================================================
|Event | Parameters | Notes
|+"part"+ | +part+ | Emitted when a new part is found in the stream.
+part+ is an instance of +multipart.Part+.
|+"complete"+ | | Emitted when the end of the stream is reached.
|=========================================================

==== +multipart.Part+

[cols="1,2,10",options="header"]
|=========================================================
|Event | Parameters | Notes
|+"body"+ | +chunk+ | Emitted when a chunk of body is read.
|+"complete"+ | | Emitted when the end of the part is reached.
|=========================================================


=== TCP
Expand Down
115 changes: 115 additions & 0 deletions doc/api.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1609,6 +1609,121 @@ After emitted no other events will be emitted on the response.</simpara></entry>
</variablelist>
</refsect3>
</refsect2>
<refsect2 id="_multipart_parsing">
<title>Multipart Parsing</title>
<simpara>A library to parse HTTP requests with <literal>multipart/form-data</literal> is included with
Node. To use it, <literal>require("/multipart.js")</literal>.</simpara>
<variablelist>
<varlistentry>
<term>
<literal>multipart.parse(options)</literal>
</term>
<listitem>
<itemizedlist>
<listitem>
<simpara>
on success: Returns an object where each key holds the value of one part of
the stream. <literal>options</literal> can either be an instance of
<literal>http.ServerRequest</literal> or an object containing a <emphasis>boundary</emphasis> and a
<emphasis>data</emphasis> key.
</simpara>
</listitem>
<listitem>
<simpara>
on error: no parameters.
</simpara>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
<refsect3 id="_literal_multipart_stream_literal">
<title><literal>multipart.Stream</literal></title>
<simpara>Here is an example for parsing a <literal>multipart/form-data</literal> request:</simpara>
<screen>var multipart = require('/multipart.js');
var stream = new multipart.Stream(options);
var parts = {};

stream.addListener('part', function (part) {
var name = part.headers['Content-Disposition'].name;
var buffer = '';

part.addListener('body', function(chunk) {
buffer = buffer + chunk;
});

part.addListener('complete', function() {
parts[name] = buffer;
});
});

stream.addListener('complete', function() {
// The parts object now contains all parts and data
});</screen>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="3">
<colspec colname="col_1" colwidth="7*"/>
<colspec colname="col_2" colwidth="15*"/>
<colspec colname="col_3" colwidth="76*"/>
<thead>
<row>
<entry align="left" valign="top">Event </entry>
<entry align="left" valign="top"> Parameters </entry>
<entry align="left" valign="top"> Notes</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara><literal>"part"</literal></simpara></entry>
<entry align="left" valign="top"><simpara><literal>part</literal></simpara></entry>
<entry align="left" valign="top"><simpara>Emitted when a new part is found in the stream.
<literal>part</literal> is an instance of <literal>multipart.Part</literal>.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara><literal>"complete"</literal></simpara></entry>
<entry align="left" valign="top"><simpara></simpara></entry>
<entry align="left" valign="top"><simpara>Emitted when the end of the stream is reached.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect3>
<refsect3 id="_literal_multipart_part_literal">
<title><literal>multipart.Part</literal></title>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="3">
<colspec colname="col_1" colwidth="7*"/>
<colspec colname="col_2" colwidth="15*"/>
<colspec colname="col_3" colwidth="76*"/>
<thead>
<row>
<entry align="left" valign="top">Event </entry>
<entry align="left" valign="top"> Parameters </entry>
<entry align="left" valign="top"> Notes</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara><literal>"body"</literal></simpara></entry>
<entry align="left" valign="top"><simpara><literal>chunk</literal></simpara></entry>
<entry align="left" valign="top"><simpara>Emitted when a chunk of body is read.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara><literal>"complete"</literal></simpara></entry>
<entry align="left" valign="top"><simpara></simpara></entry>
<entry align="left" valign="top"><simpara>Emitted when the end of the part is reached.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect3>
</refsect2>
<refsect2 id="_tcp">
<title>TCP</title>
<simpara>To use the TCP server and client one must <literal>require("/tcp.js")</literal> or
Expand Down
Loading

0 comments on commit eeaa267

Please sign in to comment.