General procedure for writing API programs
Learn how to write API programs for Caching Proxy.
Before writing your Caching Proxy plug-in programs, you need to understand how the proxy server works. The behavior of the proxy server can be divided into several distinct processing steps. For each of these steps, you can supply your own customized functions using the API. For example, do you want to do something after a client request is read but before performing any other processing? Or maybe you want to perform special routines during authentication and then again after the requested file is sent.
A library of predefined functions is provided with the API. Your plug-in programs can call the predefined API functions in order to interact with the proxy server process (for example, to manipulate requests, to read or write request headers, or to write to the proxy server's logs). These functions should not be confused with the plug-in functions that you write, which are called by the proxy server. The predefined functions are described in Predefined functions and macros.
You instruct the proxy server to call your plug-in functions at the appropriate steps by using the corresponding Caching Proxy API directives in your server configuration file. These directives are described in Caching Proxy configuration directives for API steps.
- A basic explanation of the Caching Proxy steps that can be customized (see Server process steps)
- Guidelines for writing plug-ins (see Guidelines)
- Prototypes for the customized functions that you can write for each step performed by the server, and their return codes (see Plug-in function prototypes)
- Definitions of predefined functions and macros that you can call from within your plug-ins, and their return codes (see Predefined functions and macros)
- Caching Proxy API configuration directives (see Caching Proxy configuration directives for API steps)
You can use these components and procedures to write your own Caching Proxy plug-in programs.
Server process steps
The basic operation of the proxy server can be broken up into steps based on the type of processing that the server performs during that phase. Each step includes a juncture at which a specified part of your program can run. By adding API directives to your Caching Proxy configuration file (ibmproxy.conf), you indicate which of your plug-in functions you want to be called during a particular step. You can call several plug-in functions during a particular process step by including more than one directive for that step.
Some steps are part of the server request process. In other words, the proxy server executes these steps each time it processes a request. Other steps are performed independently of request processing; that is, the server executes these steps regardless of whether a request is being processed.
Your compiled program resides in a shared object, for example, a DLL or .so file, depending on your operating system. As the server proceeds through its request process steps, it calls the plug-in functions associated with each step until one of the functions indicates that it has handled the request. If you specify more than one plug-in function for a particular step, the functions are called in the order in which their directives appear in the configuration file.
If the request is not handled by a plug-in function (either you did not include a Caching Proxy API directive for that step, or your plug-in function for that step returned HTTP_NOACTION), the server performs its default action for that step.
Note: This is true for all steps except the Service step; the Service step does not have a default action.

- Server Initialization
- Midnight
- GC Advisor
- Server Termination
The following list explains the purpose of each step pictured in Figure 1. Note that not all steps are guaranteed to be called for a particular request.
- Server Initialization
- Performs initialization when the proxy server is started and before any client requests are accepted.
- Midnight
- Runs a plug-in at midnight, with no request context. This step is shown separately in the diagram because it is not part of the request process; in other words, its execution is independent of any request.
- GC Advisor
- Influences garbage collection decisions for files in the cache. This step is shown separately in the diagram because it is not part of the request process; in other words, its execution is independent of any request. Garbage collection is done when the cache size reaches the maximum value. (Information about configuring cache garbage collection is included in the WebSphere® Application Server Caching Proxy Administration Guide.)
- PreExit
-
Performs processing after a request is read but before anything else is done.
If this step returns an indication that the request was processed (HTTP_OK), the server bypasses the other steps in the request process and performs only the Transmogrifier, Log, and PostExit steps.
- Name Translation
- Translates the virtual path (from a URL) to the physical path.
- Authorization
-
Uses stored security tokens to check the physical path for protections, ACLs, and other access controls, and generates the WWW-Authenticate headers required for basic authentication. If you write your own plug-in function to replace this step, you must generate these headers yourself.
See Authentication and authorization for more information.
- Authentication
-
Decodes, verifies, and stores security tokens.
See Authentication and authorization for more information.
- Object Type
- Locates the file system object indicated by the path.
- Post Authorization
-
Performs processing after authorization and object location but before the request is satisfied.
If this step returns an indication that the request was processed (HTTP_OK), the server bypasses the other steps in the request process and performs only the Transmogrifier, Log, and PostExit steps.
- Service
- Satisfies the request (by sending the file, running the CGI, etc.)
- Proxy Advisor
- Influences proxy and caching decisions.
- PICSDBLookup
- Looks for the PICS labels for the specified URL.
- Transmogrifier
- Gives write access to the data portion of the response sent to the client.
- Log
- Enables customized transaction logging.
- Error
- Enables customized responses to error conditions.
- PostExit
- Cleans up resources allocated for request processing.
- Server Termination
- Performs clean-up processing when an orderly shutdown occurs.
Guidelines
- Write your program, following the syntax and guidelines provided
for the server's plug-in functions. Give each of your plug-in functions
a unique function name and call the server's predefined functions
as needed.
On AIX® systems, you need an export file (for example, libmyapp.exp) that lists your plug-in functions, and you must link with the Caching Proxy API import file, libhttpdapi.exp.
On Linux, HP-UX, and Solaris systems, you must link with the libhttpdapi and libc libraries.
On Windows systems, you need a module definition file (.def) that lists your plug-in functions, and you must link with HTTPDAPI.LIB.
Be sure to include HTAPI.h and to use the HTTPD_LINKAGE macro in your function definitions. This macro ensures that all the functions use the same calling conventions.
- The server runs in a multithreaded environment; therefore, your plug-ins must be thread safe. If your application is reentrant, performance does not decrease.
- Keep the actions in your plug-ins to a thread scope. Do not perform any actions at a process scope, for example, exiting, changing the user ID, or registering a signal handler.
- Do not use global variables, or, if you must use them, protect global variables with a mutual exclusion semaphore.
- Remember to set the Content-Type header if you are using the HTTPD_write() function to send data back to the client.
- Always check return codes and provide conditional processing where necessary.
- Compile and link your program, referring to the documentation
for your compiler to build a shared object (for example, a DLL or
.so file) as required for your operating system.
Use the following compile and link commands as a guideline.
- AIX
, using IBM® CSet++
- Compile:
cc_r -c -qdbxextra -qcpluscmt foo.c
- Link:
(This command is shown on two lines for readability only.)cc_r -bM:SRE -bnoentry -o libfoo.so foo.o -bI:libhttpdapi.exp -bE:foo.exp
- Compile:
- HP-UX, using HP C/ANSI C
Developer's Bundle and HP aC++ Compiler
- Compile:
cc -Ae -c +Z +DAportable
- Link:
aCC +Z -mt -c +DAportable
- Compile:
- Linux, using the Gnu Compiler C (GCC)
Version 3.2.X
- Compile:
gcc -c foo.c
- Link:
ld -G -Bsymbolic -o libfoo.so foo.o -lhttpdapi -lc
- Compile:
- Solaris, using Sun Workshop
- Compile:
cc -mt -Bsymbolic -c foo.c
- Link:
cc -mt -Bsymbolic -G -o libfoo.so foo.o -lhttpdapi -lc
- Compile:
- Windows , using Microsoft Visual C++
- Compile:
cl /c /MD /DWIN32 foo.c
- Link:
link httpdapi.lib foo.obj /def:foo.def /out:foo.dll /dll
- Compile:
To specify exports, use one of these methods:
- Add _declspec(dllexport) definitions in the source.
- Specify /EXPORT:entryname on the LIB command line.
- Create a module definition file with an EXPORTS statement.
- AIX
, using IBM® CSet++
- Add Caching Proxy API
directives to your configuration file to associate your program's
plug-in functions with the appropriate steps. There is a separate
directive for each step in the server request process. Stop and restart
your server to make the new directives take effect. Note: The Caching Proxy does not unload shared objects (DLL or .so files) even at restart. You must stop and then start the server in order to release shared objects.
- Test your program rigorously before using it in a production environment. Because the Caching Proxy is a threaded server, you must apply more rigorous testing than is necessary for a forking server. Errors in your program can cause the proxy server to fail because the proxy server calls your program directly, and they both run in the same process space.
Plug-in functions
Follow the syntax presented in Plug-in function prototypes to write your own program functions for the defined request processing steps.
Each of your functions must fill in the return code parameter with a value that indicates what action was taken:
- The code HTTP_NOACTION (value 0) means that no relevant action was taken. If this code is returned, the proxy server takes its default action for this step.
- One of the valid HTTP return codes indicates that the plug-in function handled the step. (See HTTP return codes and values for a list of valid return codes.) If a valid HTTP return code is given, no other plug-in functions are called to handle that step of this request.
Plug-in function prototypes
The function prototypes for each Caching Proxy step show the format to use and explain the type of processing they can perform. Note that the function names are not predefined. You must give your functions unique names, and you can choose your own naming conventions. For ease of association, this document uses names that relate to the server's processing steps.
- HTTPD_set
- HTTPD_extract
- httpd_setvar
- httpd_getvar
- HTTPD_log* functions
The value of the handle parameter sent to your functions can be passed as the first argument to the predefined functions. Predefined API functions are described in Predefined functions and macros.
- Server Initialization
-
void HTTPD_LINKAGE ServerInitFunction ( unsigned char *handle, unsigned long *major_version, unsigned long *minor_version, long *return_code )
A function defined for this step is called once when your module is loaded during server initialization. It is your opportunity to perform initialization before any requests have been accepted.
Although all server initialization functions are called, a error return code from a function in this step causes the server to ignore all other functions configured in the same module as the function that returned the error code. (That is, any other functions contained in the same shared object as the function that returned the error are not called.)
The version parameters contain the proxy server's version number; these are supplied by the Caching Proxy.
- PreExit
-
void HTTPD_LINKAGE PreExitFunction ( unsigned char *handle, long *return_code )
A function defined for this step is called for each request after the request has been read but before any processing has occurred. A plug-in at this step can be used to access the client's request before it is processed by the Caching Proxy.
Valid return codes for the preExit function are the following:- 0 (HTTP_NOACTION)
- 200 (HTTP_OK)
- HTTP errors in the 4 xx or 5 xx series (for example, 404, HTTP_NOT_FOUND)
If this function returns HTTP_OK, the proxy server assumes that the request has been handled. All subsequent request processing steps are bypassed, and only the response steps (Transmogrifier, Log, and PostExit) are performed.
All predefined API functions are valid during this step.
- Midnight
-
void HTTPD_LINKAGE MidnightFunction ( unsigned char *handle, long *return_code )
A function defined for this step runs daily at midnight and contains no request context. For example, it can be used to invoke a child process to analyze logs. (Note that extensive processing during this step can interfere with logging.)
- Authentication
-
void HTTPD_LINKAGE AuthenticationFunction ( unsigned char *handle, long *return_code )
A function defined for this step is called for each request based on the request's authentication scheme. This function can be used to customize verification of the security tokens that are sent with a request.
- Name Translation
-
void HTTPD_LINKAGE NameTransFunction ( unsigned char *handle, long *return_code )
A function defined for this step is called for each request. A URL template can be specified in the configuration file directive if you want the plug-in function to be called only for requests that match the template. The Name Translation step occurs before the request is processed and provides a mechanism for mapping URLs to objects such as file names.
- Authorization
-
void HTTPD_LINKAGE AuthorizationFunction ( unsigned char *handle, long *return_code )
A function defined for this step is called for each request. A URL template can be specified in the configuration file directive if you want the plug-in function to be called only for requests that match the template. The Authorization step occurs before the request is processed and can be used to verify that the identified object can be returned to the client. If you are doing basic authentication, you must generate the required WWW-Authenticate headers.
- Object Type
-
void HTTPD_LINKAGE ObjTypeFunction ( unsigned char *handle, long *return_code )
A function defined for this step is called for each request. A URL template can be specified in the configuration file directive if you want the plug-in function to be called only for requests that match the template. The Object Type step occurs before the request is processed and can be used to check whether the object exists, and to perform object typing.
- PostAuthorization
-
void HTTPD_LINKAGE PostAuthFunction ( unsigned char *handle, long *return_code )
A function defined for this step is called after the request has been authorized but before any processing has occurred. If this function returns HTTP_OK, the proxy server assumes that the request has been handled. All subsequent request steps are bypassed, and only the response steps (Transmogrifier, Log, and PostExit) are performed.
All server predefined functions are valid during this step.
- Service
-
void HTTPD_LINKAGE ServiceFunction ( unsigned char *handle, long *return_code )
A function defined for this step is called for each request. A URL template can be specified in the configuration file directive if you want the plug-in function to be called only for requests that match the template. The Service step satisfies the request, if it was not satisfied in the PreExit or PostAuthorization steps.
All server predefined functions are valid during this step.
Refer to the Enable directive in the WebSphere Application Server Caching Proxy Administration Guide for information on configuring your Service function to be executed based on the HTTP method rather than on the URL.
- PICSDBLookup
-
void HTTPD_LINKAGE PICSDBLookupFunction ( unsigned char *handle, long *return_code )
This function enables you to either dynamically create a PICS label for the requested document or to search for a PICS label in an alternative file or database. Your plug-in function can evaluate the PICS_SERVICENAME, PICS_SITENAME, and PICS_PATHNAME variables to determine which document was requested.
If your plug-in function finds or creates a label, it must call the HTTPD_supply_label() predefined function to make the label available to the Caching Proxy and return a code of 200. Only the HTTPD_extract(), HTTPD_set(), and HTTPD_supply_label() predefined functions are valid during this step.
Note: You can process this step more than once for each request. If a request asks for labels for multiple documents or from multiple rating services, the server calls the plug-in function once for each label that is requested. - Transmogrifier
- The functions
called in this process step can be used to filter response data as
a stream. Four plug-in functions for this step are called in sequence,
and each acts as a segment of pipe through which the data flows. That
is, the open, write, close, and error functions
that you provide are called, in that order, for each response. Each
function processes the same data stream, in turn. For this step, you must implement the following four functions. (Your function names do not need to match these names.)
- Open
void * HTTPD_LINKAGE openFunction ( unsigned char *handle, long *return_code )
The open function performs any initialization (such as buffer allocation) required to process the data for this stream. Any return code other than HTTP_OK causes this filter to abort (the write and close functions are not called). Your function can return a void pointer so that you can allocate space for a structure and have the pointer passed back to you in the correlator parameter of the subsequent functions.
- Write
void HTTPD_LINKAGE writeFunction ( unsigned char *handle, unsigned char *data, /* response data sent by the origin server */ unsigned long *length, /* length of response data */ void *correlator, /* pointer returned by the 'open' function */ long *return_code )
The write function processes the data and can call the server's predefined HTTPD_write() function with the new or changed data. The plug-in must not attempt to free the buffer passed to it or expect the server to free the buffer it receives.
If you decide not to change the data during the scope of your write function, you still must call the HTTPD_write() function during the scope of either your open, write, or close function in order to pass the data for the response to the client. The correlator argument is the pointer to the data buffer that was returned in your open routine.
- Close
void HTTPD_LINKAGE closeFunction ( unsigned char *handle, void *correlator, long *return_code )
The close function performs any clean-up actions (such as flushing and freeing the correlator buffer) required to complete processing the data for this stream. The correlator argument is the pointer to the data buffer that was returned in your open routine.
- Error
void HTTPD_LINKAGE errorFunction ( unsigned char *handle, void *correlator, long *return_code )
The error function enables performance of clean-up actions, such as flushing or freeing the buffered data (or both) before an error page is sent. At this point, your open, write, and close functions are called to process the error page. The correlator argument is the pointer to the data buffer that was returned in your open routine.
Notes:- When writing a plug-in for the Transmogrifier step, you must call HTTPD_open(), HTTPD_write(), and HTTPD_close() at some time during the scope of your open, write, and close functions. HTTPD_write() can be called only after the HTTPD_open() function has been called. The purpose of these predefined functions is to give control to the server so that the next function in the sequence can be invoked.
- Calling the HTTPD_* functions is necessary for your Transmogrifier API step and the server to perform correctly. For example, if HTTPD_open() and HTTPD_close() are not called, headers are not returned to the client.
- Be aware that undesirable effects can occur if data filtering applications are not properly selective in their filtering of data streams. It is possible that CGIs will not work if filtered incorrectly, GIF files will not be displayed, and other binary streams will not work as expected.
- It is not necessary for the plug-in to buffer content body. The Caching Proxy automatically determines the content length.
- It is desirable to call HTTPD_open() when you are ready to give
control of the headers to the server. However, if you need to set
a header later in the API program, you can wait until the write or
close function to call the HTTPD_open() function. Note: You must set any headers by using HTTPD_set() or httpd_setvar() before calling the HTTPD_open() function.
- The data stream does not include headers. Plug-ins must use set and extract functions to manipulate headers. The plug-in's open function is not invoked until all headers have been read.
- You can use multiple transmogrifier plug-ins, which are invoked in the order in which they appear in the configuration file.
- SSL tunneling is not passed through the transmogrifier plug-ins.
- Open
- GC Advisor
-
void HTTPD_LINKAGE GCAdvisorFunction ( unsigned char *handle, long *return_code )
A function defined for this step is called for each file in the cache during garbage collection. This function enables you to influence which files are kept and which files are discarded. For more information, see the GC_* variables.
- Proxy Advisor
-
void HTTPD_LINKAGE ProxyAdvisorFunction ( unsigned char *handle, long *return_code )
A function defined for this step is invoked during service of each proxy request. For example, it can be used to set the USE_PROXY variable.
- Log
-
void HTTPD_LINKAGE LogFunction ( unsigned char *handle, long *return_code )
A function defined for this step is called for each request after the request has been processed and the communication to the client has been closed. A URL template can be specified in the configuration file directive if you want the plug-in function to be called only for requests that match the template. This function is called regardless of the success or failure of the request processing. If you do not want your log plug-in to override the default log mechanism, set your return code to HTTP_NOACTION instead of HTTP_OK.
- Error
-
void HTTPD_LINKAGE ErrorFunction ( unsigned char *handle, long *return_code )
A function defined for this step is called for each request that fails. A URL template can be specified in the configuration file directive if you want the plug-in function to be called only for failed requests that match the template. The Error step provides an opportunity for you to customize the error response.
- PostExit
-
void HTTPD_LINKAGE PostExitFunction ( unsigned char *handle, long *return_code )
A function defined for this step is called for each request, regardless of the success or failure of the request. This step enables you to do clean-up tasks for any resources allocated by your plug-in to process the request.
- Server Termination
-
void HTTPD_LINKAGE ServerTermFunction ( unsigned char *handle, long *return_code )
A function defined for this step is called when an orderly shutdown of the server occurs. It enables you to clean up resources allocated during the Server Initialization step. Do not call any HTTP_* functions in this step (the results are unpredictable). If you have more than one Caching Proxy API directive in your configuration file for Server Termination, they will all be called.
Note: Because of a current limitation in Solaris code, the Server Termination plug-in step is not executed when the ibmproxy -stop command is used to shut down the Caching Proxy on Solaris platforms. Refer to the WebSphere Application Server Caching Proxy Administration Guide for information about starting and stopping the Caching Proxy.
HTTP return codes and values
Value | Return code |
0 | HTTP_NOACTION |
100 | HTTP_CONTINUE |
101 | HTTP_SWITCHING_PROTOCOLS |
200 | HTTP_OK |
201 | HTTP_CREATED |
202 | HTTP_ACCEPTED |
203 | HTTP_NON_AUTHORITATIVE |
204 | HTTP_NO_CONTENT |
205 | HTTP_RESET_CONTENT |
206 | HTTP_PARTIAL_CONTENT |
300 | HTTP_MULTIPLE_CHOICES |
301 | HTTP_MOVED_PERMANENTLY |
302 | HTTP_MOVED_TEMPORARILY |
302 | HTTP_FOUND |
303 | HTTP_SEE_OTHER |
304 | HTTP_NOT_MODIFIED |
305 | HTTP_USE_PROXY |
307 | HTTP_TEMPORARY_REDIRECT |
400 | HTTP_BAD_REQUEST |
401 | HTTP_UNAUTHORIZED |
403 | HTTP_FORBIDDEN |
404 | HTTP_NOT_FOUND |
405 | HTTP_METHOD_NOT_ALLOWED |
406 | HTTP_NOT_ACCEPTABLE |
407 | HTTP_PROXY_UNAUTHORIZED |
408 | HTTP_REQUEST_TIMEOUT |
409 | HTTP_CONFLICT |
410 | HTTP_GONE |
411 | HTTP_LENGTH_REQUIRED |
412 | HTTP_PRECONDITION_FAILED |
413 | HTTP_ENTITY_TOO_LARGE |
414 | HTTP_URI_TOO_LONG |
415 | HTTP_BAD_MEDIA_TYPE |
416 | HTTP_BAD_RANGE |
417 | HTTP_EXPECTATION_FAILED |
500 | HTTP_SERVER_ERROR |
501 | HTTP_NOT_IMPLEMENTED |
502 | HTTP_BAD_GATEWAY |
503 | HTTP_SERVICE_UNAVAILABLE |
504 | HTTP_GATEWAY_TIMEOUT |
505 | HTTP_BAD_VERSION |
Predefined functions and macros
You can call the server's predefined functions and macros from your own plug-in functions. You must use their predefined names and follow the format described below. In the parameter descriptions, the letter i indicates an input parameter, the letter o indicates an output parameter, and i/o indicates that a parameter is used for both input and output.
Each of these functions returns one of the HTTPD return codes, depending on the success of the request. These codes are described in Return codes from predefined functions and macros.
Use the handle provided to your plug-in as the first parameter when calling these functions. Otherwise, the function returns an HTTPD_PARAMETER_ERROR error code. NULL is not accepted as a valid handle.
- HTTPD_authenticate()
- Authenticates
a user ID or password, or both. Valid only in PreExit, Authentication,
Authorization, and PostAuthorization steps.
void HTTPD_LINKAGE HTTPD_authenticate ( unsigned char *handle, /* i; handle */ long *return_code /* o; return code */ )
- HTTPD_cacheable_url()
- Returns
whether the specified URL content is cacheable according to the Caching Proxy's standards.
void HTTPD_LINKAGE HTTPD_cacheable_url ( unsigned char *handle, /* i; handle */ unsigned char *url, /* i; URL to check */ unsigned char *req_method, /* i; request method for the URL */ long *retval /* o; return code */ )
The return value HTTPD_SUCCESS indicates that the URL content is cacheable; HTTPD_FAILURE indicates the content is not cacheable. HTTPD_INTERNAL_ERROR also is a possible return code for this function.
- HTTPD_close()
- (Valid
only in the Transmogrifier step.) Transfers control to the next close routine
in the stream stack. Call this function from the Transmogrifier open,
write, or close functions after any desired processing is done. This
function notifies the proxy server that
the response has been processed and the Transmogrifier step is complete.
void HTTPD_LINKAGE HTTPD_close ( unsigned char *handle, /* i; handle */ long *return_code /* o; return code */ )
- HTTPD_exec()
- Executes
a script to satisfy this request. Valid in the PreExit, Service, PostAuthorization,
and Error steps.
void HTTPD_LINKAGE HTTPD_exec ( unsigned char *handle, /* i; handle */ unsigned char *name, /* i; name of script to run */ unsigned long *name_length, /* i; length of the name */ long *return_code /* o; return code */ )
- HTTPD_extract()
- Extracts
the value of a variable associated with this request. The valid variables
for the name parameter are the same as those used in the
CGI. See Variables for more information.
Note that this function is valid in all steps; however, not all variables
are valid in all steps.
void HTTPD_LINKAGE HTTPD_extract ( unsigned char *handle, /* i; handle */ unsigned char *name, /* i; name of variable to extract */ unsigned long *name_length, /* i; length of the name */ unsigned char *value, /* o; buffer in which to put the value */ unsigned long *value_length, /* i/o; buffer size */ long *return_code /* o; return code */ )
If this function returns the code HTTPD_BUFFER_TOO_SMALL, the buffer size you requested was not big enough for the extracted value. In this case, the function does not use the buffer but updates the value_length parameter with the buffer size that you need in order to successfully extract this value. Retry the extraction with a buffer that is at least as big as the returned value_length.
Note: If the variable being extracted is for an HTTP header, the HTTPD_extract() function will extract only the first matching occurrence, even if the request contains multiple headers with the same name. The httpd_getvar() function can be used instead of HTTPD_extract(), and also offers other benefits. Refer to the section on the httpd_getvar() function for more information. - HTTPD_file()
- Sends a
file to satisfy this request. Valid only in the PreExit, Service,
Error, PostAuthorization, and Transmogrifier steps.
void HTTPD_LINKAGE HTTPD_file ( unsigned char *handle, /* i; handle */ unsigned char *name, /* i; name of file to send */ unsigned long *name_length, /* i; length of the name */ long *return_code /* o; return code */ )
- httpd_getvar()
- The same
as HTTPD_extract(), except that it is easier to use because the user
does not have to specify lengths for the arguments.
The index for the array containing the header begins with 0. To obtain the first item in the array, use the value 0 for n ; to obtain the fifth item, use the value 4 for n .const unsigned char * /* o; value of variable */ HTTPD_LINKAGE httpd_getvar( unsigned char *handle, /* i; handle */ unsigned char *name, /* i; variable name */ unsigned long *n /* i; index number for the array containing the header */ )
Note: Do not discard or change the contents of the returned value. The returned string is null terminated. - HTTPD_log_access()
- Writes
a string to the server's access log.
Note that escape symbols are not required when writing the percent symbol (%) in server access logs.void HTTPD_LINKAGE HTTPD_log_access ( unsigned char *handle, /* i; handle */ unsigned char *value, /* i; data to write */ unsigned long *value_length, /* i; length of the data */ long *return_code /* o; return code */ )
- HTTPD_log_error()
- Writes
a string to the server's error log.
Note that escape symbols are not required when writing the percent symbol (%) in server error logs.void HTTPD_LINKAGE HTTPD_log_error ( unsigned char *handle, /* i; handle */ unsigned char *value, /* i; data to write */ unsigned long *value_length, /* i; length of the data */ long *return_code /* o; return code */ )
- HTTPD_log_event()
- Writes
a string to the server's event log.
void HTTPD_LINKAGE HTTPD_log_event ( unsigned char *handle, /* i; handle */ unsigned char *value, /* i; data to write */ unsigned long *value_length, /* i; length of the data */ long *return_code /* o; return code */ )
Note that escape symbols are not required when writing the percent symbol (%) in server event logs.
- HTTPD_log_trace()
- Writes
a string to the server's trace log.
Note that escape symbols are not required when writing the percent symbol (%) in server trace logs.void HTTPD_LINKAGE HTTPD_log_trace ( unsigned char *handle, /* i; handle */ unsigned char *value, /* i; data to write */ unsigned long *value_length, /* i; length of the data */ long *return_code /* o; return code */ )
- HTTPD_open()
- (Valid only
in the Transmogrifier step.) Transfers control to the next routine
in the stream stack. Call this from the Transmogrifier open, write,
or close functions after any desired headers are set and you are ready
to begin the write routine.
void HTTPD_LINKAGE HTTPD_open ( unsigned char *handle, /* i; handle */ long *return_code /* o; return code */ )
- HTTPD_proxy()
- Makes a
proxy request. Valid in the PreExit, Service, and PostAuthorization
steps. Note: This is a completion function; the request is complete after this function.
void HTTPD_LINKAGE HTTPD_proxy ( unsigned char *handle, /* i; handle */ unsigned char *url_name, /* i; URL for the proxy request */ unsigned long *name_length, /* i; length of URL */ void *request_body, /* i; body of request */ unsigned long *body_length, /* i; length of body */ long *return_code /* o; return code */ )
- HTTPD_read()
- Reads the
body of the client's request. Use HTTPD_extract() for headers. Valid
only in the PreExit, Authorization, PostAuthorization, and Service
steps and is useful only if a PUT or POST request has been done. Call
this function in a loop until HTTPD_EOF is returned.
If there is no body for this request, this function fails.
void HTTPD_LINKAGE HTTPD_read ( unsigned char *handle, /* i; handle */ unsigned char *value, /* i; buffer for data */ unsigned long *value_length, /* i/o; buffer size (data length) */ long *return_code /* o; return code */ )
- HTTPD_restart()
- Restarts
the server after all active requests have been processed. Valid in
all steps except for Server Initialization, Server Termination, and
Transmogrifier.
void HTTPD_LINKAGE HTTPD_restart ( long *return_code /* o; return code */ )
- HTTPD_set()
- Sets the
value of a variable associated with this request. The variables that
are valid for the name parameter are the same as those used
in the CGI. See Variables for more
information.
Note that you can also create variables with this function. Variables that you create are subject to the conventions for HTTP_ and PROXY_ prefixes, which are described in Variables. If you create a variable that begins with HTTP_, it is sent as a header in the response to the client, without the HTTP_ prefix. For example, to set a Location header, use HTTPD_set() with the variable name HTTP_LOCATION. Variables created with a PROXY_ prefix are sent as headers in the request to the content server. Variables created with a CGI_ prefix are passed to CGI programs.
This function is valid in all steps; however, not all variables are valid in all steps.
void HTTPD_LINKAGE HTTPD_set ( unsigned char *handle, /* i; handle */ unsigned char *name, /* i; name of value to set */ unsigned long *name_length, /* i; length of the name */ unsigned char *value, /* i; buffer with value */ unsigned long *value_length, /* i; length of value */ long *return_code /* o; return code */ )
Note: You can use the httpd_setvar() function to set a variable value without having to specify a buffer and length. Refer to the section on httpd_setvar() function for information. - httpd_setvar()
- The same
as HTTPD_set(), except that it is easier to use because the user does
not have to specify lengths for the arguments.
The addHdr parameter has four possible values:long /* o; return code */ HTTPD_LINKAGE httpd_setvar ( unsigned char *handle, /* i; handle */ unsigned char *name, /* i; variable name */ unsigned char *value, /* i; new value */ unsigned long *addHdr /* i; add header or replace it */ )
- HTTPD_SETVAR_REPLACE — Replace all occurrences of the header variable with the new value.
- HTTPD_SETVAR_REPLACE_ADD — If the header variable exists, replace its first occurrence with the new value; if the variable does not exist, append the new value to the headers.
- HTTPD_SETVAR_ADD — Append this value to the headers.
- HTTPD_SETVAR_REMOVE_ALL — Delete all occurrences of this header variable.
- HTTPD_supply_label()
- Provides
the Caching Proxy with
a PICS label that was generated or retrieved during the PICSDBLookup
step.
Valid only during the PICSDBLookup step.
void HTTPD_LINKAGE HTTPD_supply_label ( unsigned char *handle, /* i; handle */ unsigned char *value, /* i; PICS label being supplied */ unsigned long *value_length, /* i; length of PICS label */ long *return_code /* o; return code */ )
- httpd_variant_insert()
- Inserts
a variant into the cache.
void HTTPD_LINKAGE httpd_variant_insert ( unsigned char *handle, /* i; handle */ unsigned char *URI, /* i; URI of this object */ unsigned char *dimension, /* i; dimension of variation */ unsigned char *variant, /* i; value of the variant */ unsigned char *filename, /* i; file containing the object */ long *return_code /* o; return code */ )
Notes:- The dimension argument refers to the header by which this object varies from the URI. For instance, in the example above, a possible dimension value is User-Agent.
- The variant argument refers to the value of the header for the
header given in the dimension argument. This varies from the URI.
For instance, in the example above, a possible value for the variant
argument is the following:
Mozilla 4.0 (compatible; BatBrowser 94.1.2; Bat OS)
- The filename argument must point to a null-terminated copy of the file name in which the user has saved the modified content. The user is responsible for removing the file; this action is safe after return from this function. The file contains only the body with no headers.
- When caching variants, the server updates the content-length header and adds a Warning: 214 header. Strong entity tags are removed.
- httpd_variant_lookup()
- Determines
if a given variant exists in the cache.
void HTTPD_LINKAGE httpd_variant_lookup ( unsigned char *handle, /* i; handle */ unsigned char *URI, /* URI of this object */ unsigned char *dimension, /* i; dimension of variation */ unsigned char *variant, /* i; value of the variant */ long *return_code); /* o; return code */
- HTTPD_write()
- Writes
the body of the response. Valid in the PreExit, Service, Error, and
Transmogrifier steps.
If you do not set the content type before calling this function for the first time, the server assumes that you are sending a CGI data stream.
void HTTPD_LINKAGE HTTPD_write ( unsigned char *handle, /* i; handle */ unsigned char *value, /* i; data to send */ unsigned char *value_length, /* i; length of the data */ long *return_code); /* o; return code */
Note: To set response headers, refer to the section on the HTTPD_set() function.
Return codes from predefined functions and macros
Value | Status code | Explanation |
---|---|---|
-1 | HTTPD_UNSUPPORTED | The function is not supported. |
0 | HTTPD_SUCCESS | The function succeeded, and the output fields are valid. |
1 | HTTPD_FAILURE | The function failed. |
2 | HTTPD_INTERNAL_ERROR | An internal error was encountered and processing for this request cannot continue. |
3 | HTTPD_PARAMETER_ERROR | One or more invalid parameters was passed. |
4 | HTTPD_STATE_CHECK | The function is not valid in this process step. |
5 | HTTPD_READ_ONLY | (Returned only by HTTPD_set and httpd_setvar.) The variable is read-only and cannot be set by the plug-in. |
6 | HTTPD_BUFFER_TOO_SMALL | (Returned by HTTPD_set, httpd_setvar, and HTTPD_read.) The buffer provided was too small. |
7 | HTTPD_AUTHENTICATE_FAILED | (Returned only by HTTPD_authenticate.) The authentication failed. Examine the HTTP_RESPONSE and HTTP_REASON variables for more information. |
8 | HTTPD_EOF | (Returned only by HTTPD_read.) Indicates the end of the request body. |
9 | HTTPD_ABORT_REQUEST | The request was aborted because the client provided an entity tag that did not match the condition specified by the request. |
10 | HTTPD_REQUEST_SERVICED | (Returned by HTTPD_proxy.) The function that was called completed the response for this request. |
11 | HTTPD_RESPONSE_ALREADY_ COMPLETED | The function failed because the response for that request has already been completed. |
12 | HTTPD_WRITE_ONLY | The variable is write-only and cannot be read by the plug-in. |
Caching Proxy configuration directives for API steps
Each step in the request process has a configuration directive that you use to indicate which of your plug-in functions you want to call and execute during that step. You can add these directives to your server's configuration file (ibmproxy.conf) by manually editing and updating it, or by using the API Request Processing form in the Caching Proxy Configuration and Administration forms.
API usage notes
- Except for the Service and NameTrans directives, the API directives for each step do not need to appear in any particular order in the configuration file. Note that the order of multiple entries for one API directive is significant, as described later in this list.
- It is not necessary to include an entry for every API step. If you do not have a plug-in for a particular step, omit the corresponding directive and the standard processing for that step will be used.
- The Service and NameTrans
directives work like the other mapping directives (for example, the
Pass directive) and are dependent on their occurrence and placement
relative to other mapping directives within the configuration file.
For example, a rule for /cgi-bin/foo.so must appear before the rule
for /cgi-bin/*.
This means that the server processes the Service, NameTrans, Exec, Fail, Map, Pass, Proxy, ProxyWAS, and Redirect directives in their sequence within the configuration file. When the server successfully maps a URL to a file, it does not read or process any other of these directives. (The Map directive is an exception. Refer to the WebSphere Application Server Caching Proxy Administration Guide for complete information about proxy server mapping rules.)
- You can have more than one configuration
directive for a step. For example, you can include two NameTrans directives,
each pointing to a different plug-in function. When the server performs
the name translation step, it processes your name translation functions
in the order in which they appear within the configuration file. Note: If a plug-in function provided with the Caching Proxy uses the same API directive as a plug-in you have written, place your plug-in's directive after the system plug-in directive.
- Certain plug-in functions do not have to be executed for every
request:
- Several directives include a URL mask. Specifying a URL mask with these directives causes the plug-in application to be called only for requests whose URLs match that pattern. Refer to API directives and syntax for information about which steps can use URL masks and to API directive variables for information about how to use this feature.
- Specify an authentication scheme with the Authentication directive to indicate that you want the plug-in to be called only for certain types of authentication. Currently, only basic authentication is supported by the HTTP protocol. See API directive variables for additional information.
- If the server fails to load a specific plug-in function, or if you have a ServerInit directive that does not return an OK return code, no other plug-in functions for that compiled Caching Proxy plug-in are called. Any processing specific to that plug-in that was done up to this point is ignored. Other Caching Proxy plug-ins that you include in these directives, and their functions, are not affected.
API directives and syntax
ServerInit | /path/file:function_name init_string | |
PreExit | /path/file:function_name | |
Authentication | type | /path/file:function_name |
NameTrans | /URL | /path/file:function_name |
Authorization | /URL | /path/file:function_name |
ObjectType | /URL | /path/file:function_name |
PostAuth | /path/file:function_name | |
Service | /URL | /path/file:function_name |
Midnight | /path/file:function_name | |
Transmogrifier | /path/file:open_function_name: write_function_name: close_function_name:error_function | |
PICSDBLookup | /path/file:function_name | |
Log | /URL | /path/file:function_name |
Error | /URL | /path/file:function_name |
PostExit | /path/file:function_name | |
ServerTerm | /path/file:function_name | |
ProxyAdvisor | /path/file:function_name | |
GCAdvisor | /path/file:function_name |
API directive variables
The variables in these directives have the following meanings:
- type
- Used only with the Authentication directive to specify whether
or not your plug-in function is called. Valid values are the following:
- Basic — The plug-in function is called only for basic authentication requests.
- * — The plug-in function is called for all requests. Currently, only basic authentication is supported by HTTP protocol. For nonbasic authentication requests, you can return an error code indicating that this type of authentication is not supported.
- URL
- Specifies the requests for which your plug-in function is called.
Requests with URLs that match this template will cause the plug-in
function to be used. URL specifications in these directives are virtual
(they do not include the protocol) but are preceded by a slash (/).
For example, /www.ics.raleigh.ibm.com is correct, but http://www.ics.raleigh.ibm.com
is not. You can specify this value as a specific URL or as a template.
- specific URL — The plug-in function is called only for that exact URL.
- URL template — The plug-in function is called
for all URLs that match the template. Templates can include the wildcard
character * and can be specified in the forms /
URL *
or /* or * Note: A URL template is required with the Service directive if you want path translation to occur.
- path/file
- The fully qualified file name of your compiled program.
- function_name
- The name that you gave your plug-in function within your program.
The Service directive requires an asterisk (*) after the function name if you want to have access to path information.
- init_string
- This optional part of the ServerInit directive can contain any text that you want to pass to your plug-in function. Use httpd_getvar() to extract the text from the INIT_STRING variable.
For additional information, including syntax, for these directives, see the WebSphere Application Server Caching Proxy Administration Guide.