Merge pull request #656 from nlhintz/pull-request
[project/luci.git] / documentation / api / modules / luci.http.protocol.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html>
4 <head>
5     <title>Reference</title>
6     <link rel="stylesheet" href="../luadoc.css" type="text/css" />
7         <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/-->
8 </head>
9
10 <body>
11 <div id="container">
12
13 <div id="product">
14         <div id="product_logo"></div>
15         <div id="product_name"><big><b></b></big></div>
16         <div id="product_description"></div>
17 </div> <!-- id="product" -->
18
19 <div id="main">
20
21 <div id="navigation">
22
23
24 <h1>LuaDoc</h1>
25 <ul>
26         
27         <li><a href="../index.html">Index</a></li>
28         
29 </ul>
30
31
32 <!-- Module list -->
33
34 <h1>Modules</h1>
35 <ul>
36
37         <li>
38                 <a href="../modules/luci.dispatcher.html">luci.dispatcher</a>
39         </li>
40
41         <li>
42                 <a href="../modules/luci.http.html">luci.http</a>
43         </li>
44
45         <li><strong>luci.http.protocol</strong></li>
46         
47         <li>
48                 <a href="../modules/luci.http.protocol.conditionals.html">luci.http.protocol.conditionals</a>
49         </li>
50
51         <li>
52                 <a href="../modules/luci.http.protocol.date.html">luci.http.protocol.date</a>
53         </li>
54
55         <li>
56                 <a href="../modules/luci.http.protocol.mime.html">luci.http.protocol.mime</a>
57         </li>
58
59         <li>
60                 <a href="../modules/luci.i18n.html">luci.i18n</a>
61         </li>
62
63         <li>
64                 <a href="../modules/luci.ip.html">luci.ip</a>
65         </li>
66
67         <li>
68                 <a href="../modules/luci.ip.cidr.html">luci.ip.cidr</a>
69         </li>
70
71         <li>
72                 <a href="../modules/luci.json.html">luci.json</a>
73         </li>
74
75         <li>
76                 <a href="../modules/luci.jsonc.html">luci.jsonc</a>
77         </li>
78
79         <li>
80                 <a href="../modules/luci.jsonc.parser.html">luci.jsonc.parser</a>
81         </li>
82
83         <li>
84                 <a href="../modules/luci.model.ipkg.html">luci.model.ipkg</a>
85         </li>
86
87         <li>
88                 <a href="../modules/luci.model.uci.html">luci.model.uci</a>
89         </li>
90
91         <li>
92                 <a href="../modules/luci.rpcc.html">luci.rpcc</a>
93         </li>
94
95         <li>
96                 <a href="../modules/luci.rpcc.ruci.html">luci.rpcc.ruci</a>
97         </li>
98
99         <li>
100                 <a href="../modules/luci.sys.html">luci.sys</a>
101         </li>
102
103         <li>
104                 <a href="../modules/luci.sys.init.html">luci.sys.init</a>
105         </li>
106
107         <li>
108                 <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
109         </li>
110
111         <li>
112                 <a href="../modules/luci.sys.net.html">luci.sys.net</a>
113         </li>
114
115         <li>
116                 <a href="../modules/luci.sys.process.html">luci.sys.process</a>
117         </li>
118
119         <li>
120                 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
121         </li>
122
123         <li>
124                 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
125         </li>
126
127         <li>
128                 <a href="../modules/luci.util.html">luci.util</a>
129         </li>
130
131         <li>
132                 <a href="../modules/nixio.html">nixio</a>
133         </li>
134
135         <li>
136                 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
137         </li>
138
139         <li>
140                 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
141         </li>
142
143         <li>
144                 <a href="../modules/nixio.File.html">nixio.File</a>
145         </li>
146
147         <li>
148                 <a href="../modules/nixio.README.html">nixio.README</a>
149         </li>
150
151         <li>
152                 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
153         </li>
154
155         <li>
156                 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
157         </li>
158
159         <li>
160                 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
161         </li>
162
163         <li>
164                 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
165         </li>
166
167         <li>
168                 <a href="../modules/nixio.bin.html">nixio.bin</a>
169         </li>
170
171         <li>
172                 <a href="../modules/nixio.bit.html">nixio.bit</a>
173         </li>
174
175         <li>
176                 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
177         </li>
178
179         <li>
180                 <a href="../modules/nixio.fs.html">nixio.fs</a>
181         </li>
182
183 </ul>
184
185
186
187 <!-- File list -->
188
189
190
191
192
193
194
195 </div><!-- id="navigation" -->
196
197 <div id="content">
198
199 <h1>Class <code>luci.http.protocol</code></h1>
200
201 <p></p>
202
203
204
205
206
207
208
209 <h2>Functions</h2>
210 <table class="function_list">
211
212         <tr>
213         <td class="name" nowrap><a href="#header_source">header_source</a>&nbsp;(sock)</td>
214         <td class="summary">
215  
216 Creates a ltn12 source from the given socket.</td>
217         </tr>
218
219         <tr>
220         <td class="name" nowrap><a href="#mimedecode_message_body">mimedecode_message_body</a>&nbsp;(src, msg, filecb)</td>
221         <td class="summary">
222  
223 Decode a mime encoded http message body with multipart/form-data 
224  
225 Content-Type.</td>
226         </tr>
227
228         <tr>
229         <td class="name" nowrap><a href="#parse_message_body">parse_message_body</a>&nbsp;(src, msg, filecb)</td>
230         <td class="summary">
231  
232 Try to extract and decode a http message body from the given ltn12 source.</td>
233         </tr>
234
235         <tr>
236         <td class="name" nowrap><a href="#parse_message_header">parse_message_header</a>&nbsp;(src)</td>
237         <td class="summary">
238  
239 Try to extract an http message header including information like protocol 
240  
241 version, message headers and resulting CGI environment variables from the 
242 given ltn12 source.</td>
243         </tr>
244
245         <tr>
246         <td class="name" nowrap><a href="#urldecode">urldecode</a>&nbsp;(str, no_plus)</td>
247         <td class="summary">
248  
249 Decode an urlencoded string - optionally without decoding 
250  
251 the "+" sign to " " - and return the decoded string.</td>
252         </tr>
253
254         <tr>
255         <td class="name" nowrap><a href="#urldecode_message_body">urldecode_message_body</a>&nbsp;(src, msg)</td>
256         <td class="summary">
257  
258 Decode an urlencoded http message body with application/x-www-urlencoded 
259  
260 Content-Type.</td>
261         </tr>
262
263         <tr>
264         <td class="name" nowrap><a href="#urldecode_params">urldecode_params</a>&nbsp;(url, tbl)</td>
265         <td class="summary">
266  
267 Extract and split urlencoded data pairs, separated bei either "&" or ";" 
268  
269 from given url or string.</td>
270         </tr>
271
272         <tr>
273         <td class="name" nowrap><a href="#urlencode">urlencode</a>&nbsp;(str)</td>
274         <td class="summary">
275  
276 Encode given string to x-www-urlencoded format.</td>
277         </tr>
278
279         <tr>
280         <td class="name" nowrap><a href="#urlencode_params">urlencode_params</a>&nbsp;(tbl)</td>
281         <td class="summary">
282  
283 Encode each key-value-pair in given table to x-www-urlencoded format, 
284  
285 separated by "&".</td>
286         </tr>
287
288 </table>
289
290
291
292
293
294
295 <br/>
296 <br/>
297
298
299 <h2><a name="functions"></a>Functions</h2>
300 <dl class="function">
301
302
303
304 <dt><a name="header_source"></a><strong>header_source</strong>&nbsp;(sock)</dt>
305 <dd>
306
307  
308 Creates a ltn12 source from the given socket. The source will return it's 
309  
310 data line by line with the trailing \r\n stripped of.
311
312
313 <h3>Parameters</h3>
314 <ul>
315         
316         <li>
317           sock: Readable network socket
318         </li>
319         
320 </ul>
321
322
323
324
325
326
327 <h3>Return value:</h3>
328 Ltn12 source function
329
330
331
332 </dd>
333
334
335
336
337 <dt><a name="mimedecode_message_body"></a><strong>mimedecode_message_body</strong>&nbsp;(src, msg, filecb)</dt>
338 <dd>
339
340  
341 Decode a mime encoded http message body with multipart/form-data 
342  
343 Content-Type. Stores all extracted data associated with its parameter name 
344 in the params table within the given message object. Multiple parameter
345 values are stored as tables, ordinary ones as strings. 
346 If an optional file callback function is given then it is feeded with the 
347 file contents chunk by chunk and only the extracted file name is stored 
348 within the params table. The callback function will be called subsequently 
349 with three arguments: 
350  o Table containing decoded (name, file) and raw (headers) mime header data 
351  o String value containing a chunk of the file data 
352  o Boolean which indicates wheather the current chunk is the last one (eof)
353
354
355 <h3>Parameters</h3>
356 <ul>
357         
358         <li>
359           src: Ltn12 source function
360         </li>
361         
362         <li>
363           msg: HTTP message object
364         </li>
365         
366         <li>
367           filecb: File callback function (optional)
368         </li>
369         
370 </ul>
371
372
373
374
375
376
377 <h3>Return values:</h3>
378 <ol>
379         
380         <li>Value indicating successful operation (not nil means "ok")
381         
382         <li>String containing the error if unsuccessful
383         
384 </ol>
385
386
387
388 <h3>See also:</h3>
389 <ul>
390         
391         <li><a href="#parse_message_header">
392                 parse_message_header
393         </a>
394         
395 </ul>
396
397 </dd>
398
399
400
401
402 <dt><a name="parse_message_body"></a><strong>parse_message_body</strong>&nbsp;(src, msg, filecb)</dt>
403 <dd>
404
405  
406 Try to extract and decode a http message body from the given ltn12 source. 
407  
408 This function will examine the Content-Type within the given message object 
409 to select the appropriate content decoder. 
410 Currently the application/x-www-urlencoded and application/form-data 
411 mime types are supported. If the encountered content encoding can't be 
412 handled then the whole message body will be stored unaltered as "content" 
413 property within the given message object.
414
415
416 <h3>Parameters</h3>
417 <ul>
418         
419         <li>
420           src: Ltn12 source function
421         </li>
422         
423         <li>
424           msg: HTTP message object
425         </li>
426         
427         <li>
428           filecb: File data callback (optional, see mimedecode_message_body())
429         </li>
430         
431 </ul>
432
433
434
435
436
437
438 <h3>Return values:</h3>
439 <ol>
440         
441         <li>Value indicating successful operation (not nil means "ok")
442         
443         <li>String containing the error if unsuccessful
444         
445 </ol>
446
447
448
449 <h3>See also:</h3>
450 <ul>
451         
452         <li><a href="#parse_message_header">
453                 parse_message_header
454         </a>
455         
456 </ul>
457
458 </dd>
459
460
461
462
463 <dt><a name="parse_message_header"></a><strong>parse_message_header</strong>&nbsp;(src)</dt>
464 <dd>
465
466  
467 Try to extract an http message header including information like protocol 
468  
469 version, message headers and resulting CGI environment variables from the 
470 given ltn12 source.
471
472
473 <h3>Parameters</h3>
474 <ul>
475         
476         <li>
477           src: Ltn12 source function
478         </li>
479         
480 </ul>
481
482
483
484
485
486
487 <h3>Return value:</h3>
488 HTTP message object
489
490
491
492 <h3>See also:</h3>
493 <ul>
494         
495         <li><a href="#parse_message_body">
496                 parse_message_body
497         </a>
498         
499 </ul>
500
501 </dd>
502
503
504
505
506 <dt><a name="urldecode"></a><strong>urldecode</strong>&nbsp;(str, no_plus)</dt>
507 <dd>
508
509  
510 Decode an urlencoded string - optionally without decoding 
511  
512 the "+" sign to " " - and return the decoded string.
513
514
515 <h3>Parameters</h3>
516 <ul>
517         
518         <li>
519           str: Input string in x-www-urlencoded format
520         </li>
521         
522         <li>
523           no_plus: Don't decode "+" signs to spaces
524         </li>
525         
526 </ul>
527
528
529
530
531
532
533 <h3>Return value:</h3>
534 The decoded string
535
536
537
538 <h3>See also:</h3>
539 <ul>
540         
541         <li><a href="#urlencode">
542                 urlencode
543         </a>
544         
545 </ul>
546
547 </dd>
548
549
550
551
552 <dt><a name="urldecode_message_body"></a><strong>urldecode_message_body</strong>&nbsp;(src, msg)</dt>
553 <dd>
554
555  
556 Decode an urlencoded http message body with application/x-www-urlencoded 
557  
558 Content-Type. Stores all extracted data associated with its parameter name 
559 in the params table within the given message object. Multiple parameter
560 values are stored as tables, ordinary ones as strings.
561
562
563 <h3>Parameters</h3>
564 <ul>
565         
566         <li>
567           src: Ltn12 source function
568         </li>
569         
570         <li>
571           msg: HTTP message object
572         </li>
573         
574 </ul>
575
576
577
578
579
580
581 <h3>Return values:</h3>
582 <ol>
583         
584         <li>Value indicating successful operation (not nil means "ok")
585         
586         <li>String containing the error if unsuccessful
587         
588 </ol>
589
590
591
592 <h3>See also:</h3>
593 <ul>
594         
595         <li><a href="#parse_message_header">
596                 parse_message_header
597         </a>
598         
599 </ul>
600
601 </dd>
602
603
604
605
606 <dt><a name="urldecode_params"></a><strong>urldecode_params</strong>&nbsp;(url, tbl)</dt>
607 <dd>
608
609  
610 Extract and split urlencoded data pairs, separated bei either "&" or ";" 
611  
612 from given url or string. Returns a table with urldecoded values. 
613 Simple parameters are stored as string values associated with the parameter 
614 name within the table. Parameters with multiple values are stored as array 
615 containing the corresponding values.
616
617
618 <h3>Parameters</h3>
619 <ul>
620         
621         <li>
622           url: The url or string which contains x-www-urlencoded form data
623         </li>
624         
625         <li>
626           tbl: Use the given table for storing values (optional)
627         </li>
628         
629 </ul>
630
631
632
633
634
635
636 <h3>Return value:</h3>
637 Table containing the urldecoded parameters
638
639
640
641 <h3>See also:</h3>
642 <ul>
643         
644         <li><a href="#urlencode_params">
645                 urlencode_params
646         </a>
647         
648 </ul>
649
650 </dd>
651
652
653
654
655 <dt><a name="urlencode"></a><strong>urlencode</strong>&nbsp;(str)</dt>
656 <dd>
657
658  
659 Encode given string to x-www-urlencoded format. 
660
661
662
663 <h3>Parameters</h3>
664 <ul>
665         
666         <li>
667           str: String to encode
668         </li>
669         
670 </ul>
671
672
673
674
675
676
677 <h3>Return value:</h3>
678 String containing the encoded data
679
680
681
682 <h3>See also:</h3>
683 <ul>
684         
685         <li><a href="#urldecode">
686                 urldecode
687         </a>
688         
689 </ul>
690
691 </dd>
692
693
694
695
696 <dt><a name="urlencode_params"></a><strong>urlencode_params</strong>&nbsp;(tbl)</dt>
697 <dd>
698
699  
700 Encode each key-value-pair in given table to x-www-urlencoded format, 
701  
702 separated by "&". Tables are encoded as parameters with multiple values by 
703 repeating the parameter name with each value.
704
705
706 <h3>Parameters</h3>
707 <ul>
708         
709         <li>
710           tbl: Table with the values
711         </li>
712         
713 </ul>
714
715
716
717
718
719
720 <h3>Return value:</h3>
721 String containing encoded values
722
723
724
725 <h3>See also:</h3>
726 <ul>
727         
728         <li><a href="#urldecode_params">
729                 urldecode_params
730         </a>
731         
732 </ul>
733
734 </dd>
735
736
737 </dl>
738
739
740
741
742
743 </div> <!-- id="content" -->
744
745 </div> <!-- id="main" -->
746
747 <div id="about">
748         <p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
749 </div> <!-- id="about" -->
750
751 </div> <!-- id="container" -->
752 </body>
753 </html>