From eeaa267cbe6a3534dd8c21fa950521068a14ea34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20Geisend=C3=B6rfer?= Date: Sat, 3 Oct 2009 16:40:06 +0200 Subject: [PATCH] Documentation for Multipart parser Also added multipart.parse as a convenience function --- doc/api.html | 112 +++++++++++++++++++++++++++++++++++++- doc/api.txt | 58 +++++++++++++++++++- doc/api.xml | 115 +++++++++++++++++++++++++++++++++++++++ doc/node.1 | 137 ++++++++++++++++++++++++++++++++++++++++++++++- lib/multipart.js | 28 +++++++++- 5 files changed, 444 insertions(+), 6 deletions(-) diff --git a/doc/api.html b/doc/api.html index 015889ea8f..4c51750430 100644 --- a/doc/api.html +++ b/doc/api.html @@ -1516,6 +1516,116 @@ After emitted no other events will be emitted on the response.

+

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
+});
+
+
+ ++++ + + + + + + + + + + + + + + + + + + +
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

+
+ ++++ + + + + + + + + + + + + + + + + + + +
Event Parameters Notes

"body"

chunk

Emitted when a chunk of body is read.

"complete"

Emitted when the end of the part is reached.

+

TCP

To use the TCP server and client one must require("/tcp.js") or include("/tcp.js").

@@ -2029,7 +2139,7 @@ init (Handle<Object> target) diff --git a/doc/api.txt b/doc/api.txt index 46c806c79d..098364301b 100644 --- a/doc/api.txt +++ b/doc/api.txt @@ -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 @@ -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 diff --git a/doc/api.xml b/doc/api.xml index 9dc8793695..8a542c3943 100644 --- a/doc/api.xml +++ b/doc/api.xml @@ -1609,6 +1609,121 @@ After emitted no other events will be emitted on the response. + +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. + + + + + + + +<literal>multipart.Stream</literal> +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 +}); + + + + + + + +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. + + + + + + +<literal>multipart.Part</literal> + + + + + + + +Event + Parameters + Notes + + + + +"body" +chunk +Emitted when a chunk of body is read. + + +"complete" + +Emitted when the end of the part is reached. + + + + + + TCP To use the TCP server and client one must require("/tcp.js") or diff --git a/doc/node.1 b/doc/node.1 index 7d2c7a4fd9..656982fdc1 100644 --- a/doc/node.1 +++ b/doc/node.1 @@ -1,11 +1,11 @@ .\" Title: node .\" Author: .\" Generator: DocBook XSL Stylesheets v1.73.2 -.\" Date: 09/30/2009 +.\" Date: 10/03/2009 .\" Manual: .\" Source: .\" -.TH "NODE" "1" "09/30/2009" "" "" +.TH "NODE" "1" "10/03/2009" "" "" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) @@ -1374,6 +1374,139 @@ http\.Client that this response belongs to\. .RE .RE +.SS "Multipart Parsing" +A library to parse HTTP requests with multipart/form\-data is included with Node\. To use it, require("/multipart\.js")\. +.PP +multipart\.parse(options) +.RS 4 +.sp +.RS 4 +\h'-04'\(bu\h'+03'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 +\fIboundary\fR +and a +\fIdata\fR +key\. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'on error: no parameters\. +.RE +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +multipart.Stream +.RS +Here is an example for parsing a multipart/form\-data request: +.sp +.sp +.RS 4 +.nf +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 +}); +.fi +.RE +.TS +allbox tab(:); +ltB ltB ltB. +T{ +Event +T}:T{ +Parameters +T}:T{ +Notes +T} +.T& +lt lt lt +lt lt lt. +T{ +"part" +.sp +T}:T{ +part +.sp +T}:T{ +Emitted when a new part is found in the stream\. part is an instance of multipart\.Part\. +.sp +T} +T{ +"complete" +.sp +T}:T{ +.sp +T}:T{ +Emitted when the end of the stream is reached\. +.sp +T} +.TE +.sp +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +multipart.Part +.RS +.TS +allbox tab(:); +ltB ltB ltB. +T{ +Event +T}:T{ +Parameters +T}:T{ +Notes +T} +.T& +lt lt lt +lt lt lt. +T{ +"body" +.sp +T}:T{ +chunk +.sp +T}:T{ +Emitted when a chunk of body is read\. +.sp +T} +T{ +"complete" +.sp +T}:T{ +.sp +T}:T{ +Emitted when the end of the part is reached\. +.sp +T} +.TE +.sp +.RE .SS "TCP" To use the TCP server and client one must require("/tcp\.js") or include("/tcp\.js")\. .sp diff --git a/lib/multipart.js b/lib/multipart.js index ddcd48a067..5bf8cc1263 100644 --- a/lib/multipart.js +++ b/lib/multipart.js @@ -1,5 +1,30 @@ +exports.parse = function(options) { + var stream = new exports.Stream(options); + var promise = new node.Promise(); + + 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() { + promise.emitSuccess(parts); + }); + + return promise; +}; + exports.Stream = function(options) { - node.EventEmitter.call(this); + node.EventEmitter.call(this); this.init(options); }; @@ -37,6 +62,7 @@ proto.init = function(options) { }); } else { this.boundary = options.boundary; + this.write(options.data || ''); } };