NumberWatcher サーバとクライアント間の通信インターフェースは TCP/IP 通信と IP マルチキャスト通信の 2 つに対応しています。 ここではそれぞれの通信プロトコルを説明します。

TCP/IP インターフェースの通信プロトコル

TCP/IP インターフェースを使う場合は numwat.ini ファイルを以下のように TCP/IP インターフェースを有効にしておく必要があります。

クライアントはサーバに何らかの要求コマンド（以下、コマンドと言う）を送信すると、サーバはそのコマンドを実行して、結果レスポンス（以下、レスポンスと言う）を返します。 基本的にはこのやりとりを繰り返して対話しますが、サーバへコマンドを送信しない場合にもレスポンスが返ってくる場合があります。 これは右図の中の「イベント」です。このイベントは電話着信時に発生し、クライアントには非同期に通知されます。そのため、例えば右図中の「イベント 2」のケースでは、クライアントからのコマンドに対するレスポンスを返す前に、クライアントにイベントを送っています。

クライアントはサーバに何も送信しない状態が長く続くと、サーバから接続解除されます。 これは、クライアントが生きているかどうかサーバは常にクライアントからの送信を監視しており、クライアントから何らかのデータを受信するたびに接続継続確認用タイマをリセットします。 このタイマが指定した時間経過すると、その対象のクライアントとの接続を解除します。

付属のクライアントモジュールを使わずに、クライアント側を独自実装する場合は、このようなサーバの動作に対応した実装にするようにして下さい。（付属のクライアントモジュールを使って開発する場合はこのようなことをあまり意識する必要はありません。）

クライアントからサーバに送るコマンドは 1 行のデータとして送信します。データの終わりは CRLF コードです。

サーバからクライアントに送るレスポンスは「ヘッダ部」と「データ部」で構成されています。 右図中の がヘッダ部で がデータ部です。（データ部がないレスポンスもあります。） はヘッダ部とデータ部の境界を示すための CRLF だけの空の行で、 はレスポンスデータの終わりを示すための CRLF だけの空の行を 2 行としています。

個々のコマンドとそのレスポンスの説明をします。コマンドは大文字でも小文字でも構いません。

NOP

サーバはただレスポンスを返すだけで何もしません。このコマンドにはデータ部はありません。

READ アダプタインデックス, メモリアドレス

ナンバーディスプレイアダプタのメモリ読み出しを行います。アダプタインデックスには対象のナンバーディスプレイアダプタを指定します。例えばナンバーディスプレイアダプタを 2 台使っている場合は 1 台目が 0 で、2 台目が 1 となります。メモリアドレスは 1 ～ 30 の範囲で指定します。（範囲外の指定してもエラーにはなりません。）

指定のナンバーディスプレイアダプタのメモリ読み出せた場合はレスポンスのデータ部に電話番号情報がセットされます。このフォーマットは以下の通りです。

アダプタインデックス,年,月,日,曜日,時,分,電話番号の種類,"電話番号"

アダプタインデックス	コマンドパラメータで指定した値です。
年	4 桁の西暦です。PC のカレンダーから自動補完しています。
月, 日, 曜日, 時, 分	アロハ PC1 から読み出した内容です。 曜日は 0:日 ～ 6:土 です。
電話番号の種類	0 ･･･ 有効な電話番号 1 ･･･ 非通知 2 ･･･ 表示圏外 3 ･･･ 公衆電話 4 ･･･ 電話番号なし（メモリ履歴がないアドレス読み出し時） 5 ･･･ エラー
電話番号	電話番号（ハイフンは含まない） 電話番号の種類が 0 のときのみ有効な電話番号が入っています。

コマンド実行がエラーの場合（"Result" ヘッダの内容が "Failed" の場合）はデータ部はありません。

WRITE アダプタインデックス, 電話番号

ナンバーディスプレイアダプタのメモリに電話番号を書き込みます。（書き込みメモリにはアドレスはありません。）　アダプタインデックスには対象のナンバーディスプレイアダプタを指定します。電話番号にはハイフンを除いた電話番号文字列を指定します。

このコマンドレスポンスにはデータ部はありません。

CLLIST

NumberWatcher サーバに TCP/IP 接続している全クライアントのリストを取得します。このコマンドは管理者権限のあるクライアントからのみ実行できます。管理者権限のないクライアントがこのコマンドを実行しようとするとエラーになります。管理者権限の設定に関しては numwat.ini ファイル（[Dispatch.TCP] adminFilter）を参照して下さい。

正常にコマンドが実行できた場合は、コマンドレスポンスのデータ部に接続クライアント群がセットされます。 （1 行に 1 クライアントの情報が入ります。） このフォーマットは以下の通りです。

接続クライアントの IP アドレス (接続クライアントのポート番号)

コマンド実行がエラーの場合（"Result" ヘッダの内容が "Failed" の場合）はデータ部はありません。

RESET

NumberWatcher サーバを再起動させます。再起動させると現在接続中のすべてのクライアントは接続解除されます。（また、numwat.ini ファイルを再読み込みします。） このコマンドは管理者権限のあるクライアントからのみ実行できます。管理者権限のないクライアントがこのコマンドを実行しようとするとエラーになります。管理者権限の設定に関しては numwat.ini ファイル（[Dispatch.TCP] adminFilter）を参照して下さい。

このコマンドレスポンスにはデータ部はありません。

SHUTDOWN

NumberWatcher サーバをシャットダウンさせます。このコマンドは管理者権限のあるクライアントからのみ実行できます。管理者権限のないクライアントがこのコマンドを実行しようとするとエラーになります。管理者権限の設定に関しては numwat.ini ファイル（[Dispatch.TCP] adminFilter）を参照して下さい。

このコマンドレスポンスにはデータ部はありません。

QUIT

NumberWatcher サーバに、このクライアントとの接続を解除させます。

このコマンドレスポンスにはデータ部はありません。

イベントは電話着信時の OnPhoneDetect のみとなります。イベントは非同期にクライアントに通知するため、コマンドに対するレスポンスを返す前に、イベントレスポンスを送るケースもあります。

OnPhoneDetect

電話着信時にクライアントに送るイベントレスポンスです。

レスポンスのデータ部に電話番号情報が入っていますが、このフォーマット READ コマンドのレスポンスのデータ部と同じです。

サーバ側でコマンド実行エラーが起こった場合にはレスポンスヘッダ部の "Result" ヘッダにエラーコードがセットされます。（"Result: Failed *" の * の値） エラーコードの意味は以下の通りです。

IP マルチキャストインターフェースの通信プロトコル

IP マルチキャストインターフェースを使う場合は numwat.ini ファイルを以下のように IP マルチキャストインターフェースを有効にしておく必要があります。

TCP/IP インターフェースとは異なり、IP マルチキャストインターフェースでは NumberWatcher サーバがクライアントへデータを送るだけの単方向通信となります。そのため TCP/IP インターフェースのようなコマンド／レスポンスの対話はできません。サーバは電話着信時に同一のマルチキャストグループのメンバー（クライアント）に電話番号パケットを送信しています。

マルチキャストパケットが届く範囲は TTL によって決まります。TTL の設定は numwat.ini ファイルの [Dispatch.Multicast] ttl にて行います。

電話番号パケットは右図のように構成されています。

先頭の 6 バイトは "NUMBER" という文字列が入っています。

アダプタインデックスは電話着信元のナンバーディスプレイアダプタの識別用の番号（1台目=0, 2台目=1,...）です。

電話着信日時はナンバーディスプレイアダプタから取得した内容ですが、[年] に関してはナンバーディスプレイアダプタに存在しないため、月と日と NumberWatcher のサーバマシンの日付を元に自動計算した値がセットされています。そのため正確にならない場合があります。

電話番号の種別は 0=有効な電話番号, 1=非通知, 2=表示圏外, 3=公衆電話, 4=電話番号なし（この値は実際にはあり得ないはずです）, 5=エラー という意味です。電話番号は取り出しやすくするために末尾に 0x00 コードが付いています。

最後の項目のチェックサムは先頭から 39 バイト分のバイト単位の加算結果としています。

プログラマーズガイド

クライアントインターフェース