Procedura generale per la scrittura dei programmi API

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.

Fasi del processo server

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.

Figura 1. Grafico delle operazioni nel processo del server proxy

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.

Inizializzazione del server
Esegue l'inizializzazione all'avvio del server proxy e prima che qualsiasi richiesta client venga accettata.
Mezzanotte
Esegue un plug-in a mezzanotte, senza nessun contesto di richiesta. Questa fase viene illustrata separatamente nel diagramma poiché non fa parte del processo di richiesta; in altri termini, la sua esecuzione è indipendente da qualsiasi richiesta.
Advisor GC
Influenza le decisioni relative alla raccolta di dati inutili per i file presenti nella cache. Questa fase viene illustrata separatamente nel diagramma poiché non fa parte del processo di richiesta; in altri termini, la sua esecuzione è indipendente da qualsiasi richiesta. La raccolta di dati inutili viene effettuata quando la dimensione della cache raggiunge il valore massimo. (Le informazioni relative alla configurazione della raccolta di dati inutili della cache sono incluse nella WebSphere Application Server Caching Proxy - Guida alla gestione.)
PreExit

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.

Conversione nome
Converte il percorso virtuale (da una URL) in percorso fisico.
Autorizzazione

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.

Autenticazione

Decodifica, verifica e memorizza i token di sicurezza.

Per ulteriori informazioni, consultare Autenticazione e autorizzazione.

Tipo di oggetto
Individua l'oggetto del file system indicato dal percorso.
Post 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.

Servizio
Soddisfa la richiesta (inviando il file, eseguendo il CGI, ecc.)
Proxy Advisor
Influenza le decisioni relative al proxy e alla memorizzazione nella cache.
Transmogrifier
Fornisce l'accesso in scrittura alla parte di dati della risposta inviata al client.
Log
Abilita la registrazione della transazione personalizzata.
Errore
Abilita le risposte personalizzate alle condizioni di errore.
PostExit
Elimina le risorse assegnate per l'elaborazione della richiesta.
Chiusura del server
Esegue l'operazione di ripulitura quando si verifica una chiusura corretta.

Linee guida

Funzioni del plugin

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:

Prototipi della funzione del plugin

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.

Inizializzazione del server

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.

PreExit

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.

Mezzanotte

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.

Autenticazione

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.

Conversione nome

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.

Autorizzazione

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.

Tipo di oggetto

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.

PostAuthorization

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.

Servizio

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.

Transmogrifier
Le funzioni chiamate in questa fase del processo possono essere utilizzate per filtrare i dati di risposta come un flusso. Quattro delle funzioni del plugin per questa fase vengono chiamate in sequenza e ciascuna di esse agisce come un segmento del pipe tramite cui fluiscono i dati. Vale a dire che per ogni risposta vengono chiamate le funzioni open, write, close e error nello stesso ordine in cui sono state citate. Ciascuna di esse, a sua volta, elabora lo stesso flusso di dati.

In questa fase, è necessario implementare le seguenti quattro funzioni. (Non è necessario che i nomi delle funzioni corrispondano a questi nomi.)

Note:

Advisor GC

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_*.

Proxy Advisor

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.

Log

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.

Errore

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.

PostExit

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.

Chiusura del server

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.

Nota:
a causa di una limitazione nel codice Solaris, la fase del plugin Chiusura del server non viene eseguita se si utilizza il comando ibmproxy -stop per chiudere il Caching Proxy sulle piattaforme Solaris. Fare riferimento al manuale WebSphere Application Server Caching Proxy - Guida alla gestione per informazioni sull'avvio e sull'arresto di Caching Proxy.

Valori e codici di ritorno HTTP

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.

Tabella 2. Codici di ritorno HTTP per le funzioni API del Caching Proxy
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

Funzioni e macro predefinite

È 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.

HTTPD_authenticate()
Autentica un ID utente o una password, o entrambi. È valido unicamente nelle fasi PreExit, Autenticazione, Autorizzazione e Post autorizzazione.

void
HTTPD_LINKAGE  HTTPD_authenticate (
         unsigned char *handle,       /* i; handle */
         long *return_code         /* o; codice di ritorno */
         )
HTTPD_cacheable_url()
Viene restituito se il contenuto dell'URL specificato può essere memorizzato nella cache in base agli standard del Caching Proxy.

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.

HTTPD_close()
(Valido solo nella fase Transmogrifier.) Trasferisce il controllo alla routine close successiva nello stack del flusso. Chiamare questa funzione dalle funzioni open, write o close di Transmogrifier dopo l'esecuzione di qualsiasi elaborazione desiderata. Questa funzione indica al server proxy che la risposta è stata elaborata e che la fase Transmogrifier è completa.

void  HTTPD_LINKAGE
HTTPD_close (
         unsigned char *handle,       /* i; handle */
         long *return_code            /* o; return code */ 
         )
HTTPD_exec()
Esegue uno script per soddisfare questa richiesta. Valido nelle fasi PreExit, Servizio, Post autorizzazione e Errore.

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 */
         )
HTTPD_extract()
Estrae il valore di una variabile associata a questa richiesta. Le variabili valide per il parametro name sono uguali a quelle utilizzate nel CGI. Per ulteriori informazioni, consultare Variabili. Si noti che questa funzione è valida in tutte le fasi; tuttavia, non tutte le variabili sono valide in tutte le fasi.

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.

Nota:
se la variabile estratta è per un'intestazione HTTP, la funzione HTTPD_extract() estrarrà solo la prima occorrenza corrispondente, anche se la richiesta contiene più intestazioni aventi lo stesso nome. La funzione httpd_getvar() può essere utilizzata al posto della funzione HTTPD_extract(), inoltre offre altri vantaggi. Fare riferimento alla sezione su httpd_getvar() function per ulteriori informazioni.
HTTPD_file()
Invia un file per soddisfare questa richiesta. Valido solo nelle fasi PreExit, Servizio, Errore, Post autorizzazione e Transmogrifier.

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 */
         )
httpd_getvar()
Ha la stessa funzione di HTTPD_extract(), fatta eccezione per il fatto che è più semplice da utilizzare in quanto l'utente non è tenuto a specificare le lunghezze degli argomenti.

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.

Nota:
non eliminare o modificare il contenuto del valore restituito. La stringa restituita termina con null.
HTTPD_log_access()
Scrive una stringa sul log di accesso del server.

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.

HTTPD_log_error()
Scrive una stringa sul log degli errori 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.

HTTPD_log_event()
Scrive una stringa nel registro eventi 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.

HTTPD_log_trace()
Scrive una stringa nel registro tracce 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.

HTTPD_open()
(Valido solo nella fase Transmogrifier.) Trasferisce il controllo alla successiva routine nello stack del flusso. Chiamare questa funzione dalle funzioni open, write o close di Transmogrifier dopo aver impostato tutte le intestazioni desiderate e se si è pronti ad avviare la routine di scrittura.

void  HTTPD_LINKAGE  HTTPD_open (
         unsigned char *handle,       /* i; handle */
         long *return_code           /* o; return code */ 
         )	
HTTPD_proxy()
Effettua una richiesta proxy. Valido nelle fasi PreExit, Servizio e Post autorizzazione.
Nota:
questa è una funzione di completamento; infatti, dopo questa funzione, la richiesta è completa.

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 */
         ) 
HTTPD_read()
Legge il corpo della richiesta del client. Utilizzare HTTPD_extract() per le intestazioni. Valido solo per le fasi PreExit, Autorizzazione, Post autorizzazione e Servizio ed è utile solo se è stata effettuata una richiesta PUT o POST. Chiamare questa funzione in un loop fino a quando non viene restituito HTTPD_EOF. Se non è presente nessun corpo per questa richiesta, la funzione ha esito negativo.

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 */
         )
HTTPD_restart()
Riavvia il server dopo che tutte le richieste attive sono state elaborate. Valido in tutte le fasi, tranne per Inizializzazione del server, Chiusura del server e Transmogrifier.

void  HTTPD_LINKAGE  HTTPD_restart ( 
         long *return_code         /* o; codice di ritorno */
         )
HTTPD_set()
Imposta il valore di una variabile associata a questa richiesta. Le variabili valide per il parametro name sono uguali a quelle utilizzate nel CGI. Per ulteriori informazioni, consultare Variabili.

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 */
         ) 
Nota:
è possibile utilizzare la funzione httpd_setvar() per impostare un valore della variabile senza dover specificare un buffer e la lunghezza. Fare riferimento alla sezione su httpd_setvar() function per ulteriori informazioni.
httpd_setvar()
Ha la stessa funzione di HTTPD_set(), tranne per il fatto che è più semplice da utilizzare in quanto l'utente non deve specificare le lunghezze degli argomenti.

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.

httpd_variant_insert()
Inserisce una variante nella cache.

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:

  1. L'argomento dimensione si riferisce all'intestazione con cui questo oggetto si differenzia dall'URI. Ad esempio, nel precedente esempio, un valore dimensione possibile è User-Agent.
  2. L'argomento variante si riferisce al valore dell'intestazione per l'intestazione fornita nell'argomento dimensione. Questo varia dall'URI. Ad esempio, nel precedente esempio, un valore possibile per l'argomento variante è il seguente:
    Mozilla 4.0 (compatible; BatBrowser 94.1.2; Bat OS)
  3. L'argomento nomefile deve ountare a una copia del nome del file terminata da null in cui l'utente ha salvato il contenuto modificato. L'utente è responsabile della rimozione del file; questa operazione è sicura dopo essere stata restituita da questa funzione. Il file contiene solo il corpo senza intestazioni.
  4. Durante la memorizzazione nella cache delle varianti, il server aggiorna l'intestazione content-lenght e aggiunge un'intestazione Warning: 214. Le tag di entità Strong vengono rimosse.
httpd_variant_lookup()
Determina se una variante specifica è già esistente nella cache.

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 */      
HTTPD_write()
Scrive il corpo della risposta. Valido nelle fasi PreExit, Servizio, Errore e Transmogrifier.

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 */
Nota:
Per impostare le intestazioni di risposta, fare riferimento alla sezione su HTTPD_set() function.
Nota:
Al termina di funzione HTTPD_*, si consiglia di liberare la memoria utilizzata.

Codici di ritorno delle funzioni e delle macro predefinite

Il server imposterà il parametro del codice di ritorno su uno di questi valori, a seconda della riuscita della richiesta:

Tabella 3. Codici di ritorno
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.

Direttive di configurazione del Caching Proxy per le fasi dell'API

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.

Note sull'utilizzo delle API

Sintassi e direttive API

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.

Tabella 4. Direttive dell'API del plugin del Caching Proxy
ServerInit /path/file:function_name init_string
PreExit /path/file:function_name
Autenticazione tipo /path/file:function_name
NameTrans /URL /path/file:function_name
Autorizzazione /URL /path/file:function_name
Tipo di oggetto /URL /path/file:function_name
PostAuth /path/file:function_name
Servizio /URL /path/file:function_name
Mezzanotte /path/file:function_name
Transmogrifier /path/file:open_function_name: write_function_name: close_function_name:error_function
Log /URL /path/file:function_name
Errore /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

Variabili della direttiva API

Le variabili contenute in queste direttive hanno i seguenti significati:

tipo
Utilizzata solo con la direttiva di autenticazione per specificare se la funzione del plugin deve essere chiamata o meno. I valori validi sono i seguenti:
URL
Specifica le richieste per cui viene chiamata la funzione del plugin. Le richieste con gli URL che corrispondono a questa maschera richiederanno l'utilizzo della funzione del plugin. Le specifiche URL in queste direttive sono virtuali (non includono il protocollo) ma sono precedute da una barra (/). Ad esempio, /www.ics.raleigh.ibm.com è corretto, mentre http://www.ics.raleigh.ibm.com non lo è. È possibile specificare questo valore come un URL specifico o come una maschera.
path/file
Il nome file completo del programma compilato.
function_name
Il nome assegnato alla funzione del plugin all'interno del programma.

Se si desidera accedere alle informazioni presenti sul percorso, la direttiva Servizio richiede un asterisco (*) dopo il nome della funzione.

init_string
Questa parte facoltativa della direttiva ServerInit può contenere qualsiasi testo che si desidera inviare alla funzione di plugin. Utilizzare httpd_getvar() per estrarre il testo dalla variabile INIT_STRING.

Per ulteriori informazioni su queste direttive, inclusa la sintassi, consultare la WebSphere Application Server Caching Proxy - Guida alla gestione.