Procedimiento general para escribir programas de la API

Antes de escribir los programas de plug-in de Caching Proxy, tiene que entender cómo funciona el servidor proxy. El comportamiento del servidor proxy se puede dividir en varios pasos de proceso distintos. Para cada uno de estos pasos, puede proporcionar funciones personalizadas propias mediante la API. Por ejemplo, si desea realizar alguna acción después de que se lea una solicitud de cliente, pero antes de llevar a cabo otro proceso. O quizá desea llevar a cabo rutinas especiales durante la autenticación y de nuevo después de que se envíe el archivo solicitado.

Con la API se proporciona una biblioteca de funciones predefinidas. Los programas de plug-in pueden llamar a funciones de API predefinidas para que interactúen con el proceso del servidor proxy (por ejemplo, para manejar peticiones, para leer o grabar cabeceras de solicitud o para grabar en las anotaciones cronológicas del servidor proxy). Estas funciones no deben confundirse con las funciones de plug-in que escriba, a las que llama el servidor proxy. Las funciones predefinidas se describen en Funciones y macros predefinidas.

Puede indicar al servidor proxy que llame a las funciones de plug-in en los pasos adecuados mediante las directivas de la API de Caching Proxy correspondientes en el archivo de configuración del servidor. Estas directivas se describen en Directivas de configuración de Caching Proxy para pasos de API.

Este documento incluye lo siguiente:

Puede utilizar estos componentes y procedimientos para escribir sus propios programas de plug-in de Caching Proxy.

Pasos de proceso del servidor

El funcionamiento básico del servidor proxy se puede dividir en pasos en función del tipo de proceso que realiza el servidor durante dicha fase. Cada paso incluye una coyuntura en la que una parte específica del programa se puede ejecutar. Al añadir directivas de la API al archivo de configuración de Caching Proxy (ibmproxy.conf), se indican las funciones de plug-in a las que se desea llamar durante un paso concreto. Puede llamar a varias funciones de plug-in durante un paso de proceso concreto si incluye más de una directiva para ese paso.

Algunos pasos forman parte del proceso de solicitudes del servidor. En otras palabras, el servidor proxy ejecuta estos pasos cada vez que procesa una solicitud. Otros pasos se realizan de forma independiente del proceso de solicitudes, es decir, el servidor ejecuta estos pasos independientemente de si se ha procesado o no una solicitud.

El programa compilado reside en un objeto compartido, por ejemplo un archivo DLL o .so, en función del sistema operativo. A medida que el servidor avanza por los pasos de proceso de solicitudes, llama a las funciones de plug-in asociadas con cada paso hasta que una de las funciones indica que ha gestionado la solicitud. Si especifica más de una función de plug-in para un paso concreto, las funciones se llaman en el orden en el que aparecen sus directivas en el archivo de configuración.

Si una función de plug-in no gestiona la solicitud (no ha incluido una directiva de la API de Caching Proxy para ese paso o la función de plug-in de ese paso ha devuelto HTTP_NOACTION), el servidor realiza la acción predeterminada para ese paso.

Nota: Esto es así para todos los pasos excepto el paso Service; el paso Service no tiene una acción predeterminada.

En la Figura 1 se detallan los pasos del proceso de servidor proxy y se define el orden de proceso de los pasos relacionados con el proceso de solicitudes.

Figura 1. Diagrama de flujo de los pasos del proceso del servidor proxy

Cuatro de los pasos del diagrama se ejecutan independientemente del proceso de las solicitudes del cliente. Estos pasos están relacionados con la ejecución y el mantenimiento del servidor proxy. Son los siguientes:

La lista siguiente explica la finalidad de cada uno de los pasos representados en la Figura 1. Tenga en cuenta que no se garantiza que se llame a todos los pasos para una solicitud determinada.

Inicialización de servidor
Realiza la inicialización cuando se inicia el servidor proxy y antes de aceptar cualquier solicitud de cliente.
Midnight
Ejecuta un plug-in a medianoche, sin contexto de solicitud. Este paso se muestra de forma independiente en el diagrama porque no forma parte del proceso de solicitud; en otras palabras, su ejecución es independiente de cualquier solicitud.
GC Advisor
Influye en las decisiones de recogida de basura para los archivos de la memoria caché. Este paso se muestra de forma independiente en el diagrama porque no forma parte del proceso de solicitud; en otras palabras, su ejecución es independiente de cualquier solicitud. La recogida de basura se realiza cuando el tamaño de memoria caché alcanza el valor máximo. (La información sobre la configuración de la recogida de basura de memoria caché se incluye en la WebSphere Application Server Guía de administración de Caching Proxy).
PreExit

Lleva a cabo un proceso después de leer una solicitud pero antes de realizar cualquier otra acción.

Si este paso devuelve una indicación de que la solicitud se ha procesado (HTTP_OK), el servidor omite el resto de pasos del proceso de solicitudes y realiza sólo los pasos Transmogrifier, Log y PostExit.

Name Translation
Convierte la vía de acceso virtual (de un URL) en la vía de acceso física.
Authorization

Utiliza los símbolos de seguridad almacenados para comprobar la vía de acceso física para protecciones, ACL y otros controles de acceso y genera las cabeceras de autenticación WWW obligatorias para la autenticación básica. Si escribe una función de plug-in propia para sustituir este paso, debe generar estas cabeceras personalmente.

Para obtener más información, consulte el apartado Autenticación y autorización.

Authentication

Decodifica, verifica y almacena símbolos de seguridad.

Para obtener más información, consulte el apartado Autenticación y autorización.

Object Type
Localiza el objeto del sistema de archivos que indica la vía de acceso.
Post Authorization

Lleva a cabo el proceso después de la autorización y la localización del objeto, pero antes de que se dé respuesta a la solicitud.

Si este paso devuelve una indicación de que la solicitud se ha procesado (HTTP_OK), el servidor omite el resto de pasos del proceso de solicitudes y realiza sólo los pasos Transmogrifier, Log y PostExit.

Service
Da respuesta a la solicitud (enviando el archivo, ejecutando el CGI, etc.).
Proxy Advisor
Influye en las decisiones de proxy y memoria caché.
Transmogrifier
Proporciona acceso de escritura a la parte de datos de la respuesta enviada al cliente.
Log
Habilita el registro cronológico de transacciones personalizado.
Error
Permite respuestas personalizas a condiciones de error.
PostExit
Borra los recursos asignados para el proceso de solicitudes.
Server Termination
Realiza un proceso de limpieza cuando tiene lugar una conclusión normal.

Directrices

Funciones de plug-in

Siga la sintaxis presentada en Prototipos de función de plug-in para escribir sus propias funciones de programa para los pasos de proceso de solicitudes definidos.

Cada una de las funciones debe rellenar el parámetro de código de retorno con un valor que indique la acción que se ha llevado a cabo:

Prototipos de función de plug-in

Los prototipos de función de cada paso de Caching Proxy muestran el formato que se va a utilizar y explican el tipo de proceso que pueden realizar. Tenga en cuenta que los nombres de función no están predefinidos. Debe asignar a las funciones nombres exclusivos y puede elegir convenios de nombres propios. Para que la asociación resulte más fácil, en este documento se utilizan nombres relacionados con los pasos de proceso del servidor.

En cada una de estas funciones de plug-in, son válidas algunas funciones predefinidas de la API. Otras funciones predefinidas no son válidas para todos los pasos. Las siguientes funciones predefinidas de la API son válidas cuando se llaman desde todas estas funciones de plug-in:

En las descripciones de prototipos de función se indican las funciones válidas o no válidas adicionales de la API.

El valor del parámetro handle enviado a las funciones se puede pasar como primer argumento a las funciones predefinidas. Las funciones predefinidas de la API se describen en Funciones y macros predefinidas.

Inicialización de servidor

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

La función definida para este paso se llama cuando se carga el módulo durante la inicialización del servidor. Es su oportunidad de realizar la inicialización antes de que se hayan aceptado las solicitudes.

Aunque se llame a todas las funciones de inicialización del servidor, un código de retorno de error de una función en este paso provoca que el servidor omita todas las funciones restantes configuradas en el mismo módulo que la función que retornó el código de error. (Es decir, no se llamará a ninguna otra función contenida en el mismo objeto compartido que la función que devolvió el error.)

Los parámetros de versión contienen el número de versión del servidor proxy; los proporciona el Caching Proxy.

PreExit

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

La función definida para este paso se llama para cada solicitud después de que la solicitud se haya leído, pero antes que se haya producido el proceso. Un plug-in en este paso se puede utilizar para acceder a la solicitud del cliente antes de que sea procesado por el Caching Proxy.

Los códigos de retorno válidos para la función preExit son los siguientes:

No se deben utilizar otros códigos de retorno.

Si esta función devuelve HTTP_OK, el servidor proxy supone que la solicitud se ha gestionado. Los pasos posteriores de proceso de solicitud se pasan por alto y sólo se realizan los pasos de respuesta (Transmogrifier, Log y PostExit).

Todas las funciones predefinidas de la API son válidas durante este paso.

Midnight

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

La función definida para este paso se ejecuta diariamente a medianoche y no contiene contexto de solicitud. Por ejemplo, se puede utilizar para invocar un proceso hijo y analizar los registros. (Tenga en cuenta que el proceso extensivo durante este paso puede interferir con el registro cronológico.)

Authentication

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

La función definida para este paso se llama para cada solicitud basada en el esquema de autenticación de solicitudes. Esta función se puede utilizar para personalizar la verificación de las señales de seguridad que se envían con una solicitud.

Name Translation

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

La función definida para este paso se llama para cada solicitud. Se puede especificar una plantilla de URL en la directiva del archivo de configuración si desea que se llame a la función de plug-in sólo para las solicitudes que coincidan con la plantilla. El paso de Name Translation tiene lugar antes de que se procese la solicitud y proporciona un mecanismo para correlacionar URL con objetos, como nombres de archivo.

Authorization

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

La función definida para este paso se llama para cada solicitud. Se puede especificar una plantilla de URL en la directiva del archivo de configuración si desea que se llame a la función de plug-in sólo para las solicitudes que coincidan con la plantilla. El paso de autorización tiene lugar antes de que se procese la solicitud y se puede utilizar para verificar que el objeto identificado se pueda devolver al cliente. Si va a realizar una autenticación básica, debe generar las cabeceras WWW-Authenticate obligatorias.

Object Type

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

La función definida para este paso se llama para cada solicitud. Se puede especificar una plantilla de URL en la directiva del archivo de configuración si desea que se llame a la función de plug-in sólo para las solicitudes que coincidan con la plantilla. El paso de tipo de objeto tiene lugar antes de que se procese la solicitud y se puede utilizar para comprobar si el objeto existe y para realizar una configuración de tipo de objeto.

PostAuthorization

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

La función definida para este paso se llama después de que se haya autorizado la solicitud pero antes de que tenga lugar un proceso. Si esta función devuelve HTTP_OK, el servidor proxy supone que la solicitud se ha gestionado. Los pasos posteriores de solicitud se pasan por alto y sólo se llevan a cabo los pasos de respuesta (Transmogrifier, Log y PostExit).

Todas las funciones predefinidas de servidor son válidas durante este paso.

Service

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

La función definida para este paso se llama para cada solicitud. Se puede especificar una plantilla de URL en la directiva del archivo de configuración si desea que se llame a la función de plug-in sólo para las solicitudes que coincidan con la plantilla. El paso Service da respuesta a la solicitud, si no se ha dado respuesta en los pasos PreExit o PostAuthorization.

Todas las funciones predefinidas de servidor son válidas durante este paso.

Consulte la directiva Enable en el WebSphere Application Server Guía de administración de Caching Proxy para obtener información sobre cómo configurar la función Service que se debe ejecutar según el método HTTP en lugar del URL.

Transmogrifier
Las funciones a las que se llama en este paso de proceso se pueden utilizar para filtrar datos de respuesta como secuencia de datos. Se llama a cuatro funciones de plug-in para este paso de forma secuencial y cada una actúa como segmento de conducto a través del que fluyen los datos. Es decir, se llama a las funciones open, write, close y error que proporcione, en ese orden, para cada respuesta. Cada función procesa la misma secuencia de datos por su parte.

Para este paso, debe implementar las cuatro funciones siguientes. Los nombres de función no tienen que coincidir con estos nombres.

Notas:

GC Advisor

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

La función definida para este paso se llama para cada archivo de la memoria caché durante la recogida de basura. Esta función permite asesorar sobre los archivos que se conservan y los que se descartan. Para obtener más información, consulte las variables GC_*.

Proxy Advisor

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

Se invoca una función definida durante el servicio de cada solicitud de proxy. Por ejemplo, se puede utilizar para establecer la variable USE_PROXY.

Log

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

La función definida para este paso se llama para cada solicitud después de que se haya procesado la solicitud y se haya cerrado la comunicación con el cliente. Se puede especificar una plantilla de URL en la directiva del archivo de configuración si desea que se llame a la función de plug-in sólo para las solicitudes que coincidan con la plantilla. Se llama a esta función independientemente de la ejecución satisfactoria o no del proceso de solicitudes. Si no desea que el plug-in de anotaciones cronológicas altere temporalmente el mecanismo de anotaciones cronológicas predeterminado, establezca el código de retorno en HTTP_NOACTION, en lugar de HTTP_OK.

Error

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

La función definida para este paso se llama para cada solicitud que falla. Se puede especificar una plantilla de URL en la directiva del archivo de configuración si desea que se llame a la función de plug-in sólo para las solicitudes que hayan fallado y que coincidan con la plantilla. El paso Error le ofrece la oportunidad de personalizar la respuesta al error.

PostExit

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

La función definida para este paso se llama para cada solicitud, independientemente de la ejecución satisfactoria o no de la solicitud. Este paso permite realizar tareas de limpieza para los recursos asignados por el plug-in a fin de procesar la solicitud.

Server Termination

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

La función definida para este paso se llama cuando tiene lugar una conclusión normal del servidor. Permite limpiar los recursos asignados durante el paso Server Initialization. No llame a funciones HTTP_* en este paso (los resultados son imprevisibles). Si tiene más de una directiva de la API de Caching Proxy en el archivo de configuración para Server Termination, se les realizará una llamada.

Nota:
Debido a una limitación actual en el código de Solaris, el paso de plug-in de Server Termination no se ejecuta cuando se utiliza el mandato ibmproxy-stop para cerrar el Caching Proxy en las plataformas Solaris. Consulte la publicación WebSphere Application Server Guía de administración de Caching Proxy para obtener información acerca del inicio y la detención de Caching Proxy.

Códigos y valores de retorno de HTTP

Estos códigos de retorno siguen la especificación HTTP 1.1, RFC 2616, publicada por World Wide Web Consortium (www.w3.org/pub/WWW/Protocols/). Las funciones de plug-in deben devolver uno de estos valores.

Tabla 2. Códigos de retorno HTTP para las funciones de la API de Caching Proxy
Valor Código de retorno
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

Funciones y macros predefinidas

Puede llamar a las funciones y las macros predefinidas del servidor desde funciones de plug-in propias. Debe utilizar sus nombres predefinidos y respetar el formato que se describe a continuación. En las descripciones de parámetros, la letra e indica un parámetro de entrada, la letra s indica un parámetro de salida y e/s indica que se utiliza un parámetro tanto para la entrada como para la salida.

Cada una de estas funciones devuelve uno de los códigos de retorno HTTPD, en función de si la solicitud se ha llevado a cabo de forma satisfactoria. Estos códigos se describen en Códigos de retorno de funciones y macros predefinidas.

Utilice el descriptor de contexto que se proporciona para el plug-in como primer parámetro cuando llame a estas funciones. De lo contrario, la función devuelve un código de error HTTPD_PARAMETER_ERROR. NULL no se acepta como descriptor de contexto válido.

HTTPD_authenticate()
Autentica un ID de usuario o una contraseña, o ambos. Sólo es válida en los pasos PreExit, Authentication, Authorization y PostAuthorization.

void  HTTPD_LINKAGE  HTTPD_authenticate (
    unsigned char *handle,             /* e; descriptor de contexto */
         long *return_code         /* s; código de retorno */
         )
HTTPD_cacheable_url()
Indica si el contenido del URL especificado se puede almacenar en la memoria caché de acuerdo con los estándares de Caching Proxy.

void HTTPD_LINKAGE  HTTPD_cacheable_url ( 
    unsigned char *handle,             /* e; descriptor de contexto */
        unsigned char *url,         /* e; URL que se debe comprobar */
        unsigned char *req_method,  /* e; método de solicitud del URL */
        long *retval                /* s; código de retorno */
        )

El valor de retorno HTTPD_SUCCESS indica que el contenido del URL se puede almacenar en memoria caché; HTTPD_FAILURE indica que el contenido no se puede almacenar en memoria caché. HTTPD_INTERNAL_ERROR también es un código de retorno posible para esta función.

HTTPD_close()
Sólo es válida para el paso Transmogrifier. Transfiere el control a la siguiente rutina close de la pila de secuencias. Llame a esta función desde las funciones open, write o close de Transmogrifier después de que se realicen los procesos que desee. Esta función notifica al servidor proxy que la respuesta se ha procesado y que el paso Transmogrifier se ha completado.

void  HTTPD_LINKAGE  HTTPD_close (
    unsigned char *handle,             /* e; descriptor de contexto */
         long *return_code         /* s; código de retorno */
         )
HTTPD_exec()
Ejecuta un script para satisfacer esta solicitud. Es válida en los pasos PreExit, Service, PostAuthorization y Error.

void  HTTPD_LINKAGE  HTTPD_exec (
    unsigned char *handle,             /* e; descriptor de contexto */
         unsigned char *name,           /* e; nombre del script que debe
                                           ejecutarse */
         unsigned long *name_length,  /* e; longitud del nombre */
         long *return_code         /* s; código de retorno */
         )
HTTPD_extract()
Extrae el valor de una variable asociada con esta solicitud. Las variables válidas del parámetro name son las mismas que las que se utilizan en la CGI. Para obtener más información, consulte el apartado Variables. Tenga en cuenta que esta función es válida en todos los pasos; no obstante, no todas las variables son válidas en todos los pasos.

void  HTTPD_LINKAGE  HTTPD_extract (
    unsigned char *handle,             /* e; descriptor de contexto */
      unsigned char *name,         /* e; nombre de la variable que debe
                                      extraerse */
         unsigned long *name_length,  /* e; longitud del nombre */
      unsigned char *value,        /* o; almacenamiento intermedio en el que
                                      que se debe colocar el valor */
      unsigned long *value_length, /* e/s; tamaño de almacenamiento
                                      intermedio */
         long *return_code         /* s; código de retorno */
      )

Si esta función devuelve el código HTTPD_BUFFER_TOO_SMALL, el tamaño del almacenamiento intermedio que ha solicitado no era lo suficientemente grande para el valor extraído. En tal caso, la función no utiliza el almacenamiento intermedio, pero actualiza el parámetro value_length con el tamaño del almacenamiento intermedio que necesite a fin de extraer satisfactoriamente este valor. Vuelva a intentar la extracción con un almacenamiento intermedio que tenga, como mínimo, el mismo tamaño que el valor de longitud_valor devuelto.

Nota:
Si la variable que se va a extraer es para una cabecera HTTP, la función HTTPD_extract() extraerá sólo la primera aparición coincidente, aunque la solicitud contenga varias cabeceras con el mismo nombre. La función httpd_getvar() se puede utilizar en lugar de HTTPD_extract() y también tiene otras ventajas. Consulte la sección sobre el httpd_getvar() function para obtener más información.
HTTPD_file()
Envía un archivo para dar respuesta a esta solicitud. Sólo es válida en los pasos PreExit, Service, Error, PostAuthorization y Transmogrifier.

void  HTTPD_LINKAGE  HTTPD_file (
    unsigned char *handle,             /* e; descriptor de contexto */
         unsigned char *name,            /* e; nombre del archivo que
                                            debe enviarse */
         unsigned long *name_length,  /* e; longitud del nombre */
         long *return_code         /* s; código de retorno */
         )
httpd_getvar()
Es la misma que HTTPD_extract(), excepto que es más fácil de utilizar porque el usuario no tiene que especificar longitudes para los argumentos.

const  unsigned char *          /* s; valor de la variable */
HTTPD_LINKAGE
httpd_getvar(
    unsigned char *handle,             /* e; descriptor de contexto */
       unsigned char *name,         /* e; nombre de la variable */
   unsigned long *n             /* i; número de índice para la matriz
                                   que contiene la cabecera */
   )

El índice de la matriz que contiene la cabecera empieza por 0. Para obtener el primer elemento de la matriz, utilice el valor 0 para n; para obtener el quinto elemento, utilice el valor 4 para n.

Nota:
No descarte ni cambie el contenido del valor devuelto. La serie devuelta tiene una terminación con un valor null.
HTTPD_log_access()
Graba una serie en las anotaciones cronológicas de acceso del servidor.

void  HTTPD_LINKAGE  HTTPD_log_access (
    unsigned char *handle,             /* e; descriptor de contexto */
         unsigned char *value,        /* e; datos que se deben grabar */
         unsigned long *value_length, /* e; longitud de los datos */
         long *return_code         /* s; código de retorno */
         )  

Tenga en cuenta que los símbolos de escape no son obligatorios cuando se graba el símbolo de porcentaje (%) en las anotaciones cronológicas de acceso del servidor.

HTTPD_log_error()
Graba una serie en las anotaciones cronológicas de errores del servidor.

void  HTTPD_LINKAGE  HTTPD_log_error (
    unsigned char *handle,             /* e; descriptor de contexto */
         unsigned char *value,        /* e; datos que se deben grabar */
         unsigned long *value_length, /* e; longitud de los datos */
         long *return_code         /* s; código de retorno */
         )

Tenga en cuenta que los símbolos de escape no son obligatorios cuando se graba el símbolo de porcentaje (%) en las anotaciones cronológicas de errores del servidor.

HTTPD_log_event()
Graba una serie en las anotaciones cronológicas de sucesos del servidor.

void  HTTPD_LINKAGE  HTTPD_log_event (
    unsigned char *handle,             /* e; descriptor de contexto */
         unsigned char *value,        /* e; datos que se deben grabar */
         unsigned long *value_length, /* e; longitud de los datos */
         long *return_code         /* s; código de retorno */
         )

Tenga en cuenta que los símbolos de escape no son obligatorios cuando se graba el símbolo de porcentaje (%) en las anotaciones cronológicas de sucesos del servidor.

HTTPD_log_trace()
Graba una serie en las anotaciones cronológicas de rastreo del servidor.

void  HTTPD_LINKAGE  HTTPD_log_trace (
    unsigned char *handle,             /* e; descriptor de contexto */
         unsigned char *value,        /* e; datos que se deben grabar */
         unsigned long *value_length, /* e; longitud de los datos */
         long *return_code         /* s; código de retorno */
         )

Tenga en cuenta que los símbolos de escape no son obligatorios cuando se graba el símbolo de porcentaje (%) en las anotaciones cronológicas de rastreo del servidor.

HTTPD_open()
Sólo es válida para el paso Transmogrifier. Transfiere el control a la siguiente rutina de la pila de secuencias. Llame a esta función desde las funciones open, write o close de Transmogrifier después de establecer las cabeceras que desee y si está preparado para iniciar la rutina write.

void  HTTPD_LINKAGE  HTTPD_open (
    unsigned char *handle,             /* e; descriptor de contexto */
         long *return_code         /* s; código de retorno */
         )	
HTTPD_proxy()
Realiza una solicitud de proxy. Es válida en los pasos PreExit, Service y PostAuthorization.
Nota:
Es una función de finalización; la solicitud finaliza después de esta función.

void  HTTPD_LINKAGE  HTTPD_proxy (
         unsigned char *handle,        /* e; descriptor de contexto */
         unsigned char *url_name,      /* i; URL para la
                                        solicitud de proxy */
         unsigned long *name_length, /* e; longitud del URL */
         void *request_body,         /* e; cuerpo de la solicitud */
         unsigned long *body_length, /* e; longitud del cuerpo */
         long *return_code         /* s; código de retorno */
         ) 
HTTPD_read()
Lee el cuerpo de la solicitud del cliente. Utilice HTTPD_extract() para las cabeceras. Sólo es válida en los pasos PreExit, Authorization, PostAuthorization y Service y sólo es útil si se ha realizado una solicitud PUT o POST. Llame a esta función en un bucle hasta que se devuelva HTTPD_EOF. Si no hay ningún cuerpo para esta solicitud, esta función falla.

void  HTTPD_LINKAGE  HTTPD_read (
    unsigned char *handle,             /* e; descriptor de contexto */
         unsigned char *value,           /* i; alm. int. para datos */
         unsigned long *value_length,    /* i/o; tamaño del almacenamiento
                                         intermedio (longitud de datos) */
         long *return_code         /* s; código de retorno */
         )
HTTPD_restart()
Reinicia el servidor después de que se hayan procesado todas las solicitudes activas. Es válida en todos los pasos excepto Server Initialization, Server Termination y Transmogrifier.

void  HTTPD_LINKAGE  HTTPD_restart ( 
         long *return_code         /* s; código de retorno */
         )
HTTPD_set()
Establece el valor de una variable asociada con esta solicitud. Las variables válidas del parámetro name son las mismas que las que se utilizan en la CGI. Para obtener más información, consulte el apartado Variables.

Tenga en cuenta que también puede crear variables con esta función. Las variables que cree están sujetas a los convenios de los prefijos HTTP_ y PROXY_, que se describen en Variables. Si crea una variable que empieza por HTTP_, se envía como cabecera en la respuesta al cliente, sin el prefijo HTTP_. Por ejemplo, para establecer una cabecera Location, utilice HTTPD_set() con el nombre de variable HTTP_LOCATION. Las variables creadas con un prefijo PROXY_ se envían como cabeceras en la solicitud al servidor de contenido. Las variables creadas con un prefijo CGI_ se pasan a los programas de CGI.

Esta función es válida en todos los pasos; no obstante, no todas las variables son válidas en todos los pasos.

void  HTTPD_LINKAGE  HTTPD_set (
         unsigned char *handle,        /* e; descriptor de contexto */
         unsigned char *name,         /* e; nombre de la variable que se
                                         debe establecer */
         unsigned long *name_length,  /* e; longitud del nombre */
         unsigned char *value,         /* i; alm. int. con el valor */
         unsigned long *value_length, /* e; longitud del valor */
         long *return_code         /* s; código de retorno */
         ) 
Nota:
Puede utilizar la función httpd_setvar() para establecer un valor de variable sin tener que especificar un almacenamiento intermedio y una longitud. Consulte la sección sobre httpd_setvar() function para obtener información.
httpd_setvar()
Es la misma que HTTPD_set(), excepto que es más fácil de utilizar porque el usuario no tiene que especificar longitudes para los argumentos.

long             /* s; código de retorno */
HTTPD_LINKAGE   httpd_setvar (
    unsigned char *handle,             /* e; descriptor de contexto */
       unsigned char *name,         /* e; nombre de la variable */
       unsigned char *value,        /* i; valor nuevo */
       unsigned long *addHdr        /* e; añadir cabecera o sustituirla */
       )

El parámetro addHdr tiene cuatro valores posibles:

Estos valores se definen en HTAPI.h.

httpd_variant_insert()
Inserta un variant en la memoria caché.

void  HTTPD_LINKAGE  httpd_variant_insert (
         unsigned char *handle,        /* e; descriptor de contexto */
         unsigned char *URI,       /* e; URI de este objeto */
    unsigned char *dimension,          /* e; dimensión de variant */
    unsigned char *variant,            /* e; valor de variant */
         unsigned char *filename,  /* e; archivo que contiene el objeto */
         long *return_code         /* s; código de retorno */
         )

Notas:

  1. El argumento dimensión hace referencia a la cabecera que establece la variación de este objeto a partir del URI. Por ejemplo, en el ejemplo anterior, un valor de dimensión posible es User-Agent.
  2. El argumento variant hace referencia al valor de la cabecera que se indica en el argumento dimension. Varía a partir del URI. Por ejemplo, en el ejemplo anterior, un valor posible para el argumento variant es el siguiente:
    Mozilla 4.0 (compatible; BatBrowser 94.1.2; Bat OS)
  3. El argumento filename debe apuntar a una copia con terminación en valor nulo del nombre de archivo en el que el usuario ha guardado el contenido modificado. El usuario es responsable de eliminar el archivo; esta acción es segura después de volver de esta función. El archivo sólo contiene el cuerpo sin cabeceras.
  4. Cuando se almacenan variantes en memoria caché, el servidor actualiza la cabecera content-length y añade un aviso: cabecera 214. Los códigos de entidad Strong se eliminan.
httpd_variant_lookup()
Determina si existe un variant determinado en la memoria caché.

void  HTTPD_LINKAGE  httpd_variant_lookup (
    unsigned char *handle,             /* e; descriptor de contexto */
    unsigned char *URI,                /* URI de este objeto */
    unsigned char *dimension,          /* e; dimensión de variant */
    unsigned char *variant,            /* e; valor de variant */
             long *return_code);       /* s; código de retorno */
HTTPD_write()
Graba el cuerpo de la respuesta. Es válida en los pasos PreExit, Service, Error y Transmogrifier.

Si no establece el tipo de contenido antes de llamar a esta función por primera vez, el servidor presupone que va a enviar una secuencia de datos de CGI.

void  HTTPD_LINKAGE  HTTPD_write (
    unsigned char *handle,             /* e; descriptor de contexto */
    unsigned char *value,              /* e; datos que se deben enviar */
    unsigned char *value_length,       /* e; longitud de los datos */
             long *return_code);       /* s; código de retorno */
Nota:
Para establecer cabeceras de respuesta, consulte la sección en función HTTPD_set().
Nota:
Después de que se devuelva una función HTTPD_*, lo seguro es liberar la memoria que se ha pasado con dicha función.

Códigos de retorno de funciones y macros predefinidas

El servidor establecerá el parámetro de código de retorno en uno de estos valores, en función de si la ejecución de la solicitud es satisfactoria:

Tabla 3. Códigos de retorno
Valor Código de estado Explicación
-1 HTTPD_UNSUPPORTED La función no recibe soporte.
0 HTTPD_SUCCESS La función se ha realizado satisfactoriamente y los campos de salida son válidos.
1 HTTPD_FAILURE La función ha fallado.
2 HTTPD_INTERNAL_ERROR Se ha encontrado un error interno y el proceso de esta solicitud no puede continuar.
3 HTTPD_PARAMETER_ERROR Se han pasado uno o más parámetros no válidos.
4 HTTPD_STATE_CHECK La función no es válida en este paso de proceso.
5 HTTPD_READ_ONLY Sólo lo devuelve HTTPD_set y httpd_setvar. La variable es de sólo lectura y no la puede establecer el plug-in.
6 HTTPD_BUFFER_TOO_SMALL Sólo lo devuelve HTTPD_set, httpd_setvar y HTTPD_read. El almacenamiento intermedio era demasiado pequeño.
7 HTTPD_AUTHENTICATE_FAILED Sólo lo devuelve HTTPD_authenticate. La autenticación ha fallado. Examine las variables HTTP_RESPONSE y HTTP_REASON para obtener más información.
8 HTTPD_EOF Sólo lo devuelve HTTPD_read. Indica el final del cuerpo de la solicitud.
9 HTTPD_ABORT_REQUEST La solicitud ha terminado anormalmente porque el cliente ha proporcionado un código de entidad que no coincidía con la condición especificada por la solicitud.
10 HTTPD_REQUEST_SERVICED Lo devuelve HTTPD_proxy. La función a la que se ha llamado ha dado respuesta a esta solicitud.
11 HTTPD_RESPONSE_ALREADY_COMPLETED La función ha fallado porque ya se ha dado respuesta a esa solicitud.
12 HTTPD_WRITE_ONLY La variable es de sólo escritura y no la puede leer el plug-in.

Directivas de configuración de Caching Proxy para pasos de API

Cada paso del proceso de solicitud tiene una directiva de configuración que se utiliza para indicar cuál de las funciones del plug-in desea llamar y ejecutar durante dicho paso. Puede añadir estas directivas al archivo de configuración del servidor (ibmproxy.conf) editándolo y actualizándolo manualmente o utilizando el formulario de proceso de solicitud de API en los formularios de configuración y administración de Caching Proxy.

Notas sobre el uso de la API

Directivas y sintaxis de la API

Estas directivas de archivo de configuración deben aparecer en el archivo ibmproxy.conf en una línea, sin espacios que no sean los especificados explícitamente aquí. Aunque aparecen saltos de línea por cuestiones de legibilidad en algunos de los ejemplos de sintaxis, no debe haber espacios en esos puntos en la directiva real.

Tabla 4. directivas de API de plug-in de Caching Proxy
ServerInit /path/file:function_name init_string
PreExit /path/file:function_name
Authentication tipo /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
Servicio /URL /path/file:function_name
Midnight /path/file:function_name
Transmogrifier /path/file:open_function_name: write_function_name: close_function_name:error_function
Registros cronológicos /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

Variables de directivas de la API

Las variables de estas directivas tienen los siguientes significados:

tipo
Se utiliza sólo con la directiva Authentication para especificar si se va a llamar o no a la función de plug-in. Los valores válidos son los siguientes:
URL
Especifica las solicitudes para las que se llama a la función de plug-in. Las solicitudes con URL que coincidan con esta plantilla harán que se utilice la función de plug-in. Las especificaciones de URL de estas directivas son virtuales (no incluyen el protocolo), pero van precedidas por una barra inclinada (/). Por ejemplo, /www.ics.raleigh.ibm.com es correcto, pero http://www.ics.raleigh.ibm.com no lo es. Puede especificar este valor como URL específico o como plantilla.
path/file
Nombre de archivo plenamente cualificado del programa compilado.
function_name
Nombre asignado a la función de plug-in dentro del programa.

La directiva Service exige un asterisco (*) después del nombre de función si desea tener acceso a la información de vía de acceso.

init_string
Esta parte opcional de la directiva ServerInit puede contener cualquier texto que desee pasar a la función de plug-in. Utilice httpd_getvar() para extraer el texto de la variable INIT_STRING.

Para obtener información adicional, incluida la sintaxis, de estas directivas, consulte la publicación WebSphere Application Server Guía de administración de Caching Proxy.