Allgemeine Vorgehensweise zum Schreiben von API-Programmen

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.

Schritte des Serverprozesses

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.

Abbildung 1. Ablaufdiagramm der Schritte im Proxy-Server-Prozess

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.

Server Initialization
Führt die Initialisierung aus, wenn der Proxy-Server gestartet wird und bevor Clientanforderungen akzeptiert werden.
Midnight
Führt um Mitternacht ein Plug-in ohne Anforderungskontext aus. Dieser Schritt wird im Diagramm gesondert dargestellt, weil er nicht Teil des Anforderungsprozesses ist, d. h., seine Ausführung ist nicht von einer Anforderung abhängig.
GC Advisor
Beeinflusst die Garbage-Collection-Entscheidungen für Dateien im Cache. Dieser Schritt wird im Diagramm gesondert dargestellt, weil er nicht Teil des Anforderungsprozesses ist, d. h., seine Ausführung ist nicht von einer Anforderung abhängig. Die Garbage-Collection findet statt, wenn die Cachegröße den Maximalwert erreicht hat. (Informationen zur Konfiguration der Garbage-Collection finden Sie in der Veröffentlichung WebSphere Application Server Caching Proxy Administratorhandbuch.)
PreExit

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.

Name Translation
Setzt den virtuellen Pfad (aus einer URL) in den physischen Pfad um.
Authorization

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.

Authentication

Entschlüsselt, überprüft und speichert Sicherheitstoken.

Weitere Informationen hierzu finden Sie im Abschnitt Authentifizierung und Berechtigung.

Object Type
Lokalisiert das im Pfad angegebene Dateisystemobjekt.
Post Authorization

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.

Service
Erfüllt die Anforderung (durch Senden der Datei, Ausführen der CGI usw.)
Proxy Advisor
Beeinflusst Proxy- und Caching-Entscheidungen.
Transmogrifier
Legt für den Datenabschnitt der an den Client gesendeten Antwort den Schreibzugriff fest.
Log
Ermöglicht die angepasste Transaktionsprotokollierung.
Error
Ermöglicht angepasste Antworten auf Fehlerbedingungen.
PostExit
Bereinigt die Ressourcen, die zum Zweck der Anforderungsverarbeitung zugeordnet wurden.
Server Termination
Führt eine Bereinigung durch, wenn der Server ordnungsgemäß beendet wird.

Richtlinien

Plug-in-Funktionen

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:

Plug-in-Funktionsprototypen

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.

Server Initialization

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.

PreExit

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.

Midnight

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

Authentication

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.

Name Translation

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.

Authorization

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.

Object Type

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.

PostAuthorization

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.

Service

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.

Transmogrifier
Mit den Funktionen, die in diesem Verarbeitungsschritt aufgerufen werden, können die Antwortdaten gefiltert werden, z. B. als Datenstrom. Für diesen Schritt werden nacheinander vier Plug-in-Funktionen aufgerufen, wobei jede als Segment einer Pipe fungiert, durch die die Daten fließen. Dies bedeutet, dass die Funktionen open, write, close und error, die Sie bereitstellen, in dieser Reihenfolge für jede Antwort aufgerufen werden. Die Funktionen verarbeiten der Reihe nach denselben Datenstrom.

Für diesen Schritt müssen Sie die folgenden vier Funktionen implementieren. (Ihre Funktionsnamen müssen nicht mit diesen Namen übereinstimmen.)

Anmerkungen:

GC Advisor

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.

Proxy Advisor

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.

Log

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.

Error

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.

PostExit

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.

Server Termination

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.

Anmerkung:
Aufgrund einer aktuellen Einschränkung im Solaris-Code wird der Schritt "Server Termination" nicht ausgeführt, wenn der Befehl ibmproxy -stop verwendet wird, um Caching Proxy auf Solaris-Plattformen zu beenden. Informationen zum Starten und Stoppen von Caching Proxy finden Sie in der Veröffentlichung WebSphere Application Server Caching Proxy Administratorhandbuch.

HTTP-Rückkehrcodes und Werte

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.

Tabelle 2. HTTP-Rückkehrcodes für API-Funktionen für Caching Proxy
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

Vordefinierte Funktionen und Makros

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.

HTTPD_authenticate()
Authentifiziert eine Benutzer-ID und/oder ein Kennwort. Nur gültig in den Schritten "PreExit", "Authentication", "Authorization" und "PostAuthorization".

void  HTTPD_LINKAGE  HTTPD_authenticate (
    unsigned char *handle,             /* i; interne Kennung */
         long *return_code            /* o; Rückkehrcode */
         )
HTTPD_cacheable_url()
Gibt an, ob der angegebene URL-Inhalt gemäß den Standards von Caching Proxy im Cache zwischengespeichert werden kann.

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.

HTTPD_close()
(Nur gültig im Schritt "Transmogrifier".) Überträgt die Steuerung an die nächste close-Routine im Datenstromstapel. Diese Funktion sollte aus den Funktionen für Öffnen, Schreiben oder Schließen ("open", "write", "close") des Schrittes "Transmogrifier" aufgerufen werden, nachdem die gewünschte Verarbeitung durchgeführt wurde. Diese Funktion benachrichtigt den Proxy-Server darüber, dass die Antwort verarbeitet wurde und der Schritt "Transmogrifier" abgeschlossen ist.

void  HTTPD_LINKAGE  HTTPD_close (
         unsigned char *handle,       /* i; interne Kennung */
         long *return_code            /* o; Rückkehrcode */
         )
HTTPD_exec()
Führt ein Script aus, um diese Anforderung zu erfüllen. Gültig in den Schritten "PreExit", "Service", "PostAuthorization" und "Error".

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 */
         )
HTTPD_extract()
Extrahiert den Wert einer Variablen, die dieser Anforderung zugeordnet ist. Die gültigen Variablen für den Parameter name stimmen mit den im CGI verwendeten überein. Weitere Informationen hierzu finden Sie im Abschnitt Variablen. Beachten Sie, dass diese Funktion in allen Schritten gültig ist. Es sind aber nicht alle Variablen in allen Schritten gültig.

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

Anmerkung:
Wenn die extrahierte Variable für einen HTTP-Header verwendet wird, extrahiert die Funktion HTTPD_extract() nur die erste passende Übereinstimmung, selbst wenn die Anforderung mehrere Header mit demselben Namen enthält. Anstelle von HTTPD_extract() kann die Funktion httpd_getvar() verwendet werden. Sie bietet außerdem weitere Vorteile. Nähere Informationen hierzu finden Sie im Abschnitt zu Funktion httpd_getvar().
HTTPD_file()
Sendet eine Datei, um diese Anforderung zu erfüllen. Nur gültig in den Schritten "PreExit", "Service", "Error", "PostAuthorization" und "Transmogrifier".

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 */
         )
httpd_getvar()
Diese Funktion entspricht HTTPD_extract(), ist aber einfacher in ihrer Verwendung, da der Benutzer keine Längen für die Argumente angeben muss.

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.

Anmerkung:
Der Inhalt des Rückgabewerts darf nicht gelöscht und nicht geändert werden. Die zurückgegebene Zeichenfolge wird mit null beendet.
HTTPD_log_access()
Schreibt eine Zeichenfolge in das Zugriffsprotokoll des Servers.

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.

HTTPD_log_error()
Schreibt eine Zeichenfolge in das Fehlerprotokoll des Servers.

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.

HTTPD_log_event()
Schreibt eine Zeichenfolge in das Ereignisprotokoll des Servers.

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.

HTTPD_log_trace()
Schreibt eine Zeichenfolge in das Traceprotokoll des Servers.

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.

HTTPD_open()
(Nur gültig im Schritt "Transmogrifier".) Überträgt die Steuerung an die nächste Routine im Datenstromstapel. Diese Funktion sollte aus den Funktionen für Öffnen, Schreiben oder Schließen des Schrittes "Transmogrifier" aufgerufen werden, nachdem die gewünschten Header festgelegt wurden und mit dem Schreiben der Routine begonnen werden kann.

void  HTTPD_LINKAGE  HTTPD_open (
         unsigned char *handle,       /* i; interne Kennung */
         long *return_code           /* o; Rückkehrcode */
         )	
HTTPD_proxy()
Führt eine Proxy-Anforderung aus. Gültig in den Schritten "PreExit", "Service" und "PostAuthorization".
Anmerkung:
Dies ist eine Funktion für Beendigung. Nach dieser Funktion ist die Anforderung beendet.

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 */
         ) 
HTTPD_read()
Liest den Hauptteil der Anforderung vom Client. Verwenden Sie HTTPD_extract() für Header. Nur gültig in den Schritten "PreExit", "Authorization", "PostAuthorization" und "Service" und nur hilfreich, wenn eine PUT- oder POST-Anforderung ausgeführt wurde. Diese Funktion sollte in einer Schleife aufgerufen werden, bis HTTPD_EOF zurückgegeben wird. Wenn diese Anforderung keinen Hauptteil hat, scheitert diese Funktion.

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 */
         )
HTTPD_restart()
Startet den Server erneut, nachdem alle aktiven Anforderungen verarbeitet wurden. Gültig in allen Schritten außer "Server Initialization", "Server Termination" und "Transmogrifier".

void  HTTPD_LINKAGE  HTTPD_restart ( 
         long *return_code    /* o; Rückkehrcode */
         )
HTTPD_set()
Legt den Wert einer Variablen fest, die dieser Anforderung zugeordnet ist. Die gültigen Variablen für den Parameter name stimmen mit den im CGI verwendeten überein. Weitere Informationen hierzu finden Sie im Abschnitt Variablen.

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 */
         ) 
Anmerkung:
Mit der Funktion httpd_setvar() kann ein Variablenwert ohne Angabe eines Puffers und einer Länge festgelegt werden. Nähere Informationen hierzu finden Sie im Abschnitt zu Funktion httpd_setvar().
httpd_setvar()
Diese Funktion entspricht HTTPD_set(), ist aber einfacher in ihrer Verwendung, da der Benutzer keine Längen für die Argumente angeben muss.

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.

httpd_variant_insert()
Fügt eine Variante in den Cache ein.

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:

  1. Das Argument "dimension" bezieht sich auf den Header, in dem dieses Objekt von der URI abweicht. Ein möglicher Wert für "dimension" wäre in diesem Beispiel "User-Agent".
  2. Das Argument "variant" bezieht sich auf den Wert für den im Argument "dimension" angegebenen Header. Dieser weicht von der URI ab. Im Beispiel oben könnte ein möglicher Wert für das Argument "variant" wie folgt aussehen:
    Mozilla 4.0 (compatible; BatBrowser 94.1.2; Bat OS)
  3. Das Argument "filename" muss auf eine auf null endende Kopie des Dateinamens zeigen, in der der Benutzer den geänderten Inhalt gespeichert hat. Der Benutzer ist dafür verantwortlich, die Datei zu entfernen. Diese Aktion kann nach der Rückkehr von dieser Funktion ausgeführt werden. Die Datei enthält nur den Hauptteil ohne Header.
  4. Beim Zwischenspeichern von Varianten aktualisiert der Server den Header für die Inhaltslänge ("content-length") und fügt den Header "Warning: 214" hinzu. Die strikten Entitäts-Tags werden entfernt.
httpd_variant_lookup()
Stellt fest, ob eine bestimmte Variante im Cache existiert.

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 */      
HTTPD_write()
Schreibt den Hauptteil der Antwort. Gültig in den Schritten "PreExit", "Service", "Error" und "Transmogrifier".

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 */
Anmerkung:
Informationen zum Festlegen von Antwortheadern finden Sie im Abschnitt zu Funktion HTTPD_set().
Anmerkung:
Nach der Rückkehr von einer Funktion des Typs HTTPD_* kann der an die Funktion übergebene Speicher freigegeben werden.

Rückkehrcodes von vordefinierten Funktionen und Makros

Abhängig vom Erfolg der Anforderung legt der Server einen der folgenden Werte für den Rückkehrcodeparameter fest:

Tabelle 3. Rückkehrcodes
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.

Caching-Proxy-Konfigurationsanweisungen für die API-Schritte

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.

Hinweise zur API-Verwendung

API-Anweisungen und -Syntax

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.

Tabelle 4. API-Anweisungen für Caching-Proxy-Plug-in
ServerInit /Pfad/Datei:Funktionsname Initialisierungszeichenfolge
PreExit /Pfad/Datei:Funktionsname
Authentication Typ /Pfad/Datei:Funktionsname
NameTrans /URL /Pfad/Datei:Funktionsname
Authorization /URL /Pfad/Datei:Funktionsname
ObjectType /URL /Pfad/Datei:Funktionsname
PostAuth /Pfad/Datei:Funktionsname
Service /URL /Pfad/Datei:Funktionsname
Midnight /Pfad/Datei:Funktionsname
Transmogrifier /Pfad/Datei:open-Funktion: write-Funktion: close-Funktion:error-Funktion
Log /URL /Pfad/Datei:Funktionsname
Error /URL /Pfad/Datei:Funktionsname
PostExit /Pfad/Datei:Funktionsname
ServerTerm /Pfad/Datei:Funktionsname
ProxyAdvisor /Pfad/Datei:Funktionsname
GCAdvisor /Pfad/Datei:Funktionsname

Variablen der API-Anweisungen

Die Variablen in diesen Anweisungen haben folgende Bedeutung:

Typ
Wird nur mit der Anweisung "Authentication" verwendet, um anzugeben, ob Ihre Plug-in-Funktion aufgerufen wird oder nicht. Folgende Werte sind gültig:
URL
Gibt die Anforderungen an, für die Ihre Plug-in-Funktion aufgerufen wird. Für Anforderungen mit URLs, die mit dieser Schablone übereinstimmen, wird die Plug-in-Funktion verwendet. URL-Spezifikationen in diesen Anweisungen sind virtuell (sie enthalten nicht das Protokoll), beginnen aber mit einem Schrägstrich (/). Beispielsweise ist die Angabe der URL "/www.ics.raleigh.ibm.com" korrekt, die Angabe von "http://www.ics.raleigh.ibm.com" aber nicht. Sie können als Wert dieser Variablen entweder eine bestimmte URL oder eine Schablone angeben.
Pfad/Datei
Der vollständig qualifizierte Dateiname Ihres kompilierten Programms.
Funktionsname
Der Name Ihrer Plug-in-Funktion in Ihrem Programm.

In der Anweisung "Service" muss nach dem Funktionsnamen ein Stern (*) angegeben werden, falls Sie Zugriff auf die Pfadinformationen haben möchten.

Initialisierungszeichenfolge
Diese optionale Komponente der Anweisung "ServerInit" kann Text enthalten, den Sie an Ihre Plug-in-Funktion übergeben möchten. Verwenden Sie die Funktion httpd_getvar(), um den Text aus der Variablen INIT_STRING zu extrahieren.

Weitere Informationen zu diesen Anweisungen, einschließlich der Syntax, finden Sie in der Veröffentlichung WebSphere Application Server Caching Proxy Administratorhandbuch.