API プログラム作成の一般手順

Caching Proxy プラグイン・プログラムを作成する前に、 プロキシー・サーバーがどのように機能するのかを理解する必要があります。プロキシー・サーバーの動作 は、いくつかの異なる処理ステップに分けることができます。これらのそれぞれのステップで、API を使用して独自にカスタマイズした機能を使用することが可能です。 例えば、 ある処理をクライアント要求の読み取り後、他の処理を行う前に行う、あるいは特殊ルーチンを認証時に実行してから、 要求ファイルの送信後に再度行うなどを決めます。

この API と共に、事前定義された関数のライブラリーが提供されています。 作成するプラグイン・プログラムで これらの事前定義された API 関数を呼び出すことによって、プロキシー・サーバーのプロセスと対話 する (例えば、要求の操作、要求ヘッダーの読み取り/書き込み、 プロキシー・サーバーのログへの書き込みを行う) ことができます。これらの関数を、自分で作成するプラグイン関数 (これらは、プロキシー・サーバー によって呼び出されます) と混同しないでください。事前定義された 関数については、事前定義関数およびマクロに説明があります。

適切なステップでユーザー作成のプラグイン関数を呼び出すようにプロキシー・サーバーに指示するために、 対応する Caching Proxy API ディレクティブをサーバー構成ファイル内で 使用します。これらのディレクティブについては、API ステップ用の Caching Proxy 構成ディレクティブに説明があります。

本書には、次の内容が含まれています。

これらのコンポーネントおよび手順を 使用して、独自の Caching Proxy プラグイン・プログラムを書くことができます。

サーバー・プロセス・ステップ

プロキシー・サーバーの基本的な操作 は、そのフェーズ中にサーバーが実行する処理のタイプに基づいて、いくつかの ステップに分割することができます。各ステップには、プログラムの指定された部分を実行できる接続点があります。Caching Proxy 構成 ファイル (ibmproxy.conf) に API ディレクティブを追加することによって、特定のステップ中にどのプラグイン関数が呼び出される ようにするのかを指定できます。そのステップに複数のディレクティブを組み込むことによって、特定のプロセス・ステップで 複数のプラグイン関数を呼び出すことができます。

いくつかのステップはサーバー要求プロセスの一部です。 言い換えると、プロキシー・サーバーは、要求を処理するたびにこれらの ステップを実行します。その他のステップは要求処理とは無関係に実行されます。 すなわち、要求が処理されているかどうかにかかわらず、 サーバーはこれらのステップを実行します。

コンパイルされたプログラムは、オペレーティング・システムに応じて、 いずれかの共有オブジェクト (例えば、DLL または .so ファイル) に入っています。 サーバーは、その要求プロセス・ステップを進めながら、いずれかの関数が要求の 処理を終えたことを示すまでは、各ステップに関連付けられたプラグイン関数を呼び出します。 特定のステップのプラグイン関数が複数ある場合は、これらの関数は構成ファイル内に あるディレクティブの順序で呼び出されます。

要求を処理するプラグイン関数がない (その ステップ用に Caching Proxy API ディレクティブを組み込まなかったか、 そのステップ用のプラグイン関数が HTTP_NOACTION を戻した) 場合、サーバーはそのステップに対するデフォルトのアクションを 実行します。

注 : これは、Service ステップを除くすべてのステップに当てはまります。Service ステップにはデフォルト・アクションはありません。

図 1 は、プロキシー・サーバー・プロセスのステップを表し、 要求処理に関するステップの処理順序を定義しています。

図 1. プロキシー・サーバー・プロセスのステップのフローチャート

この図の中の 4 つのステップは、クライアント要求の処理とは無関係に実行されます。 これらのステップは、プロキシー・サーバーの実行および保守に関連しています。これらのステップには以下が含まれます。

図 1 に示された各ステップの目的を以下に示します。ある特定の要求に対して必ずすべてのステップが呼び出される わけではないことに注意してください。

Server Initialization
プロキシー・サーバーの開始時、何らかのクライアント要求が受け入れられる前に、初期化 を実行します。
Midnight
夜間にプラグインを実行します。 要求コンテキストはありません。 このステップは要求プロセスの一部ではないため、図では別個に表示されています。 すなわち、このステップの実行はどの要求からも独立しています。
GC Advisor
キャッシュ内のファイルに関するガーベッジ・コレクションの決定に影響を与えます。 このステップは要求プロセスの一部ではないため、図では別個に表示されています。 すなわち、このステップの実行はどの要求からも独立しています。 ガーベッジ・コレクションは、キャッシュ・サイズが最大値に達したときに行われます。 (キャッシュ・ガーベッジ・コレクションの構成については、 「WebSphere® Application Server Caching Proxy 管理ガイド 」に記載されています)
PreExit

要求が読み込まれた後、まだ何も実行されないうちに処理を実行します。

このステップで要求が処理されたことを示す標識 (HTTP_OK) が戻された場合には、 サーバーは要求プロセスの他のステップをバイパスし、Transmogrifier、Log、および PostExit ステップだけを実行します。

Name Translation
仮想パスを (URL から) 物理パスに変換します。
Authorization

保管されたセキュリティー・トークンを使用して保護、ACL、およびその他のアクセス制御用の 物理パスを検査し、基本認証に必要な WWW 認証ヘッダーを生成します。 独自のプラグイン関数を作成してこのステップを置き換える場合は、これらのヘッダーを 自分で生成しなければなりません。

詳しくは、認証および許可を参照してください。

Authentication

セキュリティー・トークンのデコード、検査、および保管を行います。

詳しくは、認証および許可を参照してください。

Object Type
パスが示すファイル・システム・オブジェクトを探します。
Post Authorization

許可およびオブジェクト検索後に (ただし要求が満たされる前に) 処理を実行します。

このステップで要求が処理されたことを示す標識 (HTTP_OK) が戻された場合には、 サーバーは要求プロセスの他のステップをバイパスし、Transmogrifier、Log、および PostExit ステップだけを実行します。

Service
ファイルの送信、CGI の実行などによって要求を満たします。
Proxy Advisor
プロキシーとキャッシングの決定に影響を与えます。
Transmogrifier
クライアントに送信される応答のデータ部分に書き込みアクセス権限を与えます。
Log
カスタマイズされたトランザクション・ロギングを使用可能にします。
Error
エラー条件に対して、カスタマイズされた応答を使用可能にします。
PostExit
要求処理に割り振られたリソースをクリーンアップします。
Server Termination
正常シャットダウンが行われたときにクリーンアップ処理を実行します。

ガイドライン

プラグイン関数

定義された要求処理の各ステップ用に独自のプログラム関数を書く場合は、プラグイン関数プロトタイプに示されている 構文に従ってください。

各ユーザー関数では、実行されたアクションを示す値が 戻りコード・パラメーターに使用される必要があります。

プラグイン関数プロトタイプ

各 Caching Proxy ステップ用の関数プロトタイプは、使用する形式を示し、 実行できる処理のタイプを記述します。関数名は事前定義されないので、注意してください。関数には固有の名前を指定する必要がありますが、 命名規則は自由に決めることができます。 わかりやすくするため、本書では、サーバーの処理ステップに関連する名前を使用しています。

各プラグイン関数で、特定の事前定義 API 関数が有効です。 すべてのステップで無効な事前定義関数もあります。 以下の事前定義 API 関数は、これらのどのプラグイン関数からでも呼び出すことができます。

その他の有効または無効な API 関数については、関数のプロトタイプの説明に 示されています。

関数に送られる handle パラメーターの値は、 最初の引数として事前定義関数に渡すことができます。 事前定義 API 関数は、事前定義関数およびマクロに説明されています。

Server Initialization

void HTTPD_LINKAGE ServerInitFunction (
     unsigned char *handle,
     unsigned long *major_version,
     unsigned long *minor_version, 
     long *return_code
     )

このステップに定義された関数は、サーバー初期化の間のモジュールのロード時に一度呼び出されます。初期化を行うことができるのはいずれかの要求が受け入れられる前です。

すべてのサーバー初期化関数が呼び出されますが、このステップの関数から エラー戻りコードが戻されると、サーバーはエラー・コードを戻した関数と 同じモジュールで構成された他のすべての関数を無視します。 (すなわち、エラーを戻した関数と同じ共有オブジェクトに入っている 関数はどれも呼び出されません。)

バージョンに関するパラメーターは プロキシー・サーバーのバージョン番号を含んでいて、 Caching Proxy によって提供されます。

PreExit

void  HTTPD_LINKAGE  PreExitFunction (
         unsigned char *handle,
         long *return_code
         )

このステップに定義された関数は、要求が読み取られた後、処理が行われる前に それぞれの要求ごとに呼び出されます。 このステップでプラグインを使用して、クライアントの要求 に、要求が Caching Proxy によって処理される前にアクセスできます。

preExit 関数の有効な戻りコードは次のとおりです。

その他の戻りコードは使用しないでください。

この関数が HTTP_OK を戻す 場合、プロキシー・サーバーは、要求が処理されたものと想定します。それ以降のすべての要求処理ステップはバイパスされ、応答ステップ (Transmogrifier、 Log、および PostExit) のみが実行されます。

このステップ中は、事前定義 API 関数はすべて有効です。

Midnight

void  HTTPD_LINKAGE  MidnightFunction (
         unsigned char *handle,
         long *return_code
         )

このステップに定義された関数は毎日、真夜中に実行されます。要求コンテキストは含まれていません。 例えば、この関数はログを分析する子プロセスを起動するために使用できます。 (このステップで処理が長引くと、ロギングの妨げになる可能性があることに注意してください。)

Authentication

void  HTTPD_LINKAGE  AuthenticationFunction (
         unsigned char *handle,
         long *return_code
         )

このステップに定義された関数は、要求の認証方式に基づいて要求ごとに呼び出されます。 この関数は、要求とともに送信されるセキュリティー・トークンの検査を カスタマイズするために使用できます。

Name Translation

void  HTTPD_LINKAGE  NameTransFunction (
         unsigned char *handle,
         long *return_code
         )

このステップに定義された関数は、要求ごとに呼び出されます。 テンプレートと一致する要求のみについてプラグイン関数が呼び出されるようにしたい場合は、 URL テンプレートを構成ファイル・ディレクティブに指定します。 Name Translation ステップは要求が処理される前に実行され、URL を ファイル名などのオブジェクトにマッピングするためのメカニズムを提供します。

Authorization

void  HTTPD_LINKAGE  AuthorizationFunction (
         unsigned char *handle,
         long *return_code
         )

このステップに定義された関数は、要求ごとに呼び出されます。 テンプレートと一致する要求のみについてプラグイン関数が呼び出されるようにしたい場合は、 URL テンプレートを構成ファイル・ディレクティブに指定します。 Authorization ステップは要求が処理される前に実行され、 識別されたオブジェクトをクライアントに戻すことができるかどうかを 検査するために使用できます。基本認証を行う場合は、必要な WWW 認証ヘッダーを生成しなければなりません。

Object Type

void  HTTPD_LINKAGE  ObjTypeFunction (
         unsigned char *handle,
         long *return_code
         )

このステップに定義された関数は、要求ごとに呼び出されます。 テンプレートと一致する要求のみについてプラグイン関数が呼び出されるようにしたい場合は、 URL テンプレートを構成ファイル・ディレクティブに指定します。 Object Type ステップは要求が処理される前に実行され、 オブジェクトが存在するかどうかを調べてオブジェクトの型定義を行うために使用できます。

PostAuthorization

void  HTTPD_LINKAGE  PostAuthFunction (
         unsigned char *handle,
         long *return_code
         )

このステップに定義された関数は、要求が許可された後、処理が起こる前に呼び出されます。 この関数が HTTP_OK を戻す 場合、プロキシー・サーバーは、要求が処理されたものと想定します。それ以降のすべての要求ステップはバイパスされ、応答ステップ (Transmogrifier、 Log、および PostExit) のみが実行されます。

このステップ中は、サーバー事前定義関数はすべて有効です。

Service

void  HTTPD_LINKAGE  ServiceFunction (
         unsigned char *handle,
         long *return_code
         )

このステップに定義された関数は、要求ごとに呼び出されます。 テンプレートと一致する要求のみについてプラグイン関数が呼び出されるようにしたい場合は、 URL テンプレートを構成ファイル・ディレクティブに指定します。 Service ステップは、要求が PreExit または PostAuthorization ステップで 満たされなかった場合に、この要求を満たします。

このステップ中は、サーバー事前定義関数はすべて有効です。

URL では なく HTTP メソッドに基づいて実行するように Service 関数を構成する方法については、「WebSphere Application Server Caching Proxy 管理ガイド 」内 の Enable ディレクティブについての説明を参照してください。

Transmogrifier
このプロセス・ステップで呼び出される関数は、応答データをストリームとしてフィルターに掛けるために使用できます。このステップの 4 つのプラグイン関数は順番に呼び出され、 それぞれがデータが流れるパイプのセグメントとして動作します。 すなわち、指定した openwriteclose、および error 関数が 応答ごとにこの順番で呼び出されます。 それぞれの関数は、順番に同じデータ・ストリームを処理します。

このステップには、以下の 4 つの関数を実装しなければなりません。 (使用する関数名は、以下で使用されているものと同じでなくてもかまいません。)

注 :

GC Advisor

void  HTTPD_LINKAGE  GCAdvisorFunction (
         unsigned char *handle,
         long *return_code
         )

このステップに定義された関数は、ガーベッジ・コレクションの際、キャッシュ内のファイルごとに呼び出されます。この関数によって、保持するファイルと廃棄するファイルの決定に 影響を与えることができます。 詳細については、GC_* 変数を参照してください。

Proxy Advisor

void  HTTPD_LINKAGE  ProxyAdvisorFunction (
         unsigned char *handle,
         long *return_code
         )

このステップに定義された関数は、各プロキシー要求のサービス時に呼び出されます。 例えば、USE_PROXY 変数を設定するために使用することができます。

Log

void  HTTPD_LINKAGE  LogFunction (
         unsigned char *handle,
         long *return_code
         )

このステップに定義された関数は、要求が処理され、クライアントへの通信が クローズされた後で、それぞれの要求ごとに呼び出されます。 テンプレートと一致する要求のみについてプラグイン関数が呼び出されるようにしたい場合は、 URL テンプレートを構成ファイル・ディレクティブに指定します。 この関数は、要求処理の成否に関係なく呼び出されます。 ログ・プラグインにデフォルトのログ・メカニズムを変更させたくない場合は、戻りコードを HTTP_OK ではなく HTTP_NOACTION に設定します。

Error

void  HTTPD_LINKAGE  ErrorFunction (
         unsigned char *handle,
         long *return_code
         )

このステップに定義された関数は、失敗した要求ごとに呼び出されます。 テンプレートと一致する、失敗した要求のみについてプラグイン関数が呼び出されるようにしたい場合は、 URL テンプレートを構成ファイル・ディレクティブに指定します。 Error ステップを使用して、エラー応答をカスタマイズできます。

PostExit

void  HTTPD_LINKAGE  PostExitFunction (
         unsigned char *handle,
         long *return_code
         )

このステップに定義された関数は、要求の成否に関係なく、 要求ごとに呼び出されます。 このステップを使用して、要求を処理するプラグインによって割り振られたリソースに対して クリーンアップ・タスクを行うことができます。

Server Termination

void  HTTPD_LINKAGE  ServerTermFunction (
         unsigned char *handle,
         long *return_code
         )

このステップに定義された関数は、サーバーが正常にシャットダウンしたときに呼び出されます。 これにより、サーバー初期化ステップの際に割り振られたリソースをクリーンアップすることができます。このステップでは、いずれの HTTP_* 関数も呼び出さないでください (呼び出しの結果は保証できません)。Server Termination 用の複数の Caching Proxy API ディレクティブ が構成ファイル内にある場合、それらがすべて呼び出されます。

注:
Solaris コードでの現在の制約のため、ibmproxy -stop コマンドが Solaris プラットフォームの Caching Proxy をシャットダウンするのに使用される場合は、Server Termination プラグイン・ステップ は実行されません。Caching Proxy の開始と停止について は、「WebSphere Application Server Caching Proxy 管理ガイド 」を参照してください。

HTTP 戻りコードおよび値

これらの戻りコードは、World Wide Web Consortium によって公開されている HTTP 1.1 仕様書 (www.w3.org/pub/WWW/Protocols/) の RFC 2616 に準拠しています。 プラグイン関数は、以下のいずれかの値を戻す必要があります。

表 2. Caching Proxy API 関数の HTTP 戻りコード
戻りコード
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

事前定義関数およびマクロ

サーバーの事前定義関数およびマクロを、 ユーザー独自のプラグイン関数から呼び出すことができます。その事前定義された名前を使用し、以下の形式に従う必要があります。パラメーターの説明で、 i は入力パラメーターを示し、o は出力パラメーターを示し、 i/o はパラメーターが入力と出力の両方であることを示しています。

これらの関数は、要求の結果に応じて、いずれかの HTTPD 戻りコードを戻します。これらのコードについては、事前定義関数およびマクロからの戻りコードに記述されています。

これらの関数を呼び出すときは、プラグインへ提供されたハンドルを最初のパラメーターとして使用します。最初の パラメーターとして使用しない場合、関数は HTTPD_PARAMETER_ERROR エラー・コードを戻します。 NULL は、有効なハンドルとしては受け入れられません。

HTTPD_authenticate()
ユーザー ID またはパスワード、あるいはその両方を認証します。 PreExit、Authentication、Authorization、および PostAuthorization ステップでのみ有効です。

void  HTTPD_LINKAGE  HTTPD_authenticate (
         unsigned char *handle,      /* i; handle */
         long *return_code           /* o; return code */
         )
HTTPD_cacheable_url()
Caching Proxy の標準に従って指定された URL のコンテンツがキャッシュ可能な場合に示す値を戻します。

void HTTPD_LINKAGE  HTTPD_cacheable_url ( 
        unsigned char *handle,      /* i; handle */
        unsigned char *url,         /* i; URL to check */
        unsigned char *req_method,  /* i; request method for the URL */
        long *retval                /* o; return code */
        )

戻り値 HTTPD_SUCCESS は、URL コンテンツがキャッシュできることを示します。HTTPD_FAILURE はコンテンツがキャッシュできないことを示します。また、HTTPD_INTERNAL_ERROR もこの関数の可能な戻りコードです。

HTTPD_close()
(Transmogrifier ステップでのみ有効です。) ストリーム・スタック内の次の close ルーチンに制御権を移動します。この関数は、 必要な処理が済んだ後に、Transmogrifier の open、write、close のいずれかの関数から呼び出してください。 この関数は、応答が処理され、Transmogrifier ステップが完了したことを、プロキシー・サーバーに 通知します。

void  HTTPD_LINKAGE  HTTPD_close (
         unsigned char *handle,       /* i; handle */
         long *return_code                /* o; return code */
         )
HTTPD_exec()
この要求を満たすためにスクリプトを 実行します。PreExit、Service、 PostAuthorization、および Error ステップで有効です。

void  HTTPD_LINKAGE  HTTPD_exec (
         unsigned char *handle,         /* i; handle */
         unsigned char *name,           /* i; name of script to run */
         unsigned long *name_length,    /* i; length of the name */
         long *return_code              /* o; return code */
         )
HTTPD_extract()
この要求に関連する変数の値を抽出しま す。name パラメーターで有効な変数は、CGI で使用されるものと同じです。 詳しくは、変数を参照してください。 この関数はすべてのステップで有効です。 ただし、すべての変数がすべてのステップで有効であるとは限りません。

void  HTTPD_LINKAGE  HTTPD_extract (
      unsigned char *handle,       /* i; handle */
      unsigned char *name,         /* i; name of variable to extract */
      unsigned long *name_length,  /* i; length of the name */
      unsigned char *value,        /* o; buffer in which to put 
                                         the value */
      unsigned long *value_length, /* i/o; buffer size */
      long *return_code            /* o; return code */
      )

この関数が HTTPD_BUFFER_TOO_SMALL コードを戻した場合、要求したバッファー・サイズは、抽出された値を入れるのに十分な大きさではありませんでした。この場合、 この関数はバッファーを使用せず、この値を正常に抽出するために必要な バッファー・サイズで value_length パラメーターを更新します。 少なくとも、戻された value_length と同じ大きさのバッファーを使用して抽出を再試行します。

注:
抽出される変数が HTTP ヘッダー用である場合、 要求に同じ名前の複数のヘッダーが含まれていても、HTTPD_extract() 関数は 最初に一致するオカレンスのみを抽出します。 httpd_getvar() 関数を HTTPD_extract() の代わりに使用することができます。 httpd_getvar() 関数を使用した場合、その他の利点もあります。 詳しくは、httpd_getvar() 関数に関するセクションを参照してください。
HTTPD_file()
この要求を満たすために、ファイルを送信します。 PreExit、Service、 Error、PostAuthorization、および Transmogrifier ステップでのみ有効です。

void  HTTPD_LINKAGE  HTTPD_file (
         unsigned char *handle,          /* i; handle */
         unsigned char *name,            /* i; name of file to send */
         unsigned long *name_length,     /* i; length of the name */
         long *return_code               /* o; return code */
         )
httpd_getvar()
HTTPD_extract() と同じですが、引数の長さを指定する必要がないので、簡単に使用できます。

const  unsigned char *          /* o; value of variable */
HTTPD_LINKAGE
httpd_getvar(
   unsigned char *handle,       /* i; handle */
   unsigned char *name,         /* i; variable name */
   unsigned long *n             /* i; index number for the array 
                                      containing the header */
   )

ヘッダーが入っている配列の指標は 0 から始まります。配列で最初の項目を得るには、n に値 0 を使用します。5 番目の項目を得るには、n には値 4 を使用します。

注:
戻り値の内容を廃棄したり変更したりしないでください。戻されたストリングは、ヌル文字で終了しています。
HTTPD_log_access()
サーバーのアクセス・ログにストリング を書き込みます。

void  HTTPD_LINKAGE  HTTPD_log_access (
         unsigned char *handle,           /* i; handle */
         unsigned char *value,            /* i; data to write */
         unsigned long *value_length,     /* i; length of the data */
         long *return_code                /* o; return code */
         )  

サーバー・アクセス・ログにパーセント記号 (%) を書き込むときに、 エスケープ記号は必要がない ことに注意してください。

HTTPD_log_error()
サーバーのエラー・ログにストリングを書き込みます。

void  HTTPD_LINKAGE  HTTPD_log_error (
         unsigned char *handle,          /* i; handle */
         unsigned char *value,           /* i; data to write */
         unsigned long *value_length,    /* i; length of the data */
         long *return_code               /* o; return code */
         )

サーバー・エラー・ログにパーセント記号 (%) を書き込むときに、 エスケープ記号は必要がない ことに注意してください。

HTTPD_log_event()
サーバーのイベント・ログにストリングを書き込みます。

void  HTTPD_LINKAGE  HTTPD_log_event (
         unsigned char *handle,          /* i; handle */
         unsigned char *value,           /* i; data to write */
         unsigned long *value_length,    /* i; length of the data */
         long *return_code               /* o; return code */
         )

サーバー・イベント・ログにパーセント記号 (%) を書き込むときに、 エスケープ記号は必要がない ことに注意してください。

HTTPD_log_trace()
サーバーのトレース・ログにストリングを書き込みます。

void  HTTPD_LINKAGE  HTTPD_log_trace (
         unsigned char *handle,          /* i; handle */
         unsigned char *value,           /* i; data to write */
         unsigned long *value_length,    /* i; length of the data */
         long *return_code               /* o; return code */
         )

サーバー・トレース・ログにパーセント記号 (%) を書き込むときに、 エスケープ記号は必要がない ことに注意してください。

HTTPD_open()
(Transmogrifier ステップでのみ有効です。) ストリーム・スタック内の次のルーチンに制御権を移動します。 必要なヘッダーを設定して、write ルーチンを開始する準備ができたら、 Transmogrifier の open、write、close のいずれかの関数からこれを呼び出してください。

void  HTTPD_LINKAGE  HTTPD_open (
         unsigned char *handle,      /* i; handle */
         long *return_code                /* o; return code */
         )	
HTTPD_proxy()
プロキシー要求を行います。PreExit、Service、および PostAuthorization ステップでのみ有効です。
注:
これは完了関数です。 要求は、この関数の後に完了します。

void  HTTPD_LINKAGE  HTTPD_proxy (
         unsigned char *handle,        /* i; handle */
         unsigned char *url_name,      /* i; URL for the   
                                             proxy request */
         unsigned long *name_length,   /* i; length of URL */
         void *request_body,           /* i; body of request */
         unsigned long *body_length,   /* i; length of body */
         long *return_code             /* o; return code */
         ) 
HTTPD_read()
クライアントの要求の本体を読み取ります。ヘッダーの読み取りには HTTPD_extract() を 使用してください。PreExit、Authorization、 PostAuthorization、および Service ステップでのみ有効であり、PUT または POST 要求が実行された場合にだけ使用できます。この関数は、HTTPD_EOF が戻されるまでループの中で呼び出してください。 この要求に本体がない場合、この関数は失敗します。

void  HTTPD_LINKAGE  HTTPD_read (
         unsigned char *handle,          /* i; handle */
         unsigned char *value,           /* i; buffer for data */
         unsigned long *value_length,    /* i/o; buffer size 
                                                 (data length) */
         long *return_code               /* o; return code */
         )
HTTPD_restart()
すべてのアクティブ状態の要求を処理した後で、サーバーを再始動します。 Server Initialization、 Server Termination、および Transmogrifier を除くすべてのステップで有効です。

void  HTTPD_LINKAGE  HTTPD_restart ( 
         long *return_code    /* o; return code */
         )
HTTPD_set()
この要求に関連する変数の値を設定します。name パラメーターで 有効な変数は、CGI で使用されるものと同じです。 詳しくは、変数を参照してください。

この関数で変数を作成することもできますので注意してください。作成する変数 は、変数に説明されている HTTP_ 接頭部および PROXY_ 接頭部の規則に準拠 する必要があります。HTTP_ で始まる変数を作成した場合、この変数は、接頭部 HTTP_ なしで、 クライアントへの応答でヘッダーとして送信されます。 例えば、Location ヘッダーを設定するには、変数名 HTTP_LOCATION で HTTPD_set() を使用します。 接頭部 PROXY_ を付けて作成した変数は、コンテンツ・サーバーへの要求でヘッダーとして送信されます。 接頭部 CGI_ を付けて作成した変数は CGI プログラムに渡されます。

この関数はすべてのステップで有効です。 ただし、すべての変数がすべてのステップで有効であるとは限りません。

void  HTTPD_LINKAGE  HTTPD_set (
         unsigned char *handle,        /* i; handle */
         unsigned char *name,          /* i; name of value to set */
         unsigned long *name_length,   /* i; length of the name */
         unsigned char *value,         /* i; buffer with value */
         unsigned long *value_length,  /* i; length of value */
         long *return_code             /* o; return code */
         ) 
注:
httpd_setvar() 関数を使用して、バッファーおよび長さを指定せずに変数値を 設定することができます。 詳しくは、httpd_setvar() 関数に関するセクションを参照してください。
httpd_setvar()
HTTPD_set() と同じですが、引数の長さを指定する必要がないので、簡単に使用できます。

long             /* o; return code */
HTTPD_LINKAGE   httpd_setvar (
       unsigned char *handle,       /* i; handle */
       unsigned char *name,         /* i; variable name */
       unsigned char *value,        /* i; new value */ 
       unsigned long *addHdr        /* i; add header or replace it */
       )
addHdr

パラメーターには、以下の 4 つの値を使用できます。

これらの値は HTAPI.h で定義されます。

httpd_variant_insert()
バリアントをキャッシュに挿入します。

void  HTTPD_LINKAGE  httpd_variant_insert (
         unsigned char *handle,    /* i; handle */
         unsigned char *URI,       /* i; URI of this object */
         unsigned char *dimension, /* i; dimension of variation */
         unsigned char *variant,   /* i; value of the variant */
         unsigned char *filename,  /* i; file containing the object */
         long *return_code         /* o; return code */
         )

注 :

  1. dimension 引数は、このオブジェクトが URI と異なる点となっているヘッダーを参照します。 例えば、上記の例で、dimension 値を User-Agent にすることができます。
  2. variant 引数は、dimension 引数で指定されたヘッダーの値を参照します。 これは URI とは異なります。例えば、上記の例で、variant 引数を次の値にすることができます。
    Mozilla 4.0 (compatible; BatBrowser 94.1.2; Bat OS)
  3. filename 引数は、ユーザーが変更済みコンテンツを保存したファイル名の ヌル終了コピーを指す必要があります。 ユーザーには、ファイルを除去する責任があります。 このアクションは、この関数から戻った後で行うのが安全です。 このファイルには、ヘッダーのない本体だけが入っています。
  4. バリアントをキャッシュする場合、サーバーはコンテンツ長ヘッダーを更新して、Warning: 214 (警告 : 214) ヘッダーを追加します。ストロング・エンティティー・タグは除去されます。
httpd_variant_lookup()
キャッシュ内の指定のバリアントの有無を判別します。

void  HTTPD_LINKAGE  httpd_variant_lookup (
    unsigned char *handle,             /* i; handle */
    unsigned char *URI,                /* URI of this object */
    unsigned char *dimension,          /* i; dimension of variation */
    unsigned char *variant,            /* i; value of the variant */
             long *return_code);       /* o; return code */      
HTTPD_write()
応答の本文を書き込みます。この関数は、PreExit、Service、Error、および Transmogrifier ステップで有効です。

初めてこの関数を呼び出す前にコンテンツ・タイプを設定しなかった場合、 サーバーは、CGI データ・ストリームが送信されるものと想定します。

void  HTTPD_LINKAGE  HTTPD_write (
    unsigned char *handle,             /* i; handle */
    unsigned char *value,              /* i; data to send */
    unsigned char *value_length,       /* i; length of the data */
             long *return_code);       /* o; return code */      
注:
応答ヘッダーを設定するには、HTTPD_set() 関数に関するセクションを参照してください。
注:
HTTPD_* 関数が戻った後で、それと一緒に渡したメモリーを解放しておくと安全です。

事前定義関数およびマクロからの戻りコード

サーバーは、戻りコード・パラメーターを、 要求の成功に応じて次のいずれかの値に設定します。

表 3. 戻りコード
状況コード 説明
-1 HTTPD_UNSUPPORTED この関数はサポートされていません。
0 HTTPD_SUCCESS この関数は正常に実行され、出力フィールドが有効です。
1 HTTPD_FAILURE 関数は失敗しました。
2 HTTPD_INTERNAL_ERROR 内部エラーを検出し、 この要求の処理を続行できません。
3 HTTPD_PARAMETER_ERROR 1 つ以上の無効なパラメーターが渡されました。
4 HTTPD_STATE_CHECK この関数はこのプロセス・ステップでは無効です。
5 HTTPD_READ_ONLY (これを戻すのは HTTPD_set と httpd_setvar だけです。) 変数は読み取り専用であり、プラグインによって設定できません。
6 HTTPD_BUFFER_TOO_SMALL (これを戻すのは HTTPD_set、 httpd_setvar、および HTTPD_read だけです。)指定のバッファーが小さすぎます。
7 HTTPD_AUTHENTICATE_FAILED (これを戻すのは HTTPD_authenticate だけです。) 認証は失敗しました。 詳細については、HTTP_RESPONSE および HTTP_REASON 変数を調べてください。
8 HTTPD_EOF (これを戻すのは HTTPD_read だけです。) 要求本文の終わりを示します。
9 HTTPD_ABORT_REQUEST クライアントが要求が指定する条件と一致しないエンティティー・タグを指定したために、 要求は打ち切られました。
10 HTTPD_REQUEST_SERVICED (これを戻すのは HTTPD_proxy だけです。) 呼び出した関数は この要求の応答を完了しました。
11 HTTPD_RESPONSE_ALREADY_COMPLETED その要求の応答は既に完了しているので、 この関数は失敗しました。
12 HTTPD_WRITE_ONLY 変数は書き込み専用であり、プラグインによって読み取ることはできません。

API ステップ用の Caching Proxy 構成ディレクティブ

要求プロセスの各ステップ にはそれぞれ 1 つの構成ディレクティブがあり、それを使用して、そのステップ中に呼び出して実行するプラグイン関数を 指示することができます。 サーバーの構成ファイル (ibmproxy.conf) を手動で編集して更新するか、 または、Caching Proxy の「構成および管理」の各種フォームの中の「API 要求処理」フォームを使用 して、これらのディレクティブを構成ファイルに追加できます。

API 使用上の注意

API ディレクティブおよび構文

これらの構成ファイル・ディレクティブは、ここに明確に指定されたものを除いてスペースを入れずに、ibmproxy.conf ファイル中に 1 行で記述しなければなりません。構文例の一部では 読みやすさのために改行していますが、実際のディレクティブではそこにスペースを入れないでください。

表 4. Caching Proxy プラグイン API ディレクティブ
ServerInit /path/file:function_name init_string
PreExit /path/file:function_name
Authentication type /path/file:function_name
NameTrans /URL /path/file:function_name
Authorization /URL /path/file:function_name
ObjectType /URL /path/file:function_name
PostAuth /path/file:function_name
Service /URL /path/file:function_name
Midnight /path/file:function_name
Transmogrifier /path/file:open_function_name: write_function_name: close_function_name:error_function
Log /URL /path/file:function_name
Error /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

API ディレクティブ変数

これらのディレクティブの変数には、以下の意味があります。

type
プラグイン関数が呼び出されるかどうかを指定するために Authentication ディレクティブでのみ 使用されます。 有効な値は次のとおりです。
URL
プラグイン関数が呼び出される要求を指定します。 このテンプレートに一致する URL を持つ要求によって、プラグイン関数が使用されます。 これらのディレクティブの URL 指定は、仮想 (プロトコルを組み込んでいない) ですが、前にスラッシュ (/) が付いています。例えば、 /www.ics.raleigh.ibm.com は正しい形ですが、http://www.ics.raleigh.ibm.com は正しくありません。この値は、特定の URL またはテンプレートとして指定することができます。
path/file
コンパイル済みプログラムの完全修飾ファイル名。
function_name
プログラム内でプラグイン関数に指定した名前。

パス情報にアクセスする場合、Service ディレクティブには、関数名の後に アスタリスク (*) が必要です。

init_string
ServerInit ディレクティブのこのオプション部分には、プラグイン関数に渡したい テキストを入れることができます。 httpd_getvar() を使用して INIT_STRING 変数からテキストを抽出します。

構文など、これらのディレクティブに関する追加情報については、 「WebSphere Application Server Caching Proxy 管理ガイド 」を参照してください。