编写 API 程序的一般过程

在编写高速缓存代理插件程序之前,需要了解代理服务器的工作方式。可以将代理服务器的行为分成若干不同的处理步骤。对于其中每个步骤,您可以使用该 API 提供自己的定制函数。例如,要在读取客户机请求之后但在执行任何其他处理之前执行某些操作吗?或者,也许要在认证期间执行特殊例程,然后在发送请求的文件之后再次执行这些例程。

该 API 附带了一个预定义函数库。您的插件程序可以调用预定义 API 函数以便与代理服务器进程交互(例如,处理请求、读取或写入请求头或者写入至代理服务器的日志)。这些函数应该不会与您编写的插件函数混淆,您编写的插件函数由代理服务器进行调用。预定义函数和宏中描述了预定义函数。

您应该通过在服务器配置文件中使用相应的高速缓存代理 API 伪指令在适当的步骤中指示代理服务器调用插件函数。用于 API 步骤的高速缓存代理配置伪指令中描述了这些伪指令。

本文档包含以下内容:

可以使用这些组件和过程来编写自己的高速缓存代理插件程序。

服务器进程步骤

可以根据服务器在该阶段执行的处理类型将代理服务器的基本操作分成若干步骤。每个步骤都包括一个接合点,程序的指定部分可以在该接合点运行。通过将 API 伪指令添加到高速缓存代理配置文件 (ibmproxy.conf),可以指示要在特定步骤中调用哪个插件函数。通过包括用于特定进程步骤的多个伪指令,可以在该步骤期间调用若干插件函数。

某些步骤是服务器请求进程的一部分。换句话说,代理服务器在每次处理请求时将执行这些步骤。将独立于请求处理执行其他步骤;即,无论是否在处理请求,服务器都将执行这些步骤。

您的已编译程序驻留在一个共享对象中,例如,DLL 或 .so 文件,这取决于您的操作系统。当服务器执行其请求进程步骤时,服务器将调用与每个步骤相关联的插件函数,直到其中一个函数指示它已处理该请求为止。如果您为特定步骤指定多个插件函数,那么将按其伪指令出现在配置文件中的顺序调用这些函数。

如果插件函数未处理该请求(您未包括用于该步骤的高速缓存代理 API 伪指令,或者用于该步骤的插件函数返回了 HTTP_NOACTION),那么服务器将对该步骤执行缺省操作。

注意:此指示对于除“服务”步骤之外的所有步骤都是正确的;“服务”步骤没有缺省操作。

图 1 说明了代理服务器进程的步骤并定义了与请求处理相关的步骤的处理顺序。

图 1. 代理服务器进程中步骤的流程图

将独立于任何客户机请求的处理来执行图中的四个步骤。这些步骤与代理服务器的运行和维护相关。它们包括以下各项:

以下列表说明了图 1 中图示的每个步骤的目的。注意,并不保证为特定请求调用所有步骤。

服务器初始化
在启动代理服务器后但在接受任何客户机请求之前执行初始化。
午夜
在没有任何请求上下文的情况下在午夜运行插件。因为此步骤不是请求进程的一部分,所以在图中单独显示了此步骤;换句话说,其执行过程独立于任何请求。
GC 顾问程序
影响高速缓存中文件的垃圾回收决策。因为此步骤不是请求进程的一部分,所以在图中单独显示了此步骤;换句话说,其执行过程独立于任何请求。当高速缓存大小达到最大值时将执行垃圾回收。(WebSphere® Application Server 高速缓存代理 Administration Guide 中包含有关配置高速缓存垃圾回收的信息。)
退出前

在读取请求之后但在执行任何其他操作之前执行处理。

如果此步骤返回一个表明已处理该请求的指示 (HTTP_OK),那么服务器将绕过请求进程中的其他步骤并仅执行转换器、记录和退出后步骤。

名称转换
将虚拟路径(来自 URL)转换为实际路径。
授权

使用存储的安全性令牌来检查保护、ACL 和其他访问控制的实际路径并生成基本认证所需的 WWW-Authenticate 头。如果要编写您自己的插件函数来替换此步骤,那么您必须自己生成这些头。

请参阅认证和授权,以了解更多信息。

认证

解码、验证和存储安全性令牌。

请参阅认证和授权,以了解更多信息。

对象类型
查找由路径指示的文件系统对象。
授权后

在授权和对象定位之后但在满足该请求之前执行处理。

如果此步骤返回一个表明已处理该请求的指示 (HTTP_OK),那么服务器将绕过请求进程中的其他步骤并仅执行转换器、记录和退出后步骤。

服务
满足该请求(通过发送文件和运行 CGI 等)。
代理顾问程序
影响代理和高速缓存决策。
转换器
对于发送到客户机的响应的数据部分授予写访问权。
日志
启用定制事务记录。
错误
启用对于错误情况的定制响应。
退出后
清除为请求处理所分配的资源。
服务器终止
在进行有序关闭时执行清除处理。

准则

插件函数

遵循插件函数原型中显示的语法,以便为已定义的请求处理步骤编写您自己的程序函数。

您的每个函数必须为返回码参数填入值以指示所执行的操作:

插件函数原型

每个高速缓存代理步骤的函数原型显示了要使用的格式并说明了这些原型可以执行的处理类型。注意,没有预定义函数名。您必须给函数指定唯一名称,并且您可以选择自己的命名约定。为了便于关联,本文档使用与服务器的处理步骤相关的名称。

在其中每个插件函数中,某些预定义 API 函数都有效。某些预定义函数并非对所有步骤都有效。从所有这些插件函数中调用下列预定义 API 函数时,这些 API 函数都有效:

在函数原型描述中指明了其他有效或无效 API 函数。

可以将发送到函数的 handle 参数的值作为第一个自变量传递到预定义函数。预定义函数和宏中描述了预定义 API 函数。

服务器初始化

void HTTPD_LINKAGE ServerInitFunction (
     unsigned char *handle, 
     unsigned long *major_version,
     unsigned long *minor_version, 
     long *return_code
     )

在服务器初始化期间装入模块时,将调用为此步骤定义的函数。它使您有机会在接受任何请求之前执行初始化。

虽然将调用所有服务器初始化函数,但此步骤中某个函数的错误返回码会导致服务器忽略模块(返回了错误代码的函数所在的模块)中配置的所有其他函数。(即,将不调用返回了错误的函数所在的共享对象中包含的任何其他函数。)

version 参数包含代理服务器的版本号,这些版本号由高速缓存代理提供。

preExit

void  HTTPD_LINKAGE  PreExitFunction (
         unsigned char *handle, 
         long *return_code
         )

在读取每个请求之后但在执行任何处理之前,将对该请求调用为此步骤定义的函数。在高速缓存代理处理客户机的请求之前,可以使用此步骤中的插件来访问该请求。

preExit 函数的有效返回码如下:

不能使用其他返回码。

如果此函数返回 HTTP_OK,那么代理服务器假定已处理请求。将绕过所有后续请求处理步骤,并且仅执行响应步骤(转换器、记录和 退出后)。

在此步骤期间,所有预定义 API 函数都有效。

午夜

void  HTTPD_LINKAGE  MidnightFunction (
         unsigned char *handle, 
         long *return_code
         )

为此步骤定义的函数每天在午夜运行,并且它不包含任何请求上下文。例如,可以使用该函数来调用子进程以分析日志。(注意,在此步骤期间进行的大量处理会影响记录。)

认证

void  HTTPD_LINKAGE  AuthenticationFunction (
         unsigned char *handle, 
         long *return_code
         )

将根据每个请求的认证模式对该请求调用为此步骤定义的函数。可以使用此函数来定制随请求一起发送的安全性令牌的验证方式。

名称转换

void  HTTPD_LINKAGE  NameTransFunction (
         unsigned char *handle, 
         long *return_code
         )

将对每个请求调用为此步骤定义的函数。如果仅希望对与某个 URL 模板匹配的请求调用该插件函数,那么可以在配置文件伪指令中指定该模板。名称转换步骤在处理请求之前进行,它提供了一个用于将 URL 映射至对象(例如文件名)的机制。

授权

void  HTTPD_LINKAGE  AuthorizationFunction (
         unsigned char *handle, 
         long *return_code
         )

将对每个请求调用为此步骤定义的函数。如果仅希望对与某个 URL 模板匹配的请求调用该插件函数,那么可以在配置文件伪指令中指定该模板。授权步骤在处理请求之前进行,可以用于验证是否可以将所标识的对象返回给客户机。如果正在执行基本认证,那么必须生成必需的 WWW-Authenticate 头。

对象类型

void  HTTPD_LINKAGE  ObjTypeFunction (
         unsigned char *handle, 
         long *return_code
         )

将对每个请求调用为此步骤定义的函数。如果仅希望对与某个 URL 模板匹配的请求调用该插件函数,那么可以在配置文件伪指令中指定该模板。对象类型步骤在处理请求之前进行,可以用于检查对象是否存在,并可以用于输入对象。

授权后

void  HTTPD_LINKAGE  PostAuthFunction (
         unsigned char *handle, 
         long *return_code
         )

在对请求进行授权之后但在执行任何处理之前,将调用为此步骤定义的函数。如果此函数返回 HTTP_OK,那么代理服务器假定已处理请求。将绕过所有后续请求步骤,并且仅执行响应步骤(转换器、记录和 退出后)。

在此步骤期间,所有服务器预定义函数都有效。

服务

void  HTTPD_LINKAGE  ServiceFunction (
         unsigned char *handle, 
         long *return_code 
         )

将对每个请求调用为此步骤定义的函数。如果仅希望对与某个 URL 模板匹配的请求调用该插件函数,那么可以在配置文件伪指令中指定该模板。如果在退出前或授权后步骤中未满足请求,那么服务步骤将满足该请求。

在此步骤期间,所有服务器预定义函数都有效。

请参阅 WebSphere Application Server 高速缓存代理 Administration Guide 中的 Enable 伪指令,以了解有关配置根据 HTTP 方法而不是 URL 来执行的 Service 函数的信息。

转换器
可以使用此进程步骤中调用的函数来过滤流形式的响应数据。将按顺序调用此步骤的四个插件函数,每个函数充当一段管道,数据通过该管道流动。即,将对每个响应按顺序调用您提供的 openwritecloseerror 函数。每个函数依次处理同一个数据流。

对于此步骤,您必须实现下列四个函数。(您的函数名不需要与这些名称匹配。)

注意:

GC 顾问程序

void  HTTPD_LINKAGE  GCAdvisorFunction (
         unsigned char *handle, 
         long *return_code
         )

将在垃圾回收期间对高速缓存中的每个文件调用为此步骤定义的函数。此函数使您能够影响将保存和废弃哪些文件。有关更多信息,请参阅 GC_* 变量。

代理顾问程序

void  HTTPD_LINKAGE  ProxyAdvisorFunction (
         unsigned char *handle, 
         long *return_code
         )

将在每个代理请求的服务期间调用为此步骤定义的函数。例如,可以使用该函数来设置 USE_PROXY 变量。

日志

void  HTTPD_LINKAGE  LogFunction (
         unsigned char *handle,
         long *return_code
         )

在处理每个请求并且关闭与客户机的通信之后,将对该请求调用为此步骤定义的函数。如果仅希望对与某个 URL 模板匹配的请求调用该插件函数,那么可以在配置文件伪指令中指定该模板。无论请求处理成功与否,都将调用此函数。如果不希望您的记录插件覆盖缺省记录机制,请将返回码设置为 HTTP_NOACTION,而不是设置为 HTTP_OK。

错误

void  HTTPD_LINKAGE  ErrorFunction (
         unsigned char *handle, 
         long *return_code
         )

将对失败的每个请求调用为此步骤定义的函数。如果仅希望对与某个 URL 模板匹配的失败请求调用该插件函数,那么可以在配置文件伪指令中指定该模板。错误步骤使您有机会定制错误响应。

PostExit

void  HTTPD_LINKAGE  PostExitFunction (
         unsigned char *handle, 
         long *return_code
         )

将对每个请求调用为此步骤定义的函数,而无论该请求成功与否。此步骤使您能够对插件为了处理请求而分配的任何资源执行清除任务。

服务器终止

void  HTTPD_LINKAGE  ServerTermFunction (
         unsigned char *handle, 
         long *return_code
         )

在服务器执行有序关闭时,将调用为此步骤定义的函数。该函数使您能够清除服务器初始化步骤期间分配的资源。不要在此步骤中调用任何 HTTP_* 函数(结果是不可预测的)。如果配置文件中有多个用于服务器终止的高速缓存代理 API 伪指令,那么将调用所有这些伪指令。

注:
因为 Solaris 代码中当前存在局限性,所以在 Solaris 平台上发出 ibmproxy -stop 命令以关闭高速缓存代理时,不会执行服务器终止插件步骤。请参阅 WebSphere Application Server 高速缓存代理 Administration Guide,以了解有关启动和停止高速缓存代理的信息。

HTTP 返回码和值

这些返回码遵循万维网联盟 (www.w3.org/pub/WWW/Protocols/) 发布的 HTTP 1.1 规范 RFC 2616。您的插件函数必须返回其中一个值。

表 2. 高速缓存代理 API 函数的 HTTP 返回码
返回码
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

预定义函数和宏

您可以从自己的插件函数调用服务器的预定义函数和宏。您必须使用其预定义名称并遵循下面所描述的格式。在参数描述中,字母 i 指示输入参数,字母 o 指示输出参数,而 i/o 则指示同时用于输入和输出的参数。

其中每个函数都将根据请求成功与否返回一个 HTTPD 返回码。预定义函数和宏的返回码中描述了这些代码。

在调用这些函数时,请使用对您的插件提供的句柄作为第一个参数。否则,函数将返回 HTTPD_PARAMETER_ERROR 错误代码。不接受 NULL 作为有效句柄。

HTTPD_authenticate()
认证用户标识和/或密码。仅在退出前、认证、授权和授权后步骤中有效。

void  HTTPD_LINKAGE  HTTPD_authenticate (
         unsigned char *handle,      /* i; handle */
         long *return_code           /* o; return code */
         )
HTTPD_cacheable_url()
返回指定的 URL 内容按照高速缓存代理的标准是否可高速缓存。

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 */
        )

返回值 HTTPD_SUCCESS 指示 URL 内容可高速缓存;HTTPD_FAILURE 指示该内容不可高速缓存。HTTPD_INTERNAL_ERROR 也是此函数的可能返回码。

HTTPD_close()
(仅在转换器步骤中有效。)将控制权移交给流堆栈中的下一个 close 例程。请在执行任何期望的处理之后从 Transmogrifier open、write 或 close 函数调用此函数。此函数通知代理服务器,已处理响应并且完成了转换器步骤。

void  HTTPD_LINKAGE  HTTPD_close (
         unsigned char *handle,       /* i; handle */
         long *return_code            /* o; return code */ 
         )
HTTPD_exec()
执行脚本以满足此请求。在退出前、服务、授权后和错误步骤中有效。

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()
抽取与此请求相关联的变量的值。name 参数的有效变量与 CGI 中使用的那些有效变量相同。请参阅变量,以了解更多信息。注意,此函数在所有步骤中都有效;然而,并非所有变量在所有步骤中都有效。

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 */
      )

如果此函数返回代码 HTTPD_BUFFER_TOO_SMALL,那么您请求的缓冲区大小对于所抽取的值来说不够大。在这种情况下,此函数不会使用该缓冲区,但是会使用您成功抽取此值所需要的缓冲区大小更新 value_length 参数。请使用至少与返回的 value_length 一样大的缓冲区重试抽取操作。

注:
如果正在抽取的变量用于 HTTP 头,那么 HTTPD_extract() 函数将仅抽取出现的第一个匹配项,即使该请求包含多个同名的头。可以使用 httpd_getvar() 函数代替 HTTPD_extract(),并且它还有其他益处。请参阅有关 httpd_getvar() 函数的部分,以了解更多信息。
HTTPD_file()
发送文件以满足此请求。仅在退出前、服务、错误、授权后和转换器步骤中有效。

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()
与 HTTPD_extract() 相同,但更容易使用,因为用户不必指定自变量的长度。

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 */
   )

包含头的数组的下标从 0 开始。要获取数组中的第一项,请使用值 0 来表示 n;要获取第五项,请使用值 4 来表示 n

注:
不要废弃或更改返回值的内容。返回的字符串是以 null 结束的字符串。
HTTPD_log_access()
将一个字符串写入服务器的访问日志中。

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()
将一个字符串写入服务器的错误日志中。

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()
将一个字符串写入服务器的事件日志中。

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 */
         )

注意,在服务器事件日志中写入百分比符号 (%) 时,需要使用转义符号。

HTTPD_log_trace()
将一个字符串写入服务器的跟踪日志中。

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()
(仅在转换器步骤中有效。)将控制权移交给流堆栈中的下一个例程。请在设置任何期望的头并且已准备好开始 write 例程之后从 Transmogrifier open、write 或 close 函数调用此函数。

void  HTTPD_LINKAGE  HTTPD_open (
         unsigned char *handle,      /* i; handle */
         long *return_code           /* o; return code */ 
         )	
HTTPD_proxy()
生成代理请求。在退出前、服务和授权后步骤中有效。
注:
这是一个完成函数;在此函数后将完成请求。

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()
读取客户机请求的主体。将 HTTPD_extract() 用于头。仅在退出前、授权、授权后和服务步骤中有效,并且仅在完成 PUT 或 POST 请求后才有用。请在循环中调用此函数,直到返回 HTTPD_EOF 为止。如果此请求没有主体,那么此函数将失败。

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()
在处理了所有活动的请求之后重新启动服务器。在除服务器初始化、服务器终止和转换器之外的所有步骤中有效。

void  HTTPD_LINKAGE  HTTPD_restart ( 
         long *return_code    /* o; return code */
         )
HTTPD_set()
设置与此请求相关联的变量的值。对 name 参数有效的变量与 CGI 中使用的那些变量相同。请参阅变量,以了解更多信息。

注意,您还可以使用此函数创建变量。您创建的变量遵循 HTTP_ 和 PROXY_ 前缀的约定,在变量中描述了这些约定。如果创建一个以 HTTP_ 开头的变量,那么该变量将作为响应中的头发送到客户机,而不会带有 HTTP_ 前缀。例如,要设置 Location 头,请将 HTTPD_set() 与变量名 HTTP_LOCATION 配合使用。使用 PROXY_ 前缀创建的变量将作为请求中的头发送到内容服务器。使用 CGI_ 前缀创建的变量将传递到 CGI 程序。

此函数在所有步骤中都有效;然而,并非所有变量在所有步骤中都有效。

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 */
         ) 
注:
可以使用 httpd_setvar() 函数来设置变量值,而不必指定缓冲区和长度。请参阅有关 httpd_setvar() 函数的部分,以了解更多信息。
httpd_setvar()
与 HTTPD_set() 相同,但更容易使用,因为用户不必指定自变量的长度。

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 */
       )
addHdr

参数具有四个可能的值:

在 HTAPI.h 中定义了这些值。

httpd_variant_insert()
将一个变体插入高速缓存中。

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 */
         )

注意:

  1. dimension 自变量表示一个头,此对象通过该头随 URI 而变。例如,在以上示例中,一个可能的 dimension 值是 User-Agent。
  2. variant 自变量表示 dimension 自变量中给定的头的头值。此值随 URI 而变。例如,在以上示例中,variant 自变量的一个可能值如下:
    Mozilla 4.0 (compatible; BatBrowser 94.1.2; Bat OS)
  3. filename 自变量必须指向文件名的一个以 null 结束的副本,用户在该文件中保存了已修改的内容。用户负责除去该文件;在从此函数返回之后,此操作是安全的。该文件仅包含没有头的主体。
  4. 高速缓存变体时,服务器会更新 content-length 头并添加一个 Warning: 214 头。将除去 Strong 实体标记。
httpd_variant_lookup()
确定给定的变体在高速缓存中是否存在。

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()
写入响应的主体。在退出前、服务、错误和转换器步骤中有效。

如果在首次调用此函数之前未设置内容类型,那么服务器会假定您正在发送 CGI 数据流。

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 */
注:
要设置响应头,请参阅有关 HTTPD_set() 函数的部分。
注:
在 HTTPD_* 函数返回之后,可以安全地释放您使用该函数传递的任何内存。

预定义函数和宏的返回码

服务器将根据请求成功与否将返回码参数设置为下列其中一个值:

表 3. 返回码
状态码 说明
-1 HTTPD_UNSUPPORTED 该函数不受支持。
0 HTTPD_SUCCESS 该函数已成功,并且输出字段有效。
1 HTTPD_FAILURE 该函数失败。
2 HTTPD_INTERNAL_ERROR 遇到内部错误,无法继续处理此请求。
3 HTTPD_PARAMETER_ERROR 传递了一个或多个无效参数。
4 HTTPD_STATE_CHECK 该函数在此进程步骤中无效。
5 HTTPD_READ_ONLY (仅由 HTTPD_set 和 httpd_setvar 返回。)该变量是只读的,无法由插件设置。
6 HTTPD_BUFFER_TOO_SMALL (仅由 HTTPD_set、httpd_setvar 和 HTTPD_read 返回。)提供的缓冲区太小。
7 HTTPD_AUTHENTICATE_FAILED (仅由 HTTPD_authenticate 返回。)认证失败。请检查 HTTP_RESPONSE 和 HTTP_REASON 变量,以了解更多信息。
8 HTTPD_EOF (仅由 HTTPD_read 返回。)指示请求主体已结束。
9 HTTPD_ABORT_REQUEST 请求已异常中止,因为客户机提供了与该请求所指定的条件不匹配的实体标记。
10 HTTPD_REQUEST_SERVICED (由 HTTPD_proxy 返回。)调用的函数已完成此请求的响应。
11 HTTPD_RESPONSE_ALREADY_COMPLETED 函数失败,因为已完成该请求的响应。
12 HTTPD_WRITE_ONLY 该变量是只写的,无法由插件读取。

用于 API 步骤的高速缓存代理配置伪指令

请求进程中的每个步骤都有一个配置伪指令,可以使用该伪指令来指示您要在该步骤期间调用并执行的插件函数。通过手动编辑并更新服务器的配置文件 (ibmproxy.conf),或者通过使用高速缓存代理“配置”和“管理”表单中的“API 请求处理”表单,可以将这些伪指令添加到该文件。

API 使用注意事项

API 伪指令和语法

这些配置文件伪指令必须在 ibmproxy.conf 文件中显示为一行,并且之间没有空格,此处明确指定的那些空格除外。虽然在某些语法示例中出现换行符以便于理解,但在实际的伪指令中那些位置不能有任何空格。

表 4. 高速缓存代理插件 API 伪指令
ServerInit /path/file:function_name init_string
退出前 /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
转换器 /path/file:open_function_name: write_function_name: close_function_name:error_function
Log /URL /path/file:function_name
Error /URL /path/file:function_name
退出后 /path/file:function_name
ServerTerm /path/file:function_name
ProxyAdvisor /path/file:function_name
GCAdvisor /path/file:function_name

API 伪指令变量

这些伪指令中的变量具有下列含义:

type
仅与 Authentication 伪指令一起使用,以指定是否调用插件函数。以下是有效值:
URL
指定一些请求,将对这些请求调用您的插件函数。其 URL 与此模板匹配的请求将导致使用插件函数。这些伪指令中的 URL 规范是虚拟的(它们不包含协议),但前面加了一个斜杠 (/)。例如,/www.ics.raleigh.ibm.com 是正确的,但 http://www.ics.raleigh.ibm.com 是错误的。可以将此值指定为特定 URL 或指定为模板。
path/file
已编译程序的标准文件名。
function_name
您在程序中给插件函数指定的名称。

如果您要访问路径信息,那么 Service 伪指令要求函数名后面有一个星号 (*) 。

init_string
ServerInit 伪指令的此可选部分可以包含您要传递到插件函数的任何文本。请使用 httpd_getvar() 从 INIT_STRING 变量抽取该文本。

有关这些伪指令的其他信息(包括语法),请参阅 WebSphere Application Server 高速缓存代理 Administration Guide