http.md (19027B)
1 # HTTP
2
3 This page contains all available public functions related to understanding and responding to HTTP requests.
4
5 ## Index
6
7 * [http\_response](#http_response)
8 * [http\_response\_header](#http_response_header)
9 * [http\_response\_stream](#http_response_stream)
10 * [http\_response\_fileref](#http_response_fileref)
11 * [http\_response\_close](#http_response_close)
12 * [http\_response\_json](#http_response_json)
13 * [http\_request\_header](#http_request_header)
14 * [http\_file\_lookup](#http_file_lookup)
15 * [http\_file\_read](#http_file_read)
16 * [http\_file\_rewind](#http_file_rewind)
17 * [http\_populate\_post](#http_populate_post)
18 * [http\_populate\_qs](#http_populate_qs)
19 * [http\_populate\_multipart\_form](#http_populate_multipart_form)
20 * [http\_body\_read](#http_body_read)
21 * [http\_state\_run](#http_state_run)
22 * [http\_state\_create](#http_state_create)
23 * [http\_state\_get](#http_state_get)
24 * [http\_state\_cleanup](#http_state_cleanup)
25 * [http\_status\_text](#http_status_text)
26 * [http\_method\_text](#http_method_text)
27 * [http\_argument\_get\_string](#http_argument_get_string)
28 * [http\_argument\_get\_byte](#http_argument_get_byte)
29 * [http\_argument\_get\_int16](#http_argument_get_int16)
30 * [http\_argument\_get\_uint16](#http_argument_get_uint16)
31 * [http\_argument\_get\_int32](#http_argument_get_int32)
32 * [http\_argument\_get\_uint32](#http_argument_get_uint32)
33 * [http\_argument\_get\_int64](#http_argument_get_int64)
34 * [http\_argument\_get\_uint64](#http_argument_get_uint64)
35 * [http\_argument\_get\_float](#http_argument_get_float)
36 * [http\_argument\_get\_double](#http_argument_get_double)
37 * [http\_runlock\_init](#http_runlock_init)
38 * [http\_runlock\_acquire](#http_runlock_acquire)
39 * [http\_runlock\_release](#http_runlock_release)
40
41 ---
42
43 # http\_response {#http_response}
44
45 ### Synopsis
46
47 ```
48 void http_response(struct http_request *req, int status, const void *data, size_t length)
49 ```
50
51 ### Description
52
53 Creates an HTTP response for an HTTP request.
54
55 | Parameter | Description |
56 | --- | --- |
57 | req | The HTTP request to respond to. |
58 | status | The HTTP status code to include in the response. |
59 | data | The data to be sent in the response body. |
60 | length | The length of the data to be sent. |
61
62 ### Returns
63
64 Nothing
65
66 ---
67
68 # http\_response\_header {#http_response_header}
69
70 ### Synopsis
71
72 ```
73 void http_response_header(struct http_request *req, const char *header, const char *value)
74 ```
75
76 ### Description
77
78 Includes HTTP header into response.
79
80 | Parameter | Description |
81 | --- | --- |
82 | req | The HTTP request to respond to. |
83 | header | The HTTP header to include in the response. |
84 | value | The HTTP header value to include in the response. |
85
86 ### Returns
87
88 Nothing
89
90 ---
91
92 # http\_response\_stream {#http_response_stream}
93
94 ### Synopsis
95
96 ```
97 void http_response_stream(struct http_request *req, int status, void *base, size_t length, int (*cb)(struct netbuf *), void *arg)
98 ```
99
100 ### Description
101
102 Creates an HTTP response for an HTTP request much like _http\_response\(\)_.
103
104 However unlike that function this one does not copy the response body data but rather streams from it. It will call the given callback _cb_ when all data has been sent.
105
106 | Parameter | Description |
107 | --- | --- |
108 | req | The HTTP request to respond to. |
109 | status | The HTTP status code to include in the response. |
110 | base | The base pointer of the data to be sent in the response body. |
111 | length | The length of the data to be sent. |
112 | cb | A callback that is called when all data has been sent. |
113 | arg | A user supplied argument that is passed in the callback. |
114
115 ### Returns
116
117 Nothing
118
119 ---
120
121 # http\_response\_fileref {#http_response_fileref}
122
123 ### Synopsis
124
125 ```
126 void http_response_fileref(struct http_request *req, struct kore_fileref *ref)
127 ```
128
129 ### Description
130
131 Creates an HTTP response for an HTTP request much like _http\_response\(\)_.
132
133 This function however takes a kore filereference data structure as its argument
134 and will send the ondisk file it represents to the client.
135
136 | Parameter | Description |
137 | --- | --- |
138 | req | The HTTP request to respond to. |
139 | ref | The kore file reference. |
140
141 ### Returns
142
143 Nothing
144
145 ---
146
147 # http\_response\_close {#http_response_close}
148
149 ### Synopsis
150
151 ```
152 void http_response_close(struct http_request *req, int code, const void *data, size_t length)
153 ```
154
155 ### Description
156
157 Creates an HTTP response for an HTTP request much like _http\_response\(\)_.
158
159 This function however will force the connection to be closed immediately
160 after the response has been sent to the server.
161
162 It will automatically add a "connection" header with "close" as its value.
163
164 | Parameter | Description |
165 | --- | --- |
166 | req | The HTTP request to respond to. |
167 | status | The HTTP status code to include in the response. |
168 | data | The data to be sent in the response body. |
169 | length | The length of the data to be sent. |
170
171 ### Returns
172
173 Nothing
174
175 ---
176
177 # http\_response\_json {#http_response_json}
178
179 ### Synopsis
180
181 ```
182 void http_response_json(struct http_request *req, int code, struct kore_json_item *json)
183 ```
184
185 ### Description
186
187 Creates an HTTP response for an HTTP request much like _http\_response\(\)_.
188
189 This function takes a Kore JSON item that is to be sent as a response.
190
191 It will automatically add a "content-type" header with "application/json"
192 as its value.
193
194 The caller *must* not free the provided JSON item nor *use* it after
195 calling this function as this function will free it.
196
197 | Parameter | Description |
198 | --- | --- |
199 | req | The HTTP request to respond to. |
200 | status | The JSON data to be sent that was previously created.
201 | json | The data to be sent in the response body. |
202
203 ### Returns
204
205 Nothing
206
207 ---
208
209 # http\_request\_header {#http_request_header}
210
211 ### Synopsis
212
213 ```
214 int http_request_header(struct http_request *req, const char *header, const char **out)
215 ```
216
217 ### Description
218
219 Attempts to find the given _header_ in an HTTP request and returns the value of the header in the _out_ parameter. The returned pointer should not be freed.
220
221 | Parameter | Description |
222 | --- | --- |
223 | req | The HTTP request. |
224 | header | The name of the header to find. |
225 | out | Pointer to where the pointer to the result is stored. |
226
227 ### Returns
228
229 KORE\_RESULT\_OK if a result was set in _out_.
230 KORE\_RESULT\_ERROR if the header was not present in the request.
231
232 ---
233
234 # http\_file\_lookup {#http_file_lookup}
235
236 ### Synopsis
237
238 ```
239 struct http_file *http_file_lookup(struct http_request *req, const char *name)
240 ```
241
242 ### Description
243
244 Lookup a file that was uploaded as part of a multipart form submission.
245
246 | Parameter | Description |
247 | --- | --- |
248 | req | The HTTP request. |
249 | name | The name of the form field the file was sent as. |
250
251 ### Returns
252
253 A pointer to an _http\_file_ data structure containing information about the uploaded file.
254
255 Will return NULL if the file could not be found.
256
257 ### Note
258
259 You must call _http\_populate\_multipart\_form\(\)_ before this function will return any result at all.
260
261 ---
262
263 # http\_file\_read {#http_file_read}
264
265 ### Synopsis
266
267 ```
268 ssize_t http_file_read(struct http_file *file, void *buf, size_t length)
269 ```
270
271 ### Description
272
273 Read file data from the given file up to _length_ size.
274
275 | Parameter | Description |
276 | --- | --- |
277 | file | The file from which to read. |
278 | buf | Where the file data is copied into. |
279 | length | The maximum length that can be copied into _buf_. |
280
281 ### Returns
282
283 Returns the number of bytes successfully read from the file, or 0 on end of file, or -1 on error.
284
285 ---
286
287 # http\_file\_rewind {#http_file_rewind}
288
289 ### Synopsis
290
291 ```
292 void http_file_rewind(struct http_file *file)
293 ```
294
295 ### Description
296
297 Sets the offset member of the given _file_ data structure back to 0 for sequential reads.
298
299 | Parameter | Description |
300 | --- | --- |
301 | file | The file to rewind. |
302
303 ### Returns
304
305 Nothing
306
307 ---
308
309 # http\_populate\_post {#http_populate_post}
310
311 ### Synopsis
312
313 ```
314 void http_populate_post(struct http_request *req)
315 ```
316
317 ### Description
318
319 Processes an HTTP POST by taking the HTTP body and parsing it according to _application/x-www-form-urlencoded_.
320
321 This function will automatically match any fields found against configured validators to check if they contained sensible data. If the validators fail the field is automatically removed.
322
323 | Parameter | Description |
324 | --- | --- |
325 | req | The HTTP request to parse. |
326
327 ### Returns
328
329 Nothing
330
331 ---
332
333 # http\_populate\_qs {#http_populate_qs}
334
335 ### Synopsis
336
337 ```
338 void http_populate_qs(struct http_request *req)
339 ```
340
341 ### Description
342
343 The same as _http\_populate\_post\(\)_ but for query string parameters instead.
344
345 | Parameter | Description |
346 | --- | --- |
347 | req | The HTTP request to parse. |
348
349 ### Returns
350
351 Nothing
352
353 ---
354
355 # http\_populate\_multipart\_form {#http_populate_multipart_form}
356
357 ### Synopsis
358
359 ```
360 void http_populate_multipart_form(struct http_request *req)
361 ```
362
363 ### Description
364
365 Parses a multipart form that was received via a POST request.
366
367 | Parameter | Description |
368 | --- | --- |
369 | req | The HTTP request to parse. |
370
371 ### Returns
372
373 Nothing
374
375 ---
376
377 # http\_body\_read {#http_body_read}
378
379 ### Synopsis
380
381 ```
382 ssize_t http_body_read(struct http_request *req, void *out, size_t length)
383 ```
384
385 ### Description
386
387 Attempts to read data from the HTTP body received in a request.
388
389 | Parameter | Description |
390 | --- | --- |
391 | req | The HTTP request. |
392 | out | Where the data is copied into. |
393 | length | The maximum number of bytes that will fit in _out_. |
394
395 ### Returns
396
397 Returns the number of bytes copied or 0 on end of body or -1 on error.
398
399 ---
400
401 # http\_state\_run {#http_state_run}
402
403 ### Synopsis
404
405 ```
406 int http_state_run(struct http_state *states, u_int8_t elm, struct http_request *req)
407 ```
408
409 ### Description
410
411 Runs an HTTP state machine.
412
413 | Parameter | Description |
414 | --- | --- |
415 | states | The HTTP state machine to be run. |
416 | elm | The number of elements in this state machine. |
417 | req | The HTTP request to be passed to the state machine functions. |
418
419 ### Returns
420
421 * KORE\_RESULT\_OK
422 * KORE\_RESULT\_ERROR
423 * KORE\_RESULT\_RETRY
424
425 ### Note
426
427 This should be called from a page handler.
428
429 ---
430
431 # http\_state\_create {#http_state_create}
432
433 ### Synopsis
434
435 ```
436 void *http_state_create(struct http_request *req, size_t len, void (*onfree)(struct http_request *))
437 ```
438
439 ### Description
440
441 Allocates a state attached to the HTTP request that the user can use to
442 store temporary data for the request.
443
444 | Parameter | Description |
445 | --- | --- |
446 | req | The HTTP request. |
447 | len | Size of the state context. |
448 | onfree | Callback function called when an HTTP request is being free'd. |
449
450 ### Returns
451
452 The state context.
453
454 ---
455
456 # http\_state\_get {#http_state_get}
457
458 ### Synopsis
459
460 ```
461 void *http_state_get(struct http_request *req)
462 ```
463
464 ### Description
465
466 Get the user-defined state attached to the HTTP request.
467
468 | Parameter | Description |
469 | --- | --- |
470 | req | The HTTP request. |
471
472 ### Returns
473
474 The state context or NULL if none was set.
475
476 ---
477
478 # http\_state\_cleanup {#http_state_cleanup}
479
480 ### Synopsis
481
482 ```
483 void http_state_cleanup(struct http_request *req)
484 ```
485
486 ### Description
487
488 Free the previously allocated user-defined state attached to the HTTP request.
489
490 | Parameter | Description |
491 | --- | --- |
492 | req | The HTTP request. |
493
494 ### Returns
495
496 Nothing
497
498 ---
499
500 # http\_status\_text {#http_status_text}
501
502 ### Synopsis
503
504 ```
505 const char *http_status_text(int status)
506 ```
507
508 ### Description
509
510 Returns a pointer to a human readable string for the given HTTP status code.
511
512 | Parameter | Description |
513 | --- | --- |
514 | status | The HTTP status code for which to find the string. |
515
516 ### Returns
517
518 A pointer to a human readable string for the HTTP status code.
519
520 ---
521
522 # http\_method\_text {#http_method_text}
523
524 ### Synopsis
525
526 ```
527 const char *http_method_text(int method)
528 ```
529
530 ### Description
531
532 Returns a pointer to a human readable string for the given HTTP method.
533
534 | Parameter | Description |
535 | --- | --- |
536 | method | The HTTP method for which to find the matching string. |
537
538 ### Returns
539
540 A pointer to a human readable string for the HTTP method.
541
542 ---
543
544 # http\_argument\_get\_string {#http_argument_get_string}
545
546 ### Synopsis
547
548 ```
549 int http_argument_get_string(struct http_request *req, const char *name, char **out)
550 ```
551
552 ### Description
553
554 Lookup an argument as a string. The caller should not free the result.
555
556 | Parameter | Description |
557 | --- | --- |
558 | req | The HTTP request. |
559 | name | The name of the argument to find. |
560 | out | Where the pointer to the result is stored. |
561
562 ### Returns
563
564 KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not found.
565
566 ---
567
568 # http\_argument\_get\_byte {#http_argument_get_byte}
569
570 ### Synopsis
571
572 ```
573 int http_argument_get_byte(struct http_request *req, const char *name, u_int8_t *out)
574 ```
575
576 ### Description
577
578 Lookup an argument as a byte.
579
580 | Parameter | Description |
581 | --- | --- |
582 | req | The HTTP request. |
583 | name | The name of the argument to find. |
584 | out | Where the result is stored. |
585
586 ### Returns
587
588 KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not found.
589
590 ---
591
592 # http\_argument\_get\_int16 {#http_argument_get_int16}
593
594 ### Synopsis
595
596 ```
597 int http_argument_get_int16(struct http_request *req, const char *name, int16_t *out)
598 ```
599
600 ### Description
601
602 Lookup an argument as a 16-bit signed integer. This function will check that the result fits in a 16-bit signed integer before returning it.
603
604 | Parameter | Description |
605 | --- | --- |
606 | req | The HTTP request. |
607 | name | The name of the argument to find. |
608 | out | Where the result is stored. |
609
610 ### Returns
611
612 KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not found.
613
614 ---
615
616 # http\_argument\_get\_uint16 {#http_argument_get_uint16}
617
618 ### Synopsis
619
620 ```
621 int http_argument_get_uint16(struct http_request *req, const char *name, uint16_t *out)
622 ```
623
624 ### Description
625
626 Lookup an argument as a 16-bit unsigned integer. This function will check that the result fits in a 16-bit unsigned integer before returning it.
627
628 | Parameter | Description |
629 | --- | --- |
630 | req | The HTTP request. |
631 | name | The name of the argument to find. |
632 | out | Where the result is stored. |
633
634 ### Returns
635
636 KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not found.
637
638 ---
639
640 # http\_argument\_get\_int32 {#http_argument_get_int32}
641
642 ### Synopsis
643
644 ```
645 int http_argument_get_int32(struct http_request *req, const char *name, int32_t *out)
646 ```
647
648 ### Description
649
650 Lookup an argument as a 32-bit signed integer. This function will check that the result fits in a 32-bit signed integer before returning it.
651
652 | Parameter | Description |
653 | --- | --- |
654 | req | The HTTP request. |
655 | name | The name of the argument to find. |
656 | out | Where the result is stored. |
657
658 ### Returns
659
660 KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not found.
661
662 ---
663
664 # http\_argument\_get\_uint32 {#http_argument_get_uint32}
665
666 ### Synopsis
667
668 ```
669 int http_argument_get_uint32(struct http_request *req, const char *name, uint32_t *out)
670 ```
671
672 ### Description
673
674 Lookup an argument as a 32-bit unsigned integer. This function will check that the result fits in a 32-bit unsigned integer before returning it.
675
676 | Parameter | Description |
677 | --- | --- |
678 | req | The HTTP request. |
679 | name | The name of the argument to find. |
680 | out | Where the result is stored. |
681
682 ### Returns
683
684 KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not found.
685
686 ---
687
688 # http\_argument\_get\_int64 {#http_argument_get_int64}
689
690 ### Synopsis
691
692 ```
693 int http_argument_get_int64(struct http_request *req, const char *name, int64_t *out)
694 ```
695
696 ### Description
697
698 Lookup an argument as a 64-bit signed integer. This function will check that the result fits in a 64-bit signed integer before returning it.
699
700 | Parameter | Description |
701 | --- | --- |
702 | req | The HTTP request. |
703 | name | The name of the argument to find. |
704 | out | Where the result is stored. |
705
706 ### Returns
707
708 KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not found.
709
710 ---
711
712 # http\_argument\_get\_uint64 {#http_argument_get_uint64}
713
714 ### Synopsis
715
716 ```
717 int http_argument_get_uint64(struct http_request *req, const char *name, uint64_t *out)
718 ```
719
720 ### Description
721
722 Lookup an argument as a 64-bit unsigned integer. This function will check that the result fits in a 64-bit unsigned integer before returning it.
723
724 | Parameter | Description |
725 | --- | --- |
726 | req | The HTTP request. |
727 | name | The name of the argument to find. |
728 | out | Where the result is stored. |
729
730 ### Returns
731
732 KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not found.
733
734 ---
735
736 # http\_argument\_get\_float {#http_argument_get_float}
737
738 ### Synopsis
739
740 ```
741 int http_argument_get_float(struct http_request *req, const char *name, float *out)
742 ```
743
744 ### Description
745
746 Lookup an argument as a float. This function will check that the result fits in a float before returning it.
747
748 | Parameter | Description |
749 | --- | --- |
750 | req | The HTTP request. |
751 | name | The name of the argument to find. |
752 | out | Where the result is stored. |
753
754 ### Returns
755
756 KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not found.
757
758 ---
759
760 # http\_argument\_get\_double {#http_argument_get_double}
761
762 ### Synopsis
763
764 ```
765 int http_argument_get_double(struct http_request *req, const char *name, double *out)
766 ```
767
768 ### Description
769
770 Lookup an argument as a double. This function will check that the result fits in a double before returning it.
771
772 | Parameter | Description |
773 | --- | --- |
774 | req | The HTTP request. |
775 | name | The name of the argument to find. |
776 | out | Where the result is stored. |
777
778 ### Returns
779
780 KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not found.
781
782 ---
783
784 # http\_runlock\_init {#http_runlock_init}
785
786 ### Synopsis
787
788 ```
789 void http_runlock_init(struct http_runlock *lock)
790 ```
791
792 ### Description
793
794 Initializes a runlock for use later.
795
796 | Parameter | Description |
797 | --- | --- |
798 | lock | The HTTP runlock to initialize. |
799
800 ### Returns
801
802 Nothing
803
804 ---
805
806 # http\_runlock\_acquire {#http_runlock_acquire}
807
808 ### Synopsis
809
810 ```
811 int http_runlock_acquire(struct http_runlock *lock, struct http_request *req)
812 ```
813
814 ### Description
815
816 Attempts to acquire a runlock. If the runlock is busy the **req** request
817 is put to sleep.
818
819 | Parameter | Description |
820 | --- | --- |
821 | lock | The HTTP runlock. |
822 | req | The HTTP request that wants the lock. |
823
824 ### Returns
825
826 Returns KORE\_RESULT\_OK if the runlock was acquired or KORE\_RESULT\_ERROR
827 if the runlock was busy. If the runlock was busy the HTTP request is
828 automatically put to sleep and the calling handler should return
829 KORE\_RESULT\_RETRY accordingly.
830
831 ---
832
833 # http\_runlock\_release {#http_runlock_release}
834
835 ### Synopsis
836
837 ```
838 void http_runlock_release(struct http_runlock *lock, struct http_request *req)
839 ```
840
841 ### Description
842
843 Releases the runlock held by the given **req** request. If the holder of
844 the lock mismatches the request given the worker will fatal().
845
846 | Parameter | Description |
847 | --- | --- |
848 | lock | The HTTP runlock. |
849 | req | The HTTP request that held the lock. |
850
851 ### Returns
852
853 Nothing
854
855 ---
856
857 # Data structures
858
859 ### http\_request
860
861 ### http\_file
862
863 ### http\_header
864
865 ### http\_arg
866
867 ### http\_state
868
869 ---
870
871
872