introspection.inc (21127B)
1 This chapter explains how applications can introspect the state of the 2 MHD library, a @code{struct MHD_Daemon}, a @code{struct 3 MHD_Connection}, a @code{struct MHD_Session} or a 4 @code{MHD_Request}. Now, until now most of the discussed APIs have 5 primarily interacted with a daemon or a request, which raises the 6 question how applications can even get hold of a connection or 7 session. The two main ways are either to set daemon options to receive 8 callbacks (say when a connection or session is established or 9 completed), or via introspection of a given request. 10 11 All introspection APIs work in a similar way: they are given the 12 object to inspect, a member of an enumeration specifying what 13 property the application is interested in, and a pointer to a 14 @code{union} where MHD is to store the value of the property. 15 16 Introspection APIs for each type of object are split into two 17 sub-APIs. One function to obtain @emph{fixed} data that never changes 18 during the lifetime of the inspected object and that the application 19 can thus continue to reference until the underlying object is 20 destroyed, and a second function to obtain @emph{dynamic} data that is 21 ephemeral and that can change over time (including becoming available 22 later or disappearing) and where the application thus has to be 23 careful when to ask for the data and to not keep pointers to stale 24 addresses. 25 26 Furthermore, each of the two sub-APIs comes in two variants, one 27 main function (such as @code{MHD_daemon_get_info_dynamic_sz()}) 28 and associated macro (for example, @code{MHD_daemon_get_info_dynamic()}) 29 that the application should actually use. The difference between 30 the macro and the function is that the function takes an extra 31 @code{size_t} argument that specifies the size of the 32 @code{union} used for the @var{output}. This argument allows MHD 33 to check that the application's output buffer is of sufficient 34 size, which could be important if the @code{union} changes between 35 MHD versions and thus the application possibly has been built with 36 a different @code{union} definition. The macro simply runs 37 @code{sizeof()} on the @var{output} variable to provide the 38 size of the application's allocation. If the buffer is too small 39 for the requested information, MHD fails safe and returns 40 @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL}. In the next subsections 41 we will thus only present the macros that applications should 42 use, and skip over the @code{_sz()}-functions with the extra 43 @code{size_t} argument. 44 45 @menu 46 * libmicrohttpd2-info library:: State information about the library 47 * libmicrohttpd2-info daemon:: State information about a daemon 48 * libmicrohttpd2-info connection:: State information about a connection 49 * libmicrohttpd2-info session:: State information about a session 50 * libmicrohttpd2-info request:: State information about a request 51 @end menu 52 53 @node libmicrohttpd2-info library 54 @section Obtaining state information about the MHD library 55 56 This introspection API returns information about how the MHD 57 library was compiled. It is primarily useful for applications 58 that want to double-check that particular features are available. 59 60 @anchor{MHD_lib_get_info_fixed} 61 @deftypefun {enum MHD_StatusCode} MHD_lib_get_info_fixed (enum MHD_LibInfoFixed info_type, union MHD_LibInfoFixedData *output_buf) 62 63 Obtain information about the MHD library. 64 65 @table @var 66 @item info_type 67 the type of information that is desired 68 69 @item output_buf 70 where to write the desired information (which member is set depends on @var{info_type}) 71 @end table 72 73 Returns a status code: 74 @itemize 75 @item @code{MHD_SC_OK} on success, 76 @item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown, 77 @item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL} 78 if @var{output_buf} is too small for this request 79 @end itemize 80 The list is not exhaustive, other error codes may be added in the future. 81 @end deftypefun 82 83 @anchor{MHD_LibInfoFixed} 84 @deftp {Enumeration} MHD_LibInfoFixed 85 Values of this enum are used to specify what 86 dynamic information about a daemon is desired. 87 88 @table @code 89 90 @item FIXME_CONSTANT_NAME 91 FIXME_CONSTANT_DESCRIPTION 92 93 @end table 94 @end deftp 95 96 97 @anchor{MHD_LibInfoFixedData} 98 @deftp {C Union} MHD_LibInfoFixedData 99 Represents introspection data that can be returned about the 100 MHD library. Which member will be set on success depends on the value 101 given for @var{info_type}. 102 @table @var 103 @item @code{FIXME_DATATYPE} FIXME_name 104 FIXME_DESCRIPTION. 105 106 @end table 107 @end deftp 108 109 110 111 @anchor{MHD_lib_get_info_dynamic} 112 @deftypefun {enum MHD_StatusCode} MHD_lib_get_info_dynamic (enum MHD_LibInfoDynamicType info_type, union MHD_LibInfoDynamicData *output_buf) 113 114 Obtain information about the MHD library. 115 This information may change after the start of MHD. 116 117 @table @var 118 @item info_type 119 the type of information that is desired 120 121 @item output_buf 122 where to write the desired information (which member is set depends on @var{info_type}) 123 @end table 124 125 Returns a status code: 126 @itemize 127 @item @code{MHD_SC_OK} on success, 128 @item @code{MHD_SC_TOO_EARLY} if the information is not yet available, 129 usually because the respective stage in processing was not yet reached, 130 @item @code{MHD_SC_TOO_LATE} if the information is no longer available, 131 usually because processing is past the stage where the information is kept, 132 @item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown, 133 @item @code{MHD_SC_INFO_GET_TYPE_NOT_APPLICABLE} 134 if the requested information is not available for this specific 135 object due to how that object was configured 136 @item @code{MHD_SC_INFO_GET_TYPE_UNOBTAINABLE} 137 if the requested information should be available 138 but cannot be provided due to some error or other reason, 139 @item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL} 140 if @var{output_buf} is too small for this request 141 @end itemize 142 The list is not exhaustive, other error codes may be added in the future. 143 @end deftypefun 144 145 146 @anchor{MHD_LibInfoDynamic} 147 @deftp {Enumeration} MHD_LibInfoDynamic 148 Values of this enum are used to specify what 149 dynamic information about a lib is desired. 150 151 @table @code 152 @anchor{MHD_LIB_INFO_FIXED_HAS_AGGREGATE_FD} 153 @item MHD_LIB_INFO_FIXED_HAS_AGGREGATE_FD 154 Check if aggregate file-descriptor support is available 155 for this build of the libarary. 156 157 @anchor{MHD_LIB_INFO_FIXED_HAS_UPGRADE} 158 @item MHD_LIB_INFO_FIXED_HAS_UPGRADE 159 Check if HTTP upgrade support is available 160 for this build of the libarary. 161 162 @anchor{MHD_LIB_INFO_FIXED_HAS_AUTH_BASIC} 163 @item MHD_LIB_INFO_FIXED_HAS_AUTH_BASIC 164 Check if HTTP basic authentication support is available 165 for this build of the libarary. 166 167 @anchor{MHD_LIB_INFO_FIXED_HAS_AUTH_DIGEST} 168 @item MHD_LIB_INFO_FIXED_HAS_AUTH_DIGEST 169 Check if HTTP digest authentication support is available 170 for this build of the libarary. 171 172 @anchor{MHD_LIB_INFO_FIXED_HAS_LARGE_FILE} 173 @item MHD_LIB_INFO_FIXED_HAS_LARGE_FILE 174 Check if MHD was build with support for "large" files 175 (above 2 Gigabytes). This should be the case on all modern 176 platforms, but may not be the case on some embedded or legacy 177 systems. 178 179 @item FIXME_CONSTANT_NAME 180 FIXME_CONSTANT_DESCRIPTION 181 182 @end table 183 @end deftp 184 185 186 @deftp {C Union} MHD_LibInfoDynamicData 187 Represents introspection data that can be returned about a 188 @var{lib}. Which member will be set on success depends on the value 189 given for @var{info_type}. 190 @table @var 191 @item @code{FIXME_DATATYPE} FIXME_name 192 FIXME_DESCRIPTION. 193 194 @end table 195 @end deftp 196 197 198 199 @node libmicrohttpd2-info daemon 200 @section Obtaining state information about a daemon 201 202 This introspection API returns information about a daemon. 203 204 @anchor{MHD_daemon_get_info_fixed} 205 @deftypefun {enum MHD_StatusCode} MHD_daemon_get_info_fixed (struct MHD_Daemon *daemon, enum MHD_DaemonInfoFixed info_type, union MHD_DaemonInfoFixedData *output_buf) 206 207 Obtain information about the MHD @var{daemon}. 208 The information returned is not changed at after the start 209 of the daemon until the daemon is destroyed. 210 211 @table @var 212 @item info_type 213 the type of information that is desired 214 215 @item output_buf 216 where to write the desired information (which member is set depends on @var{info_type}) 217 @end table 218 219 Returns a status code: 220 @itemize 221 @item @code{MHD_SC_OK} on success, 222 @c FIXME: can we really have TOO_EARLY/TOO_LATE for *fixed* data? 223 @item @code{MHD_SC_TOO_EARLY} if the information is not yet available, 224 usually because the respective stage in processing was not yet reached, 225 @item @code{MHD_SC_TOO_LATE} if the information is no longer available, 226 usually because processing is past the stage where the information is kept, 227 @item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown, 228 @item @code{MHD_SC_INFO_GET_TYPE_NOT_APPLICABLE} 229 if the requested information is not available for this specific 230 object due to how that object was configured 231 @item @code{MHD_SC_INFO_GET_TYPE_UNOBTAINABLE} 232 if the requested information should be available 233 but cannot be provided due to some error or other reason, 234 @item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL} 235 if @var{output_buf} is too small for this request 236 @end itemize 237 The list is not exhaustive, other error codes may be added in the future. 238 @end deftypefun 239 240 241 @anchor{MHD_DaemonInfoFixed} 242 @deftp {Enumeration} MHD_DaemonInfoFixed 243 Values of this enum are used to specify what 244 dynamic information about a @var{daemon} is desired. 245 246 @table @code 247 @anchor{MHD_DAEMON_INFO_FIXED_AGGREGATE_FD} 248 @item MHD_DAEMON_INFO_FIXED_AGGREGATE_FD 249 Aggregate file-descriptor applications should use when 250 using an external event loop in combination with 251 @ref{MHD_D_OPTION_WM_EXTERNAL_SINGLE_FD_WATCH}. 252 253 @item FIXME_CONSTANT_NAME 254 FIXME_CONSTANT_DESCRIPTION 255 256 @end table 257 @end deftp 258 259 260 @anchor{MHD_DaemonInfoFixedData} 261 @deftp {C Union} MHD_DaemonInfoFixedData 262 Represents introspection data that can be returned about a 263 @var{daemon}. Which member will be set on success depends on the value 264 given for @var{info_type}. 265 @table @var 266 267 @item @code{FIXME_DATATYPE} FIXME_name 268 FIXME_DESCRIPTION. 269 270 @end table 271 @end deftp 272 273 @anchor{MHD_daemon_get_info_dynamic} 274 @deftypefun {enum MHD_StatusCode} MHD_daemon_get_info_dynamic (struct MHD_Daemon *daemon, enum MHD_DaemonInfoDynamicType info_type, union MHD_DaemonInfoDynamicData *output_buf) 275 276 Obtain information about the given @var{daemon}. 277 This information may change after the start of the @var{daemon}. 278 279 @table @var 280 @item daemon 281 the daemon about which information is desired; 282 283 @item info_type 284 the type of information that is desired 285 286 @item output_buf 287 where to write the desired information (which member is set depends on @var{info_type}) 288 @end table 289 290 Returns a status code: 291 @itemize 292 @item @code{MHD_SC_OK} on success, 293 @item @code{MHD_SC_TOO_EARLY} if the information is not yet available, 294 usually because the respective stage in processing was not yet reached, 295 @item @code{MHD_SC_TOO_LATE} if the information is no longer available, 296 usually because processing is past the stage where the information is kept, 297 @item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown, 298 @item @code{MHD_SC_INFO_GET_TYPE_NOT_APPLICABLE} 299 if the requested information is not available for this specific 300 object due to how that object was configured 301 @item @code{MHD_SC_INFO_GET_TYPE_UNOBTAINABLE} 302 if the requested information should be available 303 but cannot be provided due to some error or other reason, 304 @item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL} 305 if @var{output_buf} is too small for this request 306 @end itemize 307 The list is not exhaustive, other error codes may be added in the future. 308 @end deftypefun 309 310 311 @c FIXME: inconsistent suffix "Type" not used for others! 312 @anchor{MHD_DaemonInfoDynamicType} 313 @deftp {Enumeration} MHD_DaemonInfoDynamicType 314 Values of this enum are used to specify what 315 dynamic information about a daemon is desired. 316 317 @table @code 318 @item FIXME_CONSTANT_NAME 319 FIXME_CONSTANT_DESCRIPTION 320 321 @end table 322 @end deftp 323 324 325 @anchor{MHD_DaemonInfoDynamicData} 326 @deftp {C Union} MHD_DaemonInfoDynamicData 327 Represents introspection data that can be returned about a 328 @var{daemon}. Which member will be set on success depends on the value 329 given for @var{info_type}. 330 @table @var 331 @item @code{FIXME_DATATYPE} FIXME_name 332 FIXME_DESCRIPTION. 333 334 @end table 335 @end deftp 336 337 338 @node libmicrohttpd2-info connection 339 @section Obtaining state information about a connection 340 341 This introspection API returns information about a connection. 342 343 344 @anchor{MHD_connection_get_info_fixed} 345 @deftypefun {enum MHD_StatusCode} MHD_connection_get_info_fixed (struct MHD_Connection *connection, enum MHD_ConnectionInfoFixed info_type, union MHD_ConnectionInfoFixedData *output_buf) 346 347 Obtain information about the MHD @var{connection}. 348 The information returned is not changed at after the start 349 of the connection until the connection is destroyed. 350 351 @table @var 352 @item info_type 353 the type of information that is desired 354 355 @item output_buf 356 where to write the desired information (which member is set depends on @var{info_type}) 357 @end table 358 359 Returns a status code: 360 @itemize 361 @item @code{MHD_SC_OK} on success, 362 @c FIXME: can we really have TOO_EARLY/TOO_LATE for *fixed* data? 363 @item @code{MHD_SC_TOO_EARLY} if the information is not yet available, 364 usually because the respective stage in processing was not yet reached, 365 @item @code{MHD_SC_TOO_LATE} if the information is no longer available, 366 usually because processing is past the stage where the information is kept, 367 @item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown, 368 @item @code{MHD_SC_INFO_GET_TYPE_NOT_APPLICABLE} 369 if the requested information is not available for this specific 370 object due to how that object was configured 371 @item @code{MHD_SC_INFO_GET_TYPE_UNOBTAINABLE} 372 if the requested information should be available 373 but cannot be provided due to some error or other reason, 374 @item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL} 375 if @var{output_buf} is too small for this request 376 @end itemize 377 The list is not exhaustive, other error codes may be added in the future. 378 @end deftypefun 379 380 381 @anchor{MHD_ConnectionInfoFixed} 382 @deftp {Enumeration} MHD_ConnectionInfoFixed 383 Values of this enum are used to specify what 384 dynamic information about a @var{connection} is desired. 385 386 @table @code 387 @item FIXME_CONSTANT_NAME 388 FIXME_CONSTANT_DESCRIPTION 389 390 @end table 391 @end deftp 392 393 394 @anchor{MHD_ConnectionInfoFixedData} 395 @deftp {C Union} MHD_ConnectionInfoFixedData 396 Represents introspection data that can be returned about a 397 @var{connection}. Which member will be set on success depends on the value 398 given for @var{info_type}. 399 @table @var 400 @item @code{FIXME_DATATYPE} FIXME_name 401 FIXME_DESCRIPTION. 402 403 @end table 404 @end deftp 405 406 407 @anchor{MHD_connection_get_info_dynamic} 408 @deftypefun {enum MHD_StatusCode} MHD_connection_get_info_dynamic (struct MHD_Connection *connection, enum MHD_ConnectionInfoDynamicType info_type, union MHD_ConnectionInfoDynamicData *output_buf) 409 410 Obtain information about the given @var{connection}. 411 This information may change after the start of the @var{connection}. 412 413 @table @var 414 @item connection 415 the connection about which information is desired; 416 417 @item info_type 418 the type of information that is desired 419 420 @item output_buf 421 where to write the desired information (which member is set depends on @var{info_type}) 422 @end table 423 424 Returns a status code: 425 @itemize 426 @item @code{MHD_SC_OK} on success, 427 @item @code{MHD_SC_TOO_EARLY} if the information is not yet available, 428 usually because the respective stage in processing was not yet reached, 429 @item @code{MHD_SC_TOO_LATE} if the information is no longer available, 430 usually because processing is past the stage where the information is kept, 431 @item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown, 432 @item @code{MHD_SC_INFO_GET_TYPE_NOT_APPLICABLE} 433 if the requested information is not available for this specific 434 object due to how that object was configured 435 @item @code{MHD_SC_INFO_GET_TYPE_UNOBTAINABLE} 436 if the requested information should be available 437 but cannot be provided due to some error or other reason, 438 @item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL} 439 if @var{output_buf} is too small for this request 440 @end itemize 441 The list is not exhaustive, other error codes may be added in the future. 442 @end deftypefun 443 444 445 @c FIXME: inconsistent suffix "Type" not used for others! 446 @deftp {Enumeration} MHD_ConnectionInfoDynamicType 447 Values of this enum are used to specify what 448 dynamic information about a connection is desired. 449 450 @table @code 451 @item FIXME_CONSTANT_NAME 452 FIXME_CONSTANT_DESCRIPTION 453 454 @end table 455 @end deftp 456 457 458 @deftp {C Union} MHD_ConnectionInfoDynamicData 459 Represents introspection data that can be returned about a 460 @var{connection}. Which member will be set on success depends on the value 461 given for @var{info_type}. 462 @table @var 463 @item @code{FIXME_DATATYPE} FIXME_name 464 FIXME_DESCRIPTION. 465 466 @end table 467 @end deftp 468 469 470 471 @node libmicrohttpd2-info session 472 @section Obtaining state information about a session 473 474 475 This introspection API returns information about a session. 476 477 @deftypefun {enum MHD_StatusCode} MHD_session_get_info_fixed (struct MHD_Session *session, enum MHD_SessionInfoFixed info_type, union MHD_SessionInfoFixedData *output_buf) 478 479 Obtain information about the MHD @var{session}. 480 The information returned is not changed at after the start 481 of the session until the session is destroyed. 482 483 @table @var 484 @item info_type 485 the type of information that is desired 486 487 @item output_buf 488 where to write the desired information (which member is set depends on @var{info_type}) 489 @end table 490 491 Returns a status code: 492 @itemize 493 @item @code{MHD_SC_OK} on success, 494 @c FIXME: can we really have TOO_EARLY/TOO_LATE for *fixed* data? 495 @item @code{MHD_SC_TOO_EARLY} if the information is not yet available, 496 usually because the respective stage in processing was not yet reached, 497 @item @code{MHD_SC_TOO_LATE} if the information is no longer available, 498 usually because processing is past the stage where the information is kept, 499 @item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown, 500 @item @code{MHD_SC_INFO_GET_TYPE_NOT_APPLICABLE} 501 if the requested information is not available for this specific 502 object due to how that object was configured 503 @item @code{MHD_SC_INFO_GET_TYPE_UNOBTAINABLE} 504 if the requested information should be available 505 but cannot be provided due to some error or other reason, 506 @item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL} 507 if @var{output_buf} is too small for this request 508 @end itemize 509 The list is not exhaustive, other error codes may be added in the future. 510 @end deftypefun 511 512 513 @deftp {Enumeration} MHD_SessionInfoFixed 514 Values of this enum are used to specify what 515 dynamic information about a @var{session} is desired. 516 517 @table @code 518 @item FIXME_CONSTANT_NAME 519 FIXME_CONSTANT_DESCRIPTION 520 521 @end table 522 @end deftp 523 524 525 @deftp {C Union} MHD_SessionInfoFixedData 526 Represents introspection data that can be returned about a 527 @var{session}. Which member will be set on success depends on the value 528 given for @var{info_type}. 529 @table @var 530 @item @code{FIXME_DATATYPE} FIXME_name 531 FIXME_DESCRIPTION. 532 533 @end table 534 @end deftp 535 536 537 @deftypefun {enum MHD_StatusCode} MHD_session_get_info_dynamic (struct MHD_Session *session, enum MHD_SessionInfoDynamicType info_type, union MHD_SessionInfoDynamicData *output_buf) 538 539 Obtain information about the given @var{session}. 540 This information may change after the start of the @var{session}. 541 542 @table @var 543 @item session 544 the session about which information is desired; 545 546 @item info_type 547 the type of information that is desired 548 549 @item output_buf 550 where to write the desired information (which member is set depends on @var{info_type}) 551 @end table 552 553 Returns a status code: 554 @itemize 555 @item @code{MHD_SC_OK} on success, 556 @item @code{MHD_SC_TOO_EARLY} if the information is not yet available, 557 usually because the respective stage in processing was not yet reached, 558 @item @code{MHD_SC_TOO_LATE} if the information is no longer available, 559 usually because processing is past the stage where the information is kept, 560 @item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown, 561 @item @code{MHD_SC_INFO_GET_TYPE_NOT_APPLICABLE} 562 if the requested information is not available for this specific 563 object due to how that object was configured 564 @item @code{MHD_SC_INFO_GET_TYPE_UNOBTAINABLE} 565 if the requested information should be available 566 but cannot be provided due to some error or other reason, 567 @item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL} 568 if @var{output_buf} is too small for this request 569 @end itemize 570 The list is not exhaustive, other error codes may be added in the future. 571 @end deftypefun 572 573 574 @c FIXME: inconsistent suffix "Type" not used for others! 575 @anchor{MHD_SessionInfoDynamicType} 576 @deftp {Enumeration} MHD_SessionInfoDynamicType 577 Values of this enum are used to specify what 578 dynamic information about a session is desired. 579 580 @table @code 581 @item FIXME_CONSTANT_NAME 582 FIXME_CONSTANT_DESCRIPTION 583 584 @end table 585 @end deftp 586 587 588 @anchor{MHD_SessionInfoDynamicData} 589 @deftp {C Union} MHD_SessionInfoDynamicData 590 Represents introspection data that can be returned about a 591 @var{session}. Which member will be set on success depends on the value 592 given for @var{info_type}. 593 @table @var 594 @item @code{FIXME_DATATYPE} FIXME_name 595 FIXME_DESCRIPTION. 596 597 @end table 598 @end deftp 599 600 601 @node libmicrohttpd2-info request 602 @section Obtaining state information about a request 603 604 Introspection of requests is described in 605 @ref{libmicrohttpd-request-status-info}.