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



第 3 章   サーバによる HTML タグの構文解析


HTML ファイルには、サーバで実行されるタグを含めることができます。 iPlanet Web Server 6.0 は標準のサーバサイドのタグをサポートしていますが、さらにサーブレットを使用することで、ユーザ独自のサーバサイドのタグを定義することもできます。

この章では次の項目について説明します。

構文解析を有効にしたら、magnus.conf ファイルに次の指令が追加されていることを確認します (ネイティブスレッドがオフになっていることを確認してください)。

Init funcs="shtml_init,shtml_send" shlib="install_dir/bin/https/bin/Shtml.dll" NativeThreads="no" fn="load-modules"

iPlanet Web Server 6.0 に、 NativeThread="no" を設定する必要があります。 また、これらの関数は Shtml.dll (UNIX では libShtml.so) から作成されます。このファイルは Windows NT では install_dir/bin/https/bin に、UNIX では install_dir/bin/https/lib にあります。

また、次の指令が obj.conf ファイルに追加されていることも確認してください。

<Object name="default">
...
...
Service fn="shtml_send" type="magnus-internal/parsed-html" method="(GET|HEAD)"
...
</Object>



サーバサイドの HTML コマンドの使用方法


この節では、サーバが構文解析するタグを HTML ファイルに指定するための HTML コマンドを説明します。 これらのコマンドは HTML ファイルに埋め込まれ、組み込み SAF parse-html で処理されます。

サーバはそれぞれのコマンドを、コマンドとその属性で決定したデータと置き換えます。

コマンドの形式は次のとおりです。

<!--#command attribute1 attribute2 <Body>... -->

それぞれの attribute の形式は、次のような名前(name) と値 (value) の組み合わせです。

name="value"

コマンド (command) と属性名 (attribute) は小文字で表します。

コマンドは HTML のコメントの中に「隠されて」いるので、サーバが構文解析を実行しない場合は無視されてしまいます。 サーバサイドの標準的なコマンドは次のとおりです。


config

config コマンドは、ほかのコマンドの書式を初期化します。

  • errmsg 属性は、ファイルの構文解析中にエラーが発生したとき、クライアントに送信されるメッセージを定義する。 この処理で発生したエラーも、エラーログファイルに記録される

  • timefmt 属性は、flastmod コマンドの日付書式を指定する。この属性では、 util_strftime 関数と同じ書式指定文字が使用される。 デフォルトの時刻書式は次のとおり： "%A, %d-%b-%y %T"

    時刻書式については、iPlanet Web Server の『NSAPI プログラマーズガイド』の付録「時刻書式」を参照

  • sizefmt 属性では、fsize コマンドのファイルサイズ書式を指定する。 次のいずれかの値を取る

    • bytes、12,345,678 の書式で全体のファイルサイズを示す

    • abbrev、ファイルサイズを K バイトまたは M バイトで示す (デフォルト)

例：

<!--#config timefmt="%r %a %b %e, %Y" sizefmt="abbrev"-->

この例では、データ書式を 08:23:15 AM Wed Apr 15, 1996 のように設定し、ファイルサイズの書式を、ファイルで使用される文字を使用し、 K バイトまたは M バイトの単位で表示するように設定します。


include

include コマンドは、構文解析済みのファイルに、別のファイルの内容を挿入します。 別の解析済みファイルをインクルードし、さらに別のファイルにインクルードすることによって、入れ子にすることもできます。 ただし、サーバが構文解析されたファイルのあるディレクトリへのアクセス制御を行なっている場合、クライアントが構文解析済みのドキュメントを要求するには、入れ子になっているファイルへのアクセス権も必要です。

iPlanet Web Server 6.0 では、virtual 属性の付いた include コマンドを使って、 CGI プログラムファイルを組み込むことができます。 CGI プログラムを実行するには、exec コマンドも使う必要があります。

  • virtual 属性はサーバ上のファイルの URI

  • file 属性は、現在のディレクトリを起点とする相対パス名。 このパス名には ../ などの要素を含めることはできない。また、絶対パスを指定することもできない

例：

<!--#include file="bottle.gif"-->


echo

echo コマンドで、環境変数の値を挿入します。 var 属性では、挿入する環境変数を指定します。 変数がない場合は、「(none)」が挿入されます。 環境変数のリストについては、サーバサイド HTML コマンドの環境変数."

例：

<!--#echo var="DATE_GMT"-->


fsize

fsize コマンドでファイルのサイズを送信します。 属性は include コマンドの属性 (virtual および file)と同じです。 ファイルサイズ書式は、config コマンドの sizefmt 属性で決定します。

例：

<!--#fsize file="bottle.gif"-->


flastmod

flastmod コマンドで、ファイルを最後に変更した日付をプリントします。 属性は include コマンドの属性 (virtual および file)と同じです。 時刻書式は、config コマンドの timefmt 属性で決定します。

例：

<!--#flastmod file="bottle.gif"-->


exec

exec コマンドで、シェルコマンドまたは CGI プログラムを実行します。

  • cmd は UNIX 専用の属性で、/bin/sh を使ってコマンドを実行する。 コマンドには任意の特別環境変数を指定することができる

  • cgi 属性で CGI プログラムを実行し、構文解析済みファイルに実行結果を出力することができる

例：

<!--#exec cgi="workit.pl"-->


サーバサイド HTML コマンドの環境変数

CGI で使用する通常の環境変数以外に、構文解析済みコマンドには次の変数を指定できます。

  • DOCUMENT_NAME

    構文解析済みファイルのファイル名

  • DOCUMENT_URI

    構文解析済みファイルへの仮想パス (たとえば /shtml/test.shtml)

  • QUERY_STRING_UNESCAPED

    「\」でエスケープされたシェル独自の特殊文字を含む、クライアントが送信した検索照会に対して、その結果からエスケープ文字を消したもの

  • DATE_LOCAL

    現在の日付とローカル時刻

  • DATE_GMT

    グリニッジ標準時で表した現在の日付と時刻

  • LAST_MODIFIED

    ファイルが最後に変更された日付



サーブレットを埋め込む方法

iPlanet Web Server 6.0 は、Java Web Server と同様に、<SERVLET> タグをサポートしています。 このタグによって、 SHTML ファイルにサーブレット出力を埋め込むことができます。 この操作を有効にするために、設定を変更する必要はありません。 SSI とサーブレットの両方が有効な場合、<SERVLET> が有効になります。

<SERVLET> タグ構文は、他の SSI コマンドのタグとは少し異なります。次のように、<APPLET> タグ構文に似ています。

<servlet name=name code=code codebase=path iParam1=v1 iParam2=v2>
<param name=param1 value=v3>
<param name=param2 value=v4>
.
.
</servlet>

サーブレットが Web アプリケーションの一部である場合、code パラメータが必要です。他のパラメータは無視されます。 code パラメータには、次の値が必要になります。

  • Web アプリケーションの web.xml ファイルで定義された url-pattern 要素の値。web.xml については、次の Web サイトの「Servlet 2.2 API specification」を参照。

    http://java.sun.com/products/servlet/index.html

  • Web アプリケーションの web-apps.xml ファイルで定義された uri 属性の値。web-apps.xml については、iPlanet Web Server の『サーブレットに関するプログラマーズガイド』を参照。

たとえば、次の構文を SHTML ファイルに記述した場合、

<servlet name=pparams code="/PrintApp/PrintParams">
</servlet>

web-apps.xml ファイルには、次の構文を追加する必要があります。

<web-app uri="/PrintApp" dir="/iws60/https-server.iplanet.com/acme.com/webapps/PrintApp"/>

また、web.xml ファイルには、次の構文も追加する必要があります。

<servlet>
<servlet-name> pparams </servlet-name>
<servlet-class> PrintPackage.PrintParams </servlet-class>
</servlet>
<servlet-mapping>
<servlet-name> pparams </servlet-name>
<url-pattern> /PrintParams </url-pattern>
</servlet-mapping>

さらに、web.xml ファイルに、任意のサーブレット初期化パラメータも追加する必要があります。

古いバージョンの (iPlanet Web Server 4.x) サーブレットに対しては、code パラメータでサーブレットの .class ファイルを指定するので、このパラメータが必要になります。 codebase パラメータは、サーブレットが servlets.properties ファイルに定義されておらず、.class ファイルが <SERVLET> タグを含む HTML ファイルと同じディレクトリにない場合に必要になります。 古いバージョンのサーブレットはデフォルトの仮想サーバに設定する必要があり、web.xml ファイルは必要ありません。

サーブレットの作成については、iPlanet Web Server の『サーブレットに関するプログラマーズガイド』を参照してください。



サーバが構文解析するカスタム HTML タグの定義方法


iPlanet Web Server 6.0 では、ユーザが独自にサーバサイドのタグを定義できます。 たとえば、タグ HELLO を定義して「Hello World!」とプリントする関数を呼び出すことができます。このためには、 hello.shtml ファイルに、次のコードを指定します。

<html>
<head>
<title>shtml custom tag example</title>
</head>
<body>
<!--#HELLO-->
</body>
</html>

ブラウザでこのコードが表示されると、HELLO タグが検出されるたびに関数が呼び出されます。


実装方法

カスタムタグのサーバによる構文解析を定義する手順は次のとおりです。

  1. タグを実装する関数を定義する

    タグ実行関数を定義します。 タグの読み込みと読み込み解除時、およびページの読み込みと読み込み解除時に呼び出す他の関数も定義します。

  2. 初期化関数を記述して新しいタグを登録する

    shtml_add_tag 関数を使って、タグを登録する初期化関数を記述します。

  3. サーバに新しいタグを読み込む


タグを実装する関数を定義する

C 言語で書かれた関数を定義し、タグに実装するため、 NSAPI を使用します。

  • ヘッダー shtml_public.h をインクルードする。これは install_dir/plugins/
    include/shtml     ディレクトリにある

  • shtml 共有ライブラリにリンクする。 Windows NT では、shtml.dll は install_dir/
    bin/https/bin     にある。 UNIX プラットフォームでは、libshtml.so または .sl は install_dir/bin/https/lib にある

ShtmlTagExecuteFunc は、実際のタグハンドラです。 通常の NSAPI pblock、Session、および Request 変数で呼び出されます。 さらに、そのタグのタグ読み込み関数やページ読み込み関数 (定義されている場合) を実行した結果から作成された TagUserData が渡されます。

タグ実行関数のシグニチャは次のとおりです。

typedef int (*ShtmlTagExecuteFunc)(pblock*, Session*, Request*, TagUserData, TagUserData);

タグ実行関数の本文を記述して出力結果を生成し、.shtml ページのタグを置き換えます。 net_write 関数を使って通常の NSAPI の方法で行います。指定したバッファから、指定したソケットに指定したバイト数が書き込まれます。

NSAPI プラグインの記述については、iPlanet Web Server の『NSAPI プログラマーズガイド』の第 4 章を参照してください。

net_write および他の NSAPI 関数については、iPlanet Web Server の『NSAPI プログラマーズガイド』の第 5 章を参照してください。

タグの実行関数は、サーバが obj.conf で次の命令に進むべきかどうかを示す int を返す必要があります。次のいずれかになります。

  • REQ_PROCEED - 正常に実行された

  • REQ_NOACTION - 変化なし

  • REQ_ABORTED - エラーが発生した

  • REQ_EXIT - 接続が切れた

タグには、次の関数を定義する必要があります。

  • ShtmlTagInstanceLoad

    タグを含むページが構文解析されるときに呼び出されます。 ブラウザのキャッシュでページを取り出す場合は呼び出されません。 基本的にはコンストラクタとして機能し、実行関数が呼び出されると、結果が必ずキャッシュされて ShtmlTagExecuteFunc に渡されます。

  • ShtmlTagInstanceUnload

    基本的にはデストラクタで、ShtmlTagInstanceLoad 関数で作成されたものをすべて消去します。 ShtmlTagInstanceLoad 関数から返された結果を渡します。

  • ShtmlTagPageLoadFunc

    タグを含むページが実行されると、ページがブラウザのキャッシュにあるかどうかに関わりなく呼び出されます。 これにより、同じページに同じタグがある場合に情報の持続性が保たれます。

  • ShtmlTagPageUnLoadFn

    タグを含むページが実行された後にこの関数が呼び出されます。 ShtmlTagPageLoadFunc で行われた任意の割り当てを解除してから、ShtmlTagPageLoadFunc から戻された結果が渡されます。

この関数のシグニチャは次のとおりです。

#define TagUserData void*
typedef TagUserData (*ShtmlTagInstanceLoad)(
const char* tag, pblock*, const char*, size_t);
typedef void (*ShtmlTagInstanceUnload)(TagUserData);
typedef int (*ShtmlTagExecuteFunc)(
pblock*, Session*, Request*, TagUserData, TagUserData);
typedef TagUserData (*ShtmlTagPageLoadFunc)(
pblock* pb, Session*, Request*);
typedef void (*ShtmlTagPageUnLoadFunc)(TagUserData);

HELLO タグを実装するコードは次のとおりです。

/*
 * mytag.c: #HELLO SSI呼び出しを実装する NSAPI 関数
 *
 *
 */

#include "nsapi.h"
#include "shtml/shtml_public.h"

/* 関数: mytag_con
 *
 * 説明: ShtmlTagInstanceLoad 関数
 */
#ifdef __cplusplus
extern "C"
#endif
TagUserData
mytag_con(const char* tag, pblock* pb, const char* c1, size_t t1)
{
return NULL;
}

/* 関数: mytag_des
 *
 * 説明: ShtmlTagInstanceUnload
 */
#ifdef __cplusplus
extern "C"
#endif
void
mytag_des(TagUserData v1)
{

}

/* 関数: mytag_load
 *
 * 説明: ShtmlTagPageLoadFunc
 */
#ifdef __cplusplus
extern "C"
#endif
TagUserData
mytag_load(pblock *pb, Session *sn, Request *rq)
{
return NULL;
}

/* 関数: mytag_unload
 *
 * 説明: ShtmlTagPageUnloadFunc
 */
#
#ifdef __cplusplus
extern "C"
#endif
void
mytag_unload(TagUserData v2)
{

}

/* 関数: mytag
 *
 * 説明: ShtmlTagExecuteFunc
 */
#ifdef __cplusplus
extern "C"
#endif
int
mytag(pblock* pb, Session* sn, Request* rq, TagUserData t1, TagUserData t2)
{
char* buf;
int length;
char* client;
buf = (char *) MALLOC(100*sizeof(char));
length = util_sprintf(buf, "<h1>Hello World! </h1>", client);
if (net_write(sn->csd, buf, length) == IO_ERROR)
{
FREE(buf);
return REQ_ABORTED;
}
FREE(buf);
return REQ_PROCEED;
}

/* 関数: mytag_init
*
* 説明: 初期化関数 shtml_add_tag() を呼び出し、
* 新しいタグを読み込む
*/

#
#ifdef __cplusplus
extern "C"
#endif
int
mytag_init(pblock* pb, Session* sn, Request* rq)
{
int retVal = 0;
// 注意: shtml_add_tag() 関数には以下のすべての引数が必要
retVal = shtml_add_tag("HELLO", mytag_con, mytag_des, mytag, mytag_load, mytag_unload);

return retVal;
}
/* end mytag.c */


初期化関数を記述して新しいタグを登録する

新しいタグを定義する共有ライブラリの初期化関数に、shtml_add_tag を使ってタグを登録します。 シグニチャは次のとおりです。

NSAPI_PUBLIC int shtml_add_tag (
const char* tag,
ShtmlTagInstanceLoad ctor,
ShtmlTagInstanceUnload dtor,
ShtmlTagExecuteFunc execFn,
ShtmlTagPageLoadFunc pageLoadFn,
ShtmlTagPageUnLoadFunc pageUnLoadFn);

tag および execFn 以外は、いずれの引数も NULL を返すことができます。


サーバに新しいタグを読み込む

新しいタグを定義する共有ライブラリを作成したら、NSAPI プラグインの通常の方法で iPlanet Web Server にライブラリを読み込みます。 つまり、次の指令を構成ファイル magnus.conf に追加します。

  1. fn パラメータが load-modules で shlib パラメータが読み込む共有ライブラリである Init 指令を追加します。 たとえば、共有オブジェクト install_dir/hello.so にタグをコンパイルすると、次のようになります。

    Init funcs="mytag,mytag_init" shlib="installdir/hello.so" fn="load-modules"

  2. fn パラメータが共有ライブラリの初期化関数であり、shtml_add_tag を使ってタグがライブラリに登録される場合、別の Init 指令を追加します。たとえば次のようになります。

    Init fn="mytag_init"


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

Last Updated September 06, 2001