IAAプロトコルクラスライブラリ(β版)

目次

1. 目的

2. 概要

2.1. 環境

2.2. 概観

3. IAA_REGISTクラスライブラリ仕様書

3.1. IAA_DATA_REGISTクラス仕様

3.2. IAA_PROTOCOL_REGISTクラス仕様

3.3. IAA_REGISTクラス仕様

4. IAA_REGISTクラスライブラリの拡張について

5. テストプログラム(IAA_TEST)

1. 目的

本クラスライブラリは、WIDEプロジェクト ライフラインワーキンググループの主催するIAA災害訓練のためのWindows95/NT版IAA生存者情報登録クライアントプログラムの作成を支援するためのものである。 本クラスライブラリは、IAAクラスライブラリを利用する。

本クラスライブラリはIAAクラスライブラリ、 IAA生存者情報登録プロトコル仕様書などとともに公開され、 ライフラインワーキンググループに属さない人たちにも、 クライアントプログラムの開発者としてIAA災害訓練に参加してもらうことを意図している。

2. 概要

本クラスライブラリは、IAAアプリケーションプログラム開発者が、 IAA生存者情報登録プロトコル over SMTPをWindows95/NTから実行するクライアントプログラムを作成するのを支援するためのものである。 本クラスライブラリを使用するためには、 IAAクラスライブラリおよびIAA生存者情報登録プロトコル over SMTP仕様書を取得する必要がある。 以降に利用環境および使用方法の概要を述べる。

2.1. 環境

本クラスライブラリは、Windows95/NT用で、 Microsoft Visual C++ Ver 4.0以上で利用可能である。

本クラスライブラリの利用者は、

などに習熟している必要がある。

本クラスライブラリを利用するには、 まずIAAクラスライブラリ(IAA.zip)を適当なディレクトリ(以降IAA_SOURCESと呼ぶ)に展開し(IAAディレクトリが作成され、 そこにIAAクラスライブラリは展開される)、 次に、 IAA_SOURCESディレクトリでIAA_REGISTクラスライブラリ(IAA_REGIST.zip)を展開すると、 IAA_REGISTディレクトリが作成され、そこに本クラスライブラリは展開される。 展開されるファイルは以下のとおり。

IAA_REGIST.h IAA_REGISTクラスのインターフェイスと必要な定義
IAA_REGIST.cpp IAA_REGISTクラスのインプリメンテーション
IAA_VAL.h IAA_VALクラスのインターフェイスと必要な定義
IAA_VAL.cpp IAA_VALクラスのインプリメンテーション
IAA_REGIST.dsp 本クラスライブラリのプロジェクトファイル
IAA_REGIST.dsw 本クラスライブラリのプロジェクトワークスペースファイル
IAA_REGIST.mak 本クラスライブラリのmakeファイル
IAA_REGIST.lib 本クラスライブラリのライブラリファイル
Commonディレクトリ 本クラスライブラリで使用するWinsockクラスライブラリ*
Msvclibsディレクトリ 本クラスライブラリで使用するWinsockライブラリ*
IAA_REGIST.html 本ファイル

*これらのファイルの著作権は??????に帰属します。

本β版は、Windows95/NT4.0上のVC++5.0でのみ動作確認されている。 他の環境での確認はされていないので、問題が発見された場合には報告を頂きたい。

リリース版では、利用するWinsockライブラリが変更される可能性がある。

2.2. 概観

本クラスライブラリは、 入力データオブジェクトに設定されたデータをIAA生存者情報登録メッセージに変換し、 プロトコルパラメータオブジェクトに設定されたパラメータにしたがって、 そのメッセージをSMTP(Simple Mail Transfer Protocol)を使って伝送する実行オブジェクトクラスを提供している。 提供されているクラスは以下のとおり。

IAA_DATA_REGISTは、プロトコル実行器の入力となるもので、

などを行うオブジェクトクラスである。

IAA_DATA_DUMMYは、 実行オブジェクトクラステンプレートへの引数として使われるダミークラスで、 それ以外には必要としない。 通常は、実行オブジェクトクラスとして、 既にテンプレートに引数を適用済みのIAA_REGISTクラスを用いるので、 利用する必要はない。

IAA_PROTOCOL_REGISTは、プロトコル実行器であり、 プロトコルパラメータを設定するために用いるオブジェクトクラスである。

IAA_REGISTは、IAAテンプレートクラスを用いた実行オブジェクトクラスで、

などを行うオブジェクトクラスである。

本クラスライブラリを利用したWindows95/NT版IAA生存者情報登録クライアントプログラムは、 概ね以下のような流れとなる。

  1. ユーザーインターフェイスから生存者情報を取得
  2. IAA_DATA_REGISTオブジェクトに生存者情報を設定
  3. IAA_PROTOCOL_REGISTオブジェクトにSMTPサーバ、SMTPポート、From行、IAAサーバを設定
  4. IAA_REGISTオブジェクトに両者を設定
  5. IAA_REGISTオブジェクトのプロトコル実行器の初期化と実行
  6. IAA_REGISTオブジェクトのプロトコル終了を検出

以降、各クラスの詳細を記す。

3. IAA_REGISTクラスライブラリ仕様書

IAA_REGISTクラスライブラリは、 IAA生存者情報登録プロトコル over SMTPのWindows95/NT版クライアントプログラムを作成するためのライブラリであり、 IAAクラスライブラリを利用する。

本クラスライブラリを利用するには、

をincludeする必要があり、また、これらのヘッダファイルの他に、 (IAA_SOURCES)\IAA_REGIST\Commonにあるいくつかのヘッダファイルも利用するので、 includeパスを通しておく必要がある。 また、 をライブラリとしてリンクする必要があるほか、 ランタイムライブラリとしてマルチスレッドライブラリを選択する必要がある。

以降、本IAA_REGISTクラスライブラリ仕様書では、 を示す。

3.1. IAA_DATA_REGISTクラス仕様

2.2節において述べたとおり、 IAAアプリケーションプログラムでは本クラスライブラリを利用する場合、 入力データオブジェクトに生存者情報を与えてプロトコルを実行する。 よって、以降では入力データオブジェクトクラスであるIAA_DATA_REGISTクラスの仕様を述べる。 []内は、省略不可能なパラメータであり、 {}内は、省略可能なパラメータである。 例文中では、iaaは実行オブジェクト、 iaa_data, iaa_data2は入力データオブジェクト、 iaa_protocolはプロトコルパラメータオブジェクトとする。


データ項目

lname姓(JMS漢字)
fname名(JMS漢字)
lyomi姓の読み仮名(JMSひらがな)
fyomi名の読み仮名(JMSひらがな)
iname国際名(ASCII文字、必須ではない)
reptr報告者名(JMS漢字&ASCII文字)
place場所(JMS漢字)
note備考(JMS漢字&ASCII文字、必須ではない)
stat状況(1桁整数、1:生存、2:軽傷、3:重傷、4:死亡)
how確認方法(1桁整数、1:直接、2:伝聞)
relate続柄(1桁整数、1:本人、2:家族、3:他人)
sdate1確認年(4桁整数、1970-2037)
sdate2確認月(2桁整数、1-12)
sdate3確認日(2桁整数、1-31)
sdate4確認時(2桁整数、0-23)

解説

上の表では、生存者情報の各データ項目の内部表現名と概略、登録すべき内容と制限が記されている。 以降で、<内部表現名>と書かれている場合は、上のうちの一つがそこにくることを意味する。


IAA_DATA_REGIST

IAA_DATA_REGIST [実データオブジェクト]

IAA_DATA_REGIST iaa_data;

戻り値

なし。

引数

実データオブジェクトには生成したい実データオブジェクト名を指定する。

解説

成功すれば、実データオブジェクトが生成される。生成されたばかりの実データオブジェクトは、 エラーとしてNOT_DATA_CONFIGUREDを返す。 生成された実データオブジェクトには、 デフォルトでsdateに現在時間が設定されており、 また、各整数項目の制限が設定されている(IAA_DATA_REGIST::Consistency()で利用される)。


Set

bool Set<内部表現名>([データ])

iaa_data.Setlname("山田");

戻り値

成功すればtrue、失敗したらfalseが返る。

引数

入力データとして与えたいデータ文字列へのポインタを指定する。

解説

入力データを各データ項目に設定する。 正しくデータが設定された場合には、trueを戻り値として返し、 IAA_NO_ERRORをエラーとして返す。 失敗したら、falseを戻り値として返す。 詳細なエラーは、GetLastError()によって得ることができる。


Get

char *Get<内部表現名>()

char *a = iaa_data.Getfyomi();

戻り値

データ項目に設定されているデータ文字列へのポインタを返す。

引数

なし。

解説

データ項目に設定されているデータ文字列へのポインタを得る。


SetData

bool SetData([データオブジェクト])

iaa_data.SetData(iaa_data2);

戻り値

成功すればtrue、失敗したらfalseが返る。

引数

入力データとして与えたいデータオブジェクトを指定する。

解説

入力データオブジェクトにその入力データを設定し、データが正規化されているかを検査する。 正しくデータが設定された場合には、trueを戻り値として返し、 IAA_NO_ERRORをエラーとして返す。 失敗したら、falseを戻り値として返す。 詳細なエラーは、GetLastError()によって得ることができる。


GetData

bool GetData([データオブジェクト])

iaa_data2.GetData(iaa_data);

戻り値

成功すればtrue、失敗したらfalseが返る。

引数

入力データを格納したいデータオブジェクトを指定する。

解説

指定されたデータオブジェクトに入力データを格納する。 正しくデータが格納された場合には、trueを戻り値として返し、 IAA_NO_ERRORをエラーとして返す。 失敗したら、falseを戻り値として返す。 詳細なエラーは、GetLastError()によって得ることができる。


Consistency

bool Consistency()

iaa_data.Consistency();

戻り値

データが正規化されている場合にはtrue、されていない場合にはfalseが返る。

引数

なし。

解説

データが正規化されているかどうか、一貫性がとれているかを検査し、 正しい場合にはtrueを戻り値として返し、正しくない場合にはfalseを返す。 詳細なエラーは、GetLastError()によって得ることができる。


Presentation

char *Presentation()

char *Message = iaa_data.Presentation();

戻り値

成功した場合、データをメッセージに変換した文字列へのポインタを返す。 失敗した場合には、NULLポインタを返す。

引数

なし。

解説

データオブジェクトの保持している生存者情報をIAA生存者情報登録メッセージに変換し、 そのメッセージ文字列へのポインタを返す。 失敗した場合には、NULLポインタを返す。 詳細なエラーは、GetLastError()によって得ることができる。


Representation

bool Representation([メッセージ])

iaa_data.Representation(Message);

戻り値

常にtrueが返る。

引数

メッセージ文字列へのポインタを指定する。

解説

常にtrueを返すダミー関数。


GetLastError

IAA_ERROR GetLastError()

IAA_ERROR a = iaa.GetLastError();

戻り値

IAA_ERROR列挙型のエラーを返す。

引数

なし。

解説

データオブジェクトに起こった最後のエラーを返す。


3.2. IAA_PROTOCOL_REGISTクラス仕様

IAAアプリケーションプログラムでは本クラスライブラリを利用する場合、 プロトコルパラメータオブジェクトにSMTPサーバ、 SMTPポート、From行、IAAサーバを与えてプロトコルを実行する。 以降ではプロトコルパラメータオブジェクトクラスであるIAA_PROTOCOL_REGISTクラスの仕様を述べる。 []内は、省略不可能なパラメータであり、 {}内は、省略可能なパラメータである。 例文中では、iaaは実行オブジェクト、 iaa_dataは入力データオブジェクト、 iaa_protocol, iaa_protocol2はプロトコルパラメータオブジェクトとする。


IAA_PROTOCOL_REGIST

IAA_PROTOCOL_REGIST [実プロトコルパラメータオブジェクト]

IAA_PROTOCOL_REGIST iaa_protocol;

戻り値

なし。

引数

実プロトコルパラメータオブジェクトには生成したい実プロトコルパラメータオブジェクト名を指定する。

解説

成功すれば、実プロトコルパラメータオブジェクトが生成される。 生成されたばかりの実プロトコルパラメータオブジェクトは、 エラーとしてNOT_PROTOCOL_CONFIGUREDを返す。 生成されたばかりの実プロトコルパラメータオブジェクトには、何も設定されていない。


SetProtocol

bool SetProtocol([プロトコルパラメータオブジェクト])

iaa_protocol.SetProtocol(iaa_protocol2);

戻り値

成功すればtrue、失敗したらfalseが返る。

引数

プロトコルパラメータとして与えたいプロトコルパラメータオブジェクトを指定する。

解説

実プロトコルパラメータオブジェクトに、 与えられたプロトコルパラメータオブジェクトのプロトコルパラメータを設定する。 正しく設定された場合には、trueを戻り値として返し、 現在のエラーがNOT_CONFIGUREDならNOT_CALLBACK_CONFIGUREDを、 NOT_PROTOCOL_CONFIGUREDならIAA_NO_ERRORを返す。 それ以外の場合には、元のエラーを返す。 失敗したら、falseを戻り値として返す。 詳細なエラーは、GetLastError()によって得ることができる。


SetProtocol

bool SetProtocol([Current Instance], [Prev Instance], [SMTPサーバ], [SMTPポート], [ユーザー], [IAAサーバ])

iaa_protocol.SetProtocol(hInstance, hPrevInstance, "mailserv.iaa.wide.ad.jp", 25, "iaaregistry@iaa.wide.ad.jp", "registry@iaa.wide.ad.jp");

戻り値

成功すればtrue、失敗したらfalseが返る。

引数

Current InstanceにはWinMain関数の引数hInstanceを、Prev InstanceにはhPrevInstanceを指定する。 SMTPサーバにはメールの配送に利用するSMTPサーバ名文字列へのポインタを、 SMTPポートにはSMTPサーバのポート番号(0を指定するとデフォルトで25が設定される)を指定する。 ユーザーにはメールのfrom行に入れたいメールアドレス文字列へのポインタを指定する。 IAAサーバにはIAA生存者情報登録サーバ名(現在はregistry@iaa.wide.ad.jpであるが、 変更される可能性があるので変更可能なユーザーインターフェイスを用意することが望ましい)文字列へのポインタを指定する。

解説

実プロトコルパラメータオブジェクトに、 与えられたプロトコルパラメータを設定する。 正しく設定された場合には、trueを戻り値として返し、 現在のエラーがNOT_CONFIGUREDならNOT_CALLBACK_CONFIGUREDを、 NOT_PROTOCOL_CONFIGUREDならIAA_NO_ERRORを返す。 それ以外の場合には、元のエラーを返す。 失敗したら、falseを戻り値として返す。 詳細なエラーは、GetLastError()によって得ることができる。


InitProtocol

bool InitProtocol()

iaa_protocol.InitProtocol();

戻り値

成功すればtrue、失敗したらfalseが返る。

引数

なし。

解説

Winsockを初期化し、Winsock処理のためのイベントウィンドを生成して、 プロトコル実行器を実行可能な状態にする。 正しく初期化された場合には、trueを戻り値として返し、初期化フラグをセットし、 IAA_NO_ERRORをエラーとして返す。 失敗したら、初期化フラグをリセットし、falseを戻り値として返す。 詳細なエラーは、GetLastError()によって得ることができる。 エラーがある場合には、初期化は行われず、元のエラーを返す。


DoProtocol

char *DoProtocol([メッセージ])

char *Message = iaa_protocol.DoProtocol(iaa_data.Presentation());

戻り値

非同期型プロトコルなので、必ずNULLポインタを返す。

引数

IAA生存者情報登録メッセージ文字列へのポインタを指定する。

解説

IAA生存者情報登録メッセージをプロトコル実行器にかけ、 SMTPを使ってメッセージを伝送する。 非同期型プロトコルなので、ブロックせずにNULLポインタを返す。 プロトコルが正常に実行中の場合にはWOULD_BLOCKがエラーとして返る。 プロトコルの実行終了時には、エラーをセットし、 設定されているIAA_CALLBACK型オブジェクトのDoCallback()を呼び出す。 詳細なエラーは、GetLastError()によって得ることができる。


GetLastError

IAA_ERROR GetLastError()

IAA_ERROR a = iaa_protocol.GetLastError();

戻り値

IAA_ERROR列挙型のエラーを返す。

引数

なし。

解説

プロトコルオブジェクトに起こった最後のエラーを返す。


SetCallback

bool SetCallback([コールバックオブジェクト])

iaa_protocol.SetCallback(&iaa);

戻り値

成功すればtrue、失敗したらfalseが返る。

引数

プロトコル実行の終了時に呼び出して欲しい、 IAA_CALLBACK型のコールバックオブジェクトへのポインタを指定する。

解説

コールバック関数の実体をコールバックオブジェクトとして与えると、 与えられたコールバックオブジェクトを格納し、正しく格納できた場合には、trueを戻り値として返し、 現在のエラーがNOT_CONFIGUREDならNOT_PROTOCOL_CONFIGUREDを、 NOT_CALLBACK_CONFIGUREDならIAA_NO_ERRORを返す。 それ以外の場合には、元のエラーを返す。 正しく格納できなかった場合には、falseを戻り値として返す。 詳細なエラーは、GetLastError()によって得ることができる。 実行オブジェクト(IAA_REGIST)はプロトコルの実行時に自分自身をコールバックオブジェクトとして設定し、 内包するDoCallback()をコールバックとして呼び出してもらうことで、 プロトコル実行器の終了を検出する。


3.3. IAA_REGISTクラス仕様

IAAアプリケーションプログラムでは本クラスライブラリを利用する場合、 実行オブジェクトに入力データオブジェクトとプロトコルパラメータオブジェクトを設定し、 プロトコルを実行する。 以降では実行オブジェクトクラスであるIAA_REGISTクラスの仕様を述べる。 []内は、省略不可能なパラメータであり、 {}内は、省略可能なパラメータである。 例文中では、iaaは実行オブジェクト、 iaa_dataは入力データオブジェクト、 iaa_protocolはプロトコルパラメータオブジェクトとする。


IAA_REGIST

IAA_REGIST [実行オブジェクト]

IAA_REGIST iaa;

戻り値

なし。

引数

実行オブジェクトには生成したい実行オブジェクト名を指定する。

解説

成功すれば、実行オブジェクトが生成される。生成されたばかりの実行オブジェクトは、 エラーとしてNOT_CONFIGUREDを返す。


SetData

bool SetData([入力データオブジェクト])

iaa.SetData(iaa_data);

戻り値

成功すればtrue、失敗したらfalseが返る。

引数

入力データとして与えたい入力データオブジェクトを指定する。

解説

入力データについてデータが正規化されているかを検査し、 実行オブジェクトにその入力データを設定する。 正しくデータが設定された場合には、trueを戻り値として返し、 現在のエラーがNOT_CONFIGUREDならNOT_PROTOCOL_CONFIGUREDを、 NOT_DATA_CONFIGUREDならIAA_NO_ERRORをエラーとして返す。 それ以外の場合には、元のエラーを返す。 失敗したら、falseを戻り値として返す。 詳細なエラーは、GetLastError()によって得ることができる。


GetData

bool GetData([出力データオブジェクト])

iaa.GetData(iaa_data);

戻り値

常にtrueを返す。ダミー関数。

引数

出力データを格納する出力データオブジェクトを指定する。

解説

このプロトコルでは結果は何も返ってこないので、常にtrueを返すダミー関数。 何ら動作しない。


SetProtocol

bool SetProtocol([プロトコルパラメータオブジェクト])

iaa.SetProtocol(iaa_protocol);

戻り値

成功すればtrue、失敗したらfalseが返る。

引数

与えたいプロトコルパラメータを格納したプロトコルパラメータオブジェクトを指定する。

解説

実行オブジェクトのプロトコルパラメータを設定する。 正しく設定された場合には、trueを戻り値として返し、 現在のエラーがNOT_CONFIGUREDならNOT_DATA_CONFIGUREDを、 NOT_PROTOCOL_CONFIGUREDならIAA_NO_ERRORをエラーとして返す。 それ以外の場合には、元のエラーを返す。 失敗したら、falseを戻り値として返す。 詳細なエラーは、GetLastError()によって得ることができる。


InitProtocol

bool InitProtocol()

iaa.InitProtocol()

戻り値

成功すればtrue、失敗したらfalseが返る。

引数

なし。

解説

実行オブジェクトのプロトコル実行器を初期化する。 正しく初期化された場合には、trueを戻り値として返し、初期化フラグをセットし、 現在のエラーがNOT_INITIALIZEDならIAA_NO_ERRORをエラーとして返す。 それ以外の場合には、元のエラーを返す。 失敗したら、初期化フラグをリセットし、falseを戻り値として返す。 詳細なエラーは、GetLastError()によって得ることができる。


DoProtocol

bool DoProtocol()

iaa.DoProtocol();

戻り値

非同期型プロトコルなので常にfalseが返り、 ブロックする場合にはエラーとしてWOULD_BLOCKが返る。

引数

なし。

解説

入力データをIAA生存者情報登録メッセージに変換し、 プロトコル実行器にかけ、伝送する。 非同期型プロトコルなので、ブロックせずに常にfalseが返る。 プロトコルが正常に実行中の場合にはWOULD_BLOCKがエラーとして返る。 プロトコルの実行終了は、Done()によって知ることができる。 詳細なエラーは、GetLastError()によって得ることができる。


Done

bool Done()

iaa.Done();

戻り値

プロトコルの実行が終了していればtrue、そうでなければfalseを返す。

引数

なし。

解説

プロトコルの実行終了を検査する。 終了していればtrue、そうでなければfalseを返す。


GetLastError

IAA_ERROR GetLastError()

IAA_ERROR a = iaa.GetLastError();

戻り値

IAA_ERROR列挙型のエラーを返す。

引数

なし。

解説

実行オブジェクトに起こった最後のエラーを返す。


4. IAA_REGISTクラスライブラリの拡張について

IAA_REGISTクラスライブラリを拡張するためには、 IAA_REGISTクラスライブラリの動作原理を理解する必要がある。 以降では、IAA_REGISTクラスライブラリの内部動作について詳細に解説する。

本β版は拡張に耐えないので解説しない。

5. テストプログラム(IAA_TEST)

本クラスライブラリの動作をテストするためのテストプログラムとして、IAA_TEST.zipを用意した。 IAA_SOURCESディレクトリに展開すると、IAA_TESTディレクトリが作成され、 そこにテストプログラムは展開される。展開されるファイルは以下のとおり。

IAA_TEST.cpp テストプログラム本体
IAA_TEST.dsp テストプログラムのプロジェクトファイル
IAA_TEST.dsw テストプログラムのプロジェクトワークスペースファイル
IAA_TEST.mak テストプログラムのmakeファイル

本β版では、テストプログラムはWindows95/NT4.0上のVC++5.0でのみ動作確認されている。 他の環境での確認はされていないので、問題が発見された場合には報告を頂きたい。

使用する際には、IAA_TEST.cppのWinMain関数内、59行目からのソースブロック、

// Set Protocol Parameters // 使うときには下のブロックのコメントをはずし、必要なところを埋める(はずさないとエラー) if (!protocol.SetProtocol(hInstance, hPrevInstance, // おまじない /* "", 25,                     // SMTPサーバ名とポート番号 "iaaregistry@iaa.wide.ad.jp",          // From "")) {                      // IAA生存者情報登録サーバのメールアドレス */ MessageBox(NULL, "Set Protocol Parameter Error! But it's fatal.", "Fatal Error", MB_OK | MB_ICONWARNING); return (0); }

のコメントをはずし、空文字列となっているSMTPサーバ名、 IAA生存者情報登録サーバのメールアドレスを埋めて、 ビルドする。

このプログラムを実行すると、 83行目からのSet Datas部分に指定された生存者情報をIAA生存者情報登録メッセージに変換し、 宛先をIAA情報登録サーバとして、 そのメッセージを本体とするメールをSMTPサーバに送信し、配送を依頼する。 プログラムの実行中は何も表示されないので、終了を確かめるには、 タスクマネージャー(CTRL+ALT+DELETE)を使って、タスクが存在しているかどうかを確かめる必要がある。