0 この頁の本文へ

関連ページ

ページ案内

プラグイン仕様書。

しらぎくモバイルシステムを拡張するために作成するプラグインは、以下の仕様に従う事で作成が可能です。

目次。

プラグインの概要
プラグインの記述方法
プラグインを設置する場所
プラグイン名
プラグインのファイル名
プラグインの形式
プラグイン制作時の注意事項
特定のHTML文書のみが呼出すプラグインの場合(平成17年 3月31日追加)
データの受渡し
フォームなどを利用する場合
公開変数(平成17年 6月12日追加)
プラグイン設定変数
公開函数(平成17年 4月17日修正)
プラグインを公開する場合の注意事項(平成18年 5月12日追記)
- プラグイン利用ページにおけるPCでのキャッシュコントロール(平成18年 5月12日)
mod_perlに対応する場合(平成19年 4月 2日)

プラグインの概要。

しらぎくモバイルシステムでは、変換するHTMLコンテンツを操作するプラグインを導入する事が出来ます。

プラグインは、HTML文書を変換する前に起動します。

また、第3.001版(平成17年 3月30日)からは、特定のHTML文書だけが呼出すプラグインを作る事も可能になりました。

本文の目次へ

プラグインの記述方法。

プラグインはPerl 5.xで記述したパッケージとします。

プラグインには予め定めた名前をパッケージ名及びしらぎくモバイルシステムが呼び出す函数名とします。

呼出す際に引数として、変換前のHTML文書データと、変換モード(キャリア系統コード)が与えられます。

プラグイン函数は、処理後のHTML文書をreturn文で返しますが、しらぎくモバイルシステムで処理不能なコンテンツを出力して、exit()函数かsysExit函数で処理を強制終了させる事も出来ます。

コンテンツを独自に出力した場合、『モバイルシステム』での処理は行われません。また、複数のプラグインを実装している場合、コンテンツを独自に出力する事で、実装しているプラグインの幾つかが実行されない可能性もあります。

本文の目次へ

プラグインを設置する場所。

設置場所は「K.cgi」スクリプト設置ディレクトリに置かれたサブディレクトリ「Options」直下とします。

また、下請けスクリプトやデータファイルを収める作業用ディレクトリを要する場合は、原則的に

「Options」直下にプラグイン名と同じ名前のサブディレクトリを設置してそれを利用する

ものとします。

但し、データファイルのみを収納する作業用ディレクトリは、利用者が設定・変更出来る事を条件として任意のディレクトリに設置する事を認めます。
- 利用者の設定に制限を設ける場合(「○○と言うディレクトリ名は不可」「△△への作業用ディレクトリの設置は不可」など)は、その旨を明確にし、かつ出来得る限りそのような禁止事項に反していない事を実行時に確認する実装を勧告します。

本文の目次へ

プラグイン名。

プラグイン名は、以下の書式に従っている事が必要です。

半角の英数字のみで成り、先頭が「Add」で始まる文字列。
「_」(アンダスコア)など英数字以外のものは一切使わない事。

字数にはPerl言語での制限に依りますが、余り長いものは推奨しません。

本文の目次へ

プラグインのファイル名。

プラグインのファイル名は、以下の書式に従います(「[」「 ]」は記述しません)。

```
プラグイン名[-制限コード].pl
```

制限コードとは、プラグインを実行させないキャリア系統を指定します。

尚、制限が全く無い場合は、「-」を含めて省略します。

具体的には、実行させたく無い場合に以下の半角英字を記述します(順不同)。

e: WAP 1.0(EZウェブの旧型機)で実行しない場合。
w: WAP 2.0(EZウェブの現行機及びソフトバンクの700番台以上の機種)で実行しない場合。
j: ソフトバンクの在来機で実行しない場合。
h: H"リンク(エアーエッジフォンを除く)で実行しない場合。
i: 上記以外のキャリア(特にｉモードやPC)で実行しない場合。

尚、これ以上の細かな実行制限を希望される場合は、プラグイン内で「$ENV{'HTTP_USER_AGENT'}」などを活用して内部で処理するようにして下さい。

例えば、プラグイン名が「AddPlugIn」で、H"リンクとWAP 1.0では実行出来ないプラグインのファイル名は以下のいずれかになります。

```
AddPlugIn-wh.pl
```
```
AddPlugIn-hw.pl
```

また、プラグイン名が「AddPlugIn」で、制限の無いプラグインのファイル名は以下のようになります。

```
AddPlugIn.pl
```

尚、特定のHTML文書でのみ使われるプラグインは、ファイル名の先頭に「@」を付けます。

例えば、特定のHTML文書でのみ使われるプラグイン名が「AddPlugIn」で、H"リンクとWAP 1.0では実行出来ないプラグインのファイル名は以下のいずれかになります。

```
@AddPlugIn-wh.pl
```
```
@AddPlugIn-hw.pl
```

本文の目次へ

プラグインの形式。

プラグインは、プラグイン名で与えられるパッケージとなります。

すなわち、

```
package プラグイン名;
```

となります。

しらぎくモバイルシステムはHTML文書を変換する前に、以下の処理を実行します。

reuire "./Options/プラグイン名.pl";
eval "\$s=&$プラグイン名::プラグイン名(\$s,UA系統コード);";

つまり、「プラグイン名::プラグイン名」と言う函数を、「(変換前のHTMLコンテンツ収納変数,UA系統コード)」と言う引数で呼出し、処理の結果をHTML文書データとして受取ります。

但し、eval文内のため、実行出来なかった場合はエラーとならず、HTMLコンテンツは無処理となります。

例えば、プラグイン名が「AddPlugIn」で、ｉモード端末向けに処理しているなら、以下のように呼出されます。

reuire "./Options/AddPlugIn.pl";
eval "\$s=&$AddPluｇIn::AddPlugIn(\$s,0);";

本文の目次へ

プラグイン制作時の注意事項。

プラグインの下請けとなるスクリプトは、必ず「Options」ディレクトリの直下にプラグイン名と同名の作業用サブディレクトリを設置して、その中に入れるようにして下さい。
- 他のプラグインとの混在を可能にするため、この決まりを遵守して下さい。
- プラグイン本体と同じ階層(「Options」ディレクトリ直下)に設置していても、ファイル名がプラグインのファイル名の決まりに反していれば、現状ではプラグイン処理の対象外となりますが、将来の拡張で新たにプラグインと見なされる可能性があります。また、「Options」ディレクトリ直下にファイルが多数設置されると処理が重くなりますので同階層に下請けファイルを置く事は禁止します。
下請け処理などで新たなパッケージを必要とする場合、他のプラグインで定義した下請けパッケージ名と衝突する可能性がありますので、出来得る限り「プラグイン名_」(プラグイン名の直後にアンダスコアが付く)で始まるパッケージ名を用いて下さい(例：package AddPlugIn_Sub1;)。
上記で指定した形式以外のパッケージ名は他のプラグインとの衝突の原因となりますので使わないようにして下さい。
特に以下のパッケージ名は、システムとの衝突の原因になりますので絶対に使わないで下さい。
- main
- kconv
- img
- comp

本文の目次へ

特定のHTML文書のみが呼出すプラグインの場合(平成17年 3月31日追加)。

特定の文書が呼出すプラグインは、以下のようになります。

プラグインのファイル名。

通常のプラグインのファイル名の先頭に「@」が付きます(例：@AddPlugIn.pl)。

但し、制限コードは直前の「-」とともに記述出来ません(例：「@AddPlugIn-h.pl」は不可)。

この書式に従ったプラグインファイルは、文書側で呼出を指定されていない限り呼出されません。

プラグインを呼出す文書の設定。

文書中の任意の箇所に「」という注釈宣言を入れます(例：)。

制限コードは、プラグインのファイル名に準じたものです。制限コードが無い場合は直前の「-」も省略出来ます(例：でもでも可)。

この宣言が無い文書は、当該プラグインのファイルを呼出しません。

その他の処理は、通常のプラグインと全く同じです。

参考事項。

特定のHTML文書のみが呼出すプラグインは、全文書に適用されるプラグインより先に呼出されます。

本文の目次へ

データの受渡し。

しらぎくモバイルシステムから渡されるデータ。

上述のように、函数「プラグイン名::プラグイン名()」に「(変換前のHTMLコンテンツ収納変数,UA系統コード)」と言う引数でを与えます。

すなわち、$_[0]に変換前のHTMLデータが文字列の形で、$_[1]にUA系統コードが数値としてそれぞれ入る事になります。

UA系統コードは、どのUA系統かを示すものです。

この値を用いる事で、キャリアごとの処理分けなどが可能になります。

1: ソフトバンクの在来機。
2: WAP 1.0(EZウェブの旧型機)。
3: WAP 2.0(EZウェブの現行機及びソフトバンクの700番台以上の機種)。
4: H"リンク(エアーエッジフォンを除く)。
0: 上記以外のキャリア(特にｉモードやPC)。

尚、これ以上の細かな処理分けを希望される場合は、プラグイン内でユーザエージェント文字列を収納した公開変数「$kconv::ua_string」を活用して内部で処理するようにして下さい。

しらぎくモバイルシステムへ引渡すべきデータ。

プラグイン処理したHTMLデータを文字列としてreturn文で返す事で、システム側に処理データを引渡します。

尚、プラグインによる新たなコンテンツをHTML文書に付足す場合は、必ず<html>要素開始タグより後ろにコンテンツを付足して下さい。

<html>要素開始タグより前にコンテンツを付足すと正常に処理出来ない事があります。
<html>要素終了タグより後ろにコンテンツを付足す事は問題ありません。

追記。(平成17年 6月 2日)

第3.113版(平成17年 6月 2日)より、プラグインがHTML文書を加工・生成する際に、当該プラグインを用いるページへのアンカー(<a>要素)を出力する際に、href属性値となるファイル名に専用のクエリを附加する事が出来ます。

この場合、ファイル名の後ろに「?」に続けてクエリ列を記述して下さい(例：<a href="document.html?query1=value1;query2=value2">アンカー</a>)。

クエリ値に日本語文字などを扱う場合は予めURLエンコードした状態で出力して下さい。
クエリの区切りには「;」「&」のどちらも使えますが、「;」を推奨します。
しらぎくモバイルシステム及びソフトバンク端末サーヴァで予約しているクエリ名を用いた場合、動作は保障出来ません。

しらぎくモバイルシステムで出来ない処理を行う場合。

しらぎくモバイルシステムで対応出来ない処理を行う場合は、変換した結果をprint文で標準出力に書き出して、sysExit()函数で処理から脱出します。

この場合、出力されたコンテンツはしらぎくモバイルシステムでは処理されません。
また、他のプラグインと混在している場合、他のプラグインが実行されない場合があります。

具体的には、以下のようにします。

WAP 1.0端末

原則的に、

HDML (content-type: text/x-hdml;charset=○○)か、
WML 1.1 (content-type: text/vnd.wap.wml;charset=○○)

のデータを出力します。

日本国内の実機のみを対象としたプラグインではHTMLで出力しても構いませんが、プラグインにはその旨を表示する事を求めます。

H"端末

オープンネットコンテンツの形式に従ったプレインテキスト(content-type: text/plain)のデータで出力します。

その他の端末

HTML (content-type: text/html;charset=○○)形式のデータを出力します。

ソフトバンク端末では処理出来るHTML文書に幾つかの制約があるので注意して下さい。

H"リンク以外はcharsetパラメータ(上記の「○○」)を指定します。

データの文字コード。

日本語コンテンツの場合、しらぎくモバイルシステムから受取るデータはシフトJISコードとなり、しらぎくモバイルシステム及び端末の直接渡すデータもシフトJISコードとします。

英語コンテンツの場合は受取るデータも送るデータもiso-8859-1コードとします。

従って、端末にデータを直接送る場合、charsetパラメータ(上記の「○○」の部分)は日本語向けには「shift_jis」、英語向けには「iso-8859-1」を入れます。
内部処理で一旦別の文字コード(EUC日本語コード, UTFコードなど)に変換する事は禁止しませんが、その場合も最終的にはシフトJISコードなど指定された文字コードに戻す必要があります。

尚、言語の判断は、取得したHTML文書の<html>要素に付くlang属性またはxml:lang属性値で判断します。

本文の目次へ

フォームなどを利用する場合。

注意事項。

フォームをプラグインで発行する場合、以下の点に注意して下さい。

ソフトバンクの在来機では、以下の制限がある事に注意して下さい。
- 初期端末(ユーザエージェント文字列が「J-PHONE/2.0」で始まるもの)ではGETメソッドのみが処理出来ます。
- 在来端末では<form>要素のaction属性値にクエリを付ける事が出来ません。
このため、しらぎくモバイルシステムでは<form>要素に関して強制的に以下の処理を行います。
- 初期端末(ユーザエージェント文字列が「J-PHONE/2.0」で始まるもの)では強制的にGETメソッドとします。
- 在来端末では<form>要素のaction属性値にクエリは<input type="hidden">要素に変換されます。
つまり、POSTメソッドを用いている場合に問題が生じる可能性がある事をお含み置き下さい。
H"リンクでは、POSTメソッドは使えません。強制的にGETメソッドに読み替えられますのでご注意下さい。

フォームで使えるクエリ。

クエリの取得方法。

しらぎくモバイルシステムでは、標準入力及びクエリの双方からデータを入力しております。

GETメソッドや<a>要素などのhref属性値に付いたクエリは、$kconv::query_stringに収納されます。
POSTされたデータは、$kconv::stdin_dataに収納されます。

これらの変数は自由に参照出来ますが、内容を変える事は禁止します。

これらのデータは受取った生データです。URLデコードなどは行っておりません。

クエリ名の制限。

以下のクエリ名は使わないで下さい。

使用した場合の動作は保証しません。

しらぎくモバイルシステムで予約されているクエリ名。

「pdx」で始まるクエリ名…H"リンクではデータの受渡しにこれらのクエリ名を用います。従いまして、H"リンクからデータを受取る場合を除いて使わないようにして下さい。
ea
ia
im
a
anch
panch
lang
pcd
t
ctc
test
「marguerite」で始まるクエリ名…しらぎくさいとで予約しております。公式プラグイン以外では使わないで下さい。

ソフトバンク端末サーヴァが予約しているクエリ名

pid
sid
uid
nl
cl
「jsky」で始まるクエリ名
prc
cnt
reg

英数字と「-」及び「_」(アンダスコア)以外の文字を含んだクエリ名

しらぎくモバイルシステムではクエリ名のURLエンコード/デコードは行っておりません。

その他。

ソフトバンク在来機とH"リンクでは、クエリの区切りに「&」を用いなければなりません。また、この「&」は実体参照(&)で記述してはいけません。
<form>要素のaction属性及び<a>要素のhref属性に書かれるクエリについては、英数字以外は仕様上URLエンコードを行う必要がありますが、特に「/」はURLエンコードしないと正常に動作しなくなります。
<input type="hidden">要素のvalue属性値はURLエンコードしないで下さい。

本文の目次へ

公開変数(平成17年 6月12日追加)。

しらぎくモバイルシステムでは、以下の変数をプラグイン作成の手助けとなるよう公開しております。

$kconv::addr

変換前のHTML文書への相対パスが入ります。

パスの基準は、予め「KConfig.pl」で指定されたHTML文書設置ディレクトリ基準です。

$kconv::realdevice

ユーザエージェント文字列を見て、本物の携帯端末と判断された場合に非零値が、そうでなければ0が入ります。

但しあくまでもユーザエージェント文字列からの判断である事に注意して下さい(現在のところ、リモートホストからは判断しておりません)。

$kconv::color_device (WAP 1.0及びH"リンクのみ)

カラー端末では非零値が、白黒端末では0が入ります。

WAP 1.0及びH"リンク以外の端末では未定義値となっております。

$kconv::system_dir (平成17年 4月17日追加)

「K.cgi」が入っているディレクトリへのパスが入ります。

通常は「./」ですが、ウィンドウズサーヴァやmod_perlで利用する場合は、「K.cgi」収納ディレクトリへの絶対パスを入れる事になります。

$kconv::query_string (平成17年 4月17日追加)

呼出時のクエリストリングが入ります。

URLエンコードされたままの状態で入ります。

$kconv::stdin_data (平成17年 4月17日追加)

呼出時に標準入力に入っていたデータが入ります。

URLエンコードされたままの状態で入ります。

$kconv::ua_string (平成17年 4月17日追加)

ユーザエージェント文字列が入ります。

$kconv::optionsCredits (平成17年 6月12日追加)

プラグインのクレジットを入れる文字列変数で、この変数に限り、条件付で変更が可能です。

クレジット文字列(HTMLの<a>要素も可。但しhref属性は絶対URLとする事)に"\n"を末尾につけたものを連結する事が出来ます。

具体的には、
```
$kconv::optionsCredits.=qq|<a href="http://www.hoge/hoge/plug-in/>しらぎくモバイルシステム専用○○プラグイン Ver. ○.○ (○年○月○日)</a>\n|;
```
と言った使い方が出来ます。
上記の連結以外の文字列の改変、特にこれまで連結されてきたクレジットを消去する事は禁じられております。

この文字列はPCで閲覧した場合にのみ表示され、当該プラグインへのリンクも機能します。

この他、「KConfig.pl」で設定される変数は自由に参照する事が出来ます(パッケージ名「kconv」)。

いずれの変数も、参照のみ許されており、変更は禁じております。

本文の目次へ

プラグイン設定変数。

プラグインを利用する際に設定される変数で、「KConfig.pl」にて設定するものは、公式プラグインで無い場合は必ず「プラグイン名_」(プラグイン名の直後にアンダスコアが一個付く)で始まる変数名にして下さい。

勿論、プラグインファイル内で設定する事や作業用ディレクトリ内に設定ファイルを置く事も出来ます。

「Options」ディレクトリ直下にファイルが多数置かれると、動作が遅くなるため、必ず作業用ディレクトリを用意して下さい。

本文の目次へ

公開函数(平成17年 4月16日追加)。

しらぎくモバイルシステムでは、以下の函数をプラグイン作成の手助けとなるよう公開しております。

&kconv::f_lock(void)

ファイルロックします。

flock()函数が使えない場合はrename()函数で処理しますので、どんなシステムでも動くでしょう。

尚、特定のファイルだけをロックするもので無い事に注意して下さい。

&kconv::f_unlock(void)

&kconv::f_lock()函数でのロックを解除します。

&kconv::f_lock()を呼出した場合は必ずこの函数を呼出してロックを解除して下さい。

&kconv::sysExit(void) (平成17年 4月16日追加)

システムから脱出する場合に利用します。

exit()函数が使えないmod_perlへの対応のため用意しました。mod_perlに対応する場合は、必ずこの函数をご利用下さい。尚、現時点ではしらぎくモバイルシステムはmod_perlには対応しておりません。

&kconv::sysOut($gzip,$status,$header,\$body,$bin_mode) (平成17年 4月17日変更)

コンテンツの出力に用います。

引数は以下の通りです。

$gzip

GZIP圧縮が可能な場合は1に、出来ない場合は0を入れます。

$status

HTTPでのステータスコードとメッセージ(例：「200 OK」)を入れます。空文字列の場合は「200 OK」となります。

$header

HTTP応答ヘッダを記述します。「"content-type: ○○\n"」などと記述します。

content-lengthフィールドは、内部で自動的に附加されますので、ここには記述せず省略して下さい。

\$body

出力するコンテンツを参照渡しします。

$bin_mode (平成17年 4月17日追加)

バイナリモードで出力する場合は非零値、アスキィモードで出力する場合は零値を入れます。

&kconv::sysRedirect($status,$URL,$header) (平成17年 4月16日追加)

HTMLベースの端末でのリダイレクトに用います。

非HTMLベース(WAP 1.0及びH")には対応しておりません。

引数は以下の通りです。

$status: HTTPでのステータスコードとメッセージ(例：「200 OK」)を入れます。空文字列の場合はサーヴァに任されます。
$URL: リダイレクト先を絶対URLで指定します。
$header: location以外のHTTP応答ヘッダがある場合はそれらを記述します。「"content-type: ○○\n"」などと記述します。

本文の目次へ

プラグインを公開する場合の注意事項。(平成18年 5月12日追記)

しらぎくさいとではプラグイン名を管理する事は致しません。

このため、プラグインを公開する場合はプラグイン名を合わせて表示する事を求めます。

私的なプラグインは、プラグイン名, パッケージ名, 函数名, ファイル名及び直下のサブディレクトリ名を変更しても動作するように設計する事を勧告します。
- 勿論、この仕様書の範囲に従った変更に対応出来れば充分です。
プラグインが複数ある場合の動作の優先順位を操作する事は出来ません。唯一、特定の文書でのみ動作するプラグインは全文書で動作するプラグインより先に実行される事だけが仕様で定められております。

このため、プラグインは処理の順序に依存しないようにする事を推奨します。特に他のプラグインも同時に利用され得る事に注意して下さい。
日本語文書専用のプラグインを公開する場合は、その旨を明記して下さい。特に指定が無いプラグインは、外国語文書も処理可能なものと見なします。
HTML文書中の注釈宣言はあらゆる処理制御に用いているので勝手に削除してはいけません。逆に非公開の処理制御用注釈宣言を埋め込む事は、実装の変更で使えなくなる可能性がありますのでやらないようにして下さい。
プラグインがエラーにより動作しなかった場合、Perl処理系が出力したエラーメッセージが表示されます。

プラグイン利用ページにおけるPCでのキャッシュコントロール。(平成18年 5月12日)

プラグインを「」にて呼び出したページは、PCでの閲覧に対して原則的にHTTP応答ヘッダにLast-Modifiedフィールドを附与しません。

このため、この形式でプラグインを呼び出したページは、リロードで更新されるようになります。

但し、必要であれば、HTML文書内に「」注釈宣言を記述する事で、HTTP応答ヘッダにLast-Modifiedフィールドを附与するようになります。

動的にコンテンツを埋め込むプラグインでは、「」注釈宣言を埋め込むとPCで見た場合に動的に変化しなくなりますので、そのようなプラグインの作成では絶対に「」の記述をしないよう求めて下さい。
将来のヴァージョンアップでは、携帯端末に対してもLast-Modifiedフィールドなどに対応している端末に対応する場合があります。
尚、アクセスカウンタのみを呼び出している場合は、HTTP応答ヘッダにLast-Modifiedフィールドを附与します。

本文の目次へ

mod_perlに対応する場合。(平成19年 4月 2日)

プラグインはmod_perl上で動作する事を想定して作る必要はありません。

逆にmod_perl上でも動作するようにするには、以下の点にご留意下さい。

WAP 1.0のフォームをWMLやHDMLで書き出すと、mod_perlのヴァージョンに依っては余計な文字列が後に追加され、その結果端末でエラーとなり表示が出来なくなる場合があります。現行のモバイルシステムでは入力フォームの処理が可能になっておりますので、HTML形式のフォームをシステムに返すようにする事をお奨めします。
プラグインはモジュール分けが行われる事と、モバイルシステムではプラグイン内で利用している変数を見る事が無い事から、グローバルな変数であってもプラグインのモジュール内であれば問題はありません。
しらぎくモバイルシステムでは、mod_perl上で動作させる場合にはHTTPヘッダを自動送出する設定である事を求めております。

以上より、mod_perl対応のプラグインはその旨を表示する事が求められます。

本文の目次へ

ページ外へのご案内。

制作者へのご連絡