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>