Prima di scrivere i programmi plugin del Caching Proxy, è necessario essere a conoscenza delle modalità di funzionamento del server proxy. Tale funzionamento del server proxy può essere suddiviso in diverse fasi di elaborazione distinte. Per ciascuna di queste fasi è possibile fornire le proprie funzioni personalizzate mediante l'utilizzo delle API. Ad esempio, si desidera effettuare un'operazione dopo aver letto una richiesta client e prima di eseguire un'altra elaborazione? Oppure si desidera eseguire routine speciali durante l'autenticazione e dopo l'invio del file richiesto?
Con l'API viene fornita una libreria di funzioni specifiche. I programmi di plugin possono chiamare le funzioni API predefinite affinché interagiscano con il processo del server proxy (ad esempio, per gestire le richieste, per leggere e scrivere le intestazioni della richiesta o per scrivere sui log del server proxy). Queste funzioni non devono essere confuse con quelle del plugin, scritte dall'utente, che vengono chiamate dal server proxy. Le funzioni predefinite vengono descritte in Funzioni e macro predefinite.
L'utente indica al server proxy di chiamare le funzioni di plugin nelle fasi appropriate utilizzando le direttive API Caching Proxy corrispondenti nel file di configurazione del server. Tali direttive vengono descritte in Direttive di configurazione del Caching Proxy per le fasi dell'API.
Questo documento include quanto segue:
Questi componenti e queste procedure possono essere utilizzati per scrivere i propri programmi di plugin del Caching Proxy.
L'operazione di base del server proxy può essere suddivisa in fasi in base al tipo di elaborazione eseguita dal server durante quella fase specifica. Ogni fase include un punto di collegamento in cui è possibile eseguire una parte specifica del proprio programma. Aggiungendo le direttive API al file di configurazione del Caching Proxy (ibmproxy.conf), si indica la funzione di plugin che si desidera venga chiamata durante una particolare operazione. È possibile chiamare diverse funzioni di plugin durante una fase particolare del processo, includendo più di una direttiva per quella fase.
Alcune operazioni fanno parte del processo di richiesta del server. In altri termini, il server proxy esegue queste operazioni ogni volta che elabora una richiesta. Vengono poi eseguite altre operazioni indipendentemente dall'elaborazione della richiesta; vale a dire, il server esegue queste operazioni a prescindere dal fatto che ci sia o no una richiesta in fase di elaborazione.
Il programma compilato si trova in un oggetto condiviso, ad esempio, un file DLL o .so, a seconda del sistema operativo. Man mano che il server procede con le operazioni del processo di richiesta, chiama le funzioni plugin associate a ciascuna operazione fino a quando una delle funzioni non indica che la richiesta è stata gestita. Se si specifica più di una funzione di plugin per una fase particolare, tali funzioni vengono definite nell'ordine in cui le relative direttive vengono visualizzate nel file di configurazione.
Se la richiesta non viene gestita da una funzione di plugin (o l'utente non ha incluso una direttiva API del Caching Proxy per quella fase o la funzione di plugin per quella fase ha restituito HTTP_NOACTION), il server esegue l'operazione predefinita.
Nota: ciò è valido per tutte le fasi, tranne per quella relativa al servizio; questa fase non prevede alcuna operazione predefinita.
Figura 1 illustra le fasi del processo del server proxy e definisce l'ordine di elaborazione delle fasi correlate all'elaborazione della richiesta.
Quattro delle fasi presenti nel diagramma vengono eseguite indipendentemente dall'elaborazione di qualsiasi richiesta client. Tali fasi sono correlate all'esecuzione e alla gestione del server proxy. Esse includono quanto segue:
L'elenco riportato di seguito spiega lo scopo di ciascuna fase illustrata nella Figura 1. Non tutte le fasi verranno, comunque, chiamate per una particolare richiesta.
Esegue l'elaborazione dopo la lettura di una richiesta ma prima di qualsiasi altra operazione.
Se si riceve un'indicazione che la richiesta è stata elaborata (HTTP_OK), il server ignora le altre fasi del processo di richiesta ed esegue solo le operazioni Transmogrifier, Log e PostExit.
Utilizza i token di sicurezza memorizzati per controllare il percorso fisico delle protezioni, degli ACL e di altri controlli di accesso, nonché crea le intestazioni WWW-Authenticate necessarie per l'autenticazione di base. Se si scrive la propria funzione di plugin per sostituire questa fase, è necessario creare autonomamente queste intestazioni.
Per ulteriori informazioni, consultare Autenticazione e autorizzazione.
Decodifica, verifica e memorizza i token di sicurezza.
Per ulteriori informazioni, consultare Autenticazione e autorizzazione.
Esegue l'elaborazione dopo l'autorizzazione e l'ubicazione dell'oggetto, ma prima che la richiesta venga soddisfatta.
Se si riceve un'indicazione che la richiesta è stata elaborata (HTTP_OK), il server ignora le altre fasi del processo di richiesta ed esegue solo le operazioni Transmogrifier, Log e PostExit.
Sui sistemi AIX, è necessario un file di esportazione (ad esempio, libmyapp.exp) che elenchi le funzioni di plugin a cui è necessario collegare un file di importazione API del Caching Proxy, libhttpdapi.exp.
Sui sistemi Linux, HP-UX e Solaris, è necessario effettuare un collegamento tra le librerie libhttpdapi e libc.
Sui sistemi Windows, è necessario un file di definizione modulo (.def) che elenchi le funzioni di plugin a cui è necessario collegare HTTPDAPI.LIB.
Accertarsi di includere HTAPI.h e di utilizzare la macro HTTPD_LINKAGE nelle proprie definizioni di funzione. Questa macro assicura che tutte le funzioni utilizzeranno le stesse convenzioni di chiamata.
Utilizzare i seguenti comandi di compilazione e collegamento come linea guida.
cc_r -c -qdbxextra -qcpluscmt foo.c
cc_r -bM:SRE -bnoentry -o libfoo.so foo.o -bI:libhttpdapi.exp -bE:foo.exp
(Questo comando viene illustrato su due righe solo per facilitarne la lettura.)
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
Per specificare le esportazioni, utilizzare uno dei seguenti metodi:
Seguire la sintassi presentata in Prototipi della funzione del plugin per scrivere le proprie funzioni del programma per le fasi di elaborazione della richiesta definite.
Ciascuna delle funzioni deve completare il parametro del codice di ritorno con un valore che indica l'azione eseguita:
I prototipi della funzione per ogni fase del Caching Proxy mostrano il formato da utilizzare e illustrano il tipo di elaborazione da eseguire. Tenere presente che i nomi funzione non sono predefiniti. È necessario fornire nomi univoci alle funzioni utilizzando le proprie convenzioni di denominazione. Per rendere più semplice l'associazione, questo documento utilizza i nomi che si riferiscono alle fasi di elaborazione del server.
In ciascuna di queste funzioni del plug-in, sono valide alcune funzioni API predefinite. Alcune delle funzioni predefinite non sono valide per tutte le fasi. Le funzioni API riportate di seguito sono valide se chiamate da tutte queste funzioni del plugin:
Nelle descrizioni relative al prototipo della funzione, vi sono ulteriori funzioni API valide o non valide.
Il valore del parametro handle inviato alle funzioni può essere inoltrato come primo argomento per le funzioni predefinite. Le funzioni API predefinite sono descritte in Funzioni e macro predefinite.
void HTTPD_LINKAGE ServerInitFunction ( unsigned char *handle, unsigned long *major_version, unsigned long *minor_version, long *return_code )
Una funzione definita per questa fase viene richiamata una volta che il modulo è stato caricato durante l'inizializzazione del server. È possibile eseguire l'inizializzazione prima di accettare qualsiasi richiesta.
Nonostante vengano richiamate tutte le funzioni di inizializzazione del server, un codice di ritorno di errore da una funzione in questa fase fa sì che il server ignori tutte le altre funzioni configurate nello stesso modulo della funzione che ha restituito il codice di errore. In altre parole, qualsiasi altra funzione contenuta nello stesso oggetto condiviso della funzione che ha restituito l'errore non viene richiamata.
I parametri della versione contengono il numero di versione del server proxy; questi sono forniti da Caching Proxy.
void HTTPD_LINKAGE PreExitFunction ( unsigned char *handle, long *return_code )
Una funzione definita per questa fase viene richiamata per ogni richiesta dopo che la richiesta è stata letta, ma prima di qualsiasi elaborazione. Un plug-in può essere utilizzato in questa fase per accedere alla richiesta del client prima che venga elaborata da Caching Proxy.
I codici di ritorno validi per la funzione preExit sono:
Non devono essere utilizzati altri codici di ritorno.
Se questa funzione restituisce HTTP_OK, il server proxy presume che la richiesta sia stata gestita. Tutte le successive fasi di richiesta vengono ignorate e verranno eseguite solo le fasi del processo di risposta (Transmogrifier, Log e PostExit).
In questa fase, sono valide tutte le funzioni delle API predefinite.
void HTTPD_LINKAGE MidnightFunction ( unsigned char *handle, long *return_code )
Una funzione definita per questa fase viene eseguita ogni giorno a mezzanotte e non contiene alcun contesto della richiesta. Ad esempio, può essere utilizzata per richiamare un processo child per analizzare i log. Tenere presente che una elaborazione prolungata durante questa fase può interferire con la registrazione.
void HTTPD_LINKAGE AuthenticationFunction ( unsigned char *handle, long *return_code )
Una funzione definita per questa fase viene richiamata per ogni richiesta basata sullo schema di autenticazione della richiesta. Questa funzione può essere utilizzata per personalizzare la verifica dei token di sicurezza inviati con una richiesta.
void HTTPD_LINKAGE NameTransFunction ( unsigned char *handle, long *return_code )
Per ciascuna richiesta viene chiamata una funzione definita per questa fase. Se si desidera che la funzione del plugin venga chiamata solo per le richieste che corrispondono alla maschera, è possibile specificare una maschera URL nella direttiva del file di configurazione. La fase di Conversione nome si verifica prima che la richiesta venga elaborata e fornisce un meccanismo per la mappatura degli URL sugli oggetti, quali nomi di file.
void HTTPD_LINKAGE AuthorizationFunction ( unsigned char *handle, long *return_code )
Per ciascuna richiesta viene chiamata una funzione definita per questa fase. Se si desidera che la funzione del plugin venga chiamata solo per le richieste che corrispondono alla maschera, è possibile specificare una maschera URL nella direttiva del file di configurazione. La fase di Autorizzazione si verifica prima che la richiesta venga elaborata e può essere utilizzata per verificare se l'oggetto identificato possa essere restituito al client. Se si effettua l'autenticazione di base, è necessario creare le intestazioni WWW-Authenticate.
void HTTPD_LINKAGE ObjTypeFunction ( unsigned char *handle, long *return_code )
Per ogni richiesta viene chiamata una funzione definita per questa fase. Se si desidera che la funzione plug-in venga chiamata solo per le richieste che corrispondono al modello, è possibile specificare un modello URL nella direttiva del file di configurazione. La fase Tipo di oggetto si verifica prima che la richiesta venga elaborata e può essere utilizzata per controllare l'esistenza dell'oggetto e per immettere l'oggetto.
void HTTPD_LINKAGE PostAuthFunction ( unsigned char *handle, long *return_code )
Una funzione definita per questa fase viene richiamata dopo che la richiesta è stata autorizzata, ma prima di qualsiasi altra elaborazione. Se questa funzione restituisce HTTP_OK, il server proxy presume che la richiesta sia stata gestita. Tutte le successive fasi di richiesta vengono ignorate e verranno eseguite solo le fasi del processo di risposta (Transmogrifier, Log e PostExit).
In questa fase, sono valide tutte le funzioni predefinite del server.
void HTTPD_LINKAGE ServiceFunction ( unsigned char *handle, long *return_code )
Per ciascuna richiesta viene chiamata una funzione definita per questa fase. Se si desidera che la funzione del plugin venga chiamata solo per le richieste che corrispondono alla maschera, è possibile specificare una maschera URL nella direttiva del file di configurazione. La fase relativa al Servizio soddisfa la richiesta, nel caso non fosse stata soddisfatta nelle fasi PreExit o PostAuthorization.
In questa fase, sono valide tutte le funzioni predefinite del server.
Fare riferimento alla direttiva Enable nella WebSphere Application Server Caching Proxy - Guida alla gestione per informazioni sulla configurazione della funzione Servizio da eseguire in base al metodo HTTP piuttosto che in base all'URL.
In questa fase, è necessario implementare le seguenti quattro funzioni. (Non è necessario che i nomi delle funzioni corrispondano a questi nomi.)
void * HTTPD_LINKAGE openFunction ( unsigned char *handle, long *return_code )
La funzione open esegue qualsiasi inizializzazione (ad esempio l'assegnazione del buffer) necessaria per elaborare i dati di questo flusso. Qualsiasi codice di ritorno diverso da HTTP_OK causa l'interruzione dell'operazione di filtraggio (le funzioni write e close non vengono chiamate). La funzione può restituire un puntatore vuoto, in questo modo l'utente può assegnare spazio a una struttura e fare in modo che il puntatore gli venga restituito nel parametro correlator delle funzioni successive.
void HTTPD_LINKAGE writeFunction ( unsigned char *handle, unsigned char *data, /* dati di risposta inviati dal server di origine */ unsigned long *length, /* lunghezza dei dati di risposta */ void *correlator, /* puntatore restituito dalla funzione 'open' */ long *return_code )
La funzione write elabora i dati e può richiamare la funzione HTTPD_write() predefinita del server con i dati nuovi o modificati. Il plugin non tenta di liberare il buffer inviato al server o presuppone che il server liberi il buffer ricevuto.
Se, nell'ambito della funzione write, si decide di non modificare i dati, risulta ancora necessario chiamare la funzione HTTPD_write() nell'ambito della funzione open, write o close per inviare i dati della risposta al client. L'argomento correlator è il puntatore al buffer di dati restituito nella routine open.
void HTTPD_LINKAGE closeFunction ( unsigned char *handle, void *correlator, long *return_code )
La funzione close effettua tutte le operazioni di ripulitura (ad esempio, svuotare e liberare il buffer del correlatore) necessarie per completare l'elaborazione dei dati in questo flusso. L'argomento correlator è il puntatore al buffer di dati restituito nella routine open.
void HTTPD_LINKAGE errorFunction ( unsigned char *handle, void *correlator, long *return_code )
La funzione error abilita le prestazioni delle azioni di ripulitura, ad esempio lo svuotamento o la liberazione dei dati memorizzati nel buffer (o entrambe) prima che venga inviata una pagina di errore. A questo punto, vengono chiamate le funzioni open, write e close per elaborare la pagina di errore. L'argomento correlator è il puntatore al buffer di dati restituito nella routine open.
Note:
void HTTPD_LINKAGE GCAdvisorFunction ( unsigned char *handle, long *return_code )
Per ogni file presente nella cache durante la raccolta dei dati inutili, viene chiamata una funzione definita per questa fase. Tale funzione consente di influenzare i file che vengono conservati e quelli che vengono eliminati. Per ulteriori informazioni, consultare le variabili GC_*.
void HTTPD_LINKAGE ProxyAdvisorFunction ( unsigned char *handle, long *return_code )
Durante il servizio di ogni richiesta proxy, viene chiamata una funzione definita per questa fase. Tale funzione può essere utilizzata, ad esempio, per impostare la variabile USE_PROXY.
void HTTPD_LINKAGE LogFunction ( unsigned char *handle, long *return_code )
Dopo che ogni richiesta è stata elaborata e che la comunicazione con il client è stata interrotta viene chiamata una funzione definita per questa fase. Se si desidera che la funzione plugin venga chiamata solo per le richieste che corrispondono alla maschera, è possibile specificare una maschera URL nella direttiva del file di configurazione. Questa funzione viene chiamata indipendentemente dal fatto che la richiesta sia stata elaborata correttamente. Se non si desidera che il plugin di log sostituisca il meccanismo di log, impostare il codice di ritorno su HTTP_NOACTION invece che su HTTP_OK.
void HTTPD_LINKAGE ErrorFunction ( unsigned char *handle, long *return_code )
Per ogni richiesta che ha esito negativo viene chiamata una funzione definita per questa fase. Se si desidera che la funzione del plugin venga chiamata solo per le richieste non riuscite che corrispondono alla maschera, è possibile specificare una maschera URL nella direttiva del file di configurazione. La fase Error consente di personalizzare la risposta all'errore.
void HTTPD_LINKAGE PostExitFunction ( unsigned char *handle, long *return_code )
Per ogni richiesta, completata o non completata correttamente, viene chiamata una funzione definita per questa fase. Questa fase consente di deallocare tutte le risorse assegnate dal plugin per elaborare la richiesta.
void HTTPD_LINKAGE ServerTermFunction ( unsigned char *handle, long *return_code )
Quando si verifica una chiusura corretta del server, viene chiamata una funzione definita per questa fase. Essa consente di deallocare le risorse assegnate durante la fase di Inizializzazione del server. Non chiamare le funzioni HTTP_* in questa fase (i risultati sono imprevedibili). Se esiste più di una direttiva API del Caching Proxy nel file di configurazione per la fase Chiusura del server, verranno chiamate tutte.
Questi codici di ritorno seguono la specifica HTTP 1.1, RFC 2616, pubblicata dal World Wide Web Consortium (www.w3.org/pub/WWW/Protocols/). Le funzioni del plugin devono restituire uno di questi valori.
Valore | Codice di ritorno |
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 |
È possibile richiamare le funzioni e le macro predefinite del server dalle funzioni del plugin. A tal fine, utilizzare i relativi nomi predefiniti e rispettare il formato descritto di seguito. Nelle descrizioni relative al parametro, la lettera i indica un parametro di input, la lettera o indica un parametro di output e le lettere i/o indicano che un parametro viene utilizzato sia per l'input sia per l'output.
Ciascuna di queste funzioni restituisce uno dei codici di ritorno HTTPD, a seconda della corretta esecuzione della richiesta. Questi codici vengono descritti in Codici di ritorno delle funzioni e delle macro predefinite.
Quando vengono chiamate queste funzioni, utilizzare come primo parametro l'handle fornito al plug-in. Altrimenti, la funzione restituisce un codice di errore HTTPD_PARAMETER_ERROR. NULL non è accettato come handle valido.
void HTTPD_LINKAGE HTTPD_authenticate ( unsigned char *handle, /* i; handle */ long *return_code /* o; codice di ritorno */ )
void HTTPD_LINKAGE HTTPD_cacheable_url ( unsigned char *handle, /* i; handle */ unsigned char *url, /* i; URL da controllare */ unsigned char *req_method, /* i; metodo di richiesta per l'URL */ long *retval /* o; codice di ritorno */ )
Il valore di ritorno HTTPD_SUCCESS indica che il contenuto dell'URL può essere memorizzato nella cache; mentre HTTPD_FAILURE indica il contrario. Anche HTTPD_INTERNAL_ERROR è un possibile codice di ritorno per questa funzione.
void HTTPD_LINKAGE HTTPD_close ( unsigned char *handle, /* i; handle */ long *return_code /* o; return code */ )
void HTTPD_LINKAGE HTTPD_exec ( unsigned char *handle, /* i; handle */ unsigned char *name, /* i; nome dello script da eseguire */ unsigned long *name_length, /* i; lunghezza del nome */ long *return_code /* o; codice di ritorno */ )
void HTTPD_LINKAGE HTTPD_extract ( unsigned char *handle, /* i; handle */ unsigned char *name, /* i; nome della variabile da estrarre */ unsigned long *name_length, /* i; lunghezza del nome */ unsigned char *value, /* o; buffer in cui inserire il valore */ unsigned long *value_length, /* i/o; dimensione del buffer */ long *return_code /* o; codice di ritorno */ )
Se questa funzione restituisce il codice HTTPD_BUFFER_TOO_SMALL, significa che la dimensione del buffer richiesta non è sufficientemente grande per il valore estratto. In questo caso, la funzione non utilizza il buffer, ma aggiorna il parametro value_length con la dimensione del buffer necessaria per estrarre questo valore con esito positivo. Tentare nuovamente l'estrazione con un buffer che sia abbastanza grande da contenere il parametro value_length restituito.
void HTTPD_LINKAGE HTTPD_file ( unsigned char *handle, /* i; handle */ unsigned char *name, /* i; nome del file da inviare */ unsigned long *name_length, /* i; lunghezza del nome */ long *return_code /* o; codice di ritorno */ )
const unsigned char * /* o; valore della variabile */ HTTPD_LINKAGE httpd_getvar( unsigned char *handle, /* i; handle */ unsigned char *name, /* i; nome variabile */ unsigned long *n /* i; numero indice per la matrice contenente l'intestazione */ )
L'indice della matrice che contiene l'intestazione comincia con 0. Per ottenere la prima voce nella matrice, utilizzare il valore 0 al posto di n; per ottenere la quinta voce, utilizzare il valore 4 al posto di n.
void HTTPD_LINKAGE HTTPD_log_access ( unsigned char *handle, /* i; handle */ unsigned char *value, /* i; dati da scrivere */ unsigned long *value_length, /* i; lunghezza dei dati */ long *return_code /* o; codice di ritorno */ )
Si noti che i simboli escape non sono richiesti durante la scrittura del simbolo di percentuale (%) nei log di accesso del server.
void HTTPD_LINKAGE HTTPD_log_error ( unsigned char *handle, /* i; handle */ unsigned char *value, /* i; dati da scrivere */ unsigned long *value_length, /* i; lunghezza dei dati */ long *return_code /* o; codice di ritorno */ )
Si noti che i simboli escape non sono richiesti durante la scrittura del simbolo di percentuale (%) nei log degli errori del server.
void HTTPD_LINKAGE HTTPD_log_event ( unsigned char *handle, /* i; handle */ unsigned char *value, /* i; dati da scrivere */ unsigned long *value_length, /* i; lunghezza dei dati */ long *return_code /* o; codice di ritorno */ )
Si noti che i simboli escape non sono richiesti durante la scrittura del simbolo di percentuale (%) nei registri eventi del server.
void HTTPD_LINKAGE HTTPD_log_trace ( unsigned char *handle, /* i; handle */ unsigned char *value, /* i; dati da scrivere */ unsigned long *value_length, /* i; lunghezza dei dati */ long *return_code /* o; codice di ritorno */ )
Si noti che i simboli escape non sono richiesti durante la scrittura del simbolo di percentuale (%) nei registri di tracce del server.
void HTTPD_LINKAGE HTTPD_open ( unsigned char *handle, /* i; handle */ long *return_code /* o; return code */ )
void HTTPD_LINKAGE HTTPD_proxy ( unsigned char *handle, /* i; handle */ unsigned char *url_name, /* i; URL per la richiesta proxy */ unsigned long *name_length, /* i; lunghezza dell'URL */ void *request_body, /* i; corpo della richiesta */ unsigned long *body_length, /* i; lunghezza del corpo */ long *return_code /* o; codice di ritorno */ )
void HTTPD_LINKAGE HTTPD_read ( unsigned char *handle, /* i; handle */ unsigned char *value, /* i; buffer dei dati */ unsigned long *value_length, /* i/o; dimensione del buffer (lunghezza dati) */ long *return_code /* o; codice di ritorno */ )
void HTTPD_LINKAGE HTTPD_restart ( long *return_code /* o; codice di ritorno */ )
Si noti che con questa funzione è anche possibile creare delle variabili. Le variabili create sono soggette alle convenzioni dei prefissi HTTP_ e PROXY_, descritti in Variabili. Se si crea una variabile che comincia con HTTP_, essa viene inviata come intestazione nella risposta al client, senza il prefisso HTTP_. Ad esempio, per impostare un'intestazione di ubicazione, utilizzare HTTPD_set() con il nome variabile HTTP_LOCATION. Le variabili create con un prefisso PROXY_ vengono inviate come intestazioni nella richiesta al server dei contenuti. Le variabili create con un prefisso CGI_ vengono inviate ai programmi CGI.
Questa funzione è valida in tutte le fasi; tuttavia, non tutte le variabili sono valide in tutte le fasi.
void HTTPD_LINKAGE HTTPD_set ( unsigned char *handle, /* i; handle */ unsigned char *name, /* i; nome del valore da impostare */ unsigned long *name_length, /* i; lunghezza del nome */ unsigned char *value, /* i; buffer con valore */ unsigned long *value_length, /* i; lunghezza del valore */ long *return_code /* o; codice di ritorno */ )
long /* o; codice di ritorno */ HTTPD_LINKAGE httpd_setvar ( unsigned char *handle, /* i; handle */ unsigned char *name, /* i; nome variabile */ unsigned char *value, /* i; nuovo valore */ unsigned long *addHdr /* i; aggiungere intestaz. o sostituirla */ )
Il parametro addHdr ha quattro valori possibili:
Questi valori vengono definiti in HTAPI.h.
void HTTPD_LINKAGE httpd_variant_insert ( unsigned char *handle, /* i; handle */ unsigned char *URI, /* i; URI di questo oggetto */ unsigned char *dimension, /* i; dimensione della variante */ unsigned char *variant, /* i; valore della variante */ unsigned char *filename, /* i; file contenente l'oggetto */ long *return_code /* o; codice di ritorno */ )
Note:
Mozilla 4.0 (compatible; BatBrowser 94.1.2; Bat OS)
void HTTPD_LINKAGE httpd_variant_lookup ( unsigned char *handle, /* i; handle */ unsigned char *URI, /* URI di questo oggetto */ unsigned char *dimension, /* i; dimensione della variante */ unsigned char *variant, /* i; valore della variante */ long *return_code); /* o; codice di ritorno */
Se la prima volta che si chiama questa funzione non viene impostato il tipo di contenuto, il server presume che si sta inviando un flusso di dati CGI.
void HTTPD_LINKAGE HTTPD_write ( unsigned char *handle, /* i; handle */ unsigned char *value, /* i; dati da inviare */ unsigned char *value_length, /* i; lunghezza dei dati */ long *return_code); /* o; codice di ritorno */
Il server imposterà il parametro del codice di ritorno su uno di questi valori, a seconda della riuscita della richiesta:
Valore | Codice stato | Spiegazione |
---|---|---|
-1 | HTTPD_UNSUPPORTED | La funzione non è supportata. |
0 | HTTPD_SUCCESS | La funzione ha avuto esito positivo e i campi di output sono validi. |
1 | HTTPD_FAILURE | La funzione ha avuto esito negativo. |
2 | HTTPD_INTERNAL_ERROR | È stato rilevato un errore interno, quindi non è possibile proseguire l'elaborazione di questa richiesta. |
3 | HTTPD_PARAMETER_ERROR | Sono stati inoltrati uno o più parametri non validi. |
4 | HTTPD_STATE_CHECK | La funzione non è valida in questa fase del processo. |
5 | HTTPD_READ_ONLY | (Restituito solo da HTTPD_set e httpd_setvar.) La variabile è in sola lettura e non può essere impostata dal plugin. |
6 | HTTPD_BUFFER_TOO_SMALL | (Restituito da HTTPD_set, httpd_setvar e HTTPD_read.) Il buffer fornito è troppo piccolo. |
7 | HTTPD_AUTHENTICATE_FAILED | (Restituito solo da HTTPD_authenticate.) L'autenticazione ha avuto esito negativo. Per ulteriori informazioni, esaminare le variabili HTTP_RESPONSE e HTTP_REASON. |
8 | HTTPD_EOF | (Restituito solo da HTTPD_read.) Indica la fine del corpo della richiesta. |
9 | HTTPD_ABORT_REQUEST | La richiesta è stata interrotta perché il client ha fornito una tag entità che non corrisponde alla condizione specificata dalla richiesta. |
10 | HTTPD_REQUEST_SERVICED | (Restituito da HTTPD_proxy.) La funzione chiamata ha completato la risposta per questa richiesta. |
11 | HTTPD_RESPONSE_ALREADY_COMPLETED | La funzione ha avuto esito negativo perché la risposta per quella richiesta è già stata completata. |
12 | HTTPD_WRITE_ONLY | La variabile è in sola scrittura e non può essere letta dal plug-in. |
Ogni fase di questo processo di richiesta ha una direttiva di configurazione che viene utilizzata per indicare quale delle funzioni dei plugin si desidera chiamare ed eseguire durante quella fase specifica. Tali direttive possono essere aggiunte al file di configurazione del server (ibmproxy.conf) modificandolo e aggiornandolo manualmente o utilizzando il modulo Elaborazione delle richieste API contenuto nei moduli Configurazione e gestione del Caching Proxy.
Ciò significa che il server elabora le direttive Service, NameTrans, Exec, Fail, Map, Pass, Proxy, ProxyWAS e Redirect nella relativa sequenza all'interno del file di configurazione. Se il server mappa con esito positivo un'URL su un file, esso non legge né elabora nessun altra direttiva. (La direttiva Map è un'eccezione. Fare riferimento al manuale WebSphere Application Server Caching Proxy - Guida alla gestione per informazioni complete sulle regole di associazione di server proxy.
Queste direttive del file di configurazione devono essere visualizzate nel file ibmproxy.conf su un'unica riga, senza spazi se non quelli ivi specificati esplicitamente. Sebbene per agevolare la leggibilità, in alcuni esempi di sintassi potrebbero apparire delle interruzioni di riga, è necessario che in quei punti della direttiva reale non vi siano spazi.
Le variabili contenute in queste direttive hanno i seguenti significati:
Se si desidera accedere alle informazioni presenti sul percorso, la direttiva Servizio richiede un asterisco (*) dopo il nome della funzione.
Per ulteriori informazioni su queste direttive, inclusa la sintassi, consultare la WebSphere Application Server Caching Proxy - Guida alla gestione.