aboutsummaryrefslogtreecommitdiff
path: root/doc/microhttpd.texi
blob: e21dcc3780b1812cf3e1452e06c9c2300ad51df4 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
@setfilename microhttpd.info

@macro gnu{}
@acronym{GNU}
@end macro

@macro gpl{}
@acronym{LGPL}
@end macro

@macro http{}
@acronym{HTTP}
@end macro

@macro tcp{}
@acronym{TCP}
@end macro

@macro api{}
@acronym{API}
@end macro

@macro urloc{}
@acronym{URL}
@end macro

@macro uri{}
@acronym{URI}
@end macro

@macro ascii{}
@acronym{ASCII}
@end macro

@c ............................................................

@macro cfunction{NAME}
@code{\NAME\()}
@end macro

@macro null{}
@code{NULL}
@end macro

@c ............................................................

@macro glibcref{NODE, NODE}
@pxref{\NODE\, \NODE\, \NODE\, libc}
@end macro

@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


@c ------------------------------------------------------------
@node microhttpd
@appendix Libmicrohttpd documentation


@macro mhd{}
@acronym{MHD}
@end macro


@noindent
This appendix documents Libmicrohttpd version 0.1.2. It is built upon
the documentation in the header file @file{microhttpd.h}.

@menu
* microhttpd intro::            Introduction.
* microhttpd const::            Constants.
* microhttpd struct::           Structures type definition.
* microhttpd cb::               Callback functions definition.
* microhttpd init::             Starting and stopping the server.
* microhttpd inspect::          Inspection.
* microhttpd requests::         Handling requests.
* microhttpd responses::        Building responses to requests.
* microhttpd post::             Adding a @code{POST} processor.
@end menu

@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

@c ------------------------------------------------------------
@node microhttpd intro
@appendixsec Introduction


@noindent
All symbols defined in the public @api{} start with @code{MHD_}.  @mhd{}
is a small @http{} daemon library.  As such, it does not have any @api{}
for logging errors (you can only enable or disable logging to stderr).
Also, it may not support all of the @http{} features directly, where
applicable, portions of @http{} may have to be handled by clients of the
library.

The library is supposed to handle everything that it must handle
(because the @api{} would not allow clients to do this), such as basic
connection management; however, detailed interpretations of headers ---
such as range requests --- and @http{} methods are left to clients.  The
library does understand @code{HEAD} and will only send the headers of
the response and not the body, even if the client supplied a body.  The
library also understands headers that control connection management
(specifically, @code{Connection: close} and @code{Expect: 100 continue}
are understood and handled automatically).

@mhd{} understands @code{POST} data and is able to decode certain
formats (at the moment only @code{application/x-www-form-urlencoded}) if
the entire data fits into the allowed amount of memory for the
connection.  Unsupported encodings and large @code{POST} submissions are
provided as a stream to the main application (and thus can be processed,
just not conveniently by @mhd{}).

The header file defines various constants used by the @http{} protocol.
This does not mean that @mhd{} actually interprets all of these values.
The provided constants are exported as a convenience for users of the
library.  @mhd{} does not verify that transmitted @http{} headers are
part of the standard specification; users of the library are free to
define their own extensions of the @http{} standard and use those with
@mhd{}.

All functions are guaranteed to be completely reentrant and
thread--safe.



@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

@c ------------------------------------------------------------
@node microhttpd const
@appendixsec Constants


@deftp {Enumeration} MHD_FLAG
Options for the @mhd{} daemon.

Note that if neither @code{MHD_USER_THREAD_PER_CONNECTION} nor
@code{MHD_USE_SELECT_INTERNALLY} are used, the client wants control over
the process and will call the appropriate microhttpd callbacks.

Starting the daemon may also fail if a particular option is not
implemented or not supported on the target platform (i.e. no support for
@acronym{SSL}, threads or IPv6).

@table @code
@item MHD_NO_FLAG
No options selected.

@item MHD_USE_DEBUG
Run in debug mode.  If this flag is used, the library should print error
messages and warnings to stderr.

@item MHD_USE_SSL
Run in https mode.

@item MHD_USE_THREAD_PER_CONNECTION
Run using one thread per connection.

@item MHD_USE_SELECT_INTERNALLY
Run using an internal thread doing @code{SELECT}.

@item MHD_USE_IPv6
Run using the IPv6 protocol (otherwise, @mhd{} will just support IPv4).


@item MHD_USE_PEDANTIC_CHECKS
Be pedantic about the protocol (as opposed to as tolerant as possible).
Specifically, at the moment, this flag causes @mhd{} to reject @http{}
1.1 connections without a @code{Host} header.  This is required by the
standard, but of course in violation of the ``be as liberal as possible
in what you accept'' norm.  It is recommended to turn this @strong{ON}
if you are testing clients against @mhd{}, and @strong{OFF} in
production.
@end table
@end deftp


@deftp {Enumeration} MHD_OPTION
@mhd{} options.  Passed in the varargs portion of
@cfunction{MHD_start_daemon}.

@table @code
@item MHD_OPTION_END
No more options / last option.  This is used to terminate the VARARGs
list.
  
@item MHD_OPTION_CONNECTION_MEMORY_LIMIT
Maximum memory size per connection (followed by an @code{unsigned int}).

@item MHD_OPTION_CONNECTION_LIMIT
Maximum number of concurrenct connections to accept (followed by an
@code{unsigned int}).

@item MHD_OPTION_CONNECTION_TIMEOUT
After how many seconds of inactivity should a connection automatically
be timed out? (followed by an @code{unsigned int}; use zero for no
timeout).

@item MHD_OPTION_NOTIFY_COMPLETED
Register a function that should be called whenever a request has been
completed (this can be used for application--specific clean up).
Requests that have never been presented to the application (via
@cfunction{MHD_AccessHandlerCallback}) will not result in
notifications.

This option should be followed by @strong{TWO} pointers.  First a
pointer to a function of type @cfunction{MHD_RequestCompletedCallback}
and second a pointer to a closure to pass to the request completed
callback.  The second pointer maybe @null{}.
@end table
@end deftp


@deftp {Enumeration} MHD_ValueKind
The @code{MHD_ValueKind} specifies the source of the key--value pairs in
the @http{} protocol.

@table @code
@item MHD_RESPONSE_HEADER_KIND
Response header.

@item MHD_HEADER_KIND
@http{} header.

@item MHD_COOKIE_KIND
Cookies.  Note that the original @http{} header containing the cookie(s)
will still be available and intact.

@item MHD_POSTDATA_KIND
@code{POST} data.  This is available only if a content encoding
supported by @mhd{} is used (currently only @acronym{URL} encoding), and
only if the posted content fits within the available memory pool.  Note
that in that case, the upload data given to the
@cfunction{MHD_AccessHandlerCallback} will be empty (since it has
already been processed).

@item MHD_GET_ARGUMENT_KIND
@code{GET} (@uri{}) arguments.
@end table
@end deftp


@deftp {Enumeration} MHD_RequestTerminationCode
The @code{MHD_RequestTerminationCode} specifies reasons why a request
has been terminated (or completed).

@table @code
@item MHD_REQUEST_TERMINATED_COMPLETED_OK
We finished sending the response.

@item MHD_REQUEST_TERMINATED_WITH_ERROR
Error handling the connection (resources exhausted, other side closed
connection, application error accepting request, etc.)

@item MHD_REQUEST_TERMINATED_TIMEOUT_REACHED
No activity on the connection for the number of seconds specified using
@code{MHD_OPTION_CONNECTION_TIMEOUT}.

@item MHD_REQUEST_TERMINATED_DAEMON_SHUTDOWN
We had to close the session since @mhd{} was being shut down.
@end table
@end deftp


@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

@c ------------------------------------------------------------
@node microhttpd struct
@appendixsec Structures type definition


@deftp {C Struct} MHD_Daemon
Handle for the daemon (listening on a socket for @http{} traffic).
@end deftp


@deftp {C Struct} MHD_Connection
Handle for a connection / @http{} request.  With @http{}/1.1, multiple
requests can be run over the same connection.  However, @mhd{} will only
show one request per @tcp{} connection to the client at any given time.
@end deftp


@deftp {C Struct} MHD_Response
Handle for a response.
@end deftp


@deftp {C Struct} MHD_PostProcessor
Handle for @code{POST} processing.
@end deftp


@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

@c ------------------------------------------------------------
@node microhttpd cb
@appendixsec Callback functions definition


@deftypefn {Function Pointer} int {*MHD_AcceptPolicyCallback} (void *cls, const struct sockaddr * addr, socklen_t addrlen)
Invoked in the context of a connection to allow or deny a client to
connect.  This callback return @code{MHD_YES} if connection is allowed,
@code{MHD_NO} if not.

@table @var
@item cls
custom value selected at callback registration time;
@item addr
address information from the client;
@item addrlen
length of the address information.
@end table
@end deftypefn


@deftypefn {Function Pointer} int {*MHD_AccessHandlerCallback} (void *cls, struct MHD_Connection * connection, const char *url, const char *method, const char *version, const char *upload_data, unsigned int *upload_data_size, void **con_cls)
Invoked in the context of a connection to answer a request from the
client.  This callback must call @mhd{} functions (example: the
@code{MHD_Response} ones) to provide content to give back to the client
and return an @http{} status code (i.e. @code{200} for OK, @code{404},
etc.).

@ref{microhttpd post}, for details on how to code this callback.

Must return @code{MHD_YES} if the connection was handled successfully,
@code{MHD_NO} if the socket must be closed due to a serious error while
handling the request

@table @var
@item cls
custom value selected at callback registration time;

@item url
the @urloc{} requested by the client;

@item method
the @http{} method used by the client (@code{GET}, @code{PUT},
@code{DELETE}, @code{POST}, etc.);

@item version
the @http{} version string (i.e. @code{HTTP/1.1});

@item upload_data
the data being uploaded (excluding headers):

@itemize
@item
for a @code{POST} that fits into memory and that is encoded with a
supported encoding, the @code{POST} data will @strong{NOT} be given in
@var{upload_data} and is instead available as part of
@cfunction{MHD_get_connection_values};

@item
very large @code{POST} data @strong{will} be made available
incrementally in @var{upload_data};
@end itemize

@item upload_data_size
set initially to the size of the @var{upload_data} provided; this
callback must update this value to the number of bytes @strong{NOT}
processed;

@item con_cls
reference to a pointer, initially set to @null{}, that this callback can
set to some address and that will be preserved by @mhd{} for future
calls for this request;

since the access handler may be called many times (i.e., for a
@code{PUT}/@code{POST} operation with plenty of upload data) this allows
the application to easily associate some request--specific state;

if necessary, this state can be cleaned up in the global
@code{MHD_RequestCompletedCallback} (which can be set with the
@code{MHD_OPTION_NOTIFY_COMPLETED}).
@end table
@end deftypefn


@deftypefn {Function Pointer} void {*MHD_RequestCompletedCallback} (void *cls, struct MHD_Connectionconnection, void **con_cls, enum MHD_RequestTerminationCode toe)
Signature of the callback used by @mhd{} to notify the application about
completed requests.

@table @var
@item cls
custom value selected at callback registration time;

@item connection
connection handle;

@item con_cls
value as set by the last call to the
@code{MHD_AccessHandlerCallback};

@item toe
reason for request termination see @code{MHD_OPTION_NOTIFY_COMPLETED}.
@end table
@end deftypefn


@deftypefn {Function Pointer} int {*MHD_KeyValueIterator} (void *cls, enum MHD_ValueKind kind, const char *key, const char *value)
Iterator over key--value pairs.  This iterator can be used to iterate
over all of the cookies, headers, or @code{POST}--data fields of a
request, and also to iterate over the headers that have been added to a
response.

Return @code{MHD_YES} to continue iterating, @code{MHD_NO} to abort the
iteration.
@end deftypefn


@deftypefn {Function Pointer} int {*MHD_ContentReaderCallback} (void *cls, size_t pos, char *buf, int max)
Callback used by @mhd{} in order to obtain content.  The callback has to
copy at most @var{max} bytes of content into @var{buf}.  The total
number of bytes that has been placed into @var{buf} should be returned.

Note that returning zero will cause @mhd{} to try again, either
``immediately'' if in multi--threaded mode (in which case the callback
may want to do blocking operations) or in the next round if MHD_run is
used.  Returning zero for a daemon that runs in internal
@cfunction{select} mode is an error (since it would result in busy
waiting) and will cause the program to be aborted (@cfunction{abort}).

@table @var
@item cls
custom value selected at callback registration time;

@item pos
position in the datastream to access; note that if an
@code{MHD_Response} object is re--used, it is possible for the same
content reader to be queried multiple times for the same data; however,
if an @code{MHD_Response} is not re--used, @mhd{} guarantees that
@var{pos} will be the sum of all non--negative return values obtained
from the content reader so far.
@end table

Return @code{-1} on error (@mhd{} will no longer try to read content and
instead close the connection with the client).
@end deftypefn


@deftypefn {Function Pointer} void {*MHD_ContentReaderFreeCallback} (void *cls)
This method is called by @mhd{} if we are done with a content reader.
It should be used to free resources associated with the content reader.
@end deftypefn


@deftypefn {Function Pointer} int {*MHD_PostDataIterator} (void *cls, enum MHD_ValueKind kind, const char *key, const char *filename, const char *content_type, const char *transfer_encoding, const char *data, size_t off, size_t size)
Iterator over key--value pairs where the value maybe made available in
increments and/or may not be zero--terminated.  Used for processing
@code{POST} data.

@table @var
@item cls
custom value selected at callback registration time;

@item kind
type of the value;

@item key
zero--terminated key for the value;

@item filename
name of the uploaded file, @null{} if not known;

@item content_type
mime--type of the data, @null{} if not known;

@item transfer_encoding
encoding of the data, @null{} if not known;

@item data
pointer to size bytes of data at the specified offset;

@item off
offset of data in the overall value;

@item size
number of bytes in data available.
@end table

Return @code{MHD_YES} to continue iterating, @code{MHD_NO} to abort the
iteration.
@end deftypefn


@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

@c ------------------------------------------------------------
@node microhttpd init
@appendixsec Starting and stopping the server


@deftypefun {struct MHD_Daemon *} MHD_start_daemon (unsigned int flags, unsigned short port, MHD_AcceptPolicyCallback apc, void *apc_cls, MHD_AccessHandlerCallback dh, void *dh_cls, ...)
Start a webserver on the given port.

@table @var
@item flags
OR--ed combination of @code{MHD_FLAG} values;

@item port
port to bind to;

@item apc
callback to call to check which clients will be allowed to connect; you
can pass @null{} in which case connections from any @acronym{IP} will be
accepted;

@item apc_cls
extra argument to @var{apc};

@item dh
default handler for all @uri{}s;

@item dh_cls
extra argument to @var{dh}.
@end table

Additional arguments are a list of options (type--value pairs,
terminated with @code{MHD_OPTION_END}). It is mandatory to use
@code{MHD_OPTION_END} as last argument, even when there are no
additional arguments.

Return @null{} on error, handle to daemon on success.
@end deftypefun


@deftypefun void MHD_stop_daemon (struct MHD_Daemon *daemon)
Shutdown an @http{} daemon.
@end deftypefun


@deftypefun int MHD_run (struct MHD_Daemon *daemon)
Run webserver operations (without blocking unless in client callbacks).
This method should be called by clients in combination with
@cfunction{MHD_get_fdset} if the client--controlled @cfunction{select}
method is used.

Return @code{MHD_YES} on success, @code{MHD_NO} if this daemon was not
started with the right options for this call.
@end deftypefun


@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

@c ------------------------------------------------------------
@node microhttpd inspect
@appendixsec Inspection


@deftypefun int MHD_get_fdset (struct MHD_Daemon *daemon, fd_set * read_fd_set, fd_set * write_fd_set, fd_set * except_fd_set, int *max_fd)
Obtain the @cfunction{select} sets for this daemon. The daemon's socket
is added to @var{read_fd_set}. The list of currently existent
connections is scanned and their file descriptors added to the correct
set.

@glibcref{Waiting for I/O}, for details on file descriptor sets.

After the call completed successfully: the variable referenced by
@var{max_fd} references the file descriptor with highest integer
identifier. The variable must be set to zero before invoking this
function.

Return @code{MHD_YES} on success, @code{MHD_NO} if: the arguments are
invalid (example: @null{} pointers); this daemon was not started with
the right options for this call.
@end deftypefun


@deftypefun int MHD_get_timeout (struct MHD_Daemon *daemon, unsigned long long *timeout)
Obtain timeout value for select for this daemon (only needed if
connection timeout is used).  The returned value is how long
@cfunction{select} should at most block, not the timeout value set for
connections.

@table @var
@item timeout
set to the timeout (in milliseconds).
@end table

Return @code{MHD_YES} on success, @code{MHD_NO} if timeouts are not used
(or no connections exist that would necessiate the use of a timeout
right now).
@end deftypefun


@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

@c ------------------------------------------------------------
@node microhttpd requests
@appendixsec Handling requests


@menu
* microhttpd handlers::         @uri{} specific handlers.
* microhttpd values::           Connection headers and small
                                @code{POST} data.
@end menu


@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

@c ------------------------------------------------------------
@node microhttpd handlers
@appendixsubsec @uri{} specific handlers


@noindent
A set of callbacks can be registered in the state of a daemon
(@code{MHD_Daemon}) to handle request for specific sets of
resources.  The set is selected by specifying the prefix string of the
@uri{}, example:

@example
/bookcase
@end example

@noindent
matches all of the following:

@example
/bookcase/book.html
/bookcase/pencil.html
/bookcase/strawberry.html
@end example

Handlers are stored in a linked list (managed with @cfunction{malloc}
and @cfunction{free}). Prefixes are compared with @cfunction{strcmp}.


@deftypefun int MHD_register_handler (struct MHD_Daemon *daemon, const char *uri_prefix, MHD_AccessHandlerCallback dh, void *dh_cls)
Register an access handler for all @uri{}s beginning with
@var{uri_prefix}, a zero--terminated @ascii{}--coded string.

Return @code{MRI_NO} if: the arguments are invalid (example: @null{}
pointers); a handler for this exact prefix already exists; an error
allocating memory happens.
@end deftypefun


@deftypefun int MHD_unregister_handler (struct MHD_Daemon *daemon, const char *uri_prefix, MHD_AccessHandlerCallback dh, void *dh_cls)
Unregister an access handler for the @uri{}s beginning with
@var{uri_prefix}.

Return @code{MHD_NO} if: the arguments are invalid (example: @null{}
pointers); a handler for this exact prefix is not known for this daemon.
@end deftypefun


@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

@c ------------------------------------------------------------
@node microhttpd values
@appendixsubsec Connection headers and small @code{POST} data


@deftypefun int MHD_get_connection_values (struct MHD_Connection *connection, enum MHD_ValueKind kind, MHD_KeyValueIterator iterator, void *iterator_cls)
Get all the headers matching @var{kind} from the request.

The @var{iterator} callback is invoked once for each header, with
@var{iterator_cls} as first argument. Return the number of entries
iterated over; this can be less than the number of headers if, while
iterating, @var{iterator} returns @code{MHD_NO}.

@var{iterator} can be @null{}: in this case this function just counts
and returns the number of headers.
@end deftypefun


@deftypefun {const char *} MHD_lookup_connection_value (struct MHD_Connection *connection, enum MHD_ValueKind kind, const char *key)
Get a particular header value.  If multiple values match the @var{kind},
return one of them (the ``first'', whatever that means).  @var{key} must
reference a zero--terminated @ascii{}--coded string representing the
header to look for: it is compared against the headers using
@cfunction{strcasecmp}, so case is ignored.  Return @null{} if no such
item was found.
@end deftypefun


@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

@c ------------------------------------------------------------
@node microhttpd responses
@appendixsec Building answers to responses


@menu
* microhttpd response enqueue:: Enqueuing a response.
* microhttpd response create::  Creating a response object.
* microhttpd response headers:: Adding headers to a response.
* microhttpd response inspect:: Inspecting a response object.
@end menu


@noindent
Response objects handling by @mhd{} is asynchronous with respect to the
application execution flow. Instances of the @code{MHD_Response}
structure are not associated to a daemon and neither to a client
connection: they are managed with reference counting.

In the simplest case: we allocate a new @code{MHD_Response} structure
for each response, we use it once and finally we destroy it.

@mhd{} allows more efficient resources usages.

Example: we allocate a new @code{MHD_Response} structure for each
response @strong{kind}, we use it every time we have to give that
responce and we finally destroy it only when the daemon shuts down.


@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

@c ------------------------------------------------------------
@node microhttpd response enqueue
@appendixsubsec Enqueuing a response


@deftypefun int MHD_queue_response (struct MHD_Connection *connection, unsigned int status_code, struct MHD_Response *response)
Queue a response to be transmitted to the client as soon as possible
(increment the reference counter).

@table @var
@item connection
the connection identifying the client;

@item status_code
@http{} status code (i.e. @code{200} for OK);

@item response
response to transmit.
@end table

Return @code{MHD_YES} on success or if message has been queued.  Return
@code{MHD_NO}: if arguments are invalid (example: @null{} pointer); on
error (i.e. reply already sent).
@end deftypefun


@deftypefun void MHD_destroy_response (struct MHD_Response *response)
Destroy a response object and associated resources (decrement the
reference counter).  Note that @mhd{} may keep some of the resources
around if the response is still in the queue for some clients, so the
memory may not necessarily be freed immediatley.
@end deftypefun


An explanation of reference counting@footnote{Note to readers acquainted
to the Tcl @api{}: reference counting on @code{MHD_Connection}
structures is handled in the same way as Tcl handles @code{Tcl_Obj}
structures through @cfunction{Tcl_IncrRefCount} and
@cfunction{Tcl_DecrRefCount}.}:

@enumerate
@item
a @code{MHD_Response} object is allocated:

@example
struct MHD_Response * response = MHD_create_response_from_data(...);
/* here: reference counter = 1 */
@end example

@item
the @code{MHD_Response} object is enqueued in a @code{MHD_Connection}:

@example
MHD_queue_response(connection, , response);
/* here: reference counter = 2 */
@end example

@item
the creator of the response object discharges responsibility for it:

@example
MHD_destroy_response(response);
/* here: reference counter = 1 */
@end example

@item
the daemon handles the connection sending the response's data to the
client then decrements the reference counter by calling
@cfunction{MHD_destroy_response}: the counter's value drops to zero and
the @code{MHD_Response} object is released.
@end enumerate


@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

@c ------------------------------------------------------------
@node microhttpd response create
@appendixsubsec Creating response objects


@deftypefun {struct MHD_Response *} MHD_create_response_from_callback (size_t size, unsigned int block_size, MHD_ContentReaderCallback crc, void *crc_cls, MHD_ContentReaderFreeCallback crfc)
Create a response object.  The response object can be extended with
header information and then it can be used any number of times.

@table @var
@item size
size of the data portion of the response, @code{-1} for unknown;

@item block_size
preferred block size for querying @var{crc} (advisory only, @mhd{} may
still call @var{crc} using smaller chunks); this is essentially the
buffer size used for @acronym{IO}, clients should pick a value that is
appropriate for @acronym{IO} and memory performance requirements;

@item crc
callback to use to obtain response data;

@item crc_cls
extra argument to @var{crc};

@item crfc
callback to call to free @var{crc_cls} resources.
@end table

Return @null{} on error (i.e. invalid arguments, out of memory).
@end deftypefun


@deftypefun {struct MHD_Response *} MHD_create_response_from_data (size_t size, void *data, int must_free, int must_copy)
Create a response object.  The response object can be extended with
header information and then it can be used any number of times.

@table @var
@item size
size of the data portion of the response;

@item data
the data itself;

@item must_free
if true: @mhd{} should free data when done;

@item must_copy
if true: @mhd{} allocates a block of memory and use it to make a copy of
@var{data} embedded in the returned @code{MHD_Response} structure;
handling of the embedded memory is responsibility of @mhd{}; @var{data}
can be released anytime after this call returns.
@end table

Return @null{} on error (i.e. invalid arguments, out of memory).
@end deftypefun


Example: create a response from a statically allocated string:

@example
const char * data = "<html><body><p>Error!</p></body></html>";

struct MHD_Connection * connection = ...;
struct MHD_Response *   response;

response = MHD_create_response_from_data(strlen(data), data,
                                         MHD_NO, MHD_NO);
MHD_queue_response(connection, 404, response);
MHD_destroy_response(response);
@end example



@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

@c ------------------------------------------------------------
@node microhttpd response headers
@appendixsubsec Adding headers to a response


@deftypefun int MHD_add_response_header (struct MHD_Response *response, const char *header, const char *content)
Add a header line to the response. The strings referenced by
@var{header} and @var{content} must be zero--terminated and they are
duplicated into memory blocks embedded in @var{response}.

Notice that the strings must not hold newlines, carriage returns or tab
chars.

Return @code{MHD_NO} on error (i.e. invalid header or content format or
memory allocation error).
@end deftypefun


@deftypefun int MHD_del_response_header (struct MHD_Response *response, const char *header, const char *content)
Delete a header line from the response.  Return @code{MHD_NO} on error
(arguments are invalid or no such header known).
@end deftypefun


@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

@c ------------------------------------------------------------
@node microhttpd response inspect
@appendixsubsec Inspecting a response object


@deftypefun int MHD_get_response_headers (struct MHD_Response *response, MHD_KeyValueIterator iterator, void *iterator_cls)
Get all of the headers added to a response.

Invoke the @var{iterator} callback for each header in the response,
using @var{iterator_cls} as first argument. Return number of entries
iterated over.  @var{iterator} can be @null{}: in this case the function
just counts headers.

@var{iterator} should not modify the its key and value arguments, unless
we know what we are doing.
@end deftypefun


@deftypefun {const char *} MHD_get_response_header (struct MHD_Response *response, const char *key)
Find and return a pointer to the value of a particular header from the
response.  @var{key} must reference a zero--terminated string
representing the header to look for. The search is case sensitive.
Return @null{} if header does not exist or @var{key} is @null{}.

We should not modify the value, unless we know what we are doing.
@end deftypefun


@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

@c ------------------------------------------------------------
@node microhttpd post
@appendixsec Adding a @code{POST} processor


@menu
* microhttpd post api::         Programming interface for the
                                @code{POST} processor.
@end menu


@noindent
When a small amount of data comes from a client's @code{POST} request:
the data is available through the values interface. @ref{microhttpd
values}, for details. In this case @mhd{} invokes
@code{MHD_AccessHandlerCallback} only once and the callback must process
all the data during that invocation.

When a big amount of data comes from a client's @code{POST} request: the
@code{MHD_AccessHandlerCallback} will be invoked multiple times to
process data as it arrives; at each invocation a new chunk of data must
be processed. The arguments @var{upload_data} and @var{upload_data_size}
are used to reference the chunk of data.

When @code{MHD_AccessHandlerCallback} is invoked for a new connection:
its @code{*@var{con_cls}} argument is set to @null{}. When @code{POST}
data comes in the upload buffer it is @strong{mandatory} to use the
@var{con_cls} to hold data or to mark an ongoing process.

To detect that a new connection has come with the @code{POST} method:

@example
int
access_handler (void *cls,
                struct MHD_Connection * connection,
                const char *url,
                const char *method, const char *version,
                const char *upload_data, unsigned int *upload_data_size,
                void **con_cls)
@{
  static int old_connection_marker;
  int new_connection = (NULL == *con_cls);
  int method_is_post = strcmp("POST",method);

  if (new_connection && method_is_post)
    @{
      /* new connection with POST */
      *con_cls = &old_connection_marker;
    @}

  ...
@}
@end example

@noindent
in this example the value of @code{*con_cls} is just an unused pointer
to an unused integer: its purpose is to make @code{*con_cls} different
from @null{}. When serious processing of @code{POST} data is needed: it
can be a pointer to a dynamically allocated data structure.

To detect that @code{POST} data is in the upload buffer:

@example
int
access_handler (void *cls,
                struct MHD_Connection * connection,
                const char *url,
                const char *method, const char *version,
                const char *upload_data, unsigned int *upload_data_size,
                void **con_cls)
@{
  static int old_connection_marker;
  int new_connection = (NULL == *con_cls);
  int method_is_post = strcmp("POST",method);

  if (new_connection && method_is_post)
    @{
      int data_in_upload_buffer = (0 != *upload_data_size);

      if (data_in_upload_buffer)
        @{
          *con_cls = &old_connection_marker;
          /* POST data in the buffer */
        @}
      else
        /* POST data accessible with the values API */
    @}

  ...
@}
@end example


At each invocation there are two options:

@enumerate
@item
the callback can process the whole chunk by itself; every time @mhd{}
invokes it a new chunk is fully processed; with this mode the callback
has to @code{*upload_data_size = 0} before returning @code{MHD_YES};

@item
the callback can process a section of the chunk by itself; every time
@mhd{} invokes it the buffer holds the old data as well as new data
coming from the client; with this mode the callback has to set
@code{*upload_data_size} to the numbe of bytes still to process before
returning @code{MHD_YES};

example: @mhd{} invokes the callback with @code{100 ==
*upload_data_size}; the callback processes the first 80 bytes and before
returning the callback sets @code{*upload_data_size = 20}; the last
unprocessed 20 bytes will be the first 20 at the next invocation;

@item
when a new connection with @code{POST} data in the buffer comes: the
callback allocates a PostProcessor and hand to it the responsibility of
processing data; a pointer to the PostProcessor structure is saved in
@code{*con_cls}, so that it is available at each subsequent invocation;

the post processor data can be freed by a later invocation to an
appropriate callback.
@end enumerate


Let's see how to implement strategy 1:

@example
int
access_handler (void *cls,
                struct MHD_Connection * connection,
                const char *url,
                const char *method, const char *version,
                const char *upload_data, unsigned int *upload_data_size,
                void **con_cls)
@{
  static int old_connection_marker;
  int new_connection = (NULL == *con_cls);
  int method_is_post = strcmp("POST",method);

  if (new_connection && method_is_post)
    @{
      int data_in_upload_buffer = (0 != *upload_data_size);

      if (data_in_upload_buffer)
        @{
          *con_cls = &old_connection_marker;
        @}
      else
        @{
          /* POST data accessible with the values API */
          return MHD_YES;
        @}
    @}

  if (&old_connection_marker == *con_cls)
    @{
      consume_data(upload_data, *upload_data_size);
      *upload_data_size = 0;
      return MHD_YES;
    @}

  /* process other methods */
  return MHD_YES;
@}
@end example

Let's see how to implement strategy 2:

@example
int
access_handler (void *cls,
                struct MHD_Connection * connection,
                const char *url,
                const char *method, const char *version,
                const char *upload_data, unsigned int *upload_data_size,
                void **con_cls)
@{
  static int old_connection_marker;
  int new_connection = (NULL == *con_cls);
  int method_is_post = strcmp("POST",method);

  if (new_connection && method_is_post)
    @{
      int data_in_upload_buffer = (0 != *upload_data_size);

      if (data_in_upload_buffer)
        @{
          *con_cls = &old_connection_marker;
        @}
      else
        @{
          /* POST data accessible with the values API */
          return MHD_YES;
        @}
    @}

  if (&old_connection_marker == *con_cls)
    @{
      int number_of_bytes_to_consume = 100;

      if (number_of_bytes_to_consume > *upload_data_size)
        number_of_bytes_to_consume = *upload_data_size;

      consume_some_data(upload_data, number_of_bytes_to_consume);
      *upload_data_size -= number_of_bytes_to_consume;
      return MHD_YES;
    @}

  /* process other methods */
  return MHD_YES;
@}

@end example



@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

@c ------------------------------------------------------------
@node microhttpd post api
@appendixsubsec Programming interface for the @code{POST} processor



@deftypefun {struct MHD_PostProcessor *} MHD_create_post_processor (struct MHD_Connection *connection, unsigned int buffer_size, MHD_PostDataIterator iterator, void *iterator_cls)
Create a PostProcessor.  A PostProcessor can be used to (incrementally)
parse the data portion of a @code{POST} request.

@table @var
@item connection
the connection on which the @code{POST} is happening (used to determine
the @code{POST} format);

@item buffer_size
maximum number of bytes to use for internal buffering (used only for the
parsing, specifically the parsing of the keys).  A tiny value (256-1024)
should be sufficient; do @strong{NOT} use a value smaller than 256;

@item iterator
iterator to be called with the parsed data; must @strong{NOT} be
@null{};

@item iterator_cls
custom value to be used as first argument to @var{iterator}.
@end table

Return @null{} on error (out of memory, unsupported encoding), otherwise
a PP handle.
@end deftypefun


@deftypefun int MHD_post_process (struct MHD_PostProcessor *pp, const char *post_data, unsigned int post_data_len)
Parse and process @code{POST} data.  Call this function when @code{POST}
data is available (usually during an @code{MHD_AccessHandlerCallback})
with the @var{upload_data} and @var{upload_data_size}.  Whenever
possible, this will then cause calls to the
@code{MHD_IncrementalKeyValueIterator}.

@table @var
@item pp
the post processor;

@item post_data
@var{post_data_len} bytes of @code{POST} data;

@item post_data_len
length of @var{post_data}.
@end table

Return @code{MHD_YES} on success, @code{MHD_NO} on error
(out--of--memory, iterator aborted, parse error).
@end deftypefun


@deftypefun void MHD_destroy_post_processor (struct MHD_PostProcessor *pp)
Release PostProcessor resources.
@end deftypefun


@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++