Pila de basura, seguro tiene problemas
[VSoRC/.git] / node_modules / content-disposition / README.md
1 # content-disposition
2
3 [![NPM Version][npm-image]][npm-url]
4 [![NPM Downloads][downloads-image]][downloads-url]
5 [![Node.js Version][node-version-image]][node-version-url]
6 [![Build Status][travis-image]][travis-url]
7 [![Test Coverage][coveralls-image]][coveralls-url]
8
9 Create and parse HTTP `Content-Disposition` header
10
11 ## Installation
12
13 ```sh
14 $ npm install content-disposition
15 ```
16
17 ## API
18
19 <!-- eslint-disable no-unused-vars -->
20
21 ```js
22 var contentDisposition = require('content-disposition')
23 ```
24
25 ### contentDisposition(filename, options)
26
27 Create an attachment `Content-Disposition` header value using the given file name,
28 if supplied. The `filename` is optional and if no file name is desired, but you
29 want to specify `options`, set `filename` to `undefined`.
30
31 <!-- eslint-disable no-undef -->
32
33 ```js
34 res.setHeader('Content-Disposition', contentDisposition('∫ maths.pdf'))
35 ```
36
37 **note** HTTP headers are of the ISO-8859-1 character set. If you are writing this
38 header through a means different from `setHeader` in Node.js, you'll want to specify
39 the `'binary'` encoding in Node.js.
40
41 #### Options
42
43 `contentDisposition` accepts these properties in the options object.
44
45 ##### fallback
46
47 If the `filename` option is outside ISO-8859-1, then the file name is actually
48 stored in a supplemental field for clients that support Unicode file names and
49 a ISO-8859-1 version of the file name is automatically generated.
50
51 This specifies the ISO-8859-1 file name to override the automatic generation or
52 disables the generation all together, defaults to `true`.
53
54   - A string will specify the ISO-8859-1 file name to use in place of automatic
55     generation.
56   - `false` will disable including a ISO-8859-1 file name and only include the
57     Unicode version (unless the file name is already ISO-8859-1).
58   - `true` will enable automatic generation if the file name is outside ISO-8859-1.
59
60 If the `filename` option is ISO-8859-1 and this option is specified and has a
61 different value, then the `filename` option is encoded in the extended field
62 and this set as the fallback field, even though they are both ISO-8859-1.
63
64 ##### type
65
66 Specifies the disposition type, defaults to `"attachment"`. This can also be
67 `"inline"`, or any other value (all values except inline are treated like
68 `attachment`, but can convey additional information if both parties agree to
69 it). The type is normalized to lower-case.
70
71 ### contentDisposition.parse(string)
72
73 <!-- eslint-disable no-undef, no-unused-vars -->
74
75 ```js
76 var disposition = contentDisposition.parse('attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt')
77 ```
78
79 Parse a `Content-Disposition` header string. This automatically handles extended
80 ("Unicode") parameters by decoding them and providing them under the standard
81 parameter name. This will return an object with the following properties (examples
82 are shown for the string `'attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt'`):
83
84  - `type`: The disposition type (always lower case). Example: `'attachment'`
85
86  - `parameters`: An object of the parameters in the disposition (name of parameter
87    always lower case and extended versions replace non-extended versions). Example:
88    `{filename: "€ rates.txt"}`
89
90 ## Examples
91
92 ### Send a file for download
93
94 ```js
95 var contentDisposition = require('content-disposition')
96 var destroy = require('destroy')
97 var fs = require('fs')
98 var http = require('http')
99 var onFinished = require('on-finished')
100
101 var filePath = '/path/to/public/plans.pdf'
102
103 http.createServer(function onRequest (req, res) {
104   // set headers
105   res.setHeader('Content-Type', 'application/pdf')
106   res.setHeader('Content-Disposition', contentDisposition(filePath))
107
108   // send file
109   var stream = fs.createReadStream(filePath)
110   stream.pipe(res)
111   onFinished(res, function () {
112     destroy(stream)
113   })
114 })
115 ```
116
117 ## Testing
118
119 ```sh
120 $ npm test
121 ```
122
123 ## References
124
125 - [RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1][rfc-2616]
126 - [RFC 5987: Character Set and Language Encoding for Hypertext Transfer Protocol (HTTP) Header Field Parameters][rfc-5987]
127 - [RFC 6266: Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP)][rfc-6266]
128 - [Test Cases for HTTP Content-Disposition header field (RFC 6266) and the Encodings defined in RFCs 2047, 2231 and 5987][tc-2231]
129
130 [rfc-2616]: https://tools.ietf.org/html/rfc2616
131 [rfc-5987]: https://tools.ietf.org/html/rfc5987
132 [rfc-6266]: https://tools.ietf.org/html/rfc6266
133 [tc-2231]: http://greenbytes.de/tech/tc2231/
134
135 ## License
136
137 [MIT](LICENSE)
138
139 [npm-image]: https://img.shields.io/npm/v/content-disposition.svg
140 [npm-url]: https://npmjs.org/package/content-disposition
141 [node-version-image]: https://img.shields.io/node/v/content-disposition.svg
142 [node-version-url]: https://nodejs.org/en/download
143 [travis-image]: https://img.shields.io/travis/jshttp/content-disposition.svg
144 [travis-url]: https://travis-ci.org/jshttp/content-disposition
145 [coveralls-image]: https://img.shields.io/coveralls/jshttp/content-disposition.svg
146 [coveralls-url]: https://coveralls.io/r/jshttp/content-disposition?branch=master
147 [downloads-image]: https://img.shields.io/npm/dm/content-disposition.svg
148 [downloads-url]: https://npmjs.org/package/content-disposition