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.
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.
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.
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.
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.
Decodifica, verifica y almacena símbolos de seguridad.
Para obtener más información, consulte el apartado Autenticación y autorización.
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.
En los sistemas AIX, necesita un archivo de exportación (por ejemplo, libmyapp.exp) que enumere las funciones de plug-in y debe enlazar con el archivo de importación de la API de Caching Proxy, libhttpdapi.exp.
En sistemas Linux, HP-UX y Solaris, debe establecer un enlace con las bibliotecas libhttpdapi y libc.
En los sistemas Windows, necesitará un archivo de definición de módulo (.def) que enumera las funciones de plug-in y debe enlazar con HTTPDAPI.LIB.
Asegúrese de incluir HTAPI.h y de utilizar la macro HTTPD_LINKAGE en las definiciones de funciones. Esta macro garantiza que todas las funciones utilicen los mismos convenios de llamada.
Utilice los siguientes mandatos de compilación y enlace como directriz.
cc_r -c -qdbxextra -qcpluscmt foo.c
cc_r -bM:SRE -bnoentry -o libfoo.so foo.o -bI:libhttpdapi.exp -bE:foo.exp
Este mandato se muestra en dos líneas para poderlo leer.
cc -Ae -c +Z +DAportable
aCC +Z -mt -c +DAportable
gcc -c foo.c
ld -G -Bsymbolic -o libfoo.so foo.o -lhttpdapi -lc
cc -mt -Bsymbolic -c foo.c
cc -mt -Bsymbolic -G -o libfoo.so foo.o -lhttpdapi -lc
cl /c /MD /DWIN32 foo.c
link httpdapi.lib foo.obj /def:foo.def /out:foo.dll /dll
Para especificar exportaciones, utilice uno de estos métodos:
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:
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.
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.
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.
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.)
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.
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.
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.
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.
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.
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.
Para este paso, debe implementar las cuatro funciones siguientes. Los nombres de función no tienen que coincidir con estos nombres.
void * HTTPD_LINKAGE openFunction ( unsigned char *handle, long *return_code )
La función open realiza cualquier inicialización (como una asignación de almacenamiento intermedio) obligatoria para procesar los datos de esta secuencia de datos. Cualquier código de retorno que no sea HTTP_OK hace que este filtro termine anormalmente (no se llama a las funciones write y close). La función puede devolver un puntero void para que pueda asignar espacio para una estructura y que se le devuelva el puntero en el parámetro correlator de las funciones posteriores.
void HTTPD_LINKAGE writeFunction ( unsigned char *handle, unsigned char *data, /* datos de respuesta enviados por el servidor de origen */ unsigned long *length, /* longitud de los datos de respuesta */ void *correlator, /* puntero devuelto por la función 'open' */ long *return_code )
La función write procesa los datos y puede llamar a la función HTTPD_write() predefinida del servidor con los datos nuevos o cambiados. El plug-in no debe intentar liberar el almacenamiento intermedio que se le ha pasado ni esperar que el servidor libere el almacenamiento intermedio que reciba.
Si decide no cambiar los datos en el ámbito de la función write, aún puede llamar a la función HTTPD_write() en el ámbito de la función open, write o close a fin de pasar los datos de la respuesta al cliente. El argumento correlator es el puntero del almacenamiento intermedio de datos que se ha devuelto en la rutina open.
void HTTPD_LINKAGE closeFunction ( unsigned char *handle, void *correlator, long *return_code )
La función close realiza las acciones de limpieza (como desechar y liberar el almacenamiento intermedio de correlator) obligatorias para realizar el proceso de los datos para esta secuencia. El argumento correlator es el puntero del almacenamiento intermedio de datos que se ha devuelto en la rutina open.
void HTTPD_LINKAGE errorFunction ( unsigned char *handle, void *correlator, long *return_code )
La función error habilita la realización de acciones de limpieza, como desechar o liberar los datos en almacenamiento intermedio (o ambas acciones) antes de que se envíe una página de error. En este punto, se llama a las funciones open, write y close para procesar la página de error. El argumento correlator es el puntero del almacenamiento intermedio de datos que se ha devuelto en la rutina open.
Notas:
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_*.
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.
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.
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.
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.
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.
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.
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 |
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.
void HTTPD_LINKAGE HTTPD_authenticate ( unsigned char *handle, /* e; descriptor de contexto */ long *return_code /* s; código de retorno */ )
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.
void HTTPD_LINKAGE HTTPD_close ( unsigned char *handle, /* e; descriptor de contexto */ long *return_code /* s; código de retorno */ )
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 */ )
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.
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 */ )
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.
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.
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.
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.
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.
void HTTPD_LINKAGE HTTPD_open ( unsigned char *handle, /* e; descriptor de contexto */ long *return_code /* s; código de retorno */ )
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 */ )
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 */ )
void HTTPD_LINKAGE HTTPD_restart ( long *return_code /* s; código de retorno */ )
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 */ )
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.
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:
Mozilla 4.0 (compatible; BatBrowser 94.1.2; Bat OS)
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 */
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 */
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:
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. |
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.
Esto significa que el servidor procesa las directivas Service, NameTrans, Exec, Fail, Map, Pass, Proxy, ProxyWAS y Redirect en su secuencia dentro del archivo de configuración. Cuando el servidor correlaciona de forma satisfactoria un URL con un archivo, no lee ni procesa ninguna de estas directivas. (La directiva Map es una excepción. Consulte la publicación WebSphere Application Server Guía de administración de Caching Proxy para obtener información completa sobre las reglas de correlación del servidor proxy.)
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.
Las variables de estas directivas tienen los siguientes significados:
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.
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.