doptions.inc (3509B)
1 @anchor{MHD_DaemonOptionAndValue} 2 @cindex option 3 4 This chapter is about configuring an MHD daemon. MHD daemon 5 configuration options are represented using a @code{struct 6 MHD_DameonOptionAndValue}. However, applications should never be 7 concerned with the internals of this data structure, and only use the 8 provided API functions and macros explained in this chapter to 9 construct these options. 10 11 @node libmicrohttpd-daemon-options-setting 12 @section Setting daemon options 13 14 MHD offers three main ways to set options for a @code{struct MHD_Daemon}: 15 16 @itemize 17 @item @code{MHD_daemon_set_options()} sets an array of options, 18 @item @code{MHD_daemon_set_option()} sets an individual option, and 19 @item @code{MHD_DAEMON_SET_OPTIONS()} sets a list of options. 20 @end itemize 21 22 All three approaches can be combined for the same daemon 23 to set various options. We will now look at each of them. 24 25 @code{MHD_daemon_set_options()} is useful if the application needs 26 complex code to first initialize a set of options, or if it has a 27 static data buffer with all of the options (say in ROM). It is also 28 the underlying function used to implement the other styles. 29 30 @anchor{MHD_daemon_set_options} 31 @deftypefun {struct MHD_StatusCode} MHD_daemon_set_options (struct MHD_Daemon *daemon, const struct MHD_DaemonOptionAndValue *options, size_t options_max_num) 32 33 @table @var 34 @item daemon 35 the daemon to configure 36 37 @item options 38 array of options to set, either @code{MHD_D_OPTION_TERIMINATE()}-terminated or 39 limited by @var{options_max_num} (whatever comes first). 40 41 @item options_max_num 42 maximum number of options to process from the @var{options} array, 43 or @code{MHD_OPTIONS_ARRAY_MAX_SIZE} to process all options from 44 @var{options} until the @code{MHD_D_OPTION_TERMINATE()}-terminator. 45 46 @end table 47 48 Returns @code{MHD_SC_OK} on success, otherwise the error code of 49 the first option that could not be set. 50 @end deftypefun 51 52 To set only a single option, MHD defines a simple convenience API with 53 @code{MHD_daemon_set_option()}. This is useful if there is only one 54 option to be set, or if error handling for that specific option is 55 somehow special (like not failing when setting this particular option 56 failed). 57 58 @anchor{MHD_DAEMON_set_option} 59 @deftypefun {struct MHD_StatusCode} MHD_daemon_set_option (struct MHD_Daemon *daemon, const struct MHD_DaemonOptionAndValue *option) 60 61 @table @var 62 @item daemon 63 the daemon to configure 64 65 @item option 66 the option to set 67 68 @end table 69 70 Returns @code{MHD_SC_OK} on success, otherwise the error code from 71 trying to set the @var{option}. 72 @end deftypefun 73 74 75 An easy way to set a bunch of options without having to worry 76 about explicitly allocating an array or checking each return 77 value is to use @code{MHD_DAEMON_SET_OPTIONS()}. 78 79 @anchor{MHD_DAEMON_SET_OPTIONS} 80 @deftypefun {struct MHD_StatusCode} MHD_DAEMON_SET_OPTIONS (struct MHD_Daemon *daemon, ...) 81 82 @table @var 83 @item daemon 84 the daemon to configure 85 86 @item ... 87 variable-length list of @code{MHD_DaemonOptionAndValue} options 88 to set; does @emph{not} need to be terminated via 89 @code{MHD_D_OPTION_TERMINATE()} as such a terminator is added 90 automatically. 91 92 @end table 93 94 Returns @code{MHD_SC_OK} on success, otherwise the error code of 95 the first option that could not be set. 96 @end deftypefun 97 98 The following example illustrates how to set daemon options: 99 100 @example 101 @verbatiminclude examples/options-example.c 102 @end example 103 104 The remaining sections of this chapter discuss the various 105 daemon options available to applications today. 106 107 @include manual/daemon_options.inc