This chapter is from the book
This chapter is from the book
This chapter is from the book
This chapter is from the book
2.5 Other Key API Components
The header file httpd.h that defines these core structures is but one of many API header files that the applications developer will need to use. These fall into several loosely bounded categories that can be identified by naming conventions:
- ap_ header files generally define low-level API elements and are usually (though not always) accessed indirectly by inclusion in other headers.
- http_ header files define most of the key APIs likely to be of interest to application developers. They are also exposed in scripting languages through modules such as mod_perl and mod_python.
- util_ header files define API elements at a higher level than ap_, but are rarely used directly by application modules. Two exceptions to that rule are util_script.h and util_filter.h, which define scripting and filtering APIs, respectively, and are commonly accessed by modules.
- mod_ header files define APIs implemented by modules that are optional. Using these APIs may create dependencies. Best practice is discussed in Chapter 10.
- apr_ header files define the APR APIs. The APR libraries are external but essential to the webserver, and the APR is required (directly or indirectly) by any nontrivial module. The APR is discussed in Chapter 3.
- Other header files generally define system-level APIs only.
- Third-party APIs may follow similar conventions (e.g., a mod_ header file) or adopt their own.
As noted earlier, the primary APIs for application modules are the http_* header files.
- http_config.h—Defines the configuration API, including the configuration data structures, the configuration vectors, any associated accessors, and, in particular, the main APIs presented in Chapter 9. It also defines the module data structure itself and associated accessors, and the handler (content generator) hook. It is required by most modules.
- http_connection.h—Defines the (small) TCP connection API, including connection-level hooks. Most modules will access the connection through the conn_rec object, so this API is seldom required by application modules.
- http_core.h—Defines miscellaneous APIs exported by the Apache core, such as accessor functions for the request_rec object. It includes APIs exported for particular modules, such as to support mod_perl's configuration sections. This header file is rarely required by application modules.
- http_log.h—Defines the error logging API and piped logs. Modules will need it for the error reporting functions and associated macros.
- http_main.h—Defines APIs for server start-up. It is unlikely to be of interest to modules.
- http_protocol.h—Contains high-level functional APIs for performing a number of important operations, including all normal I/O to the client, and for dealing with aspects of the HTTP protocol such as generating the correct response headers. It also exports request processing hooks that fall outside the scope of http_request. Many modules will require this header file—for example, content generators (unless you use only the lower-level APIs) and authentication modules.
- http_request.h—Defines the main APIs discussed in Chapter 6. It exports most of the request processing hooks, and the subrequest and internal redirect APIs. It is required by some, but not all, modules.
- http_vhost.h—Contains APIs for managing virtual hosts. It is rarely needed by modules except those concerned with virtual host configuration.
- httpd.h—Contains Apache's core API, which is required by (probably) all modules. It defines a lot of system constants, some of them derived from local build parameters, and various APIs such as HTTP status codes and methods. Most importantly, it defines the core objects mentioned earlier in this chapter.
Other important API headers we will encounter include the following files:
- util_filter.h—The filter API, required by all filter modules (Chapter 8)
- ap_provider.h—The provider API (Chapter 10)
- mod_dbd.h—The DBD framework (Chapters 10 and 11)
Other API headers likely to be of interest to application developers include the following files:
- util_ldap.h—The LDAP API
- util_script.h—A scripting environment that originally supported CGI, but is also used by other modules that use CGI environment variables (e.g., mod_rewrite, mod_perl, mod_php) or that generate responses using CGI rules (e.g., mod_asis)