aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2008-03-30 04:36:05 +0000
committerChristian Grothoff <christian@grothoff.org>2008-03-30 04:36:05 +0000
commita69c23c79d5385a1c5c6da1587db1c8bcc6ba975 (patch)
tree2e442244150280b6c11910ce959286b0796b040c
parenta7ea20473a18f5a88028c7245e8e4eaad5982a5a (diff)
downloadlibmicrohttpd-a69c23c79d5385a1c5c6da1587db1c8bcc6ba975.tar.gz
libmicrohttpd-a69c23c79d5385a1c5c6da1587db1c8bcc6ba975.zip
updating docs
-rw-r--r--doc/Makefile.am6
-rw-r--r--doc/lgpl.texi561
-rw-r--r--doc/microhttpd.texi505
3 files changed, 773 insertions, 299 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index b0e78e11..2d8f5578 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,7 +1,7 @@
1man_MANS = libmicrohttpd.3 1man_MANS = libmicrohttpd.3
2EXTRA_DIST = $(man_MANS) 2EXTRA_DIST = $(man_MANS)
3 3
4#DISTCLEANFILES = microhttpd.cps 4DISTCLEANFILES = microhttpd.cps
5#info_TEXINFOS = microhttpd.texi 5info_TEXINFOS = microhttpd.texi
6#microhttpd_TEXINFOS = gpl.texi 6microhttpd_TEXINFOS = lgpl.texi
7 7
diff --git a/doc/lgpl.texi b/doc/lgpl.texi
new file mode 100644
index 00000000..260c0ce0
--- /dev/null
+++ b/doc/lgpl.texi
@@ -0,0 +1,561 @@
1@c The GNU Lesser General Public License.
2@center Version 2.1, February 1999
3
4@c This file is intended to be included within another document,
5@c hence no sectioning command or @node.
6
7@display
8Copyright @copyright{} 1991, 1999 Free Software Foundation, Inc.
951 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
10
11Everyone is permitted to copy and distribute verbatim copies
12of this license document, but changing it is not allowed.
13
14[This is the first released version of the Lesser GPL. It also counts
15as the successor of the GNU Library Public License, version 2, hence the
16version number 2.1.]
17@end display
18
19@subheading Preamble
20
21 The licenses for most software are designed to take away your
22freedom to share and change it. By contrast, the GNU General Public
23Licenses are intended to guarantee your freedom to share and change
24free software---to make sure the software is free for all its users.
25
26 This license, the Lesser General Public License, applies to some
27specially designated software---typically libraries---of the Free
28Software Foundation and other authors who decide to use it. You can use
29it too, but we suggest you first think carefully about whether this
30license or the ordinary General Public License is the better strategy to
31use in any particular case, based on the explanations below.
32
33 When we speak of free software, we are referring to freedom of use,
34not price. Our General Public Licenses are designed to make sure that
35you have the freedom to distribute copies of free software (and charge
36for this service if you wish); that you receive source code or can get
37it if you want it; that you can change the software and use pieces of it
38in new free programs; and that you are informed that you can do these
39things.
40
41 To protect your rights, we need to make restrictions that forbid
42distributors to deny you these rights or to ask you to surrender these
43rights. These restrictions translate to certain responsibilities for
44you if you distribute copies of the library or if you modify it.
45
46 For example, if you distribute copies of the library, whether gratis
47or for a fee, you must give the recipients all the rights that we gave
48you. You must make sure that they, too, receive or can get the source
49code. If you link other code with the library, you must provide
50complete object files to the recipients, so that they can relink them
51with the library after making changes to the library and recompiling
52it. And you must show them these terms so they know their rights.
53
54 We protect your rights with a two-step method: (1) we copyright the
55library, and (2) we offer you this license, which gives you legal
56permission to copy, distribute and/or modify the library.
57
58 To protect each distributor, we want to make it very clear that
59there is no warranty for the free library. Also, if the library is
60modified by someone else and passed on, the recipients should know
61that what they have is not the original version, so that the original
62author's reputation will not be affected by problems that might be
63introduced by others.
64
65 Finally, software patents pose a constant threat to the existence of
66any free program. We wish to make sure that a company cannot
67effectively restrict the users of a free program by obtaining a
68restrictive license from a patent holder. Therefore, we insist that
69any patent license obtained for a version of the library must be
70consistent with the full freedom of use specified in this license.
71
72 Most GNU software, including some libraries, is covered by the
73ordinary GNU General Public License. This license, the GNU Lesser
74General Public License, applies to certain designated libraries, and
75is quite different from the ordinary General Public License. We use
76this license for certain libraries in order to permit linking those
77libraries into non-free programs.
78
79 When a program is linked with a library, whether statically or using
80a shared library, the combination of the two is legally speaking a
81combined work, a derivative of the original library. The ordinary
82General Public License therefore permits such linking only if the
83entire combination fits its criteria of freedom. The Lesser General
84Public License permits more lax criteria for linking other code with
85the library.
86
87 We call this license the @dfn{Lesser} General Public License because it
88does @emph{Less} to protect the user's freedom than the ordinary General
89Public License. It also provides other free software developers Less
90of an advantage over competing non-free programs. These disadvantages
91are the reason we use the ordinary General Public License for many
92libraries. However, the Lesser license provides advantages in certain
93special circumstances.
94
95 For example, on rare occasions, there may be a special need to
96encourage the widest possible use of a certain library, so that it becomes
97a de-facto standard. To achieve this, non-free programs must be
98allowed to use the library. A more frequent case is that a free
99library does the same job as widely used non-free libraries. In this
100case, there is little to gain by limiting the free library to free
101software only, so we use the Lesser General Public License.
102
103 In other cases, permission to use a particular library in non-free
104programs enables a greater number of people to use a large body of
105free software. For example, permission to use the GNU C Library in
106non-free programs enables many more people to use the whole GNU
107operating system, as well as its variant, the GNU/Linux operating
108system.
109
110 Although the Lesser General Public License is Less protective of the
111users' freedom, it does ensure that the user of a program that is
112linked with the Library has the freedom and the wherewithal to run
113that program using a modified version of the Library.
114
115 The precise terms and conditions for copying, distribution and
116modification follow. Pay close attention to the difference between a
117``work based on the library'' and a ``work that uses the library''. The
118former contains code derived from the library, whereas the latter must
119be combined with the library in order to run.
120
121@subheading TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
122
123@enumerate 0
124@item
125This License Agreement applies to any software library or other program
126which contains a notice placed by the copyright holder or other
127authorized party saying it may be distributed under the terms of this
128Lesser General Public License (also called ``this License''). Each
129licensee is addressed as ``you''.
130
131 A ``library'' means a collection of software functions and/or data
132prepared so as to be conveniently linked with application programs
133(which use some of those functions and data) to form executables.
134
135 The ``Library'', below, refers to any such software library or work
136which has been distributed under these terms. A ``work based on the
137Library'' means either the Library or any derivative work under
138copyright law: that is to say, a work containing the Library or a
139portion of it, either verbatim or with modifications and/or translated
140straightforwardly into another language. (Hereinafter, translation is
141included without limitation in the term ``modification''.)
142
143 ``Source code'' for a work means the preferred form of the work for
144making modifications to it. For a library, complete source code means
145all the source code for all modules it contains, plus any associated
146interface definition files, plus the scripts used to control compilation
147and installation of the library.
148
149 Activities other than copying, distribution and modification are not
150covered by this License; they are outside its scope. The act of
151running a program using the Library is not restricted, and output from
152such a program is covered only if its contents constitute a work based
153on the Library (independent of the use of the Library in a tool for
154writing it). Whether that is true depends on what the Library does
155and what the program that uses the Library does.
156
157@item
158You may copy and distribute verbatim copies of the Library's
159complete source code as you receive it, in any medium, provided that
160you conspicuously and appropriately publish on each copy an
161appropriate copyright notice and disclaimer of warranty; keep intact
162all the notices that refer to this License and to the absence of any
163warranty; and distribute a copy of this License along with the
164Library.
165
166 You may charge a fee for the physical act of transferring a copy,
167and you may at your option offer warranty protection in exchange for a
168fee.
169
170@item
171You may modify your copy or copies of the Library or any portion
172of it, thus forming a work based on the Library, and copy and
173distribute such modifications or work under the terms of Section 1
174above, provided that you also meet all of these conditions:
175
176@enumerate a
177@item
178The modified work must itself be a software library.
179
180@item
181You must cause the files modified to carry prominent notices
182stating that you changed the files and the date of any change.
183
184@item
185You must cause the whole of the work to be licensed at no
186charge to all third parties under the terms of this License.
187
188@item
189If a facility in the modified Library refers to a function or a
190table of data to be supplied by an application program that uses
191the facility, other than as an argument passed when the facility
192is invoked, then you must make a good faith effort to ensure that,
193in the event an application does not supply such function or
194table, the facility still operates, and performs whatever part of
195its purpose remains meaningful.
196
197(For example, a function in a library to compute square roots has
198a purpose that is entirely well-defined independent of the
199application. Therefore, Subsection 2d requires that any
200application-supplied function or table used by this function must
201be optional: if the application does not supply it, the square
202root function must still compute square roots.)
203@end enumerate
204
205These requirements apply to the modified work as a whole. If
206identifiable sections of that work are not derived from the Library,
207and can be reasonably considered independent and separate works in
208themselves, then this License, and its terms, do not apply to those
209sections when you distribute them as separate works. But when you
210distribute the same sections as part of a whole which is a work based
211on the Library, the distribution of the whole must be on the terms of
212this License, whose permissions for other licensees extend to the
213entire whole, and thus to each and every part regardless of who wrote
214it.
215
216Thus, it is not the intent of this section to claim rights or contest
217your rights to work written entirely by you; rather, the intent is to
218exercise the right to control the distribution of derivative or
219collective works based on the Library.
220
221In addition, mere aggregation of another work not based on the Library
222with the Library (or with a work based on the Library) on a volume of
223a storage or distribution medium does not bring the other work under
224the scope of this License.
225
226@item
227You may opt to apply the terms of the ordinary GNU General Public
228License instead of this License to a given copy of the Library. To do
229this, you must alter all the notices that refer to this License, so
230that they refer to the ordinary GNU General Public License, version 2,
231instead of to this License. (If a newer version than version 2 of the
232ordinary GNU General Public License has appeared, then you can specify
233that version instead if you wish.) Do not make any other change in
234these notices.
235
236 Once this change is made in a given copy, it is irreversible for
237that copy, so the ordinary GNU General Public License applies to all
238subsequent copies and derivative works made from that copy.
239
240 This option is useful when you wish to copy part of the code of
241the Library into a program that is not a library.
242
243@item
244You may copy and distribute the Library (or a portion or
245derivative of it, under Section 2) in object code or executable form
246under the terms of Sections 1 and 2 above provided that you accompany
247it with the complete corresponding machine-readable source code, which
248must be distributed under the terms of Sections 1 and 2 above on a
249medium customarily used for software interchange.
250
251 If distribution of object code is made by offering access to copy
252from a designated place, then offering equivalent access to copy the
253source code from the same place satisfies the requirement to
254distribute the source code, even though third parties are not
255compelled to copy the source along with the object code.
256
257@item
258A program that contains no derivative of any portion of the
259Library, but is designed to work with the Library by being compiled or
260linked with it, is called a ``work that uses the Library''. Such a
261work, in isolation, is not a derivative work of the Library, and
262therefore falls outside the scope of this License.
263
264 However, linking a ``work that uses the Library'' with the Library
265creates an executable that is a derivative of the Library (because it
266contains portions of the Library), rather than a ``work that uses the
267library''. The executable is therefore covered by this License.
268Section 6 states terms for distribution of such executables.
269
270 When a ``work that uses the Library'' uses material from a header file
271that is part of the Library, the object code for the work may be a
272derivative work of the Library even though the source code is not.
273Whether this is true is especially significant if the work can be
274linked without the Library, or if the work is itself a library. The
275threshold for this to be true is not precisely defined by law.
276
277 If such an object file uses only numerical parameters, data
278structure layouts and accessors, and small macros and small inline
279functions (ten lines or less in length), then the use of the object
280file is unrestricted, regardless of whether it is legally a derivative
281work. (Executables containing this object code plus portions of the
282Library will still fall under Section 6.)
283
284 Otherwise, if the work is a derivative of the Library, you may
285distribute the object code for the work under the terms of Section 6.
286Any executables containing that work also fall under Section 6,
287whether or not they are linked directly with the Library itself.
288
289@item
290As an exception to the Sections above, you may also combine or
291link a ``work that uses the Library'' with the Library to produce a
292work containing portions of the Library, and distribute that work
293under terms of your choice, provided that the terms permit
294modification of the work for the customer's own use and reverse
295engineering for debugging such modifications.
296
297 You must give prominent notice with each copy of the work that the
298Library is used in it and that the Library and its use are covered by
299this License. You must supply a copy of this License. If the work
300during execution displays copyright notices, you must include the
301copyright notice for the Library among them, as well as a reference
302directing the user to the copy of this License. Also, you must do one
303of these things:
304
305@enumerate a
306@item
307Accompany the work with the complete corresponding
308machine-readable source code for the Library including whatever
309changes were used in the work (which must be distributed under
310Sections 1 and 2 above); and, if the work is an executable linked
311with the Library, with the complete machine-readable ``work that
312uses the Library'', as object code and/or source code, so that the
313user can modify the Library and then relink to produce a modified
314executable containing the modified Library. (It is understood
315that the user who changes the contents of definitions files in the
316Library will not necessarily be able to recompile the application
317to use the modified definitions.)
318
319@item
320Use a suitable shared library mechanism for linking with the Library. A
321suitable mechanism is one that (1) uses at run time a copy of the
322library already present on the user's computer system, rather than
323copying library functions into the executable, and (2) will operate
324properly with a modified version of the library, if the user installs
325one, as long as the modified version is interface-compatible with the
326version that the work was made with.
327
328@item
329Accompany the work with a written offer, valid for at
330least three years, to give the same user the materials
331specified in Subsection 6a, above, for a charge no more
332than the cost of performing this distribution.
333
334@item
335If distribution of the work is made by offering access to copy
336from a designated place, offer equivalent access to copy the above
337specified materials from the same place.
338
339@item
340Verify that the user has already received a copy of these
341materials or that you have already sent this user a copy.
342@end enumerate
343
344 For an executable, the required form of the ``work that uses the
345Library'' must include any data and utility programs needed for
346reproducing the executable from it. However, as a special exception,
347the materials to be distributed need not include anything that is
348normally distributed (in either source or binary form) with the major
349components (compiler, kernel, and so on) of the operating system on
350which the executable runs, unless that component itself accompanies the
351executable.
352
353 It may happen that this requirement contradicts the license
354restrictions of other proprietary libraries that do not normally
355accompany the operating system. Such a contradiction means you cannot
356use both them and the Library together in an executable that you
357distribute.
358
359@item
360You may place library facilities that are a work based on the
361Library side-by-side in a single library together with other library
362facilities not covered by this License, and distribute such a combined
363library, provided that the separate distribution of the work based on
364the Library and of the other library facilities is otherwise
365permitted, and provided that you do these two things:
366
367@enumerate a
368@item
369Accompany the combined library with a copy of the same work
370based on the Library, uncombined with any other library
371facilities. This must be distributed under the terms of the
372Sections above.
373
374@item
375Give prominent notice with the combined library of the fact
376that part of it is a work based on the Library, and explaining
377where to find the accompanying uncombined form of the same work.
378@end enumerate
379
380@item
381You may not copy, modify, sublicense, link with, or distribute
382the Library except as expressly provided under this License. Any
383attempt otherwise to copy, modify, sublicense, link with, or
384distribute the Library is void, and will automatically terminate your
385rights under this License. However, parties who have received copies,
386or rights, from you under this License will not have their licenses
387terminated so long as such parties remain in full compliance.
388
389@item
390You are not required to accept this License, since you have not
391signed it. However, nothing else grants you permission to modify or
392distribute the Library or its derivative works. These actions are
393prohibited by law if you do not accept this License. Therefore, by
394modifying or distributing the Library (or any work based on the
395Library), you indicate your acceptance of this License to do so, and
396all its terms and conditions for copying, distributing or modifying
397the Library or works based on it.
398
399@item
400Each time you redistribute the Library (or any work based on the
401Library), the recipient automatically receives a license from the
402original licensor to copy, distribute, link with or modify the Library
403subject to these terms and conditions. You may not impose any further
404restrictions on the recipients' exercise of the rights granted herein.
405You are not responsible for enforcing compliance by third parties with
406this License.
407
408@item
409If, as a consequence of a court judgment or allegation of patent
410infringement or for any other reason (not limited to patent issues),
411conditions are imposed on you (whether by court order, agreement or
412otherwise) that contradict the conditions of this License, they do not
413excuse you from the conditions of this License. If you cannot
414distribute so as to satisfy simultaneously your obligations under this
415License and any other pertinent obligations, then as a consequence you
416may not distribute the Library at all. For example, if a patent
417license would not permit royalty-free redistribution of the Library by
418all those who receive copies directly or indirectly through you, then
419the only way you could satisfy both it and this License would be to
420refrain entirely from distribution of the Library.
421
422If any portion of this section is held invalid or unenforceable under any
423particular circumstance, the balance of the section is intended to apply,
424and the section as a whole is intended to apply in other circumstances.
425
426It is not the purpose of this section to induce you to infringe any
427patents or other property right claims or to contest validity of any
428such claims; this section has the sole purpose of protecting the
429integrity of the free software distribution system which is
430implemented by public license practices. Many people have made
431generous contributions to the wide range of software distributed
432through that system in reliance on consistent application of that
433system; it is up to the author/donor to decide if he or she is willing
434to distribute software through any other system and a licensee cannot
435impose that choice.
436
437This section is intended to make thoroughly clear what is believed to
438be a consequence of the rest of this License.
439
440@item
441If the distribution and/or use of the Library is restricted in
442certain countries either by patents or by copyrighted interfaces, the
443original copyright holder who places the Library under this License may add
444an explicit geographical distribution limitation excluding those countries,
445so that distribution is permitted only in or among countries not thus
446excluded. In such case, this License incorporates the limitation as if
447written in the body of this License.
448
449@item
450The Free Software Foundation may publish revised and/or new
451versions of the Lesser General Public License from time to time.
452Such new versions will be similar in spirit to the present version,
453but may differ in detail to address new problems or concerns.
454
455Each version is given a distinguishing version number. If the Library
456specifies a version number of this License which applies to it and
457``any later version'', you have the option of following the terms and
458conditions either of that version or of any later version published by
459the Free Software Foundation. If the Library does not specify a
460license version number, you may choose any version ever published by
461the Free Software Foundation.
462
463@item
464If you wish to incorporate parts of the Library into other free
465programs whose distribution conditions are incompatible with these,
466write to the author to ask for permission. For software which is
467copyrighted by the Free Software Foundation, write to the Free
468Software Foundation; we sometimes make exceptions for this. Our
469decision will be guided by the two goals of preserving the free status
470of all derivatives of our free software and of promoting the sharing
471and reuse of software generally.
472
473@iftex
474@heading NO WARRANTY
475@end iftex
476@ifinfo
477@center NO WARRANTY
478
479@end ifinfo
480
481@item
482BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
483WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
484EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
485OTHER PARTIES PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY
486KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
487IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
488PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
489LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
490THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
491
492@item
493IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
494WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
495AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
496FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
497CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
498LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
499RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
500FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
501SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
502DAMAGES.
503@end enumerate
504
505@iftex
506@heading END OF TERMS AND CONDITIONS
507@end iftex
508@ifinfo
509@center END OF TERMS AND CONDITIONS
510
511@end ifinfo
512
513@page
514@subheading How to Apply These Terms to Your New Libraries
515
516 If you develop a new library, and you want it to be of the greatest
517possible use to the public, we recommend making it free software that
518everyone can redistribute and change. You can do so by permitting
519redistribution under these terms (or, alternatively, under the terms of the
520ordinary General Public License).
521
522 To apply these terms, attach the following notices to the library. It is
523safest to attach them to the start of each source file to most effectively
524convey the exclusion of warranty; and each file should have at least the
525``copyright'' line and a pointer to where the full notice is found.
526
527@smallexample
528@var{one line to give the library's name and an idea of what it does.}
529Copyright (C) @var{year} @var{name of author}
530
531This library is free software; you can redistribute it and/or modify it
532under the terms of the GNU Lesser General Public License as published by
533the Free Software Foundation; either version 2.1 of the License, or (at
534your option) any later version.
535
536This library is distributed in the hope that it will be useful, but
537WITHOUT ANY WARRANTY; without even the implied warranty of
538MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
539Lesser General Public License for more details.
540
541You should have received a copy of the GNU Lesser General Public
542License along with this library; if not, write to the Free Software
543Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
544USA.
545@end smallexample
546
547Also add information on how to contact you by electronic and paper mail.
548
549You should also get your employer (if you work as a programmer) or your
550school, if any, to sign a ``copyright disclaimer'' for the library, if
551necessary. Here is a sample; alter the names:
552
553@smallexample
554Yoyodyne, Inc., hereby disclaims all copyright interest in the library
555`Frob' (a library for tweaking knobs) written by James Random Hacker.
556
557@var{signature of Ty Coon}, 1 April 1990
558Ty Coon, President of Vice
559@end smallexample
560
561That's all there is to it!
diff --git a/doc/microhttpd.texi b/doc/microhttpd.texi
index 8d061179..4e0ad512 100644
--- a/doc/microhttpd.texi
+++ b/doc/microhttpd.texi
@@ -1,4 +1,48 @@
1\input texinfo
1@setfilename microhttpd.info 2@setfilename microhttpd.info
3@include version.texi
4@settitle The libmicrohttpd Reference Manual
5@c Unify some of the indices.
6@c %**end of header
7@copying
8This manual documents libmicrohttpd version @value{VERSION}, last
9updated @value{UPDATED}. It is built upon the documentation in the
10header file @file{microhttpd.h}.
11
12@noindent
13
14Copyright @copyright{} 2007, 2008 Christian Grothoff
15
16@quotation
17FIXME: add license terms here!
18@end quotation
19@end copying
20
21@dircategory GNU Libraries
22@direntry
23* libmicrohttpd: (microhttpd). Embedded HTTP server library.
24@end direntry
25
26@c
27@c Titlepage
28@c
29@setchapternewpage odd
30@titlepage
31@title The libmicrohttpd Reference Manual
32@subtitle Version @value{VERSION}
33@subtitle @value{UPDATED}
34@author Marco Maggi (@email{marco.maggi-ipsu@@poste.it})
35@author Christian Grothoff (@email{christian@@grothoff.org})
36
37@page
38@vskip 0pt plus 1filll
39@insertcopying
40@end titlepage
41
42@summarycontents
43@contents
44@page
45
2 46
3@macro gnu{} 47@macro gnu{}
4@acronym{GNU} 48@acronym{GNU}
@@ -34,14 +78,18 @@
34 78
35@c ............................................................ 79@c ............................................................
36 80
37@macro cfunction{NAME} 81@macro cfunction{arg}
38@code{\NAME\()} 82@code{\arg\()}
39@end macro 83@end macro
40 84
41@macro null{} 85@macro mynull{}
42@code{NULL} 86@code{NULL}
43@end macro 87@end macro
44 88
89@macro mhd{}
90@acronym{MHD}
91@end macro
92
45@c ............................................................ 93@c ............................................................
46 94
47@macro glibcref{NODE, NODE} 95@macro glibcref{NODE, NODE}
@@ -52,36 +100,40 @@
52 100
53 101
54@c ------------------------------------------------------------ 102@c ------------------------------------------------------------
55@node microhttpd 103@ifnottex
56@appendix Libmicrohttpd documentation 104@node Top
57 105@top The libmicrohttpd Library
58 106@insertcopying
59@macro mhd{} 107@end ifnottex
60@acronym{MHD}
61@end macro
62
63
64@noindent
65This appendix documents Libmicrohttpd version 0.1.2. It is built upon
66the documentation in the header file @file{microhttpd.h}.
67 108
68@menu 109@menu
69* microhttpd intro:: Introduction. 110* microhttpd-intro:: Introduction.
70* microhttpd const:: Constants. 111* microhttpd-const:: Constants.
71* microhttpd struct:: Structures type definition. 112* microhttpd-struct:: Structures type definition.
72* microhttpd cb:: Callback functions definition. 113* microhttpd-cb:: Callback functions definition.
73* microhttpd init:: Starting and stopping the server. 114* microhttpd-init:: Starting and stopping the server.
74* microhttpd inspect:: Inspection. 115* microhttpd-inspect:: Implementing external @code{select}.
75* microhttpd requests:: Handling requests. 116* microhttpd-requests:: Handling requests.
76* microhttpd responses:: Building responses to requests. 117* microhttpd-responses:: Building responses to requests.
77* microhttpd post:: Adding a @code{POST} processor. 118* microhttpd-post:: Adding a @code{POST} processor.
119
120Appendices
121
122* Copying:: The GNU Lesser General Public License says how you
123 can copy and share some parts of `libmicrohttpd'.
124
125Indices
126
127* Concept Index:: Index of concepts and programs.
128* Function and Data Index:: Index of functions, variables and data types.
129* Type Index:: Index of data types.
78@end menu 130@end menu
79 131
80@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 132@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
81 133
82@c ------------------------------------------------------------ 134@c ------------------------------------------------------------
83@node microhttpd intro 135@node microhttpd-intro
84@appendixsec Introduction 136@chapter Introduction
85 137
86 138
87@noindent 139@noindent
@@ -103,11 +155,11 @@ library also understands headers that control connection management
103are understood and handled automatically). 155are understood and handled automatically).
104 156
105@mhd{} understands @code{POST} data and is able to decode certain 157@mhd{} understands @code{POST} data and is able to decode certain
106formats (at the moment only @code{application/x-www-form-urlencoded}) if 158formats (at the moment only @code{application/x-www-form-urlencoded}
107the entire data fits into the allowed amount of memory for the 159and @code{multipart/form-data}) using the post processor API. The
108connection. Unsupported encodings and large @code{POST} submissions are 160data stream of a POST is also provided directly to the main
109provided as a stream to the main application (and thus can be processed, 161application, so unsupported encodings could still be processed, just
110just not conveniently by @mhd{}). 162not conveniently by @mhd{}.
111 163
112The header file defines various constants used by the @http{} protocol. 164The header file defines various constants used by the @http{} protocol.
113This does not mean that @mhd{} actually interprets all of these values. 165This does not mean that @mhd{} actually interprets all of these values.
@@ -118,15 +170,19 @@ define their own extensions of the @http{} standard and use those with
118@mhd{}. 170@mhd{}.
119 171
120All functions are guaranteed to be completely reentrant and 172All functions are guaranteed to be completely reentrant and
121thread-safe. 173thread-safe. @mhd{} checks for allocation failures and tries to
174recover gracefully (for example, by closing the connection).
175Additionally, clients can specify resource limits on the overall
176number of connections, number of connections per IP address and memory
177used per connection to avoid resource exhaustion.
122 178
123 179
124 180
125@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 181@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
126 182
127@c ------------------------------------------------------------ 183@c ------------------------------------------------------------
128@node microhttpd const 184@node microhttpd-const
129@appendixsec Constants 185@chapter Constants
130 186
131 187
132@deftp {Enumeration} MHD_FLAG 188@deftp {Enumeration} MHD_FLAG
@@ -146,10 +202,12 @@ No options selected.
146 202
147@item MHD_USE_DEBUG 203@item MHD_USE_DEBUG
148Run in debug mode. If this flag is used, the library should print error 204Run in debug mode. If this flag is used, the library should print error
149messages and warnings to stderr. 205messages and warnings to stderr. Note that @mhd{} also needs to be
206compiled with the configure option @code{--enable-messages} for this
207run-time option to have any effect.
150 208
151@item MHD_USE_SSL 209@item MHD_USE_SSL
152Run in https mode. 210Run in https mode (this is not yet supported).
153 211
154@item MHD_USE_THREAD_PER_CONNECTION 212@item MHD_USE_THREAD_PER_CONNECTION
155Run using one thread per connection. 213Run using one thread per connection.
@@ -204,7 +262,21 @@ notifications.
204This option should be followed by @strong{TWO} pointers. First a 262This option should be followed by @strong{TWO} pointers. First a
205pointer to a function of type @cfunction{MHD_RequestCompletedCallback} 263pointer to a function of type @cfunction{MHD_RequestCompletedCallback}
206and second a pointer to a closure to pass to the request completed 264and second a pointer to a closure to pass to the request completed
207callback. The second pointer maybe @null{}. 265callback. The second pointer maybe @mynull{}.
266
267
268@item MHD_OPTION_PER_IP_CONNECTION_LIMIT
269Limit on the number of (concurrent) connections made to the
270server from the same IP address. Can be used to prevent one
271IP from taking over all of the allowed connections. If the
272same IP tries to establish more than the specified number of
273connections, they will be immediately rejected. The option
274should be followed by an @code{unsigned int}. The default is
275zero, which means no limit on the number of connections
276from the same IP address.
277
278
279
208@end table 280@end table
209@end deftp 281@end deftp
210 282
@@ -234,6 +306,10 @@ already been processed).
234 306
235@item MHD_GET_ARGUMENT_KIND 307@item MHD_GET_ARGUMENT_KIND
236@code{GET} (@uri{}) arguments. 308@code{GET} (@uri{}) arguments.
309
310@item MHD_HEADER_KIND
311@http{} footer (only for http 1.1 chunked encodings).
312
237@end table 313@end table
238@end deftp 314@end deftp
239 315
@@ -263,8 +339,8 @@ We had to close the session since @mhd{} was being shut down.
263@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 339@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
264 340
265@c ------------------------------------------------------------ 341@c ------------------------------------------------------------
266@node microhttpd struct 342@node microhttpd-struct
267@appendixsec Structures type definition 343@chapter Structures type definition
268 344
269 345
270@deftp {C Struct} MHD_Daemon 346@deftp {C Struct} MHD_Daemon
@@ -292,8 +368,8 @@ Handle for @code{POST} processing.
292@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 368@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
293 369
294@c ------------------------------------------------------------ 370@c ------------------------------------------------------------
295@node microhttpd cb 371@node microhttpd-cb
296@appendixsec Callback functions definition 372@chapter Callback functions definition
297 373
298 374
299@deftypefn {Function Pointer} int {*MHD_AcceptPolicyCallback} (void *cls, const struct sockaddr * addr, socklen_t addrlen) 375@deftypefn {Function Pointer} int {*MHD_AcceptPolicyCallback} (void *cls, const struct sockaddr * addr, socklen_t addrlen)
@@ -319,7 +395,7 @@ client. This callback must call @mhd{} functions (example: the
319and return an @http{} status code (i.e. @code{200} for OK, @code{404}, 395and return an @http{} status code (i.e. @code{200} for OK, @code{404},
320etc.). 396etc.).
321 397
322@ref{microhttpd post}, for details on how to code this callback. 398@ref{microhttpd-post}, for details on how to code this callback.
323 399
324Must return @code{MHD_YES} if the connection was handled successfully, 400Must return @code{MHD_YES} if the connection was handled successfully,
325@code{MHD_NO} if the socket must be closed due to a serious error while 401@code{MHD_NO} if the socket must be closed due to a serious error while
@@ -360,7 +436,7 @@ callback must update this value to the number of bytes @strong{NOT}
360processed; 436processed;
361 437
362@item con_cls 438@item con_cls
363reference to a pointer, initially set to @null{}, that this callback can 439reference to a pointer, initially set to @mynull{}, that this callback can
364set to some address and that will be preserved by @mhd{} for future 440set to some address and that will be preserved by @mhd{} for future
365calls for this request; 441calls for this request;
366 442
@@ -459,13 +535,13 @@ type of the value;
459zero-terminated key for the value; 535zero-terminated key for the value;
460 536
461@item filename 537@item filename
462name of the uploaded file, @null{} if not known; 538name of the uploaded file, @mynull{} if not known;
463 539
464@item content_type 540@item content_type
465mime-type of the data, @null{} if not known; 541mime-type of the data, @mynull{} if not known;
466 542
467@item transfer_encoding 543@item transfer_encoding
468encoding of the data, @null{} if not known; 544encoding of the data, @mynull{} if not known;
469 545
470@item data 546@item data
471pointer to size bytes of data at the specified offset; 547pointer to size bytes of data at the specified offset;
@@ -485,8 +561,8 @@ iteration.
485@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 561@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
486 562
487@c ------------------------------------------------------------ 563@c ------------------------------------------------------------
488@node microhttpd init 564@node microhttpd-init
489@appendixsec Starting and stopping the server 565@chapter Starting and stopping the server
490 566
491 567
492@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, ...) 568@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, ...)
@@ -501,7 +577,7 @@ port to bind to;
501 577
502@item apc 578@item apc
503callback to call to check which clients will be allowed to connect; you 579callback to call to check which clients will be allowed to connect; you
504can pass @null{} in which case connections from any @acronym{IP} will be 580can pass @mynull{} in which case connections from any @acronym{IP} will be
505accepted; 581accepted;
506 582
507@item apc_cls 583@item apc_cls
@@ -519,7 +595,7 @@ terminated with @code{MHD_OPTION_END}). It is mandatory to use
519@code{MHD_OPTION_END} as last argument, even when there are no 595@code{MHD_OPTION_END} as last argument, even when there are no
520additional arguments. 596additional arguments.
521 597
522Return @null{} on error, handle to daemon on success. 598Return @mynull{} on error, handle to daemon on success.
523@end deftypefun 599@end deftypefun
524 600
525 601
@@ -542,8 +618,8 @@ started with the right options for this call.
542@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 618@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
543 619
544@c ----------------------------------------------------------- 620@c -----------------------------------------------------------
545@node microhttpd inspect 621@node microhttpd-inspect
546@appendixsec Inspection 622@chapter Implementing external @code{select}
547 623
548 624
549@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) 625@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)
@@ -560,7 +636,7 @@ identifier. The variable must be set to zero before invoking this
560function. 636function.
561 637
562Return @code{MHD_YES} on success, @code{MHD_NO} if: the arguments are 638Return @code{MHD_YES} on success, @code{MHD_NO} if: the arguments are
563invalid (example: @null{} pointers); this daemon was not started with 639invalid (example: @mynull{} pointers); this daemon was not started with
564the right options for this call. 640the right options for this call.
565@end deftypefun 641@end deftypefun
566 642
@@ -585,71 +661,8 @@ right now).
585@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 661@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
586 662
587@c ----------------------------------------------------------- 663@c -----------------------------------------------------------
588@node microhttpd requests 664@node microhttpd-requests
589@appendixsec Handling requests 665@chapter Handling requests
590
591
592@menu
593* microhttpd handlers:: @uri{} specific handlers.
594* microhttpd values:: Connection headers and small
595 @code{POST} data.
596@end menu
597
598
599@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
600
601@c ------------------------------------------------------------
602@node microhttpd handlers
603@appendixsubsec @uri{} specific handlers
604
605
606@noindent
607A set of callbacks can be registered in the state of a daemon
608(@code{MHD_Daemon}) to handle request for specific sets of
609resources. The set is selected by specifying the prefix string of the
610@uri{}, example:
611
612@example
613/bookcase
614@end example
615
616@noindent
617matches all of the following:
618
619@example
620/bookcase/book.html
621/bookcase/pencil.html
622/bookcase/strawberry.html
623@end example
624
625Handlers are stored in a linked list (managed with @cfunction{malloc}
626and @cfunction{free}). Prefixes are compared with @cfunction{strcmp}.
627
628
629@deftypefun int MHD_register_handler (struct MHD_Daemon *daemon, const char *uri_prefix, MHD_AccessHandlerCallback dh, void *dh_cls)
630Register an access handler for all @uri{}s beginning with
631@var{uri_prefix}, a zero-terminated @ascii{}-coded string.
632
633Return @code{MRI_NO} if: the arguments are invalid (example: @null{}
634pointers); a handler for this exact prefix already exists; an error
635allocating memory happens.
636@end deftypefun
637
638
639@deftypefun int MHD_unregister_handler (struct MHD_Daemon *daemon, const char *uri_prefix, MHD_AccessHandlerCallback dh, void *dh_cls)
640Unregister an access handler for the @uri{}s beginning with
641@var{uri_prefix}.
642
643Return @code{MHD_NO} if: the arguments are invalid (example: @null{}
644pointers); a handler for this exact prefix is not known for this daemon.
645@end deftypefun
646
647
648@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
649
650@c ------------------------------------------------------------
651@node microhttpd values
652@appendixsubsec Connection headers and small @code{POST} data
653 666
654 667
655@deftypefun int MHD_get_connection_values (struct MHD_Connection *connection, enum MHD_ValueKind kind, MHD_KeyValueIterator iterator, void *iterator_cls) 668@deftypefun int MHD_get_connection_values (struct MHD_Connection *connection, enum MHD_ValueKind kind, MHD_KeyValueIterator iterator, void *iterator_cls)
@@ -660,7 +673,7 @@ The @var{iterator} callback is invoked once for each header, with
660iterated over; this can be less than the number of headers if, while 673iterated over; this can be less than the number of headers if, while
661iterating, @var{iterator} returns @code{MHD_NO}. 674iterating, @var{iterator} returns @code{MHD_NO}.
662 675
663@var{iterator} can be @null{}: in this case this function just counts 676@var{iterator} can be @mynull{}: in this case this function just counts
664and returns the number of headers. 677and returns the number of headers.
665@end deftypefun 678@end deftypefun
666 679
@@ -670,7 +683,7 @@ Get a particular header value. If multiple values match the @var{kind},
670return one of them (the ``first'', whatever that means). @var{key} must 683return one of them (the ``first'', whatever that means). @var{key} must
671reference a zero-terminated @ascii{}-coded string representing the 684reference a zero-terminated @ascii{}-coded string representing the
672header to look for: it is compared against the headers using 685header to look for: it is compared against the headers using
673@cfunction{strcasecmp}, so case is ignored. Return @null{} if no such 686@cfunction{strcasecmp}, so case is ignored. Return @mynull{} if no such
674item was found. 687item was found.
675@end deftypefun 688@end deftypefun
676 689
@@ -678,15 +691,15 @@ item was found.
678@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 691@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
679 692
680@c ------------------------------------------------------------ 693@c ------------------------------------------------------------
681@node microhttpd responses 694@node microhttpd-responses
682@appendixsec Building answers to responses 695@chapter Building answers to responses
683 696
684 697
685@menu 698@menu
686* microhttpd response enqueue:: Enqueuing a response. 699* microhttpd-response enqueue:: Enqueuing a response.
687* microhttpd response create:: Creating a response object. 700* microhttpd-response create:: Creating a response object.
688* microhttpd response headers:: Adding headers to a response. 701* microhttpd-response headers:: Adding headers to a response.
689* microhttpd response inspect:: Inspecting a response object. 702* microhttpd-response inspect:: Inspecting a response object.
690@end menu 703@end menu
691 704
692 705
@@ -709,8 +722,8 @@ responce and we finally destroy it only when the daemon shuts down.
709@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 722@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
710 723
711@c ------------------------------------------------------------ 724@c ------------------------------------------------------------
712@node microhttpd response enqueue 725@node microhttpd-response enqueue
713@appendixsubsec Enqueuing a response 726@@section Enqueuing a response
714 727
715 728
716@deftypefun int MHD_queue_response (struct MHD_Connection *connection, unsigned int status_code, struct MHD_Response *response) 729@deftypefun int MHD_queue_response (struct MHD_Connection *connection, unsigned int status_code, struct MHD_Response *response)
@@ -729,7 +742,7 @@ response to transmit.
729@end table 742@end table
730 743
731Return @code{MHD_YES} on success or if message has been queued. Return 744Return @code{MHD_YES} on success or if message has been queued. Return
732@code{MHD_NO}: if arguments are invalid (example: @null{} pointer); on 745@code{MHD_NO}: if arguments are invalid (example: @mynull{} pointer); on
733error (i.e. reply already sent). 746error (i.e. reply already sent).
734@end deftypefun 747@end deftypefun
735 748
@@ -784,8 +797,8 @@ the @code{MHD_Response} object is released.
784@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 797@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
785 798
786@c ------------------------------------------------------------ 799@c ------------------------------------------------------------
787@node microhttpd response create 800@node microhttpd-response create
788@appendixsubsec Creating response objects 801@@section Creating response objects
789 802
790 803
791@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) 804@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)
@@ -812,7 +825,7 @@ extra argument to @var{crc};
812callback to call to free @var{crc_cls} resources. 825callback to call to free @var{crc_cls} resources.
813@end table 826@end table
814 827
815Return @null{} on error (i.e. invalid arguments, out of memory). 828Return @mynull{} on error (i.e. invalid arguments, out of memory).
816@end deftypefun 829@end deftypefun
817 830
818 831
@@ -837,7 +850,7 @@ handling of the embedded memory is responsibility of @mhd{}; @var{data}
837can be released anytime after this call returns. 850can be released anytime after this call returns.
838@end table 851@end table
839 852
840Return @null{} on error (i.e. invalid arguments, out of memory). 853Return @mynull{} on error (i.e. invalid arguments, out of memory).
841@end deftypefun 854@end deftypefun
842 855
843 856
@@ -860,8 +873,8 @@ MHD_destroy_response(response);
860@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 873@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
861 874
862@c ------------------------------------------------------------ 875@c ------------------------------------------------------------
863@node microhttpd response headers 876@node microhttpd-response headers
864@appendixsubsec Adding headers to a response 877@@section Adding headers to a response
865 878
866 879
867@deftypefun int MHD_add_response_header (struct MHD_Response *response, const char *header, const char *content) 880@deftypefun int MHD_add_response_header (struct MHD_Response *response, const char *header, const char *content)
@@ -886,8 +899,8 @@ Delete a header line from the response. Return @code{MHD_NO} on error
886@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 899@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
887 900
888@c ------------------------------------------------------------ 901@c ------------------------------------------------------------
889@node microhttpd response inspect 902@node microhttpd-response inspect
890@appendixsubsec Inspecting a response object 903@@section Inspecting a response object
891 904
892 905
893@deftypefun int MHD_get_response_headers (struct MHD_Response *response, MHD_KeyValueIterator iterator, void *iterator_cls) 906@deftypefun int MHD_get_response_headers (struct MHD_Response *response, MHD_KeyValueIterator iterator, void *iterator_cls)
@@ -895,7 +908,7 @@ Get all of the headers added to a response.
895 908
896Invoke the @var{iterator} callback for each header in the response, 909Invoke the @var{iterator} callback for each header in the response,
897using @var{iterator_cls} as first argument. Return number of entries 910using @var{iterator_cls} as first argument. Return number of entries
898iterated over. @var{iterator} can be @null{}: in this case the function 911iterated over. @var{iterator} can be @mynull{}: in this case the function
899just counts headers. 912just counts headers.
900 913
901@var{iterator} should not modify the its key and value arguments, unless 914@var{iterator} should not modify the its key and value arguments, unless
@@ -907,7 +920,7 @@ we know what we are doing.
907Find and return a pointer to the value of a particular header from the 920Find and return a pointer to the value of a particular header from the
908response. @var{key} must reference a zero-terminated string 921response. @var{key} must reference a zero-terminated string
909representing the header to look for. The search is case sensitive. 922representing the header to look for. The search is case sensitive.
910Return @null{} if header does not exist or @var{key} is @null{}. 923Return @mynull{} if header does not exist or @var{key} is @mynull{}.
911 924
912We should not modify the value, unless we know what we are doing. 925We should not modify the value, unless we know what we are doing.
913@end deftypefun 926@end deftypefun
@@ -916,35 +929,33 @@ We should not modify the value, unless we know what we are doing.
916@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 929@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
917 930
918@c ------------------------------------------------------------ 931@c ------------------------------------------------------------
919@node microhttpd post 932@node microhttpd-post
920@appendixsec Adding a @code{POST} processor 933@chapter Adding a @code{POST} processor
921 934
922 935
923@menu 936@menu
924* microhttpd post api:: Programming interface for the 937* microhttpd-post api:: Programming interface for the
925 @code{POST} processor. 938 @code{POST} processor.
926@end menu 939@end menu
927 940
928 941
929@noindent 942@noindent
930When a small amount of data comes from a client's @code{POST} request: 943@mhd{} provides the post procesor API to make it easier for applications to
931the data is available through the values interface. @ref{microhttpd 944parse the data of a client's @code{POST} request: the
932values}, for details. In this case @mhd{} invokes
933@code{MHD_AccessHandlerCallback} only once and the callback must process
934all the data during that invocation.
935
936When a big amount of data comes from a client's @code{POST} request: the
937@code{MHD_AccessHandlerCallback} will be invoked multiple times to 945@code{MHD_AccessHandlerCallback} will be invoked multiple times to
938process data as it arrives; at each invocation a new chunk of data must 946process data as it arrives; at each invocation a new chunk of data must
939be processed. The arguments @var{upload_data} and @var{upload_data_size} 947be processed. The arguments @var{upload_data} and @var{upload_data_size}
940are used to reference the chunk of data. 948are used to reference the chunk of data.
941 949
942When @code{MHD_AccessHandlerCallback} is invoked for a new connection: 950When @code{MHD_AccessHandlerCallback} is invoked for a new connection:
943its @code{*@var{con_cls}} argument is set to @null{}. When @code{POST} 951its @code{*@var{con_cls}} argument is set to @mynull{}. When @code{POST}
944data comes in the upload buffer it is @strong{mandatory} to use the 952data comes in the upload buffer it is @strong{mandatory} to use the
945@var{con_cls} to hold data or to mark an ongoing process. 953@var{con_cls} to store a reference to per-connection data. The fact
954that the pointer was initially @mynull{} can be used to detect that
955this is a new request.
946 956
947To detect that a new connection has come with the @code{POST} method: 957One method to detect that a new connection was established is
958to set @code{*con_cls} to anunused integer:
948 959
949@example 960@example
950int 961int
@@ -956,10 +967,9 @@ access_handler (void *cls,
956 void **con_cls) 967 void **con_cls)
957@{ 968@{
958 static int old_connection_marker; 969 static int old_connection_marker;
959 int new_connection = (NULL == *con_cls); 970 int new_connection = (MYNULL == *con_cls);
960 int method_is_post = strcmp("POST",method);
961 971
962 if (new_connection && method_is_post) 972 if (new_connection)
963 @{ 973 @{
964 /* new connection with POST */ 974 /* new connection with POST */
965 *con_cls = &old_connection_marker; 975 *con_cls = &old_connection_marker;
@@ -970,12 +980,10 @@ access_handler (void *cls,
970@end example 980@end example
971 981
972@noindent 982@noindent
973in this example the value of @code{*con_cls} is just an unused pointer 983In contrast to the previous example, for @code{POST} requests in particular,
974to an unused integer: its purpose is to make @code{*con_cls} different 984it is more common to use the value of @code{*con_cls} to keep track of
975from @null{}. When serious processing of @code{POST} data is needed: it 985actual state used during processing, such as the post processor (or a
976can be a pointer to a dynamically allocated data structure. 986struct containing a post processor):
977
978To detect that @code{POST} data is in the upload buffer:
979 987
980@example 988@example
981int 989int
@@ -986,156 +994,38 @@ access_handler (void *cls,
986 const char *upload_data, unsigned int *upload_data_size, 994 const char *upload_data, unsigned int *upload_data_size,
987 void **con_cls) 995 void **con_cls)
988@{ 996@{
989 static int old_connection_marker; 997 struct MHD_PostProcessor * pp = *con_cls;
990 int new_connection = (NULL == *con_cls);
991 int method_is_post = strcmp("POST",method);
992 998
993 if (new_connection && method_is_post) 999 if (pp == NULL)
994 @{ 1000 @{
995 int data_in_upload_buffer = (0 != *upload_data_size); 1001 pp = MHD_create_post_processor(connection, ...);
996 1002 *con_cls = pp;
997 if (data_in_upload_buffer) 1003 return MHD_YES;
998 @{
999 *con_cls = &old_connection_marker;
1000 /* POST data in the buffer */
1001 @}
1002 else
1003 /* POST data accessible with the values API */
1004 @}
1005
1006 ...
1007@}
1008@end example
1009
1010
1011At each invocation there are two options:
1012
1013@enumerate
1014@item
1015the callback can process the whole chunk by itself; every time @mhd{}
1016invokes it a new chunk is fully processed; with this mode the callback
1017has to @code{*upload_data_size = 0} before returning @code{MHD_YES};
1018
1019@item
1020the callback can process a section of the chunk by itself; every time
1021@mhd{} invokes it the buffer holds the old data as well as new data
1022coming from the client; with this mode the callback has to set
1023@code{*upload_data_size} to the numbe of bytes still to process before
1024returning @code{MHD_YES};
1025
1026example: @mhd{} invokes the callback with @code{100 ==
1027*upload_data_size}; the callback processes the first 80 bytes and before
1028returning the callback sets @code{*upload_data_size = 20}; the last
1029unprocessed 20 bytes will be the first 20 at the next invocation;
1030
1031@item
1032when a new connection with @code{POST} data in the buffer comes: the
1033callback allocates a PostProcessor and hand to it the responsibility of
1034processing data; a pointer to the PostProcessor structure is saved in
1035@code{*con_cls}, so that it is available at each subsequent invocation;
1036
1037the post processor data can be freed by a later invocation to an
1038appropriate callback.
1039@end enumerate
1040
1041
1042Let's see how to implement strategy 1:
1043
1044@example
1045int
1046access_handler (void *cls,
1047 struct MHD_Connection * connection,
1048 const char *url,
1049 const char *method, const char *version,
1050 const char *upload_data, unsigned int *upload_data_size,
1051 void **con_cls)
1052@{
1053 static int old_connection_marker;
1054 int new_connection = (NULL == *con_cls);
1055 int method_is_post = strcmp("POST",method);
1056
1057 if (new_connection && method_is_post)
1058 @{
1059 int data_in_upload_buffer = (0 != *upload_data_size);
1060
1061 if (data_in_upload_buffer)
1062 @{
1063 *con_cls = &old_connection_marker;
1064 @}
1065 else
1066 @{
1067 /* POST data accessible with the values API */
1068 return MHD_YES;
1069 @}
1070 @} 1004 @}
1071 1005 if (*upload_data_size)
1072 if (&old_connection_marker == *con_cls)
1073 @{ 1006 @{
1074 consume_data(upload_data, *upload_data_size); 1007 MHD_post_process(pp, upload_data, *upload_data_size);
1075 *upload_data_size = 0; 1008 *upload_data_size = 0;
1076 return MHD_YES; 1009 return MHD_YES;
1077 @} 1010 @}
1078 1011 else
1079 /* process other methods */
1080 return MHD_YES;
1081@}
1082@end example
1083
1084Let's see how to implement strategy 2:
1085
1086@example
1087int
1088access_handler (void *cls,
1089 struct MHD_Connection * connection,
1090 const char *url,
1091 const char *method, const char *version,
1092 const char *upload_data, unsigned int *upload_data_size,
1093 void **con_cls)
1094@{
1095 static int old_connection_marker;
1096 int new_connection = (NULL == *con_cls);
1097 int method_is_post = strcmp("POST",method);
1098
1099 if (new_connection && method_is_post)
1100 @{ 1012 @{
1101 int data_in_upload_buffer = (0 != *upload_data_size); 1013 return MHD_queue_response(...);
1102
1103 if (data_in_upload_buffer)
1104 @{
1105 *con_cls = &old_connection_marker;
1106 @}
1107 else
1108 @{
1109 /* POST data accessible with the values API */
1110 return MHD_YES;
1111 @}
1112 @} 1014 @}
1113
1114 if (&old_connection_marker == *con_cls)
1115 @{
1116 int number_of_bytes_to_consume = 100;
1117
1118 if (number_of_bytes_to_consume > *upload_data_size)
1119 number_of_bytes_to_consume = *upload_data_size;
1120
1121 consume_some_data(upload_data, number_of_bytes_to_consume);
1122 *upload_data_size -= number_of_bytes_to_consume;
1123 return MHD_YES;
1124 @}
1125
1126 /* process other methods */
1127 return MHD_YES;
1128@} 1015@}
1129
1130@end example 1016@end example
1131 1017
1018Note that the callback from @code{MHD_OPTION_NOTIFY_COMPLETED}
1019should be used to destroy the post processor. This cannot be
1020done inside of the access handler since the connection may not
1021always terminate normally.
1132 1022
1133 1023
1134@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1024@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1135 1025
1136@c ------------------------------------------------------------ 1026@c ------------------------------------------------------------
1137@node microhttpd post api 1027@node microhttpd-post api
1138@appendixsubsec Programming interface for the @code{POST} processor 1028@@section Programming interface for the @code{POST} processor
1139 1029
1140 1030
1141 1031
@@ -1155,13 +1045,13 @@ should be sufficient; do @strong{NOT} use a value smaller than 256;
1155 1045
1156@item iterator 1046@item iterator
1157iterator to be called with the parsed data; must @strong{NOT} be 1047iterator to be called with the parsed data; must @strong{NOT} be
1158@null{}; 1048@mynull{};
1159 1049
1160@item iterator_cls 1050@item iterator_cls
1161custom value to be used as first argument to @var{iterator}. 1051custom value to be used as first argument to @var{iterator}.
1162@end table 1052@end table
1163 1053
1164Return @null{} on error (out of memory, unsupported encoding), otherwise 1054Return @mynull{} on error (out of memory, unsupported encoding), otherwise
1165a PP handle. 1055a PP handle.
1166@end deftypefun 1056@end deftypefun
1167 1057
@@ -1196,3 +1086,26 @@ Release PostProcessor resources.
1196 1086
1197@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1087@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1198 1088
1089
1090@c **********************************************************
1091@c ******************* Appendices *************************
1092@c **********************************************************
1093
1094@include lgpl.texi
1095
1096@node Concept Index
1097@unnumbered Concept Index
1098
1099@printindex cp
1100
1101@node Function and Data Index
1102@unnumbered Function and Data Index
1103
1104@printindex fn
1105
1106@node Type Index
1107@unnumbered Type Index
1108
1109@printindex tp
1110
1111@bye