前へ     目次     索引     DocHome     次へ     
iPlanet Web Server, Enterprise Edition NSAPI プログラマーズガイド



第 4 章   カスタム SAF の作成


この章では、カスタムサーバアプリケーション関数 (Server Application Functions: SAF) を定義するユーザ独自の NSAPI プラグインを作成する方法について説明します。プラグインを作成すると、iPlanet Web Server に組み込まれている機能を変更したり拡張したりできます。たとえば、ユーザの承認を特別な方法で処理するように、またはデータベースの情報に基づいて動的な HTML ページを生成するように、サーバを変更できます。

この章には、次の節があります。

カスタム SAF を作成する前に、第 1 章「サーバの動作の基本」に説明されている要求処理プロセスについて理解しておく必要があります。また、カスタム SAF を作成する前に、作成しようとしているカスタム SAF の機能と同じ機能が、すでに組み込まれている SAF にないかを確認します。

事前定義済みの Init SAF の一覧は、第 7 章「magnus.conf の構文と使用法」を参照してください。Init SAF 以外の事前定義済みの SAF の一覧は、第 3 章「事前定義済みの SAF および要求処理プロセス」を参照してください。

カスタム SAF を実現するための NSAPI ルーチンの完全な一覧は、第 5 章「NSAPI 関数のリファレンス」を参照してください。



SAF インタフェース


すべての (カスタムおよび組み込みの) SAF のインタフェースは、対応する要求処理ステップには関係なく、同じ C のインタフェースになります。SAF は、特定の要求 - 応答ステップ内での特定の目的のために設計された小さな関数です。SAF は、obj.conf ファイルで SAF を呼び出す指令から、サーバから、および前の SAF からパラメータを受け取ります。

次に SAF の C インタフェースを示します。

int function(pblock *pb, Session *sn, Request *rq);

次の節では、パラメータについて詳しく説明します。

SAF は、成功したかどうか、またどのように成功したかを示す結果コードを返します。サーバは、要求の処理をどのように進めるべきかを判断するために、各関数からの結果コードを使います。結果コードの詳細は、「結果コード」を参照してください。



SAF パラメータ


この節では、SAF のパラメータについて詳しく説明します。SAF のパラメータを次に示します。

  • pb (parameter block)- obj.conf ファイルに含まれている、SAF を呼び出す指令からのパラメータが入っている

  • sn (session)- 1 つの TCP/IP セッションに関連する情報が入っている

  • rq (request)- 現在の要求に関連する情報が入っている


pb (parameter block)

pb パラメータは、SAF を呼び出す指令が指定する値が含まれている pblock データ構造体へのポインタです。pblock データ構造体には、一連の名前-値ペアが含まれています。

たとえば、basic-nsca 関数を呼び出す指令は次のようになります。

AuthTrans fn=basic-ncsa auth-type=basic dbm=/netscape/server4/userdb/rs

この場合、basic-ncsa に渡される pb パラメータには、auth-type=basic および dbm=/netscape/server4/userdb/rs に対応する名前-値ペアが含まれています。

NSAPI には、pblock データ構造体と共に作用するための一式の関数があります。たとえば、pblock_findval() は、pblock で指定された名前に対する値を返します。パラメータブロックと共に作用する最もよく使われる関数についての概要は、「パラメータブロック操作ルーチン」を参照してください。


sn (session)

sn パラメータは、Session データ構造体へのポインタです。このパラメータには、1 つのセッションの間 (つまり、クライアントとサーバ間の TCP/IP 接続が開始されてから終了するまでの間) に関係する変数が含まれています。1 つのセッションの間、各要求内で呼び出される各 SAF には、同じ sn ポインタが渡されます。次に、このデータ構造体の最も重要なフィールドについて説明します。

Session データ構造体を操作するための NSAPI ルーチンについては、第 5 章「NSAPI 関数のリファレンス」を参照してください。

  • sn->client

    クライアントの IP アドレス、DNS 名、または証明書などのクライアントについての情報が含まれている pblock へのポインタ。クライアントに DNS 名がないか、またはその DNS 名が見つからない場合は、-none に設定される

  • sn->csd

    プラットフォームに依存しないクライアントソケット記述子。クライアントからの読み込みやクライアントへの書き込みのために、ルーチンにこの記述子を渡す


rq (request)

rq パラメータは、request データ構造体へのポインタです。このパラメータには、要求ヘッダー、URI、ローカルファイルシステムのパスなど現在の要求に関連する変数が含まれています。1 つの HTTP 要求の要求 - 応答プロセスでは、呼び出される各 SAF には、同じ request ポインタが渡されます。

次に、このデータ構造体の最も重要なフィールドについて説明します (Request データ構造体を操作するための NSAPI ルーチンについては、第 5 章「NSAPI 関数のリファレンス」を参照してください)。

  • rq->vars

    サーバの「作業用」変数が入っている pblock へのポインタ。このフィールドには、次の 3 つの pblock に明示的に示されていないものが入る。この pblock の内容は、特定の要求と SAF のタイプによって変わる。たとえば、AuthTrans SAF がauth-user パラメータを rq->vars に挿入し、次の PathCheck SAF でこのパラメータを使うことができる

  • rq->reqpb

    HTTP 要求の要素が含まれている pblock へのポインタ。これには、HTTP のメソッド (GET、POST など)、URI、プロトコル (通常、HTTP/1.0)、照会文字列などがある。この pblock は、通常、要求 - 応答プロセスの間変化しない

  • rq->headers

    クライアントからの HTTP 要求で受け取ったすべての要求ヘッダー (User-Agent、If-Modified-Since など) が含まれている pblock へのポインタ。要求ヘッダーについては、付録 E「HTTP (HyperText Transfer Protocol)」を参照。この pblock は、通常、要求 - 応答プロセスの間変化しない

  • rq->srvhdrs

    クライアントへ HTTP 応答で送信される応答ヘッダー (Server、Date、Content-type、Content-length など) が含まれている pblock へのポインタ。応答ヘッダーについては、付録 E「HTTP (HyperText Transfer Protocol)」を参照

rq パラメータは、要求 - 応答プロセスで、情報の受け渡しをするための主要なメカニズムです。SAF への入力時には、rq には、前に実行された SAF によって挿入または変更された値がすべて含まれています。出力時には、rq には、その SAF が挿入した変更や追加情報が含まれています。一部の SAF は、プロセスの前のほうのステップによって提供される特定の情報の存在に依存します。たとえば、PathCheck SAF は、AuthTrans SAF によって前に挿入された rq->vars の値を取り出します。



結果コード


処理が完了すると、SAF は結果コードを返します。結果コードは、サーバが次に実行すべきことを示します。結果コードを次に示します。

  • REQ_PROCEED

    SAF が目的を達成したことを示す。これは、一部の要求 - 応答ステップ (AuthTrans、NameTrans、Service、および Error) の場合、現在のステップのほかの SAF をスキップして、次の要求 - 応答ステップに進むようにサーバに指示する。ほかの要求 - 応答ステップ (PathCheck、ObjectType、および AddLog) の場合は、サーバは現在のステップの次の SAF に進む

  • REQ_NOACTION

    SAF が何も実行しなかったことを示す。サーバは、サーバの現在のステップの次の SAF から処理を続ける

  • REQ_ABORTED

    エラーが発生し、エラーの原因を示すためにクライアントへ HTTP 応答を送信する必要があることを示す。REQ_ABORTED を返す SAF は、HTTP 応答状態コードも設定する必要がある。サーバが状態コードまたは説明句に一致する Error 指令を見つけた場合は、指定された SAF を実行する。そうでない場合は、サーバは状態コードと説明句から構成されるデフォルトの HTTP 応答、それにユーザのために状態コードと説明句を反映する短い HTML ページを送信する。次に、サーバは、最初の AddLog 指令に進む

  • REQ_EXIT

    クライアントへの接続が失われたことを示す。これは、SAF がクライアントからの読み込みまたはクライアントへの書き込みに失敗すると、返される。次に、サーバは、最初の AddLog 指令に進む



カスタム SAF の作成と使用

カスタム SAF は、サーバによって読み込まれ呼び出される、共用ライブラリ内の関数です。次のステップに従って、カスタム SAF を作成します。

  1. ソースコードを記述する

    NSAPI 関数を使って、ソースコードを記述します。各 SAF は、特定の指令用に作成されます。

  2. コンパイルしリンクする

    ソースコードをコンパイルしリンクして、共用ライブラリ (.so、.sl、 または .dll) ファイルを作成します。

  3. SAF を読み込んで初期化する

    次の目的のために、obj.conf ファイルを編集して、SAF を読み込み初期化します。

    - カスタム SAF が含まれている共用ライブラリファイルを読み込む

    - 必要な場合は SAF を初期化する

  4. サーバに SAF を呼び出すように指示する

    obj.conf を編集して、適切なときにカスタム SAF を呼び出すようにサーバに指示します。

  5. サーバを再構成する

  6. SAF をテストする

    カスタム関数をトリガーする URL でブラウザからサーバにアクセスして、SAF をテストします。

以下の節では、これらのステップについてより詳しく説明します。


ソースコードを記述する

NSAPI 関数を使ってカスタム SAF を作成します。最もよく使われる一部の NSAPI 関数についての要約は、「NSAPI C 関数の概要」の節を参照してください。第 5 章「NSAPI 関数のリファレンス」には、使用できるすべてのルーチンについての情報があります。

カスタム SAF の例については、サーバルートディレクトリのnsapi/examples/、および第 6 章「カスタム SAF の例」を参照してください。

すべての SAF の署名を次に示します。

int function(pblock *pb, Session *sn, Request *rq);

パラメータの詳細は、「SAF パラメータ」の節を参照してください。

iPlanet Web Server は、マルチスレッド化された単一プロセスとして実行されます。UNIX プラットフォームでは、歴史的な理由から実際には 2 つのプロセス (親と子) が存在します。親プロセスは、初期化を一部実行し、子プロセスをフォークします。子プロセスは、さらに初期化を実行し、すべての HTTP 要求を処理します。

SAF を作成するときには、これらのことを念頭においてください。スレッド安全なコードを記述します。ブロック化は、パフォーマンスに影響を及ぼすことがあります。パラメータ付きの小さな関数を作成し、作成した関数を obj.conf に構成します。慎重にすべてのエラーを調べ、対処します。また、問題の原因を調べ修正できるように、エラーをログに記録します。

必要な場合は、新しい SAF が必要とする初期化タスクを実行する初期化関数を作成します。初期化関数の署名は、その他の SAF の署名と同じです。

int function(pblock *pb, Session *sn, Request *rq);

SAF は、パラメータから特定の種類の情報を入手できることを期待します。ほとんどの場合、パラメータブロック (pblock) データ構造体が、これらのパラメータの基本的な記憶メカニズムとなります。pblock には、データが名前-値ペアの集合として保持されます。pblock 構造体と共に作用するために最もよく使われる関数についての要約は、「パラメータブロック操作ルーチン」を参照してください。

SAF を定義するときには、その SAF がどの指令用に作成されているかを特に示す必要はありません。ただし、各 SAF は、特定の指令 (AuthTrans、Service など) 用に作成する必要があります。各指令は、関連する SAF が特定のことを実行することを期待し、対応する指令の期待に従うようにカスタム SAF を作成する必要があります。各指令がその SAF に期待することについての詳細は、「各指令用の SAF に要求される動作」を参照してください。


コンパイルしリンクする

ターゲットプラットフォームのネイティブコンパイラでコードをコンパイルし、リンクします。UNIX の場合は、gmake コマンドを使います。Windows NT の場合は、nmake コマンドを使います。Windows NT の場合は、Microsoft Visual C++ 6.0 以降を使います。サーバのバイナリからアクセスするためのすべてのグローバル変数および関数を指定するインポートリストを持っている必要があります。使用しているプラットフォームに適切なコンパイラおよびリンカーのフラグを使います。server_root/plugins/nsapi/examples ディレクトリにある Makefile の例を参照してください。

コンパイルおよびリンクについては、次のガイドラインに従います。


include ディレクトリと nsapi.h ファイル

server_root/plugins/include (UNIX) ディレクトリ、または server_root\plugins\include (Windows NT) ディレクトリを Makefile に追加して、nsapi.h ファイルを組み込みます。


ライブラリ

リンカーコマンドにライブラリディレクトリの server_root/bin/https/lib (UNIX)、または server_root\bin\https\bin (Windows NT) を追加します。

表 4-1 には、リンクする必要のあるライブラリを示します。


表 4-1 ライブラリ 

プラットフォーム

ライブラリ

Windows NT  

ns-httpd40.dll (標準の Windows ライブラリに加えて)  

HPUX  

libns-httpd40.sl  

その他のすべての UNIX のプラットフォーム  

libns-httpd40.so  


共用オブジェクトの生成のためのリンカーのコマンドとオプション

共用ライブラリを生成するには、表 4-2 に示すコマンドやオプションを使います。


表 4-2 リンカーのコマンドおよびオプション

プラットフォーム

オプション

Solaris Sparc  

ld -G または cc -G  

Windows NT  

link -LD  

HPUX  

cc +Z -b -Wl,+s -Wl,-B,symbolic  

AIX  

cc -p 0 -berok -blibpath:$(LD_RPATH)  

Compaq  

cc -shared  

Linux  

gcc -shared  

IRIX  

cc -shared  


その他のリンカーフラグ

表 4-3 に示すリンカーフラグを使って、実行時にシンボルを解決するためにどのディレクトリで共用オブジェクトを検索するかを指定します。


表 4-3 リンカーフラグ

プラットフォーム

フラグ

Solaris Sparc  

-R dir:dir  

Windows NT  

(フラグではなく、システム PATH 変数に ns-httpd40.dll ファイルを指定する必要がある)  

HPUX  

-Wl,+b,dir,dir  

AIX  

-blibpath:dir:dir  

Compaq  

-rpath dir:dir  

Linux  

-Wl,-rpath,dir:dir  

IRIX  

-Wl,-rpath,dir:dir  

UNIX では、ライブラリの検索パスを、サーバを起動するときに設定する必要がある LD_LIBRARY_PATH 環境変数を使って設定することもできます。


コンパイラフラグ

表 4-4 には、ソースコードのコンパイルに使う必要のあるフラグと Defines 定義を示します。


表 4-4 コンパイラのフラグと Defines 定義

プラットフォーム

フラグ/Defines

Solaris Sparc  

-DXP_UNIX -D_REENTRANT -KPIC -DSOLARIS  

Windows NT  

-DXP_WIN32 -DWIN32 /MD  

HP-UX  

-DXP_UNIX -D_REENTRANT -DHPUX  

AIX  

-DXP_UNIX -D_REENTRANT -DAIX $(DEBUG)  

Compaq  

-DXP_UNIX -KPIC  

Linux  

-DLINUX -D_REENTRANT -fPIC  

IRIX  

-o32 -exceptions -DXP_UNIX -KPIC  

すべてのプラットフォーム  

-MCC_HTTPD -NET_SSL  

表 4-5 には、使用できる任意 (省略可能) のフラグと Defines 定義を示します。


表 4-5 フラグおよび Defines 定義 (省略可能)

フラグ/Defines 定義

プラットフォーム

説明

-DSPAPI20  

すべて  

プロキシユーティリティ関数の include ファイルの putil.h に必要  


AIX での 3.x プラグインのコンパイル

AIX の場合のみ、サーバの 3.x バージョン用にビルドされたプラグインは、4.x および 6.x バージョンと動作させるために再リンクする必要があります。server_root/plugins/nsapi/examples/ ディレクトリにあるファイルで必要なものを次に示します。

  • Makefile ファイルには、古い -bM:SRE -berok -brtl -bnoentry オプションの代わりに -G オプションが含まれています。

  • relink_36plugin スクリプトは、サーバの 3.x バージョン用にビルドされたプラグインを変更して、4.x および 6.x バージョンで動作するようにします。このスクリプトのコメントが、その用途を示しています。

iPlanet Web Server 4.x および 6.x バージョンは、実行時リンクをネイティブにサポートする AIX 4.2 にビルドされています。このため、ns-httpd 主実行可能ファイル内のシンボルを参照する NSAPI プラグインは、シンボルを実行時に解決するように指定する、-G オプションを使ってビルドする必要があります。

ただし、旧バージョンの Netscape Enterprise Server は、ネイティブ実行時リンクをサポートしない AIX 4.1 にビルドされていました。Enterprise Server には、プラグインを可能にするために特別な補足ソフトウェア (IBM AIX 開発部門から Netscape に提供された) がありました。プラグインをビルドするために、特別な実行時リンク指令は必要ありませんでした。このため、AIX で旧バージョンのサーバ用にビルドされたプラグインは、iPlanet Web Server 4.x および 6.x バージョンと共には、同じように機能しません。

ただし、それらのプラグインを iPlanet Web Server 4.x および 6.x バージョンで機能するように簡単に再リンクすることができます。relink_36plugin スクリプトは、既存のプラグインを再リンクします。このスクリプトには、既存のプラグインだけが必要です。元のソースファイルや .o ファイルは必要ありません。より具体的なコメントは、スクリプト内に記述されています。4.2 以降のすべてのバージョンの AIX は実行時リンクをネイティブにサポートするので、バージョン 4.x 以降の iPlanet Web Server 用のプラグインは再リンクする必要はありません。


SAF を読み込んで初期化する

iPlanet Web Server に読み込まれるカスタム SAF が含まれている各共用ライブラリ (プラグイン) に対して、load-modules SAF を呼び出す Init 指令を 1 つ magnus.conf に追加します。

load-modules を呼び出す指令の構文を次に示します。

Init fn=load-modules shlib=[path]sharedlibname funcs="SAF1,...,SAFn"

  • shlib は、共用ライブラリ (プラグイン) へのローカルファイルシステムのパスである

  • funcs は、共用ライブラリから読み込まれる、コンマで区切られた関数のリストである。関数名では、大文字、小文字が区別される。関数名では、下線 (_) の代わりにダッシュ (-) を使うことができる。関数名リストには、空白文字を入れてはならない

    新しい SAF を初期化する必要がある場合は、初期化関数を funcs リストに入れるようにする。

たとえば、2 つの SAF do_small_anim() と do_big_anim() を定義し、また初期化関数の init_my_animations() を定義する共用ライブラリの animations.so を作成した場合は、次の指令を追加してこのプラグインを読み込みます。

Init fn=load-modules shlib=animations.so funcs="do_small_anim,do_big_anim,init_my_animations"

必要な場合は、新たに読み込まれたプラグインのために初期化関数を呼び出す Init 指令も追加します。たとえば、maxAnimLoop パラメータの操作を実行する関数 init_my_new_SAF() を定義した場合は、次のような指令を magnus.conf に追加します。

Init fn=init_my_new_SAF maxAnimLoop=5


サーバに SAF を呼び出すように指示する

次に、指令を obj.conf に追加して、適切なときに各カスタム SAF を呼び出すようにサーバに指示します。この指令の構文を次に示します。

Directive fn=function-name [name1="value1"]...[nameN="valueN"]

  • Directive は、AuthTrans、Service、などのサーバの指令のいずれかである

  • function-name は、実行する SAF の名前である

  • nameN="valueN" は、SAF に渡されるパラメータの名前と値である

新しい SAF が実行する内容によって、1 つだけ指令を obj.conf に追加すればよい場合と、新しい SAF を呼び出すのに必要な指示をすべて含んだ、複数の指令を追加する必要がある場合があります。

たとえば、新しい AuthTrans または PathCheck SAF を定義する場合は、デフォルトのオブジェクトに適切な指令を追加するだけですみます。しかし、要求されたリソースが特定のディレクトリにあるか、またはリソースのファイル拡張子の種類が新しいときにだけ新しい Service SAF を呼び出すように定義する場合は、さらに必要なステップがあります。

要求されたリソースのファイル拡張子が新しい種類の場合にだけ新しい Service SAF を呼び出す場合は、ObjectType 段階で type の値が適切に設定されるように MIME タイプファイルにエントリを追加する必要がある場合があります。そのようにすると、Service 指令を、必要な type 値を指定するデフォルトのオブジェクトに追加できます。

要求されたリソースが特定のディレクトリにある場合にだけ新しい Service SAF を呼び出す場合は、別のオブジェクトに一致する name または ppath 値を生成する NameTrans 指令を定義する必要がある場合があり、そのようにすると新しいオブジェクトで新しい Service 関数を呼び出すことができます。

たとえば、ユーザのプラグインが、パラメータとして speed が指定される 2 つの新しい SAF do_small_anim() と do_big_anim() を定義するとします。これらの関数は、アニメーションを実行します。小さなアニメーションとして扱われるファイルはすべて、ディレクトリ D:/Netscape/server4/docs/animations/small にあり、フルスクリーンアニメーションとして扱われるファイルはすべて、ディレクトリ D:/Netscape/server4/docs/animations/fullscreen にあります。

クライアントが小さなまたはフルスクリーンのアニメーションのどちらかに対する要求を送信するたびに新しいアニメーション関数が呼び出されるようにするには、NameTrans 指令をデフォルトのオブジェクトに追加して適切な URL を対応するパス名に変換し、また要求に名前を割り当てます。

NameTrans fn=pfx2dir from="/animations/small" dir="D:/Netscape/server4/docs/animations/small" name="small_anim"
NameTrans fn=pfx2dir from="/animations/fullscreen" dir="D:/Netscape/server4/docs/animations/fullscreen" name="fullscreen_anim"

また、アニメーションを実行し、speed パラメータを指定する Service 指令が含まれているオブジェクトを定義する必要があります。

<Object name="small_anim">
Service fn=do_small_anim speed=40
</Object>
<Object name="fullscreen_anim">
Service fn=do_big_anim speed=20
</Object>


サーバを再構成する

obj.conf の変更後、サーバを再構成する必要があります。詳細は、動的再構成を参照してください。


SAF をテストする

カスタム関数をトリガーする URL でブラウザからサーバにアクセスして、SAF をテストします。たとえば、http://server-name/animations/small にあるリソースへの要求によって新しい SAF がトリガーされる場合は、その URI で始まる有効なリソースの要求を試みます。

サーバが確実にアクセスされるように、ブラウザのキャッシュ機能を無効にする必要があります。Navigator では、シフトキーを押しながら「再読み込み (Reload)」ボタンをクリックして、キャッシュが使われないようにします。(シフト-再読み込み方法では、イメージがすでにキャッシュにある場合は、クライアントがソースから常にイメージを取得するようになるとは限らないことに注意してください。)

cache-init SAF を使ってサーバのキャッシュを無効にすることもできます。

アクセスログとエラーログを調べると、デバッグに役立ちます。



NSAPI C 関数の概要


NSAPI には、SAF を実現するために使う一式の C 言語の関数があります。それらの C の関数には、いくつかの用途があります。また、iPlanet Server のオペレーティングシステムやハードウェアプラットフォームに依存しない、プラットフォームの独立を可能にします。さらに、パフォーマンスも向上させます。それらの C の関数は、スレッド安全であり、これは SAF の必要条件です。また、メモリーリークを防止します。SAF の実現に必要な機能も提供します。新しい SAF を定義するときには、必ずこれらの NSAPI ルーチンを使う必要があります。

この節では、使用できる関数のカテゴリとよく使われるルーチンの一部の概要を示します。すべての公開ルーチンの詳細は、第 5 章「NSAPI 関数のリファレンス」を参照してください。

NSAPI 関数の主なカテゴリを次に示します。


パラメータブロック操作ルーチン

pblock データ構造体内のエントリの検索、追加、および削除のために、パラメータブロック操作関数が提供するルーチンには、次のものがあります。

  • pblock_findval は、pblock に指定された名前の値を返す

  • pblock_nvinsert は、pblock に新しい名前-値エントリを追加する

  • pblock_remove は、pblock から pblock エントリを名前で削除する。エントリは廃棄されない。param_free を使って、エントリが使っていたメモリーを解放する

  • param_free は、指定された pblock エントリのメモリーを解放する

  • pblock_pblock2str は、"name=value name=value" の形式で pblock からすべての名前-値ペアが含まれる新しい文字列を作成する。これは、デバッグに役立つ関数である


Service SAF 用のプロトコルユーティリティ

プロトコルユーティリティは、Service SAF を実現するために必要な機能を提供します。

  • request_header は、必要に応じてヘッダーを読み、指定された要求ヘッダー名に対する値を返す。この関数は、ブラウザヘッダーの pblock からエントリを要求するときに使う必要がある (rq->headers)

  • protocol_status は、HTTP 応答状態コードと説明句を設定する

  • protocol_start_response は、HTTP 応答とすべての HTTP ヘッダーをブラウザに送信する


メモリーの管理

メモリー管理ルーチンは、標準メモリー管理ルーチンの、高速かつプラットフォームに依存しないバージョンです。また、各要求に一時的なメモリー (「プールされた」メモリーと呼ばれる) から割り当て、各要求の後にプール全体を廃棄することにより、メモリーのリークを防止します。メモリー管理ルーチンは、固定メモリーを使うための、標準のメモリールーチンのラッパーです。デバッグのために、プールされたメモリーを無効にする方法については、第 7 章「magnus.conf の構文と使用法」の組み込み SAF の pool-init を参照してください。


ファイル入出力

ファイル入出力関数は、プラットフォームに依存しない、スレッド安全なファイル入出力ルーチンを提供します。

  • system_fopenRO は、読み取り専用アクセスのためにファイルを開く

  • system_fopenRW は、読み込み - 書き込みアクセスのためにファイルを開き、必要な場合はファイルを作成する

  • system_fopenWA は、書き込み - 追加アクセスのためにファイルを開き、必要な場合はファイルを作成する

  • system_fclose は、ファイルを閉じる

  • system_fread は、ファイルから読み込む

  • system_fwrite は、ファイルへ書き込む

  • system_fwrite_atomic は、指定されたファイルに書き込む前に、そのファイルをロックする。このようにすると、複数のスレッドが同時に書き込むことによる干渉を防止できる


ネットワーク入出力

ネットワーク入出力関数は、プラットフォームに依存しない、スレッド安全なネットワーク入出力ルーチンを提供します。ネットワーク入出力ルーチンは、SSL (Secure Socket Layer) が有効な場合、SSL で動作します。

  • netbuf_grab は、ネットワークのバッファのソケットからネットワークのバッファに読み込む

  • netbuf_getc は、ネットワークのバッファから文字を取得する

  • net_write は、ネットワークのソケットへ書き込む


スレッド

スレッド関数には、サーバのスレッドと互換性のあるユーザ独自のスレッドを作成するための関数などがあります。クリティカルセクションおよび条件変数用のルーチンもあります。

  • systhread_start は、新しいスレッドを作成する

  • systhread_sleep は、指定された期間スレッドを休眠させる

  • crit_init は、新しいクリティカルセクション変数を作成する

  • crit_enter は、クリティカルセクションの所有権を得る

  • crit_exit は、クリティカルセクションの所有権を明け渡す

  • crit_terminate は、新しいクリティカルセクション変数を廃棄する

  • condvar_init は、新しい条件変数を作成する

  • condvar_notify は、条件変数でブロックされたスレッドを呼び起こす

  • condvar_wait は、条件変数でブロックする

  • condvar_terminate は、条件変数を廃棄する

  • prepare_nsapi_thread は、サーバによって作成されていないスレッドが、サーバにより作成されたスレッドのように動作することを可能にする


ユーティリティ

ユーティリティ関数には、多くの (文字列操作などの) 標準ライブラリ関数のプラットフォームに依存しない、スレッド安全なバージョンや、NSAPI に役立つ新しいユーティリティなどがあります。

  • daemon_atrestart (UNIX のみ) は、サーバに再起動シグナル (HUP) が送信されるときに、またはシャツトダウン時に、呼びされるユーザ関数を登録する

  • util_getline は、バッファから次の行 (LF または CRLF まで) を取得する

  • util_hostname は、絶対パスによるドメイン名としてローカルホスト名を取得する

  • util_later_than は、2 つの日付を比較する

  • util_sprintf は、標準のライブラリルーチンの sprintf() と同じである

  • util_strftime は、標準のライブラリルーチンの strftime() と同じである

  • util_uri_escape は、文字列中の特殊文字を URI エスケープ処理された形式に変換する

  • util_uri_unescape は、文字列中の URI エスケープ処理された文字を特殊文字に戻す


    注   NSAPI 関数は、null が文字列の終わりであるとみなすので、文字列中に null を埋め込むことはできません。したがって、NSAPI プラグインを介して Unicode でエンコードされた内容を渡してもうまくいきません。

     


仮想サーバ

仮想サーバ関数は、仮想サーバについての情報を取得するためのルーチンを提供します。

  • request_get_vs は、要求の送り先の仮想サーバを検索する

  • vs_alloc_slot は、特定の仮想サーバに固有のデータへのポインタを記憶するための新しいスロットを割り当てる

  • vs_get_data は、指定された仮想サーバとスロットのデータへのポインタの値を検索する

  • vs_get_default_httpd_object は、仮想サーバの仮想サーバクラス構成からデフォルト (またはルート) のオブジェクトへのポインタを取得する

  • vs_get_doc_root は、仮想サーバのドキュメントルートを検索する

  • vs_get_httpd_objset は、指定された仮想サーバの仮想サーバクラス構成へのポインタを取得する

  • vs_get_id は、仮想サーバの ID を検索する

  • vs_get_mime_type は、指定された URI のContent-type: ヘッダーに返される MIME タイプを判別する

  • vs_lookup_config_var は、指定された仮想サーバの構成変数の値を検索する

  • vs_register_cb は、仮想サーバの初期化イベントおよび破棄イベントの通知を受ける関数をプラグインが登録できるようにする

  • vs_set_data は、指定された仮想サーバおよびスロットのデータへのポインタの値を設定する

  • vs_translate_uri は、特定の仮想サーバに対する要求の一部であるかのように URI を変換する



各指令用の SAF に要求される動作

新しい SAF を作成するときには、その SAF が要求処理プロセスのどの段階で呼び出されるかに応じて、特定の動作をするように定義する必要があります。たとえば、Init 段階で呼び出す SAF は、Service 段階で呼び出す SAF とは異なる要件を満たす必要があります。

rq パラメータは、要求 - 応答プロセスで、情報の受け渡しをするための主要なメカニズムです。SAF への入力時には、rq には、前に実行された SAF によって挿入または変更された値がすべて含まれています。出力時には、rq には、SAF が挿入した変更や追加情報が含まれています。一部の SAF は、要求 - 応答プロセスの前の方のステップによって提供される特定の情報の存在に依存します。たとえば、PathCheck SAF は、前に AuthTrans SAF によって挿入された rq->vars の値を取り出します。

この節では、要求処理プロセスの各段階で使われる SAF に期待される動作の概要を示します。


Init SAF

  • 目的： 起動時に初期化する

  • サーバの起動時と再起動時に呼び出される

  • rq と sn は、NULL である

  • ファイルやグローバル変数などの共用リソースを初期化する

  • クリーンアップのために daemon_atrestart() でコールバック関数を登録できる

  • エラーが発生した場合は、error パラメータを pb に挿入してエラーを記述し、REQ_ABORTEDを返す

  • 成功した場合は、REQ_PROCEED を返す


AuthTrans SAF

  • 目的： 承認情報を検証する。現在、HTTP/1.0 仕様では基本承認だけが定義されている

  • rq->headers で、承認タイプと uu エンコードされたユーザおよびパスワード情報が含まれている Authorization ヘッダーを検査する。ヘッダーが送られてこなかった場合は、REQ_NOACTION を返す

  • ヘッダーが存在する場合は、ユーザとパスワードの正当性を確認する

  • 正当である場合は、PathCheck SAF が後で使用できるように、rq->vars に auth-type パラメータ、それに加えて auth-user または auth-group、あるいはその両方のパラメータを作成する

  • ユーザの承認に成功した場合は、REQ_PROCEED を返し、失敗した場合は REQ_NOACTION を返す


NameTrans SAF

  • 目的： 論理 URI を物理パスに変換する

  • 論理パス (rq->vars 内の ppath) に対して操作を実行して、論理パスをローカルファイルシステムの絶対パスに変換する

  • rq->vars 内の ppath にローカルファイルシステムの絶対パスが含まれている場合は、REQ_PROCEED を返し、そうでない場合は、REQ_NOACTION を返す

  • クライアントを別のサイトに転送するには、rq->vars 内の ppath を /URL に変更する。絶対パスによる URL (たとえば、http://home.netscape.com/) で url を rq->vars に追加する。REQ_PROCEED を返す


PathCheck SAF

  • 目的： パスの有効性とユーザのアクセス権を検査する

  • rq->vars 内の auth-type と、auth-user、および/または auth-group を検査する

  • ユーザ (またはグループ) がこの領域 (rq->vars 内の ppath) へのアクセスを許可されている場合は、REQ_PROCEED を返す

  • 許可されていない場合は、Basic; Realm=\"Our private area\" などの値で、 WWW-Authenticate を rq->srvhdrs に挿入する。HTTP 応答ステータスを PROTOCOL_UNAUTHORIZED に設定するために protocol_status() を呼び出す。REQ_ABORTED を返す


ObjectType SAF

  • 目的： データの内容のタイプを判別する

  • rq->srvhdrs 内の content-type がすでに存在する場合は、REQ_NOACTION を返す

  • MIME タイプを判別し、rq->srvhdrs に content-type を作成する

  • content-type が作成された場合は、REQ_PROCEED を返し、そうでない場合は REQ_NOACTION を返す


Service SAF

  • 目的： 応答を生成し、クライアントに送信する

  • Service SAF は、obj.conf の指令に指定されたオプションのパラメータの type、method、および query のそれぞれが要求に一致する場合にだけ呼び出される

  • rq->srvhdrs から既存の content-type を削除する。rq->srvhdrs に正しい content-type を挿入する

  • rq->srvhdrs にその他のヘッダーを作成する

  • HTTP 応答ステータスを設定するために protocol_status を呼び出す

  • HTTP 応答およびヘッダーを送信するために protocol_start_response を呼び出す

  • net_write を使ってデータを生成しクライアントへ送信する

  • 成功した場合は REQ_PROCEED を、書き込みエラーの場合は REQ_EXIT を、その他の失敗の場合は REQ_ABORTED を返す


Error SAF

  • 目的： HTTP ステータスエラー状態に対応する

  • Error SAF は、obj.conf の指令に指定されたオプションのパラメータの code と reason のそれぞれが現在のエラーに一致する場合にだけ呼び出される

  • Error SAF は、Service SAF と同じ動作をするが、HTTP ステータスエラー状態への対応としてのみそのように動作する


AddLog SAF

  • 目的： トランザクションをログファイルに記録する

  • AddLog SAF は、pb、sn、または rq で使用可能なデータを使ってこのトランザクションを記録できる

  • REQ_PROCEED を返す



CGI から NSAPI への変換

NSAPI を使って、CGI 変数を SAF に変換する必要がある場合があります。NSAPI には CGI 環境変数は利用できないので、それらの変数を NSAPI パラメータブロックから取得します。次の表に、各 CGI 環境変数を NSAPI で入手する方法を示します。

ユーザのコードは、NSAPI ではスレッド安全である必要があることを念頭においてください。スレッド安全な NSAPI 関数を使う必要があります。また、処理速度と、プラットフォームに依存しないために、NSAPI のメモリー管理およびその他のルーチンを使う必要があります。


表 4-6

CGI getenv()

NSAPI

AUTH_TYPE  

pblock_findval("auth-type", rq->vars);  

AUTH_USER  

pblock_findval("auth-user", rq->vars);  

CONTENT_LENGTH  

pblock_findval("content-length", rq->headers);  

CONTENT_TYPE  

pblock_findval("content-type", rq->headers);  

GATEWAY_INTERFACE  

"CGI/1.1"  

HTTP_*  

pblock_findval("*", rq->headers);
(* は小文字であり、ダッシュで下線を置き換える)  

PATH_INFO  

pblock_findval("path-info", rq->vars);  

PATH_TRANSLATED  

pblock_findval("path-translated", rq->vars);  

QUERY_STRING  

pblock_findval("query", rq->reqpb);
(GET のみ。POST は、照会文字列 (query string) を本体のデータに含める)  

REMOTE_ADDR  

pblock_findval("ip", sn->client);  

REMOTE_HOST  

session_dns(sn) ? session_dns(sn) : pblock_findval("ip", sn->client);  

REMOTE_IDENT  

pblock_findval("from", rq->headers);
(通常は使用できない)  

REMOTE_USER  

pblock_findval("auth-user", rq->vars);  

REQUEST_METHOD  

pblock_findval("method", req->reqpb);  

SCRIPT_NAME  

pblock_findval("uri", rq->reqpb);  

SERVER_NAME  

char *util_hostname();  

SERVER_PORT  

conf_getglobals()->Vport;
(文字列として)  

SERVER_PROTOCOL  

pblock_findval("protocol", rq->reqpb);  

SERVER_SOFTWARE  

MAGNUS_VERSION_STRING  

Netscape 固有:

CLIENT_CERT  

pblock_findval("auth-cert", rq->vars)  

HOST  

char *session_maxdns(sn);
( null である場合もある)  

HTTPS  

security_active ? "ON" : "OFF";  

HTTPS_KEYSIZE  

pblock_findval("keysize", sn->client);  

HTTPS_SECRETKEYSIZE  

pblock_findval("secret-keysize", sn->client);  

QUERY  

pblock_findval("query", rq->reqpb);
(GET のみ。POST は照会文字列 (query string) をエンティティ本体のデータに含める)  

SERVER_URL  

http_uri2url_dynamic("","", sn, rq);  


前へ     目次     索引     DocHome     次へ     
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.

Last Updated September 21, 2001