Palm Programmer's Laboratory
Palm OS Programmer's Companion Volume II/7-1
7-1 ネットライブラリ
ネットライブラリは、Palm OS アプリケーションがインターネット上の機械と容易に接続を確立できるようにします。また、標準的な TCP/IP プロトコルを使用してデータ転送を可能にします。
ネットライブラリによって提供される基本的なネットワークサービスには、以下のものが含まれます。
- TCP（ 転送制御プロトコル：Transmission Control Protocol ）を使った、ストリームベースの、保証されたデータ転送
- UDP（ユーザデータグラムプロトコル：User Datagram Protocol ）を使った、データグラムベースの、ベストエフォートデータ転送
これらの基本的転送サービスの頂点に、高レベルインターネットベースのサービス（ファイル転送、電子メール、Webブラウズ、など）を実装できます。
重要： アプリケーションは、無線接続を生成するために直後ネットライブラリを使用することができません。無線接続にはインターネットライブラリを使用します。
このセクションでは、アプリケーションでどのようにネットライブラリを利用するかを説明します。
- ネットライブラリについて
- ネットライブラリの利用手順
- ネットライブラリ参照番号の取得
- Berkeley ソケット API のセットアップ
- セットアップおよび設定コール
- ネットライブラリを開く
- ネットライブラリを閉じる
- バージョンチェック
- ネットワーク I/O およびユーティリティコール
- Berkeley ソケット API 関数
- ネットワークログインスクリプトサポートの拡張
ネットライブラリについて
ネットライブラリは 2 つの部品で構成されます。netlib インターフェイスとネットプロトコルスタックです。
netlib インターフェイスはアプリケーションがネットライブラリコールをするときに直接コールするルーチンのセットです。これらのルーチンは、アプリケーションのサブルーチンのように、コール側のタスクで実行されます。それらはアプリケーションとリンクしてはいませんが、ライブラリディスパッチメカニズムを通してコールされます。
ネットライブラリを開く・閉じる・セットアップする関数の例外はありますが、ネットライブラリの API はBerkeley UNIX ソケット API（インターネットアプリケーションのデファクトスタンダード API ）にほぼ対応しています。Berkeley ソケット API を使って書かれたアプリケーションを、ソースコードを多少手直しすることで Palm OS 向けにコンパイルすることができます。
ネットプロトコルスタックは、オペレーティングシステムにおいて分離したタスクとして動きます。このタスクの中では、TCP/IP プロトコルスタックが動いており、受信されたパケットはネットワークデバイスドライバから処理されます。netlib インターフェイスはオペレーティングシステムメールボックスキューを通してネットプロトコルスタックと通信します。アプリケーションからキューにリクエストをポストし、ネットプロトコルスタックがリクエストを処理するまでブロックします。
ネットプロトコルスタックが分離したタスクとして動くことには 2 つの利点があります。
- 内向きのパケットを処理するためのネットプロトコルスタックにおいて、アプリケーションがビジーであってもオペレーティングシステムは切り替えます。
- ネットワークからのデータを待ってアプリケーションがブロックされていても、ネットプロトコルスタックは他のアプリケーションのリクエストを処理しつづけることができます。
一つ以上のネットワークインターフェイスはネットプロトコルスタックタスクの内部で動作します。ネットワークインターフェイスは、リンクレベルプロトコルを抽象化するのに必要なコードを含むデータベースと単独でリンクしています。例えば、PPP や SLIP のための分離したネットワークインターフェイスデータベースがあります。ネットワークインターフェイスは一般的に、プリファレンスパネルでユーザに指定されます。この章のインターフェイス選択のセッティング?セクションで説明するように、ランタイムにおいてインターフェイスがネットライブラリからアタッチもデタッチもされる、という状況もまれながらあります。
制限
将来の全プラットフォーム（特にメモリが非常に限定されたデバイス）がネットワークサポートを必要とするかどうかは不透明なので、ネットワークサポートはオペレーティングシステムではオプションとなります。このため、ネットライブラリはシステムライブラリ（実行時にインストールされ、システムが適切に動作するのに必須ではありません）として実装されます。
ネットライブラリが存在し実行されているなら、おおよそ 32KB の追加 RAM が必要です。これは事実上は必要なシステム RAM を倍にします。現時点ではネットライブラリ無しで 32KB です。そのため、ネットライブラリを RAM 合計が 128KB 以下のあらゆるプラットフォームで動かすのは現実的ではありません。システム自体が 64KBの RAM を消費する（ユーザ領域は 64KB しか残りません）からです。
RAM要求のため、ネットライブラリは PalmPilot Professional およびそれより新しい Palm OS 2.0 以降が動作するデバイスでのみサポートされます。
Palm OS 向けに書かれた全てのアプリケーションは、メモリと CPU の利用に関して特別な注意を払わなければなりません。Palm OS はメモリ容量やその他ハードウェアリソースが限定された小さなデバイスで動作するからです。そのため、ネットライブラリを使用するアプリケーションは、メモリの扱いについてさらに注意を払わなければなりません。ネットライブラリを開いた後にアプリケーションが利用できる RAM の総量は、PalmPilot Professional でおよそ 12KB 、Palm IIITM でおよそ 36KB です。
Palm OS Garnet バージョン 5.4 以降なら、ネットライブラリの最大スタックサイズ・最大アクティブ数・同時ネットワークソケット等の制限を押し付けることはありません。Palm OS デバイスの各製造者が、適切なスタックサイズやアクティブなソケットの数を決定します。
プログラマのインターフェイス
ネットライブラリには本来 2 つの API セットがあります。ネットライブラリのネイティブ API と、Berkeley ソケット API です。2 つの API はお互いに概ね対応しています。Berkeley ソケット API を使用する際に、パフォーマンスのペナルティは無く、また既存のコードを修正する必要もあまりありません。
ヘッダファイル <unix/sys_socket.h> は、ネットライブラリコールを直接コールする Berkeley ソケットコールをマップしたマクロのセットを含んでいます。ネットライブラリ API と Berkeley ソケット API の主な違いは、ほとんどのネットライブラリAPIコールが以下の追加パラメータを受け入れることです。
- 参照番号。Palm OS における全てのライブラリコールは、ライブラリ参照番号を最初のパラメータとします。
- タイムアウト。Palm ハンドヘルドのようなコンシューマシステムでは、無限のタイムアウトは適切に動作しません。エンドユーザがプロセスを殺すことができないからです。タイムアウトによって、アプリケーションはハングした接続から優雅に回復することができます。デフォルトのタイムアウトは 2秒です。
- エラーコード。慣習的に、ソケット API はアプリケーショングローバル変数 errno にエラーコードを戻します。ネットライブラリ API はアプリケーショングローバル変数には依存しません。これにより、システムコード（グローバル変数を持たない）がネットライブラリ API を利用できるようになります。
sys_socket.h 内のマクロは以下のことを行ないます。
| For... | The macros pass... |
|---|---|
| 参照番号 | AppNetRefnum（アプリケーショングローバル変数） |
| タイムアウト | AppNetTimeout（アプリケーショングローバル変数） |
| エラーコード | アプリケーショングローバル errno の値 |
Int16 socket(Int16 domain, Int16 type, Int16 protocol);
同等のネットライブラリコールは NetLibSocketOpen で、以下のように宣言されます。
NetSocketRef NetLibSocketOpen(UInt16 libRefnum, NetSocketAddrEnum domain, NetSocketTypeEnum type, Int16 protocol, Int32 timeout, Err* errP)
socket のマクロは以下の通りです。
#define socket(domain,type,protocol) \ NetLibSocketOpen(AppNetRefnum, domain, type, protocol, AppNetTimeout, &errno)
ネットライブラリの利用手順
一般的に、ネットライブラリの利用は以下の一覧のようなステップを含みます。次のいくつかのセクションで、そのステップについて詳しく説明します。
ネットライブラリ利用の例として、Palm OS Examples ディレクトリ内のサンプルアプリケーション NetSample を参照して下さい。多くのネットライブラリコールの練習になります。
- ネットライブラリ参照番号の取得
ネットライブラリはシステムライブラリなので、全てのネットライブラリコールはライブラリ参照番号を最初のパラメータとします。このため、まず参照番号を取得してそれを保存します。「ネットライブラリ参照番号の取得」を参照して下さい。
Berkeley ソケット API を利用するためのセットアップをします。
ネットライブラリを使って行ないたいことの多くが、ネットライブラリのネイティブAPIまたは Berkeley ソケット API のどちらを利用しても実現できます。もし既に Berkeley ソケット API に慣れ親しんでいるなら、おそらくネイティブAPIではなくそちらを使いたいでしょう。もしそうなら、「Berkeley ソケット API のセットアップ」の手順に従って下さい。 - もし必要なら、ネットライブラリをやりたいように設定します。
一般的に、ユーザはネットワーク設定パネルを使ってネットワークサービスをセットアップします。ほとんどのアプリケーションはそれ自身がネットワークサービスをセットアップしません。それらは単にネットライブラリ設定データベースを通してネットワークサービスにアクセスするだけです。アプリケーションがネットワーク設定を行ない、それは通常ネットライブラリを開く前に行なうべき、ということもまれにあります。「セットアップおよび設定コール」を参照して下さい。 - 最初のネットワークアクセスの前にネットライブラリを開きます。
Palm OS環境のリソースは限定されているため、アプリケーションが実際にそのサービスを必要とするときにだけ追加のメモリを要求するように、ネットライブラリはデザインされています。そのため、インターネットアプリケーションがネットライブラリを開く・開始する・終了して閉じる際にはシステムにネットライブラリを必要とすることを通知します。「ネットライブラリを開く」を参照して下さい。 - ネットワークにアクセスするためにコールします。
一度ネットライブラリが開かれたなら、Berkeley ソケット API かネイティブネットライブラリ API を使って、ソケットが開かれデータが送信されリモートホストから受信されます。「ネットワーク I/O およびユーティリティコール」を参照して下さい。 - 終了時にネットライブラリを閉じます。
ネットライブラリを閉じることで、リソースを解放します。「ネットライブラリを閉じる」を参照して下さい。
ネットライブラリ参照番号の取得
参照番号を決定するために、AppNetRefnum をコールします。
err = SysLibFind("Net.lib", &AppNetRefnum);
if (err) {/* error handling here */}
ネットライブラリは Palm OS 2.0 以降が必要なことを覚えておいて下さい。もし SysLibFind コールがネットライブラリを見つけることができない場合は、エラーコードを戻します。
Berkeley ソケット API のセットアップ
Berkeley ソケット API の利用をセットアップ するには、以下のようにします。
- ヘッダファイル <unix/sys_socket.h>を含めます。このヘッダファイルは Palm OS SDK で提供されます。
- プロジェクトをモジュール NetSocket.c にリンクします。このモジュールは3つの必要なグローバル変数（AppNetTimeout、AppNetRefnum、errno）を宣言し初期化します。NetLibSocket.c も、いくつかの Berkeley ソケット関数に必要な glue コードを含んでいます。
- 以前のセクションで説明したように、ネットライブラリの参照番号を変数 AppNetRefnum に割り当てます。
- 必要であれば、AppNetTimeout の値を調節します。
- この値は、ネットライブラリコールが期限切れになるまで待つシステムの最大ティック値を表します。ほとんどのアプリケーションで、このタイムアウト値を調節し場合によっては別のコードセクションでも調節します。以下の例はタイムアウト値を 10 秒にセットしています。
AppNetTimeout = SysTicksPerSecond() * 10;
セットアップおよび設定コール
ネットライブラリの API コールをセットアップし設定することは、通常はネットワーク設定パネルを使ってのみ行われます。これは、IP アドレス・ホスト名・ドメイン名・ログインスクリプト・インターフェイス設定…などをセットするコールを含みます。各セットアップおよび設定コールは、後々の検索のために、ランタイムコールによって不揮発性ストレージのネットライブラリプリファレンスデータベースにその設定を保存します。
アプリケーションがそれ自身をセットアップおよび設定することも、まれにあります。例えば、接続確立試行前に特定の「サービス」をユーザに選択させるアプリケーションもあるかもしれません。そのようなアプリケーションは、サービス名のピックリストを持ち、ユーザにサービス名を選択させます。この機能はネットワーク設定パネルを経由して提供されます。パネルは、エンドユーザが選ぶことのできるサービス名の一覧をアプリケーションが示すことを可能にする起動コード（ SystemMgr.h で定義されています）を提供します。設定パネルによって、特定のサービスをセットアップするのに必要なコール（＝ネットライブラリセットアップおよび設定コール）を行なうことができます。
通常は、セットアップおよび設定コールはライブラリが閉じているときに行なわれます。コールのサブセットは、ライブラリが開かれている間に発行されます。また、コールのサブセットはライブラリの振る舞いにおけるリアルタイムな影響があります。Palm OS Programmer's API Reference の第 66 章「ネットライブラリ」?で、各コールについて詳しく説明しています。
インターフェイス選択のセッティング
「ネットライブラリについて」セクションで学習したように、ネットライブラリは低レベルネットワークプロトコルを抽象化するために一つ以上のネットワークインターフェイスを使用します。ユーザは、使用するネットワークインターフェイスをネットワーク設定パネルから指定します。
また、どのインターフェイスが使われるべきかを特定するためにネットライブラリコールを使用することもできます。
- NetLibIFAttach は、ライブラリが開かれているときに使用するためにインターフェイスをライブラリにアタッチします。
- NetLibIFDetach は、インターフェイスをライブラリからデタッチします。
- NetLibIFGet はインターフェイスのクリエータとインスタンス値を戻します。
ほとんどのネットライブラリ関数とは異なり、これらの関数はライブラリが開いているか閉じているかの間にコールできます。もしライブラリが開いているなら、特定のインターフェイスがリアルタイムにアタッチまたはデタッチされます。もしライブラリが閉じているなら、アクティブな設定に情報が保存されます。設定について詳しくは 「ネットワーク設定」? を参照して下さい。
各インターフェイスは、クリエータとインスタンス値によって識別されます。もしインターフェイスをアタッチまたはデタッチしたり、インターフェイス設定を問い合わせるまたはセットするなら、これらの値が必要になります。これらの情報を取得するには、NetLibIFGet を使用します。NetLibIFGet は 4 つのパラメータをとります。ネットライブラリの参照値、ライブラリのインターフェイスリストへのインデックス、クリエータとインスタンス値が戻される 2 つの変数のアドレス、です。
クリエータは以下の値のどれかです。
- netIFCreatorLoop（ループバックネットワーク）
- netIFCreatorSLIP（SLIP ネットワーク）
- netIFCreatorPPP（PPP ネットワーク）
情報を取得したいインターフェイスが分かっているなら、ネットワークインターフェイスリストを通して連続したインデックス値で必要なクリエータ値を持つインターフェイスが戻されるまで繰り返し NetLibIFGet をコールすることができます。
インターフェイス固有のセッティング
ネットライブラリ設定は構造化されており、そのためネットワークインターフェイス固有のセッティングが各ネットワークインターフェイスごとに独立して指定されます。これらのインターフェイス固有セッティングは、IF セッティングをコールされ、NetLibIFSettingSet コールを通してセットおよび検索されます。
- NetLibIFSettingGet コールはパラメータとして、セッティングの戻り値のためのバッファポインタとバッファサイズとともにセッティング ID をとります。ログインスクリプトのような可変長セッティングは、セッティング全体を検索するのに充分な大きさのバッファをアロケートする準備を呼び出し元がしておく必要があります（もしバッファのために NULL を渡すなら、NetLibIFSettingGet は必要なサイズを戻します）。詳しくは、リファレンスの NetLibIFSettingGet 定義を参照して下さい。
- NetLibIFSettingSet コールもパラメータとして、新しいセッティング値へのポインタと新しいセッティングのサイズとともにセッティング ID をとります。
- もしログインスクリプトをセットするために NetLibIFSettingSet を使用しているなら、次のセクションを参照して下さい。
これらの関数の利用例として、Palm OS Examples ディレクトリ内の NetSample サンプルアプリケーションを参照して下さい。例えば、CmdInfo.c ファイル内の CmdSettings 関数は、ネットワークインターフェイス全てについての情報を取得しループするやり方を示しています。
インターフェイスのログインスクリプトのセッティング
netIFSettingLoginScript セッティングは、インターフェイスのためのログインスクリプトを保持するために使用されます。ログインスクリプトは、ユーザがネットワーク設定パネルに入力したスクリプトかもしくは HotSync(R) 操作によってハンドヘルドにダウンロードされたスクリプトファイルのどちらかから生成されます。スクリプトのフォーマットは厳格です。もし誤った文法のログインスクリプトがネットライブラリに提示されたなら、予期されない結果となります。基本的なフォーマットは、スクリプトの終わりにヌルバイトが付いた、ヌルで終了する一連のコマンド行です。各コマンド行にはフォーマットがあります。
<コマンドバイト> [<パラメータ>]
コマンドバイトは行の最初のキャラクタであり、コマンドバイトとパラメータ文字列の間には 1 文字の空白だけがあります。表 7,1 は可能なコマンドの一覧です。
表 7.1 ログインスクリプトコマンド
| 機能 | コマンド | パラメータ | 例 |
|---|---|---|---|
| 送信 | s | 文字列 | s go PPP |
| 待機 | w | 文字列 | w password: |
| 遅延 | d | 秒 | d 1 |
| IP の取得 | g | g | |
| プロンプト | a | 文字列 | a Enter Name: |
| プロンプトの待機" | f | 文字列 | f ID: |
| CR の送信 | s | 文字列 | s ^M |
| ユーザ IDの送信 | s | 文字列 | s jdoe |
| パスワードの送信 | s | 文字列 | s mypassword |
| プラグインコマンド※1 | sp | 文字列 | sp plugin:cmd:arg |
送信（ s ）コマンドのパラメータ文字列は、表 7.2 に示すエスケープシーケンスを含むことができます。
表 7.2 送信コマンドエスケープシーケンス
| エスケープ シーケンス |
内容 |
|---|---|
| $USERID | ユーザ名 |
| $PASSWORD | パスワード |
| $DBUSERID | ダイヤルバックユーザ名 |
| $DBPASSWORD | ダイヤルバックパスワード |
| ^c | if c is '@' -> '_', then byte value 0 -> 31 else if c is 'a' -> 'z', then byte value 1 -> 26 else c |
| <cr> | キャリッジリターン (0x0D) |
| <lf> | ラインフィード (0x0A) |
| \" | " |
| \^ | ^ |
| \< | < |
| \\ | \ |
set serviceName set userID set password set phoneNumber set connection set ipAddr set dynamicIP set primaryDNS set secondaryDNS set queryDNS set closewait set inactivityTimeout set establishmentTimeout set protocol waitfor transmit getip delay prompt waitforprompt plugin "''pluginname'':''cmd''[:''arg'']"
plugin コマンドは、プラグインで定義されたコマンドを実行するのに使用される Palm OS 独自の拡張です。プラグインについて詳しくは「ネットワークログインスクリプトサポートの拡張」を参照して下さい。
拡張子を .pnc または .scp としてスクリプトファイルを作成し、そのファイルをユーザのインストールディレクトリに置きます。次の HotSync 操作時に、ネットワークコンジットがそのファイルをダウンロードします。各スクリプトファイルは 、サービス定義を 1 つだけ含みます。
一般的なセッティング
インターフェイス固有のセッティングに加えて、特定のインターフェイスには適用されないセッティングのクラスがあります。これらの一般的なセッティングは、NetLibSettingSet コールを通してセットおよび検索されます。これらのコールはパラメータとして、セッティング ID・バッファポインタ・バッファサイズをとります。
ネットワーク設定
Palm OS 3.2 以降では、ネットワーク設定をサポートします。設定 はユーザがインターネットに接続する特定の方法を取り込みます。ネットライブラリは設定の配列を維持します。ネットライブラリが開いたときに、その設定配列の 1 つが接続のネットワークセッティングに提供されます。
設定は以下の情報を含みます。
- ネットライブラリが使用するネットワークインターフェイス。ネットライブラリが開いたとき、これらのネットワークインターフェイスが起動します。
- 一般的なネットライブラリセッティング。これらは NetLibSettingGet や NetLibSettingSet 関数によってアクセスされるセッティングです。※1
※1:トレースセッティングを除く。これらのセッティングはグローバルであり、別の設定と区別されない。
設定配列はソフトリセット後も変更されません。ハードリセット後に削除され、最初期化されます。設定配列のダイアグラムについては 図 7.1? を参照してください。
図 7.1 設定のアーキテクチャ
設定はエイリアスをとることができます。エイリアスは設定情報を含んでいません。かわりに、他の設定を指し示します。ネットライブラリは以下の各設定についてエイリアスを定義しています。
- 一般的利用のデフォルト設定
- 一般的利用の有線設定
- 一般的利用の無線設定
- Palm.net プロクシサーバを利用した有線設定
- Palm.net プロクシサーバを利用した無線設定
API のどこででも、設定を指定するのにエイリアスを指定することができます。
設定配列の最初の設定に対するエイリアスの例は、デフォルト設定と呼ばれます。ネットライブラリを開くのに NetLibOpen をコールしたとき、ネットライブラリはこの設定から接続セッティングを取得します。デフォルト設定は典型的に、NetPanel と呼ばれる 6 つの設定（実際にセッティングを含む）を指し示します。そのため、NetLibOpen をコールしたとき、ネットライブラリはそのセッティングを NetPanel 設定から取得します。「ネットライブラリを開く」を参照してください。
ネットライブラリは、アクティブ設定と呼ばれる他の特殊な設定を維持します。この設定は、ネットライブラリが最後に開いたときに使用された設定のコピーです。ネットワークインターフェイスからアタッチ／デタッチしたとき、あるいは一般的ネットライブラリセッティングを変更したとき、アクティブ設定が変更されます。このようなアクティブ設定の変更は、保持された設定には影響を与えません。
- 注
- アクティブ設定内のセッティングによってネットライブラリを開くことはできません。ネットライブラリを開くためにそのセッティングを使用する前に、アクティブ設定を保存する必要があります。
- NetLibConfigList は、全ての設定の一覧を名前で返します。利用可能な一覧を表示し、利用するものを選ばせるのにこれを使うことができます。
- NetLibConfigIndexFromName は、名前から設定のインデックス番号を取得します。ほとんどの設定関数では、設定を参照するのに名前のかわりにインデックス番号を使用します。
- NetLibConfigAliasGet は設定エイリアスの値を取得します。
- NetLibConfigAliasSet は特定の設定を指定するためのエイリアスをセットします。
- NetLibConfigSaveAs は新しい設定を定義し名前で保存します。
- NetLibConfigDelete は一覧から設定を削除します。
- 警告!
- ネットワークパネルは設定をインターフェイスします。ユーザがネットワークパネルでサービスを修正してから終了したとき、ネットワークパネルは「NetPanel」設定を上書きし、「NetPanel」設定を指すようにデフォルト設定エイリアスをリセットします。
アプリケーションは無線通信を必要とするかもしれません。ユーザのデフォルト無線セットアップにアクセスし、以下の方法（ netCfgNameDefWireless 定数はデフォルト無線設定エイリアスの名前を定義します）でネットライブラリを初期化するのにそれを使用します。
UInt16 configIndex, ifErr; Err err; err = NetLibConfigIndexFromName(ref, netCfgNameDefWireless, &configIndex); if (!err) err = NetLibOpenConfig(ref, configIndex, 0, &ifErr);
Listing 7.1 は設定関数の別の利用例を示しています。カスタムネットワークインターフェイスを利用する設定をどのように作成するか、を示しています。また、NetLibOpen が新しい設定内のセッティングに従ってライブラリを開くので、そのコードは新しい設定を示すデフォルト設定エイリアスを指しています。
Listing 7.1 設定の作成
#define myNetIFCreator '....' // Set this value
Err CreateMyConfig () {
Err err;
UInt16 instance;
UInt32 creator;
UInt16 netLibRefNum;
UInt16 index;
NetConfigNameType myConfigName = { "..." }; // Set this too
// Find the reference number of the Net Library
err = SysLibFind("Net.lib",&netLibRefNum);
if (err) return err;
// Activate the default configuration
err = NetLibConfigMakeActive(netLibRefNum,0);
if (err) return err;
// Detach all network interfaces
while (true) {
err = NetLibIFGet(netLibRefNum,0,&creator,&instance);
if (err) break;
err = NetLibIFDetach(netLibRefNum,creator,instance,1000L);
if (err) return err;
}
// Attach the custom network interface
err = NetLibIFAttach(netLibRefNum,myNetIFCreator,0,1000L);
if (err) return err;
// Save the configuration so you can use it to open the Net Library
err = NetLibConfigSaveAs(netLibRefNum,&myConfigName);
if (err) return err;
// Get the index of the new configuration
err = NetLibConfigIndexFromName(netLibRefNum,&myConfigName,&index);
if (err) return err;
// Point the default configuration alias to the new configuration
err = NetLibConfigAliasSet(netLibRefNum,0,index);
return err;
}
ネットライブラリを開く
netErrNotOpen をコールしたエラーコードです。
err = NetLibOpen(AppNetRefnum, &ifErrs);
if (err || ifErrs) {/* error handling here */}
複数のアプリケーションが一度にライブラリを開くことができます。そのため、NetLibOpen がコールされるときにネットライブラリは既に開いているかもしれません。もしそうなら、関数はライブラリのオープンカウントを増やします。オープンカウントには、アクセス中アプリケーションの数が保持され、即座に返されます。（ NetLibOpenCount 関数で、オープンカウントを検索することができます。）
もしネットライブラリがまだ開かれていないなら、NetLibOpen はネットプロトコルスタックタスクを開始し、ネットライブラリが内部で使用するメモリをアロケートし、そしてネットワーク接続を開始します。たいてい、Palm Powerd ハンドヘルドが SLIP または PPP 接続をモデムを通して確立するようにユーザが設定しています。また、この種のセットアップでは、NetLibOpen がモデムをダイヤルアップし戻る前に接続を確立します。
もしアタッチされたネットワークインターフェイス（ SLIP や PPP ）が繋がるのに失敗したら、問題のあった最初のインターフェイスのエラー番号が最後のパラメータ（上記の例における ifErrs）に格納されます。
そして同様に、一つ以上のインターフェイスが（不正なモデムセッティングやサービスダウンなどによって）繋がるのに失敗しても、ネットライブラリは開かれます。そのため、もしエラーパラメータが非ゼロでも、アプリケーションは NetLibClose を使用してネットライブラリを閉じたり適切なメッセージをユーザに表示したりしたいかもしれません。もしアプリケーションが更に詳しい情報（例えばどのインターフェイスが繋がるのに失敗したのか）を必要とするなら、アタッチした各インターフェイスをループして繋がっているかどうか問い合わせることができます。以下に例を示します。
UInt16 index, ifInstance;
UInt32 ifCreator;
Err err;
UInt8 up;
Char ifName[32];
...
for (index = 0; 1; index++) {
err = NetLibIFGet(AppNetRefnum, index,
&ifCreator, &ifInstance);
if (err) break;
settingSize = sizeof(up);
err = NetLibIFSettingGet(AppNetRefnum,
ifCreator, ifInstance, netIFSettingUp, &up,
&settingSize);
if (err || up) continue;
settingSize = 32;
err = NetLibIFSettingGet(AppNetRefnum,
ifCreator, ifInstance, netIFSettingName,
ifName, &settingSize);
if (err) continue;
//display interface didn't come up message
}
NetLibClose(AppNetRefnum, true);
Palm OS 3.2 以降では、特定のネットワーク設定によってネットライブラリを開くことができます（NetLibOpenConfig を参照）。一般的に 、設定のエイリアスを指定します。例えば、アプリケーションが有線ネットワークを要求するなら、ユーザのデフォルト有線接続を指定するために netCfgNameDefWireline設定でネットライブラリを開きます。Palm OS 3.2 以降では、NetLibOpen は単純に NetLibOpenConfig （ユーザのデフォルト設定を指定する）をコールするだけです。
ネットライブラリを閉じる
アプリケーションが終了する前に、またはネットワーク I/O が必要なくなったら、NetLibClose をコールするべきです。
err = NetLibClose(AppNetRefnum, false);
NetLibClose は単純にオープンカウントを減少させます。false パラメータは、もしオープンカウントがゼロになったらネットライブラリをすぐに閉じるかどうかを指定します。かわりに、NetLibClose は、タイマが期限切れになる前に他の NetLibOpen が発行されない限りネットライブラリをシャットダウンするタイマをスケジュールします。ネットライブラリのオープンカウントがゼロだがタイマは期限切れになっていない場合、閉じ待ち状態として参照されます。
ネットライブラリが閉じるまでどれだけ待つかは、ユーザによってネットワーク設定パネルでのみセットされます。このタイムアウト値によって、他のネットワーク接続を確立するのを待たずに一定の時間以内であるネットワークアプリケーションを終了して別のアプリケーションを起動する、ということができます。
もし閉じるタイマが期限切れになる前に NetLibOpen がコールされたなら、戻る前に、タイマはキャンセルされライブラリはオープンカウント 1 で完全に開いているものとしてマークされます。もし他の NetLibOpen が発行される前にタイマが期限切れになるなら、存在する全てのネットワーク接続は落とされ、ネットプロトコルスタックタスクは終了され、ネットライブラリが解放されたことによる全てのメモリは内部使用にアロケートされます。
ネットライブラリが閉じ待ち状態に入ることを許可することが推奨されます。しかし、もしネットライブラリがすぐに閉じる必要があるなら、2 つのうち 1 つを行なうことができます。
- NetLibClose の第二パラメータを true にセットします。このパラメータは、ライブラリがすぐに閉じるべきかどうかを指定します。
- NetLibFinishCloseWait をコールします。この関数は、ネットライブラリが閉じ待ち状態にあるなら即座に閉じるためにネットライブラリをチェックします。
バージョンチェック
ネットライブラリがインストールされているかどうかを決定するために SysLibFind を使用するのに加えて、アプリケーションはライブラリバージョンフィーチャを参照することもできます。このフィーチャは、ネットライブラリがインストールされているときだけ存在します。このフィーチャは、ネットライブラリのバージョン番号を取得するために以下のように使用されます。
UInt32* version;
err = FtrGet(netFtrCreator, netFtrNumVersion,
&version);
もしネットライブラリがインストールされていないなら、FtrGet がゼロ以外の結果コードを返します。
バージョン番号は 0xMMmfsbbb という形式でエンコードされます。
| 文字列 | 意味 |
|---|---|
| MM | メジャーバージョン |
| m | マイナーバージョン |
| f | バグフィックスレベル |
| s | ステージ：3-リリース、2-ベータ、1-アルファ、0-開発 |
| bbb | 非リリースのビルド番号 |
V1.1.2b3 は 0x01122003 とエンコードされます。 V2.0a2 は 0x02001002 とエンコードされます。 V1.0.1 は 0x01013000 とエンコードされます。
このドキュメントは、ネットライブラリのバージョン 2.01（ 0x02013000 ）について説明しています。
ネットワーク I/O およびユーティリティコール
ネットワーク I/O およびユーティリティコールのために、Berkeley ソケット API またはネットライブラリネイティブ API を使ってコールを行ないます。
ネットワーク通信を行なう際の Berkeley ソケット API の使い方について説明した本がいくつか発行されています。このため、ネットライブラリ API は Berkeley ソケット API をかなり反映しています。しかし、一般的なコンピュータにおけるネットワーク I/O の使用と Palm Powered ハンドヘルドにおけるネットライブラリの利用には、以下の重要な違いがあることを覚えておくべきです。
- ネットライブラリでは一度に最大 4 つのソケットを開くことができます。これにより、ネットライブラリの要求メモリは最小限に抑えられます。
- 大きいデータブロックを送信しようとするとき、ネットライブラリはそのブロックの一部だけを自動的にバッファします。利用できるダイナミックメモリに限界があるからです。関数のコールは実際に転送されたデータのバイト数を返します。戻り値をチェックして、もし送信するべきデータがまだあるなら、転送が完了するまで関数を再度コールします。
- もし大きな転送の間にデータを受信することを期待するなら、小さいブロックを送信するべきであり、次のブロックを送信する前に読み取り可能なものは何でも読み戻します。この方法で、アプリケーションによって送り出されたり読み戻されたりするのを待つデータをバッファする際に使用するダイナミックヒープ内のメモリ量を最小限に抑えることができます。
詳しくは、以下を参照して下さい。
- 次の「 Berkeley ソケット API 関数」セクションは、コール（サポートされる Berkeley ソケットコール・対応するネイティブネットライブラリコール・各コールの簡単な説明）の一覧表を提供します。
- Palm OS Programmer's API Referenceの第 66 章「ネットライブラリ」は、各ネットライブラリコールの詳細な説明を提供します。適用できるところで、それは各ネットライブラリネイティブコールに相当するソケットAPIコールを与えます。
- Palm OS Examples ディレクトリ内の NetSample サンプルアプリケーションは、Palm OS アプリケーションで Berkeley ソケット API を使う方法を示しています。
Berkeley ソケット API 関数
このセクションは、Berkeley ソケット API においてネットライブラリによってサポートされる関数の一覧表を提供します。いくつかの場合では、コールはソケットAPIの完全な実装に見られる機能性と比べて限定された機能性を持ちます。また、これらの制限はここで説明されます。
ソケット関数
| Berkeley ソケット関数 | ネットライブラリ関数 | 詳細 |
|---|---|---|
| accept | NetLibSocketAccept | ストリームベースソケットからの接続を受け入れます。 |
| bind | NetLibSocketBind | ソケットをローカルアドレスにバインドします。 |
| close | NetLibSocketClose | ソケットを閉じます。 |
| connect | NetLibSocketConnect | 接続を確立するために、ソケットをリモートエンドポイントに接続します。 |
| fcntl | NetLibSocketOptionSet NetLibSocketOptionGet (... |
ソケット refnumでのみサポートされ、F_SETFL と F_GETFL コマンドのみサポートします。 コマンドは、FNDELAY フラグ（flag in the argument parameter appropriately — all other flags are ignored）をセットすることでソケットを非ブロックモードにするのに使用されます。 F_SETFL・F_GETFL・FNDELAY 定数は <unix/unix_fcntl.h> 内で定義されています。 |
| getpeername | NetLibSocketAddr | 接続のためのリモートソケットアドレスを取得します。 |
| getsockname | NetLibSocketAddr | 接続のローカルソケットアドレスを取得します。 |
| getsockopt | NetLibSocketOptionGet | ソケットのコントロールオプションを取得します。 以下のオプションだけが実装されています。 ・TCP_NODELAY アプリケーションに TCP 出力バッファリングアルゴリズムを無効にさせ、それによって TCP はできる限りすぐに小さいパケットを送信します。 この定数は <unix/netinet_tcp.h>で定義されています。 ・TCP_MAXSEGTCP 最大セグメントサイズを取得します。 この定数は <unix/netinet_tcp.h>で定義されています。 ・SO_KEEPALIVE 接続で交換されたデータが無いときに調査セグメントの定期的な転送を可能にします。 もしリモートエンドポイントが反応しないなら、接続は壊れていると判断され、so_error が ETIMEOUT にセットされます。 ・SO_LINGER ソケットが閉じられたときに未送信データをどうするか指定します。 <unix/sys_socket.h> で定義された linger 構造体を使用します。 ・SO_ERROR so_error 変数の値を返します。 これは <unix/sys_socketvar.h> で定義されています。 ・SO_TYPE呼び出し元にソケットタイプを返します。 |
| listen | NetLibSocketListen | ソケットが自分への接続要求を受け入れるようにセットアップします。 キューサイズは 1 に限定されます。 1 より大きい値は無視されます。 |
| read | NetLibReceive NetLibReceivePB |
ソケットからデータを読み取ります。 recv、recvmsg、recvfrom コールは MSG_PEEK フラグをサポートしますが MSG_OOB や MSG_DONTROUTE フラグはサポートしません。 |
| select | NetLibSelect | アプリケーションが複数の I/O イベントをブロックするようにします。 複数の I/O イベントが発生したときにシステムはアプリケーションプロセスを起動します。 この関数は、<unix/sys_time.h> で定義された timeval 構造体と sys/types.h で定義された fd_set 構造体を使用します。 <unix/sys_types.h> で定義された以下の 4 つのマクロがこの関数に関連づけられます。 ・FD_ZERO*FD_SET ・FD_CLR ・FD_ISSET ソケット修飾子に加えて、この関数は「stdin」修飾子 sysFileDescStdIn とともに機能します。 この修飾子は、ユーザまたはシステムイベントがイベントキュー内で利用可能であるときにはいつも入力の準備ができているものとしてマークされます。 これは、EvtGetEvent で返されるあらゆるイベントを含みます。 sysFileDescStdIn と refnum ソケット以外の修飾子は許可されません。 |
| send | NetLibSend NetLibSendPB |
これらの関数はデータをソケットに書き込みます。 これらのコールは、recv コールとは異なり、MSG_OOB フラグをサポートします。 MSG_PEEK フラグは利用できません。 また、MSG_DONTROUTE フラグはサポートされません。 |
| setsockopt | NetLibSocketOptionSet | この関数はソケットのコントロールオプションをセットします。 以下のオプションだけが許可されます。 ・TCP_NODELAY ・SO_KEEPALIVE ・SO_LINGER |
| shutdown | NetLibSocketShutdown | close() に似ています。 しかし、全二重接続をこえるコントロールを呼び出し元に与えます。 |
| socket | NetLibSocketOpen | 通信のためのソケットを生成します。 有効なアドレスファミリは AF_INET です。 SOCK_STREAM と SOCK_DGRAMだけが有効なソケットタイプです。 また、Palm OS バージョン 3.0 以降では、SOCK_RAWも有効です。 プロトコルパラメータにはゼロをセットします。 |
| write | NetLibSend | ソケットにデータを書き込みます。 |
サポートされるネットワークユーティリティ関数
| Berkeley ソケット関数 | ネットライブラリ関数 | 詳細 |
|---|---|---|
| getdomainname | NetLibSocketOptionGet netSettingDomainName |
ローカルホストのドメイン名を返します。 |
| gethostbyaddr | NetLibGetHostByAddr | ホストの IP アドレスから与えられるホスト情報を参照します。 <netdb.h> で定義された hostent 構造体を返します。 |
| gethostbyname | NetLibGetHostByName | ホスト名から与えられるホスト情報を参照します。 <netdb.h>で定義された hostent 構造体を返します。 |
| gethostname | NetLibSettingGet(netSettingHostName...) | ローカルホストの名前を返します。 |
| getservbyname | NetLibGetServByName | サービス名で与えられる <netdb.h> で定義された servent 構造体を返します。 |
| gettimeofday | TimGetSeconds を使った glue コード | 現在の日付と時刻を返します。 |
| setdomainname | NetLibSettingSet(.. | ローカルホストのドメイン名をセットします。 |
| sethostname | NetLibSettingSet(.. | ローカルホストの名前をセットします。 |
| settimeofday | glue code using TimSetSeconds | 現在の日時をセットします。 |
サポートされるバイト順マクロ
バイト順マクロは <unix/netinet_in.h> で定義されています。それらは、整数のバイト順をネットワークバイト順とホストバイト順の間で変換します。
| Berkeley ソケットマクロ | 詳細 |
|---|---|
| htonl | 32 ビット整数を、ホストバイト順からネットワークバイト順に変換します。 |
| htons | 16 ビット整数を、ホストバイト順からネットワークバイト順に変換します。 |
| ntohl | 32 ビット整数を、ネットワークバイト順からホストバイト順に変換します。 |
| ntohs | 16 ビット整数を、ネットワークバイト順からホストバイト順に変換します。 |
サポートされるネットワークアドレス変換関数
ネットワークアドレス変換関数は、<unix/arpa_inet.h> ヘッダファイル内で宣言されています。それらはネットワークアドレスをあるフォーマットから別のフォーマットに変換したり、ネットワークアドレスの一部を操作したりします。
| Berkeley ソケット関数 | ネットライブラリ関数 | 詳細 |
|---|---|---|
| inet_addr | NetLibAddrAToIN | IP アドレスを、ドット付き 10 進数フォーマットから 32 ビットバイナリフォーマットに変換します。 |
| inet_network | glue code | IP ネットワーク番号を、ドット付き 10 進数フォーマットから 32 ビットバイナリフォーマットに変換します。 |
| inet_makeaddr | glue code | IP ネットワーク番号と IP ホスト番号によって与えられる in_addr 構造体内の IP アドレスを、32 ビットバイナリフォーマットで返します。 |
| inet_lnaof | glue code | IPアドレスのホスト番号部分を返します。 |
| inet_netof | glue code | IPアドレスのネットワーク番号部分を返します。 |
| inet_ntoa | NetLibAddrINToA | IP アドレスを 32 ビットフォーマットからドット付き 10 進数フォーマットに変換します。 |
ネットワークログインスクリプトサポートの拡張
Palm OS 3.3 から、ネットワーク設定パネルで利用できるスクリプトコマンドの一覧を拡張するプラグインを書くことができます。例えば、以下の場合に書くことができます。
- あなたが企業の IT ショップ／システムインテグレータ／トークンカードベンダであり、認証サーバによって定義されたいくつかの接続シナリオに適切に反応するログインスクリプトを必要としている。
- あなたがトークンカードベンダであり、Palm OS 版パスワード生成ソフトウェアを作成したい。
- スクリプトの実行中に条件テストと分岐を行ないたい。
ログインスクリプト機能は、ネットワークライブラリをサポートする Palm Powered ハンドヘルド（つまり、PalmPilotTM Professional およびPalm OS 2.0 以降が動いている新しいデバイス）全てにインストールできます。インストールするには、Network.prc という名前のファイルを、使用するネットワークインターフェイス（例えば PPP や SLIP ）用の PRC ファイルと一緒にインストールします。これらのファイルは新しいネットワーク設定パネルを提供します。このパネルは、新しいコマンドのサポートとスクリプトプラグインを書く能力のサポートを含みます。
以下のセクションでは、ログインスクリプトの基本的な書き方を説明します。プラグインを書くのに利用する API について詳しくは、「Palm OS Programmer's API Reference」の「スクリプトプラグイン」章を参照して下さい。
ログインスクリプトプラグインを書く
ログインスクリプトプラグインを書くには、通常と同様のプロジェクトを作成します。しかし、データベースタイプは 'appl' ではなく 'scpt' を指定します。もし Metrowerks CodeWarrior を使用しているなら、PalmRez ポストリンカパネルでデータベースタイプを指定します。
PilotMain 関数において、プラグインは 2 つの起動コードに対応する必要があります。
- プラグインが実装するコマンドのネットワーク設定パネルを通知するための scptLaunchCmdListCmds。
- コマンドを実行するための scptLaunchCmdExecuteCmd。
scptLaunchCmdListCmds に対応する
ネットワーク設定パネルは、利用可能なコマンドのプルダウンリスト（これはスクリプトビューで表示されます）を構成するときに scptLaunchCmdListCmds 起動コードを送信します。パネルはこの起動コードを、'scpt' タイプの全ての PRC に送信します。それはパラメータブロックとして PluginInfoType タイプの空の構造体を渡します。プラグインは、構造体に以下の情報を埋めて返答する必要があります。
- プラグインの名前（ PRC ファイルの名前）
- プラグインが実装するコマンドの数（pluginMaxNumOfCmds が許すよりも多くならないこと）
- プラグインが実装する各コマンドの名前を含む配列と、プラグインが引数をとるかどうかを示すブール値
与えられたハンドヘルドは、インストールされた複数のプラグインを持ちます。もしそうなら、結果のプルダウンリストはハンドヘルドにインストールされた全てのプラグインでサポートされる全てのコマンドの結合を含みます。このため、提供するコマンド名がユニークであるように気をつけるべきです。名前にはたった 15 キャラクタだけが許可されるので、名前はできるだけ短くするべきです。
scptLaunchCmdExecuteCmdへの応答
scptLaunchCmdExecuteCmd 起動コードは、ログインスクリプトが実行されているときに送信されます。 つまり、ネットワーク設定パネルで指定されたネットワークサービスにユーザが接続を試みた、そして認証のためにパネルがスクリプトを実行している、ということです。
scptLaunchCmdExecuteCmd パラメータブロックは PluginExecCmdType 型の構造体です。以下のものを含んでいます。
- 実行されるコマンドの名前
- コマンドの引数（必要なら）
- ネットワークインターフェイス関数へのポインタ
- 現在の接続を指定する情報へのハンドル
プラグインは指定されたコマンドを実行するべきです。プラグインがこのコードで実行された場合、それはサブルーチンとして実行され、グローバル変数にはアクセスしません。プラグインが起動されたときにはネットワークライブラリと接続アプリケーション（ HotSync アプリケーションなど）は既に実行されている、ということにも気をつけて下さい。そのため、利用可能なメモリとスタックスペースはかなり限定されます。
プラグインコマンドの働きのほとんどを実行するためにはおそらく、選択されたネットワークサービスが指定するネットワークインターフェイス（ SLIP や PPP など）へのアクセスを必要とします。これにより、ネットワークインターフェイスによって定義されたコールバック関数へのポインタをプラグインが渡します。プラグインは、以下のタスクを実行する必要があるときにこの関数をコールするべきです。
- ネットワークからバイト数を読み取る
- ネットワークにバイト数を書き込む
- ユーザの名前とパスワードの情報を取得する
- 接続ログに文字列を書き込む
- ユーザに情報を教える
- ユーザがキャンセルボタンを押したかどうか確認する
- フォームを表示する
- シリアルライブラリへのアクセスを取得する
コールバックのプロトタイプは ScriptPluginSelectorProc によって定義されます。それが引数としてとるのは、起動コード内で渡された接続固有データのハンドル、ネットワークインターフェイスが行なうべき（ pluginNetLib 定数として指定された）タスク、です。そしてどのタスクが実行されるのかに依存する解釈の一連のパラメータが付随します。
例えば、以下のコードはコマンド「Send Uname」（ユーザ名をホストコンピュータに送信する）を実装します。
Listing 7.2 シンプルスクリプトプラグインコマンド
#define pluginSecondCmd "Send Uname"
UInt32 PilotMain(UInt16 cmd, void *cmdPBP,
UInt16 launchFlags) {
PluginExecCmdPtr execPtr;
UInt32 error = success;
Int16 dataSize = 0;
Char* dataBuffer = NULL;
ScriptPluginSelectorProcPtr selectorTypeP;
if (cmd == scptLaunchCmdExecuteCmd) {
execPtr = (PluginExecCmdPtr)cmdPBP;
selectorTypeP = execPtr->procP->selectorProcP;
dataBuffer = MemPtrNew(pluginMaxLenTxtStringArg+1);
if (!dataBuffer) {
return failure;
}
MemSet(dataBuffer,pluginMaxLenTxtStringArg+1,0);
if (!StrCompare(execPtr->commandName, pluginSecondCmd)) {
/* get the user name from the network interface */
error = (selectorTypeP)(execPtr->handle,
pluginNetLibGetUserName, (void*)dataBufferP,
&dataSize, 0,
NULL);
if (error) goto Exit;
dataSize = StrLen((Char*)dataBufferP);
/* have the network interface send the user name to the host
*/
error = (selectorTypeP)(execPtr->handle,
pluginNetLibWriteBytes, (void*)dataBufferP,
&dataSize, 0,
NULL);
return error;
}
}
もしコマンドがユーザと影響しあう必要があるなら、ネットワークインターフェイスを通して行なうべきです。接続試行が起こったとき、ユーザはネットワーク設定パネルと HotSync アプリケーションの両方を参照します。プラグインは画面の制御を持たないので、単にフォームを表示するだけ、ということはできません。2 つの選択肢があります。
- ネットワークインターフェイスは、ユーザに入力を促してその入力結果を返すことができます。また、ユーザが設定試行をキャンセルしたかどうかを確認するために、ネットワーク設定パネルに問い合わせをすることもできます。
- 入力を促したりキャンセル状態を確認する以上のことをしたいなら、フォームを表示して独自のユーザインターフェイスルーチンをコールするためにコマンド pluginNetLibCallUIProc を使用することができます。
pluginNetLibCallUIProc を使うには、以下のようにします。,
- 生成したフォームリソースを使ってフォームを初期化します。
- フォームのハンドルおよびユーザインターフェイスルーチンで必要とするその他の値を含む構造体を生成します。
- ネットワークインターフェイスのコールバック関数を、 pluginNetLibCallUIProc コマンド・フォームのハンドルとその他適切な情報・インターフェイスルーチンで実行される関数のプラグインにおけるアドレス、とともにコールします。この関数は一つの引数（ネットワークインターフェイスに渡した構造体）をとり、void を返します。
- ネットワークインターフェイスのコールが返されたとき、フォームを閉じます。
pluginNetLibCallUIProc の利用の例は、サンプルコード ScriptPlugin.c 内の WaitForData 関数と promptUser 関数を参照して下さい。
ソケット予告
Palm OS Garnet バージョン 5.4 は、ソケットの状態が変わったときにアプリケーションが応答できるようにするメカニズムを導入しました。例えば、ソケットが閉じているかソケットが TCP データを受け取ったときです。このメカニズムはソケット予告（ socket notice ）と呼ばれます。アプリケーションは通知タイプ（どの Palm OSがアプリケーションと通信したかの手段：例えば、通知の送信による）のコールによってソケット予告を登録します。
- 注
- Palm OS Garnet バージョン 5.4 では、ソケット予告がアプリケーションと通信できるのは通知（ notification ）を通してだけです。ソケット予告を受け取る他の手段は、現時点でサポートされていません。
ソケット通知
「通知を送るソケット予告」をソケット通知（ socket notification ）と呼びます。このセクションでは、アプリケーション内でソケット通知をどのように利用するかを説明します。
- ソケット通知定数（ 予告タイプ ）を定義します。この定数はアプリケーション内でユニークである必要があります。
- SysNotifyRegister() のコールとソケット通知定数およびアプリケーションが通知をハンドルする必要のあるあらゆるデータへのパスによって、通知を登録します。パスする他のパラメータは、sysAppLaunchCmdNotify 起動コードを通して通知を受信したのか、それともコールバック関数によって受信したのか、によって決定されます。
- NetLibSocketOptionSet() をコールしてソケット予告システムを準備します。他のパラメータの間に、NetSocketNoticeType タイプのオプション値へのポインタを渡します。この構造体は、以下の情報をネットライブラリに教えます。
- 予告タイプ。通知を使用するソケット予告を識別するために、定数 netSocketNoticeNotify を使用します。この定数は NoticeTypeEnum で定義されています。
- 通知タイプ。これはアプリケーションで定義されたソケット通知定数です。
- 状態。どのソケットがあなたの興味があるものを変えたのかを示すフラグです。もし全てのソケット状態に興味があるなら、値 0xFFFFFFFF を使用します。Palm OS Programmer's API Reference の「ソケット予告トリガ状態」を参照して下さい。
- 通知のハンドル。
- 受け取ったパラメータブロックを SysNotifyNetSocketType としてキャストします。この型について詳しくは、Palm OS Programmer's API Reference の「ソケット通知指定データ」を参照して下さい。
- どの状態が通知を引き起こしたのかを見つけます。これを行なうには、SysNotifyNetSocketType 構造体の condition フィールドをチェックします。
- 適切なアクションを行ないます。
- 次の通知を受け取るために、ソケット予告システムを再準備します。通常は、通知ハンドラで NetLibSocketOptionSet() をコールすることでそれを実行します。
予告 vs 通知
予告 と 通知 という用語は関係があるように見えますが、別々のものです。 ソケット予告 は、ソケット状態が変わったときにアプリケーションと通信するというネットライブラリ機能です。この通信が起こることには様々な手段があります。しかしその全てが実装されているわけではありません。現時点では、ネットライブラリによってシステムはアプリケーションに通知を送信します。しかし、将来、ネットライブラリがイベントキューにイベントをポストしたり特定のメールボックス ID にメッセージを送信したりできるかもしれません。
NetMgr.h 内のサポートされないコード
もし NetMgr.h を精読しているなら、現時点ではサポートされていませんが将来の Palm OS バージョンでサポートされるかもしれないコードに遭遇するかもしれません。さしあたってそのようなコードは無視します。
- NoticeTypeEnum 定義のほとんど。netSocketNoticeNotify だけが現在使用できます。他の列挙定数（ netSocketNoticeEvent やnetSocketNoticeCallback など）は、Palm OS Garnet バージョン5.4 では利用できません。
- 注
- ソケット予告コールバックは Palm OS Garnet バージョン5.4 ではサポートされません。通知コールバックと混同しないで下さい。それは「ソケット通知?」で示されるように実装されています。
- NetSocketNoticeEventType、NetSocketNoticeMailboxType、NetSocketNoticeCallbackPtr 定義。これらは現時点でサポートされていません。
- NetSocketNoticeType 内の notice 結合のほとんど。その結合内のnotify 構造体だけがサポートされます。event、mailbox、callback、wake 構造体はサポートされません。
関係するセクション
ソケット通知を実行するために、一般的な通知の働き方を理解する必要があるでしょう。そのために、以下のことを提案します。
- Palm OS Programmer's Companion Volume I の第 2 章「アプリケーションの開始と終了」
- Palm OS Programmer's API Reference の第 3 章「通知」
- Palm OS Programmer's API Reference の第 43 章「通知マネージャ」
