Bevor Sie Ihre Plug-in-Programme für Caching Proxy schreiben, müssen Sie wissen, wie der Proxy-Server arbeitet. Das Verhalten des Proxy-Servers kann in verschiedene Verarbeitungsschritte unterteilt werden. Für jeden dieser Schritte können Sie mit der API eigene angepasste Funktionen bereitstellen. Möchten Sie beispielsweise, dass eine bestimmte Aktion ausgeführt wird, nachdem eine Clientanforderung gelesen wurde, aber bevor eine weitere Verarbeitung stattfindet? Vielleicht möchten Sie auch, dass während der Authentifizierung und später, nachdem die angeforderte Datei gesendet wurde, spezielle Routinen ausgeführt werden.
Mit der API wird eine Bibliothek mit vordefinierten Funktionen bereitgestellt. Ihre Plug-in-Programme können die vordefinierten API-Funktionen aufrufen, um mit dem Proxy-Server-Prozess zu interagieren (z. B. Anforderungen bearbeiten, Anforderungsheader lesen oder schreiben oder in die Protokolle des Proxy-Servers schreiben). Diese Funktionen sollten nicht mit den Plug-in-Funktionen verwechselt werden, die Sie schreiben und die vom Proxy-Server aufgerufen werden. Eine Beschreibung der vordefinierten Funktionen finden Sie im Abschnitt Vordefinierte Funktionen und Makros.
Die Anweisungen zum Aufruf Ihrer Plug-in-Funktionen in den entsprechenden Schritten erteilen Sie dem Proxy-Server, indem Sie die zugehörigen Anweisungen der Caching-Proxy-API in Ihrer Serverkonfigurationsdatei verwenden. Diese Anweisungen werden im Abschnitt Caching-Proxy-Konfigurationsanweisungen für die API-Schritte beschrieben.
In diesem Dokument finden Sie folgende Informationen:
Mit Hilfe dieser Komponenten und Prozeduren können Sie eigene Plug-in-Programme für Caching Proxy schreiben.
Die Basisoperation des Proxy-Servers kann je nach Art der Verarbeitung, die der Server während der betreffenden Phase ausführt, in mehrere Schritte unterteilt werden. Jeder Schritt enthält einen Verbindungspunkt, an dem ein angegebener Teil Ihres Programms ausgeführt werden kann. Durch Hinzufügen Ihrer API-Anweisungen zur Konfigurationsdatei für Caching Proxy (ibmproxy.conf) legen Sie fest, welche Plug-in-Funktionen während eines bestimmten Schrittes aufgerufen werden sollen. Sie haben auch die Möglichkeit, während eines bestimmten Verarbeitungsschrittes mehrere Plug-in-Funktionen aufzurufen, indem Sie für diesen Schritt mehrere Anweisungen aufnehmen.
Einige Schritte sind Teil des Serveranforderungsprozesses, d. h., der Proxy-Server führt diese Schritte immer aus, wenn er eine Anforderung verarbeitet. Andere Schritte werden unabhängig von der Anforderungsverarbeitung ausgeführt, d. h., der Server führt diese Schritte unabhängig davon aus, ob eine Anforderung verarbeitet wird.
Ihr kompiliertes Programm ist in einem gemeinsam genutzten Objekt enthalten, das abhängig vom verwendeten Betriebssystem ist, z. B. in einer DLL- oder einer .so-Datei. Während der Server die Schritte der Anforderungsverarbeitung durchläuft, ruft er die den einzelnen Schritten zugeordneten Plug-in-Funktionen auf, bis eine der Funktionen angibt, dass die Anforderung ausgeführt wurde. Wenn Sie für einen bestimmten Schritt mehrere Plug-in-Funktionen festlegen, werden die Funktionen in der Reihenfolge aufgerufen, in der ihre Anweisungen in der Konfigurationsdatei angegeben sind.
Wird die Anforderung nicht von einer Plug-in-Funktion ausgeführt (weil entweder keine API-Anweisung für Caching Proxy für den betreffenden Schritt aufgenommen wurde oder weil Ihre Plug-in-Funktion für den entsprechenden Schritt HTTP_NOACTION zurückgegeben hat), dann führt der Server für diesen Schritt seine Standardaktion aus.
Anmerkung: Dies gilt für alle Schritte mit Ausnahme des Schrittes "Service". Für diesen Schritt ist keine Standardaktion definiert.
Abb. 1 zeigt die Schritte des Proxy-Server-Prozesses und definiert die Verarbeitungsreihenfolge der Schritte, die zur Anforderungsverarbeitung gehören.
Vier Schritte im Diagramm werden unabhängig von der Verarbeitung einer Clientanforderung ausgeführt. Diese Schritte beziehen sich auf die Ausführung und Wartung des Proxy-Servers. Dies sind folgende Schritte:
Die folgende Liste erläutert die Aufgabe der in Abb. 1 dargestellten Schritte. Beachten Sie, dass für eine bestimmte Anforderung nicht alle Schritte zwingend aufgerufen werden müssen.
Führt die Verarbeitung aus, nachdem eine Anforderung gelesen, aber bevor irgendeine andere Aktion ausgeführt wurde.
Wenn dieser Schritt eine Meldung darüber zurückgibt, dass die Anforderung verarbeitet wurde (HTTP_OK), überspringt der Server die anderen Schritte im Anforderungsprozess und führt nur die Schritte "Transmogrifier", "Log" und "PostExit" aus.
Verwendet gespeicherte Sicherheitstoken, um den physischen Pfad auf Zugriffsschutz, ACLs und andere Zugriffskontrollen zu überprüfen, und generiert die WWW-Authenticate-Header, die für die Basisauthentifizierung erforderlich sind. Wenn Sie eine eigene Plug-in-Funktion schreiben, die diesen Schritt ersetzen soll, müssen Sie diese Header selbst generieren.
Weitere Informationen hierzu finden Sie im Abschnitt Authentifizierung und Berechtigung.
Entschlüsselt, überprüft und speichert Sicherheitstoken.
Weitere Informationen hierzu finden Sie im Abschnitt Authentifizierung und Berechtigung.
Führt die Verarbeitung nach der Autorisierung und Objektlokalisierung aus, aber bevor die Anforderung erfüllt wird.
Wenn dieser Schritt eine Meldung darüber zurückgibt, dass die Anforderung verarbeitet wurde (HTTP_OK), überspringt der Server die anderen Schritte im Anforderungsprozess und führt nur die Schritte "Transmogrifier", "Log" und "PostExit" aus.
Auf AIX-Systemen wird eine Exportdatei (z. B. libmyapp.exp) benötigt, die Ihre Plug-in-Funktionen auflistet, und Sie müssen eine Verknüpfung mit der Caching-Proxy-API-Importdatei, "libhttpdapi.exp", erstellen.
Auf Linux-, HP-UX- und Solaris-Systemen müssen Sie eine Verknüpfung mit den Bibliotheken "libhttpdapi" und "libc" erstellen.
Auf Windows-Systemen wird eine Moduldefinitionsdatei (.def) benötigt, die Ihre Plug-in-Funktionen auflistet, und Sie müssen eine Verknüpfung mit HTTPDAPI.LIB erstellen.
Achten Sie darauf, dass Sie in Ihren Funktionsdefinitionen HTAPI.h aufnehmen und das Makro HTTPD_LINKAGE verwenden. Dieses Makro stellt sicher, dass alle Funktionen dieselben Anrufvereinbarungen verwenden.
Verwenden Sie die folgenden Kompilier- und Verknüpfungsbefehle als Richtlinie.
cc_r -c -qdbxextra -qcpluscmt foo.c
cc_r -bM:SRE -bnoentry -o libfoo.so foo.o -bI:libhttpdapi.exp
-bE:foo.exp
(Dieser Befehl wird nur zur besseren Lesbarkeit in zwei Zeilen dargestellt.)
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
Verwenden Sie eine der folgenden Methoden, um Exporte anzugeben:
Verwenden Sie die im Abschnitt Plug-in-Funktionsprototypen dargestellte Syntax, um eigene Programmfunktionen für die definierten Schritte der Anforderungsverarbeitung zu schreiben.
Jede Ihrer Funktionen muss für den Rückkehrcodeparameter einen Wert festlegen, der anzeigt, welche Aktion ausgeführt wurde:
Die Funktionsprototypen für jeden Caching-Proxy-Schritt zeigen das zu verwendende Format an und geben an, welche Art der Verarbeitung sie ausführen können. Beachten Sie dabei, dass die Funktionsnamen nicht vordefiniert sind. Sie müssen Ihren Funktionen eindeutige Namen zuordnen und Sie können eigene Namenskonventionen festlegen. Damit die Zuordnung besser erkennbar ist, werden in diesem Dokument Namen verwendet, die sich auf die Verarbeitungsschritte des Servers beziehen.
In jeder dieser Plug-in-Funktionen sind bestimmte vordefinierte API-Funktionen gültig. Einige vordefinierte Funktionen gelten nicht für alle Schritte. Die folgenden vordefinierten API-Funktionen sind beim Aufruf aus jeder dieser Plug-in-Funktionen gültig:
Weitere gültige oder ungültige API-Funktionen sind in den Beschreibungen der Funktionsprototypen angegeben.
Der Wert des Parameters handle (interne Kennung), der an Ihre Funktionen gesendet wird, kann als erstes Argument an die vordefinierten Funktionen übergeben werden. Eine Beschreibung der vordefinierten API-Funktionen finden Sie im Abschnitt Vordefinierte Funktionen und Makros.
void HTTPD_LINKAGE ServerInitFunction (
unsigned char *handle,
unsigned long *major_version,
unsigned long *minor_version,
long *return_code
)
Eine für diesen Schritt definierte Funktion wird ein Mal aufgerufen, wenn während der Serverinitialisierung Ihr Modul geladen wird. Sie bietet die Möglichkeit, eine Initialisierung auszuführen, bevor Anforderungen akzeptiert werden.
Obwohl alle Serverinitialisierungsfunktionen aufgerufen werden, bewirkt ein Fehlercode von einer Funktion in diesem Schritt, dass der Server alle anderen Funktionen ignoriert, die in demselben Modul konfiguriert sind wie die Funktion, die den Fehlercode zurückgegeben hat. (Dies bedeutet, dass andere Funktionen, die in demselben gemeinsam genutzten Objekt enthalten sind wie die Funktion, die den Fehlercode zurückgegeben hat, nicht aufgerufen werden.)
Die Versionsparameter enthalten die Versionsnummer des Proxy-Servers. Sie werden von Caching Proxy bereitgestellt.
void HTTPD_LINKAGE PreExitFunction (
unsigned char *handle,
long *return_code
)
Eine für diesen Schritt definierte Funktion wird für jede Anforderung aufgerufen, nachdem die Anforderung gelesen wurde, aber bevor eine Verarbeitung stattgefunden hat. Ein Plug-in in diesem Schritt kann verwendet werden, um auf die Clientanforderung zuzugreifen, bevor sie von Caching Proxy verarbeitet wird.
Gültige Rückkehrcodes für die Funktion PreExit:
Andere Rückkehrcodes dürfen nicht verwendet werden.
Wenn diese Funktion HTTP_OK zurückgibt, geht der Proxy-Server davon aus, dass die Anforderung ausgeführt wurde. Alle nachfolgenden Schritte der Anforderungsverarbeitung werden übergangen, und nur die Antwortschritte ("Transmogrifier", "Log" und "PostExit") werden ausgeführt.
Alle vordefinierten API-Funktionen sind während dieses Schrittes gültig.
void HTTPD_LINKAGE MidnightFunction (
unsigned char *handle,
long *return_code
)
Eine für diesen Schritt definierte Funktion wird täglich um Mitternacht ausgeführt und enthält keinen Anforderungskontext. Sie kann beispielsweise verwendet werden, um einen untergeordneten Prozess zur Analyse von Protokollen aufzurufen. (Beachten Sie, dass eine umfassende Verarbeitung während dieses Schrittes das Protokollieren beeinträchtigen kann.)
void HTTPD_LINKAGE AuthenticationFunction (
unsigned char *handle,
long *return_code
)
Eine für diesen Schritt definierte Funktion wird für jede Anforderung auf der Basis des Authentifizierungsschemas der Anforderung aufgerufen. Diese Funktion kann verwendet werden, um die Prüfung der mit einer Anforderung gesendeten Sicherheitstoken anzupassen.
void HTTPD_LINKAGE NameTransFunction (
unsigned char *handle,
long *return_code
)
Eine für diesen Schritt definierte Funktion wird für jede Anforderung aufgerufen. In der Konfigurationsdateianweisung kann eine URL-Schablone angegeben werden, wenn die Plug-in-Funktion nur für Anforderungen aufgerufen werden soll, die mit der Schablone übereinstimmen. Der Schritt der Namensumsetzung wird ausgeführt, bevor die Anforderung verarbeitet wird, und bietet einen Mechanismus für die Zuordnung von URLs zu Objekten, z. B. Dateinamen.
void HTTPD_LINKAGE AuthorizationFunction (
unsigned char *handle,
long *return_code
)
Eine für diesen Schritt definierte Funktion wird für jede Anforderung aufgerufen. In der Konfigurationsdateianweisung kann eine URL-Schablone angegeben werden, wenn die Plug-in-Funktion nur für Anforderungen aufgerufen werden soll, die mit der Schablone übereinstimmen. Der Schritt "Authorization" wird ausgeführt, bevor die Anforderung verarbeitet wird. Mit diesem Schritt kann geprüft werden, ob das identifizierte Objekt an den Client zurückgegeben werden kann. Bei Ausführung einer Basisauthentifizierung müssen Sie die erforderlichen WWW-Authenticate-Header generieren.
void HTTPD_LINKAGE ObjTypeFunction (
unsigned char *handle,
long *return_code
)
Eine für diesen Schritt definierte Funktion wird für jede Anforderung aufgerufen. In der Konfigurationsdateianweisung kann eine URL-Schablone angegeben werden, wenn die Plug-in-Funktion nur für Anforderungen aufgerufen werden soll, die mit der Schablone übereinstimmen. Der Schritt "Object Type" wird ausgeführt, bevor die Anforderung verarbeitet wird. Mit diesem Schritt kann geprüft werden, ob das Objekt existiert, und der Objekttyp kann angegeben werden.
void HTTPD_LINKAGE PostAuthFunction (
unsigned char *handle,
long *return_code
)
Eine für diesen Schritt definierte Funktion wird aufgerufen, nachdem die Anforderung autorisiert wurde, aber bevor eine Verarbeitung stattgefunden hat. Wenn diese Funktion HTTP_OK zurückgibt, geht der Proxy-Server davon aus, dass die Anforderung ausgeführt wurde. Alle nachfolgenden Schritte der Anforderungsverarbeitung werden übergangen, und nur die Antwortschritte ("Transmogrifier", "Log" und "PostExit") werden ausgeführt.
Alle vordefinierten Serverfunktionen sind während dieses Schrittes gültig.
void HTTPD_LINKAGE ServiceFunction (
unsigned char *handle,
long *return_code
)
Eine für diesen Schritt definierte Funktion wird für jede Anforderung aufgerufen. In der Konfigurationsdateianweisung kann eine URL-Schablone angegeben werden, wenn die Plug-in-Funktion nur für Anforderungen aufgerufen werden soll, die mit der Schablone übereinstimmen. Der Serviceschritt erfüllt die Anforderung, falls sie im Schritt "PreExit" oder "PostAuthorization" nicht erfüllt wurde.
Alle vordefinierten Serverfunktionen sind während dieses Schrittes gültig.
Informationen zur Konfiguration Ihrer Servicefunktion für die Ausführung auf der Basis der HTTP-Methode anstatt auf URL-Basis finden Sie in der Beschreibung der Anweisung "Enable" in der Veröffentlichung WebSphere Application Server Caching Proxy Administratorhandbuch.
Für diesen Schritt müssen Sie die folgenden vier Funktionen implementieren. (Ihre Funktionsnamen müssen nicht mit diesen Namen übereinstimmen.)
void * HTTPD_LINKAGE openFunction (
unsigned char *handle,
long *return_code
)
Die Funktion "open" führt die Initialisierung aus, die zur Verarbeitung der Daten für diesen Datenstrom erforderlich ist (z. B. Pufferzuordnung). Ein anderer Rückkehrcode als HTTP_OK bewirkt, dass dieser Filter scheitert (die Funktionen "write" und "close" werden nicht aufgerufen). Ihre Funktion kann einen leeren Zeiger zurückgeben, damit Sie Speicherplatz für eine Struktur zuordnen können und der Zeiger im Parameter correlator der nachfolgenden Funktionen an Sie zurückgegeben werden kann.
void HTTPD_LINKAGE writeFunction (
unsigned char *handle,
unsigned char *data, /* vom Ursprungsserver gesendete
Antwortdaten */
unsigned long *length, /* Länge der Antwortdaten */
void *correlator, /* von der Funktion "open"
zurückgegebener Zeiger */
long *return_code
)
Die Funktion "write" verarbeitet die Daten und kann die vordefinierte Serverfunktion HTTPD_write() mit den neuen oder geänderten Daten aufrufen. Das Plug-in darf nicht versuchen, den ihm übergebenen Puffer freizugeben, oder erwarten, dass der Server den erhaltenen Puffer freigibt.
Auch wenn die Daten nicht geändert werden sollen, während sie sich im Geltungsbereich der Funktion "write" befinden, muss im Geltungsbereich der Funktion "open", "write" oder "close" die Funktion HTTPD_write() aufgerufen werden, damit die Daten für die Antwort an den Client übergeben werden können. Das Argument correlator ist der Zeiger auf den Datenpuffer, der in Ihrer open-Routine zurückgegeben wurde.
void HTTPD_LINKAGE closeFunction (
unsigned char *handle,
void *correlator,
long *return_code
)
Die Funktion "close" führt die Bereinigungsaktionen aus (z. B. Flushoperation ausführen und den Korrelatorpuffer freigeben), die erforderlich sind, um die Verarbeitung der Daten für diesen Datenstrom abzuschließen. Das Argument correlator ist der Zeiger auf den Datenpuffer, der in Ihrer open-Routine zurückgegeben wurde.
void HTTPD_LINKAGE errorFunction (
unsigned char *handle,
void *correlator,
long *return_code
)
Die Funktion "error" ermöglicht die Ausführung von Bereinigungsaktionen, z. B. Flushoperation ausführen oder gepufferte Daten freigeben (oder beides), bevor eine Fehlerseite gesendet wird. An dieser Stelle werden Ihre Funktionen "open", "write" und "close" aufgerufen, um die Fehlerseite zu verarbeiten. Das Argument correlator ist der Zeiger auf den Datenpuffer, der in Ihrer open-Routine zurückgegeben wurde.
Anmerkungen:
void HTTPD_LINKAGE GCAdvisorFunction (
unsigned char *handle,
long *return_code
)
Eine für diesen Schritt definierte Funktion wird während der Garbage-Collection für jede Datei im Cache aufgerufen. Mit dieser Funktion können Sie festlegen, welche Dateien behalten und welche Dateien gelöscht werden sollen. Weitere Informationen hierzu finden Sie in der Beschreibung der "GC_*"- Variablen.
void HTTPD_LINKAGE ProxyAdvisorFunction (
unsigned char *handle,
long *return_code
)
Eine für diesen Schritt definierte Funktion wird aufgerufen, wenn eine Proxy-Anforderung bedient wird. Sie kann beispielsweise verwendet werden, um die Variable "USE_PROXY" festzulegen.
void HTTPD_LINKAGE LogFunction (
unsigned char *handle,
long *return_code
)
Eine für diesen Schritt definierte Funktion wird für jede Anforderung aufgerufen, nachdem die Anforderung verarbeitet und die Kommunikation mit dem Client beendet wurde. In der Konfigurationsdateianweisung kann eine URL-Schablone angegeben werden, wenn die Plug-in-Funktion nur für Anforderungen aufgerufen werden soll, die mit der Schablone übereinstimmen. Diese Funktion wird unabhängig davon aufgerufen, ob die Anforderungsverarbeitung erfolgreich war oder gescheitert ist. Wenn Ihr Protokoll-Plug-in den Standardprotokollierungsmechanismus außer Kraft setzen soll, legen Sie den Rückkehrcode HTTP_NOACTION anstatt HTTP_OK fest.
void HTTPD_LINKAGE ErrorFunction (
unsigned char *handle,
long *return_code
)
Eine für diesen Schritt definierte Funktion wird für jede fehlgeschlagene Anforderung aufgerufen. In der Konfigurationsdateianweisung kann eine URL-Schablone angegeben werden, wenn die Plug-in-Funktion nur für fehlgeschlagene Anforderungen aufgerufen werden soll, die mit der Schablone übereinstimmen. Der Schritt "Fehler" bietet die Möglichkeit, die Fehlerantwort anzupassen.
void HTTPD_LINKAGE PostExitFunction (
unsigned char *handle,
long *return_code
)
Eine für diesen Schritt definierte Funktion wird für jede Anforderung aufgerufen, unabhängig vom Erfolg oder Scheitern der Anforderung. Dieser Schritt ermöglicht die Ausführung von Bereinigungsaufgaben für alle Ressourcen, die von Ihrem Plug-in für die Verarbeitung der Anforderung zugeordnet wurden.
void HTTPD_LINKAGE ServerTermFunction (
unsigned char *handle,
long *return_code
)
Eine für diesen Schritt definierte Funktion wird aufgerufen, wenn der Server ordnungsgemäß beendet wird. Sie ermöglicht die Bereinigung von Ressourcen, die während des Schrittes der Serverinitialisierung zugeordnet wurden. Rufen Sie in diesem Schritt keine Funktionen des Typs HTTP_* auf (die Ergebnisse können unvorhersehbar sein). Wenn in Ihrer Konfigurationsdatei mehrere Caching-Proxy-API-Anweisungen für "Server Termination" (Serverbeendigung) enthalten sind, werden sie alle aufgerufen.
Diese Rückkehrcodes entsprechen der Spezifikation HTTP 1.1, RFC 2616, veröffentlicht vom World Wide Web Consortium (www.w3.org/pub/WWW/Protocols/). Ihre Plug-in-Funktionen müssen einen der folgenden Werte zurückgeben.
Wert | Rückkehrcode |
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 |
Sie können die vordefinierten Funktionen und Makros des Servers aus Ihren eigenen Plug-in-Funktionen aufrufen. Verwenden Sie ihre vordefinierten Namen und das unten beschriebene Format. In der Parameterbeschreibung steht der Buchstabe i für einen Eingabeparameter, der Buchstabe o für einen Ausgabeparameter und i/o gibt an, dass ein Parameter sowohl für die Eingabe als auch für die Ausgabe verwendet wird.
Jede dieser Funktionen gibt einen HTTPD-Rückkehrcode zurück, der vom Erfolg der Anforderung abhängig ist. Diese Codes werden im Abschnitt Rückkehrcodes von vordefinierten Funktionen und Makros beschrieben.
Verwenden Sie die für Ihr Plug-in angegebene interne Kennung als ersten Parameter, wenn Sie diese Funktionen aufrufen. Andernfalls gibt die Funktion den Fehlercode HTTPD_PARAMETER_ERROR zurück. NULL wird nicht als gültige interne Kennung akzeptiert.
void HTTPD_LINKAGE HTTPD_authenticate (
unsigned char *handle, /* i; interne Kennung */
long *return_code /* o; Rückkehrcode */
)
void HTTPD_LINKAGE HTTPD_cacheable_url (
unsigned char *handle, /* i; interne Kennung */
unsigned char *url, /* i; zu prüfende URL */
unsigned char *req_method, /* i; Anforderungsmethode für die URL */
long *retval /* o; Rückkehrcode */
)
Der Rückgabewert HTTPD_SUCCESS zeigt an, dass der URL-Inhalt im Cache zwischengespeichert werden kann. HTTPD_FAILURE zeigt an, dass der Inhalt nicht im Cache zwischengespeichert werden kann. HTTPD_INTERNAL_ERROR ist ebenfalls ein möglicher Rückkehrcode für diese Funktion.
void HTTPD_LINKAGE HTTPD_close (
unsigned char *handle, /* i; interne Kennung */
long *return_code /* o; Rückkehrcode */
)
void HTTPD_LINKAGE HTTPD_exec (
unsigned char *handle, /* i; interne Kennung */
unsigned char *name, /* i; Name des auszuführenden Scripts */
unsigned long *name_length, /* i; Länge des Namens */
long *return_code /* o; Rückkehrcode */
)
void HTTPD_LINKAGE HTTPD_extract (
unsigned char *handle, /* i; interne Kennung */
unsigned char *name, /* i; Name der zu extrahierenden Variablen */
unsigned long *name_length, /* i; Länge des Namens */
unsigned char *value, /* o; Puffer, in dem der Wert
gespeichert werden soll */
unsigned long *value_length, /* i/o; Puffergröße */
long *return_code /* o; Rückkehrcode */
)
Wenn diese Funktion den Code HTTPD_BUFFER_TOO_SMALL zurückgibt, war die angeforderte Puffergröße für den extrahierten Wert nicht ausreichend. In diesem Fall verwendet die Funktion den Puffer nicht, sondern aktualisiert den Parameter "value_length" mit der Puffergröße, die erforderlich ist, um diesen Wert erfolgreich zu extrahieren. Extrahieren Sie den Wert erneut und verwenden Sie dabei einen Puffer, der mindestens so groß ist wie der zurückgegebene Wert für "value_length".
void HTTPD_LINKAGE HTTPD_file (
unsigned char *handle, /* i; interne Kennung */
unsigned char *name, /* i; Name der zu sendenden Datei */
unsigned long *name_length, /* i; Länge des Namens */
long *return_code /* o; Rückkehrcode */
)
const unsigned char * /* o; Variablenwert */
HTTPD_LINKAGE
httpd_getvar(
unsigned char *handle, /* i; interne Kennung */
unsigned char *name, /* i; Variablenname */
unsigned long *n /* i; Indexnummer des Bereichs, in dem
der Header enthalten ist */
)
Der Index für den Bereich, in dem der Header enthalten ist, beginnt mit 0. Um den ersten Eintrag im Bereich abzurufen, verwenden Sie den Wert 0 für n. Um den fünften Eintrag abzurufen, verwenden Sie für n den Wert 4.
void HTTPD_LINKAGE HTTPD_log_access (
unsigned char *handle, /* i; interne Kennung */
unsigned char *value, /* i; zu schreibende Daten */
unsigned long *value_length, /* i; Länge der Daten */
long *return_code /* o; Rückkehrcode */
)
Beachten Sie, dass keine Escapezeichen erforderlich sind, wenn das Prozentsymbol (%) in Serverzugriffsprotokollen verwendet wird.
void HTTPD_LINKAGE HTTPD_log_error (
unsigned char *handle, /* i; interne Kennung */
unsigned char *value, /* i; zu schreibende Daten */
unsigned long *value_length, /* i; Länge der Daten */
long *return_code /* o; Rückkehrcode */
)
Beachten Sie, dass keine Escapezeichen erforderlich sind, wenn das Prozentsymbol (%) in Serverfehlerprotokollen verwendet wird.
void HTTPD_LINKAGE HTTPD_log_event (
unsigned char *handle, /* i; interne Kennung */
unsigned char *value, /* i; zu schreibende Daten */
unsigned long *value_length, /* i; Länge der Daten */
long *return_code /* o; Rückkehrcode */
)
Beachten Sie, dass keine Escapezeichen erforderlich sind, wenn das Prozentsymbol (%) in Serverereignisprotokollen verwendet wird.
void HTTPD_LINKAGE HTTPD_log_trace (
unsigned char *handle, /* i; interne Kennung */
unsigned char *value, /* i; zu schreibende Daten */
unsigned long *value_length, /* i; Länge der Daten */
long *return_code /* o; Rückkehrcode */
)
Beachten Sie, dass keine Escapezeichen erforderlich sind, wenn das Prozentsymbol (%) in Servertraceprotokollen verwendet wird.
void HTTPD_LINKAGE HTTPD_open (
unsigned char *handle, /* i; interne Kennung */
long *return_code /* o; Rückkehrcode */
)
void HTTPD_LINKAGE HTTPD_proxy (
unsigned char *handle, /* i; interne Kennung */
unsigned char *url_name, /* i; URL für die
Proxy-Anforderung */
unsigned long *name_length, /* i; Länge der URL */
void *request_body, /* i; Hauptteil der Anforderung */
unsigned long *body_length, /* i; Länge des Hauptteils */
long *return_code /* o; Rückkehrcode */
)
void HTTPD_LINKAGE HTTPD_read (
unsigned char *handle, /* i; interne Kennung */
unsigned char *value, /* i; Puffer für die Daten */
unsigned long *value_length, /* i/o; Puffergröße
(Datenlänge) */
long *return_code /* o; Rückkehrcode */
)
void HTTPD_LINKAGE HTTPD_restart (
long *return_code /* o; Rückkehrcode */
)
Es ist außerdem möglich, mit dieser Funktion Variablen zu erstellen. Die Variablen, die Sie erstellen, unterliegen den Konventionen für die Präfixe HTTP_ und PROXY_. Eine entsprechende Beschreibung finden Sie im Abschnitt Variablen. Wenn Sie eine Variable erstellen, die mit HTTP_ beginnt, wird sie ohne Präfix HTTP_ als Header in der Antwort an den Client gesendet. Beispiel: Zum Festlegen eines Headers für den Standort (Location) verwenden Sie HTTPD_set() zusammen mit dem Variablennamen HTTP_LOCATION. Variablen, die mit dem Präfix PROXY_ erstellt wurden, werden als Header in der Anforderung an den Content-Server gesendet. Variablen, die mit dem Präfix CGI_ erstellt wurden, werden an CGI-Programme übergeben.
Diese Funktion ist in allen Schritten gültig. Allerdings sind nicht alle Variablen in allen Schritten gültig.
void HTTPD_LINKAGE HTTPD_set (
unsigned char *handle, /* i; interne Kennung */
unsigned char *name, /* i; Name des anzugebenden Werts */
unsigned long *name_length, /* i; Länge des Namens */
unsigned char *value, /* i; Puffer mit Wert */
unsigned long *value_length, /* i; Länge des Werts */
long *return_code /* o; Rückkehrcode */
)
long /* o; Rückkehrcode */
HTTPD_LINKAGE httpd_setvar (
unsigned char *handle, /* i; interne Kennung */
unsigned char *name, /* i; Variablenname */
unsigned char *value, /* i; neuer Wert */
unsigned long *addHdr /* i; Header hinzufügen oder ersetzen */
)
Der Parameter addHdr hat vier gültige Werte:
Diese Werte werden in der Datei HTAPI.h definiert.
void HTTPD_LINKAGE httpd_variant_insert (
unsigned char *handle, /* i; interne Kennung */
unsigned char *URI, /* i; URI dieses Objekts */
unsigned char *dimension, /* i; Dimension der Abweichung */
unsigned char *variant, /* i; Wert der Variante */
unsigned char *filename, /* i; Datei mit dem Objekt */
long *return_code /* o; Rückkehrcode */
)
Anmerkungen:
Mozilla 4.0 (compatible; BatBrowser 94.1.2; Bat OS)
void HTTPD_LINKAGE httpd_variant_lookup (
unsigned char *handle, /* i; interne Kennung */
unsigned char *URI, /* i; URI dieses Objekts */
unsigned char *dimension, /* i; Dimension der Abweichung */
unsigned char *variant, /* i; Wert der Variante */
long *return_code); /* o; Rückkehrcode */
Wenn Sie vor dem ersten Aufruf dieser Funktion den Inhaltstyp nicht festgelegt haben, geht der Server davon aus, dass Sie einen CGI-Datenstrom senden.
void HTTPD_LINKAGE HTTPD_write (
unsigned char *handle, /* i; interne Kennung */
unsigned char *value, /* i; zu sendende Daten */
unsigned char *value_length, /* i; Länge der Daten */
long *return_code); /* o; Rückkehrcode */
Abhängig vom Erfolg der Anforderung legt der Server einen der folgenden Werte für den Rückkehrcodeparameter fest:
Wert | Statuscode | Erläuterung |
---|---|---|
-1 | HTTPD_UNSUPPORTED | Die Funktion wird nicht unterstützt. |
0 | HTTPD_SUCCESS | Die Funktion war erfolgreich, und die Ausgabefelder sind gültig. |
1 | HTTPD_FAILURE | Die Funktion ist fehlgeschlagen. |
2 | HTTPD_INTERNAL_ERROR | Ein interner Fehler trat auf und diese Anforderung kann nicht weiter verarbeitet werden. |
3 | HTTPD_PARAMETER_ERROR | Es wurden ein oder mehrere ungültige Parameter übergeben. |
4 | HTTPD_STATE_CHECK | Die Funktion ist in diesem Verarbeitungsschritt nicht gültig. |
5 | HTTPD_READ_ONLY | (Wird nur von HTTPD_set und httpd_setvar zurückgegeben. Die Variable ist schreibgeschützt und kann vom Plug-in nicht festgelegt werden. |
6 | HTTPD_BUFFER_TOO_SMALL | (Wird von HTTPD_set, httpd_setvar und HTTPD_read zurückgegeben.) Der bereitgestellte Puffer war zu klein. |
7 | HTTPD_AUTHENTICATE_FAILED | (Wird nur von HTTPD_authenticate zurückgegeben.) Die Authentifizierung ist fehlgeschlagen. Weitere Informationen finden Sie in den Beschreibungen der Variablen HTTP_RESPONSE und HTTP_REASON. |
8 | HTTPD_EOF | (Wird nur von HTTPD_read zurückgegeben.) Zeigt das Ende des Hauptteils der Anforderung an. |
9 | HTTPD_ABORT_REQUEST | Die Anforderung wurde abgebrochen, weil der Client ein Entitäts-Tag angegeben hat, das die von der Anforderung festgelegte Bedingung nicht erfüllt. |
10 | HTTPD_REQUEST_SERVICED | (Wird von HTTPD_proxy zurückgegeben.) Die aufgerufene Funktion hat die Antwort für diese Anforderung ausgeführt. |
11 | HTTPD_RESPONSE_ALREADY_COMPLETED | Die Funktion ist fehlgeschlagen, weil die Antwort für die Anforderung bereits ausgeführt wurde. |
12 | HTTPD_WRITE_ONLY | Die Variable ist schreibgeschützt und kann vom Plug-in nicht gelesen werden. |
Jedem Schritt im Anforderungsprozess ist eine Konfigurationsanweisung zugeordnet, in der Sie festlegen, welche Plug-in-Funktionen während dieses Schrittes aufgerufen und ausgeführt werden sollen. Sie können diese Anweisungen in die Konfigurationsdatei Ihres Servers (ibmproxy.conf) aufnehmen, indem Sie diese Datei manuell editieren und aktualisieren oder indem Sie das Formular für API-Anforderungsverarbeitung aus den Konfigurations- und Verwaltungsformularen für Caching Proxy verwenden.
Daraus folgt, dass der Server die Anweisungen "Service", "NameTrans", "Exec", "Fail", "Map", "Pass", "Proxy", "ProxyWAS" und "Redirect" in der Reihenfolge verarbeitet, in der sie in der Konfigurationsdatei vorkommen. Wenn der Server eine URL erfolgreich einer Datei zuordnet, wird keine andere dieser Anweisungen gelesen oder verarbeitet. (Die Zuordnungsanweisung "Map" ist eine Ausnahme. Ausführliche Informationen zu den Zuordnungsregeln für den Proxy-Server finden Sie in der Veröffentlichung WebSphere Application Server Caching Proxy Administratorhandbuch.)
Diese Konfigurationsdateianweisungen müssen in der Datei ibmproxy.conf in einer Zeile stehen und dürfen außer den hier explizit angegebenen Leerzeichen keine weiteren Leerzeichen enthalten. Obwohl in einigen Syntaxbeispielen aus Gründen der Lesbarkeit Zeilenumbrüche verwendet werden, dürfen in der Anweisung selbst an dieser Stelle keine Leerzeichen stehen.
Die Variablen in diesen Anweisungen haben folgende Bedeutung:
In der Anweisung "Service" muss nach dem Funktionsnamen ein Stern (*) angegeben werden, falls Sie Zugriff auf die Pfadinformationen haben möchten.
Weitere Informationen zu diesen Anweisungen, einschließlich der Syntax, finden Sie in der Veröffentlichung WebSphere Application Server Caching Proxy Administratorhandbuch.