プラグイン仕様書。

プラグインの概要。

しらぎくモバイルシステムでは、変換する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」は不可)。

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

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

文書中の任意の箇所に「<!-- plug-in: プラグイン名-制限コード -->」という注釈宣言を入れます(例：<!-- plug-in: AddPlugIn-wh -->)。

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

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

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

データの受渡し。

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

公開変数(平成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処理系が出力したエラーメッセージが表示されます。

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

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

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

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

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