[[↑7 章トップへ|Palm OS Programmer's Companion Volume II/7]]　[[2 節に進む　→|Palm OS Programmer's Companion Volume II/7-2]] ---- !!! 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 III{{sup TM}} でおよそ 36KB です。 Palm OS Garnet バージョン 5.4 以降なら、ネットライブラリの最大スタックサイズ・最大アクティブ数・同時ネットワークソケット等の制限を押し付けることはありません。Palm OS デバイスの各製造者が、適切なスタックサイズやアクティブなソケットの数を決定します。 !プログラマのインターフェイス ネットライブラリには本来 2 つの API セットがあります。ネットライブラリのネイティブ API と、Berkeley ソケット API です。2 つの API はお互いに概ね対応しています。Berkeley ソケット API を使用する際に、パフォーマンスのペナルティは無く、また既存のコードを修正する必要もあまりありません。 ヘッダファイル {{span style='color:#000000;font-family:Courier;font-style:normal;font-weight:normal;text-decoration:none;text-transform:none;vertical-align:baseline',}} は、ネットライブラリコールを直接コールする Berkeley ソケットコールをマップしたマクロのセットを含んでいます。ネットライブラリ API と Berkeley ソケット API の主な違いは、ほとんどのネットライブラリAPIコールが以下の追加パラメータを受け入れることです。 *'''参照番号'''。Palm OS における全てのライブラリコールは、ライブラリ参照番号を最初のパラメータとします。 *'''タイムアウト'''。Palm ハンドヘルドのようなコンシューマシステムでは、無限のタイムアウトは適切に動作しません。エンドユーザがプロセスを''殺す''ことができないからです。タイムアウトによって、アプリケーションはハングした接続から優雅に回復することができます。デフォルトのタイムアウトは 2秒です。 *'''エラーコード'''。慣習的に、ソケット API はアプリケーショングローバル変数 {{span style='color:blue;font-family:monospace;',errno}} にエラーコードを戻します。ネットライブラリ API はアプリケーショングローバル変数には依存しません。これにより、システムコード（グローバル変数を持たない）がネットライブラリ API を利用できるようになります。 {{span style='color: #000000; font-family: Courier; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline',sys_socket.h}} 内のマクロは以下のことを行ないます。 ,"For...","The macros pass..." ,参照番号,AppNetRefnum（アプリケーショングローバル変数） ,タイムアウト,AppNetTimeout（アプリケーショングローバル変数） ,エラーコード,アプリケーショングローバル errno の値 例えば、 Berkeley ソケットコール {{span style='color: #000000; font-family: Courier; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline',socket}} の場合は以下のように宣言されます。 Int16 socket(Int16 domain, Int16 type, Int16 protocol); 同等のネットライブラリコールは {{span style='color:blue;font-family:monospace;',NetLibSocketOpen}} で、以下のように宣言されます。 NetSocketRef NetLibSocketOpen(UInt16 libRefnum, NetSocketAddrEnum domain, NetSocketTypeEnum type, Int16 protocol, Int32 timeout, Err* errP) {{span style='color:blue;font-family:monospace;',socket}} のマクロは以下の通りです。 #define socket(domain,type,protocol) \ NetLibSocketOpen(AppNetRefnum, domain, type, protocol, AppNetTimeout, &errno) !!ネットライブラリの利用手順 一般的に、ネットライブラリの利用は以下の一覧のようなステップを含みます。次のいくつかのセクションで、そのステップについて詳しく説明します。 ネットライブラリ利用の例として、{{span style='color:blue;font-family:monospace;',Palm OS Examples}} ディレクトリ内のサンプルアプリケーション {{span style='color:blue;font-family:monospace;',NetSample}} を参照して下さい。多くのネットライブラリコールの練習になります。 +ネットライブラリ参照番号の取得{{br}}ネットライブラリはシステムライブラリなので、全てのネットライブラリコールはライブラリ参照番号を最初のパラメータとします。このため、まず参照番号を取得してそれを保存します。「ネットライブラリ参照番号の取得」を参照して下さい。{{br}}Berkeley ソケット API を利用するためのセットアップをします。{{br}}ネットライブラリを使って行ないたいことの多くが、ネットライブラリのネイティブAPIまたは Berkeley ソケット API のどちらを利用しても実現できます。もし既に Berkeley ソケット API に慣れ親しんでいるなら、おそらくネイティブAPIではなくそちらを使いたいでしょう。もしそうなら、「Berkeley ソケット API のセットアップ」の手順に従って下さい。 +もし必要なら、ネットライブラリをやりたいように設定します。{{br}}一般的に、ユーザはネットワーク設定パネルを使ってネットワークサービスをセットアップします。ほとんどのアプリケーションはそれ自身がネットワークサービスをセットアップしません。それらは単にネットライブラリ設定データベースを通してネットワークサービスにアクセスするだけです。アプリケーションがネットワーク設定を行ない、それは通常ネットライブラリを開く前に行なうべき、ということもまれにあります。「セットアップおよび設定コール」を参照して下さい。 +最初のネットワークアクセスの前にネットライブラリを開きます。{{br}}Palm OS環境のリソースは限定されているため、アプリケーションが実際にそのサービスを必要とするときにだけ追加のメモリを要求するように、ネットライブラリはデザインされています。そのため、インターネットアプリケーションがネットライブラリを開く・開始する・終了して閉じる際にはシステムにネットライブラリを必要とすることを通知します。「ネットライブラリを開く」を参照して下さい。 +ネットワークにアクセスするためにコールします。{{br}}一度ネットライブラリが開かれたなら、Berkeley ソケット API かネイティブネットライブラリ API を使って、ソケットが開かれデータが送信されリモートホストから受信されます。「ネットワーク I/O およびユーティリティコール」を参照して下さい。 +終了時にネットライブラリを閉じます。{{br}}ネットライブラリを閉じることで、リソースを解放します。「ネットライブラリを閉じる」を参照して下さい。 !!ネットライブラリ参照番号の取得 参照番号を決定するために、{{span style='color:blue;font-family:monospace;',AppNetRefnum}} をコールします。 err = SysLibFind("Net.lib", &AppNetRefnum); if (err) {/* error handling here */} ネットライブラリは Palm OS 2.0 以降が必要なことを覚えておいて下さい。もし {{span style='color:blue;font-family:monospace;',SysLibFind}} コールがネットライブラリを見つけることができない場合は、エラーコードを戻します。 !!Berkeley ソケット API のセットアップ Berkeley ソケット API の利用をセットアップ するには、以下のようにします。 *ヘッダファイル {{span style='font-family: Courier;',}}を含めます。このヘッダファイルは Palm OS SDK で提供されます。 *プロジェクトをモジュール {{span style='color:blue;font-family:monospace;',NetSocket.c}} にリンクします。このモジュールは3つの必要なグローバル変数（{{span style='font-family: Courier;',AppNetTimeout}}、{{span style='font-family: Courier;',AppNetRefnum}}、{{span style='font-family: Courier;',errno}}）を宣言し初期化します。{{span style='color:blue;font-family:monospace;',NetLibSocket.c}} も、いくつかの Berkeley ソケット関数に必要な glue コードを含んでいます。 *以前のセクションで説明したように、ネットライブラリの参照番号を変数 {{span style='color:blue;font-family:monospace;',AppNetRefnum}} に割り当てます。 *必要であれば、{{span style='color:blue;font-family:monospace;',AppNetTimeout}} の値を調節します。 *この値は、ネットライブラリコールが期限切れになるまで待つシステムの最大ティック値を表します。ほとんどのアプリケーションで、このタイムアウト値を調節し場合によっては別のコードセクションでも調節します。以下の例はタイムアウト値を 10 秒にセットしています。 AppNetTimeout = SysTicksPerSecond() * 10; !!セットアップおよび設定コール ネットライブラリの API コールをセットアップし設定することは、通常はネットワーク設定パネルを使ってのみ行われます。これは、IP アドレス・ホスト名・ドメイン名・ログインスクリプト・インターフェイス設定…などをセットするコールを含みます。各セットアップおよび設定コールは、後々の検索のために、ランタイムコールによって不揮発性ストレージのネットライブラリプリファレンスデータベースにその設定を保存します。 アプリケーションがそれ自身をセットアップおよび設定することも、まれにあります。例えば、接続確立試行前に特定の「サービス」をユーザに選択させるアプリケーションもあるかもしれません。そのようなアプリケーションは、サービス名のピックリストを持ち、ユーザにサービス名を選択させます。この機能はネットワーク設定パネルを経由して提供されます。パネルは、エンドユーザが選ぶことのできるサービス名の一覧をアプリケーションが示すことを可能にする起動コード（ {{span style='color:blue;font-family:monospace;',SystemMgr.h}} で定義されています）を提供します。設定パネルによって、特定のサービスをセットアップするのに必要なコール（＝ネットライブラリセットアップおよび設定コール）を行なうことができます。 通常は、セットアップおよび設定コールはライブラリが閉じているときに行なわれます。コールのサブセットは、ライブラリが開かれている間に発行されます。また、コールのサブセットはライブラリの振る舞いにおけるリアルタイムな影響があります。''Palm OS Programmer's API Reference'' の[[第 66 章「ネットライブラリ」]]で、各コールについて詳しく説明しています。 !インターフェイス選択のセッティング 「ネットライブラリについて」セクションで学習したように、ネットライブラリは低レベルネットワークプロトコルを抽象化するために一つ以上のネットワークインターフェイスを使用します。ユーザは、使用するネットワークインターフェイスをネットワーク設定パネルから指定します。 また、どのインターフェイスが使われるべきかを特定するためにネットライブラリコールを使用することもできます。 *{{span style='color:blue;font-family:monospace;',NetLibIFAttach}} は、ライブラリが開かれているときに使用するためにインターフェイスをライブラリにアタッチします。 *{{span style='color:blue;font-family:monospace;',NetLibIFDetach}} は、インターフェイスをライブラリからデタッチします。 *{{span style='color:blue;font-family:monospace;',NetLibIFGet}} はインターフェイスのクリエータとインスタンス値を戻します。 ほとんどのネットライブラリ関数とは異なり、これらの関数はライブラリが開いているか閉じているかの間にコールできます。もしライブラリが開いているなら、特定のインターフェイスがリアルタイムにアタッチまたはデタッチされます。もしライブラリが閉じているなら、アクティブな設定に情報が保存されます。設定について詳しくは [[「ネットワーク設定」]] を参照して下さい。 各インターフェイスは、クリエータとインスタンス値によって識別されます。もしインターフェイスをアタッチまたはデタッチしたり、インターフェイス設定を問い合わせるまたはセットするなら、これらの値が必要になります。これらの情報を取得するには、{{span style='color:blue;font-family:monospace;',NetLibIFGet}} を使用します。{{span style='color:blue;font-family:monospace;',NetLibIFGet}} は 4 つのパラメータをとります。ネットライブラリの参照値、ライブラリのインターフェイスリストへのインデックス、クリエータとインスタンス値が戻される 2 つの変数のアドレス、です。 クリエータは以下の値のどれかです。 *{{span style='color:blue;font-family:monospace;',netIFCreatorLoop}}（ループバックネットワーク） *{{span style='color:blue;font-family:monospace;',netIFCreatorSLIP}}（SLIP ネットワーク） *{{span style='color:blue;font-family:monospace;',netIFCreatorPPP}}（PPP ネットワーク） 情報を取得したいインターフェイスが分かっているなら、ネットワークインターフェイスリストを通して連続したインデックス値で必要なクリエータ値を持つインターフェイスが戻されるまで繰り返し {{span style='color:blue;font-family:monospace;',NetLibIFGet}} をコールすることができます。 !インターフェイス固有のセッティング ネットライブラリ設定は構造化されており、そのためネットワークインターフェイス固有のセッティングが各ネットワークインターフェイスごとに独立して指定されます。これらのインターフェイス固有セッティングは、IF セッティングをコールされ、{{span style='color:blue;font-family:monospace;',NetLibIFSettingSet}} コールを通してセットおよび検索されます。 *{{span style='color:blue;font-family:monospace;',NetLibIFSettingGet}} コールはパラメータとして、セッティングの戻り値のためのバッファポインタとバッファサイズとともにセッティング ID をとります。ログインスクリプトのような可変長セッティングは、セッティング全体を検索するのに充分な大きさのバッファをアロケートする準備を呼び出し元がしておく必要があります（もしバッファのために {{span style='color:blue;font-family:monospace;',NULL}} を渡すなら、{{span style='color:blue;font-family:monospace;',NetLibIFSettingGet}} は必要なサイズを戻します）。詳しくは、リファレンスの {{span style='color:blue;font-family:monospace;',NetLibIFSettingGet}} 定義を参照して下さい。 *{{span style='color:blue;font-family:monospace;',NetLibIFSettingSet}} コールもパラメータとして、新しいセッティング値へのポインタと新しいセッティングのサイズとともにセッティング ID をとります。 *もしログインスクリプトをセットするために {{span style='color:blue;font-family:monospace;',NetLibIFSettingSet}} を使用しているなら、次のセクションを参照して下さい。 これらの関数の利用例として、{{span style='color:blue;font-family:monospace;',Palm OS Examples}} ディレクトリ内の {{span style='color:blue;font-family:monospace;',NetSample}} サンプルアプリケーションを参照して下さい。例えば、{{span style='color:blue;font-family:monospace;',CmdInfo.c}} ファイル内の {{span style='color:blue;font-family:monospace;',CmdSettings}} 関数は、ネットワークインターフェイス全てについての情報を取得しループするやり方を示しています。 !インターフェイスのログインスクリプトのセッティング {{span style='color:blue;font-family:monospace;',netIFSettingLoginScript}} セッティングは、インターフェイスのためのログインスクリプトを保持するために使用されます。ログインスクリプトは、ユーザがネットワーク設定パネルに入力したスクリプトかもしくは HotSync{{sup (R)}} 操作によってハンドヘルドにダウンロードされたスクリプトファイルのどちらかから生成されます。スクリプトのフォーマットは厳格です。もし誤った文法のログインスクリプトがネットライブラリに提示されたなら、予期されない結果となります。基本的なフォーマットは、スクリプトの終わりにヌルバイトが付いた、ヌルで終了する一連のコマンド行です。各コマンド行にはフォーマットがあります。 <コマンドバイト> [<パラメータ>] コマンドバイトは行の最初のキャラクタであり、コマンドバイトとパラメータ文字列の間には 1 文字の空白だけがあります。表 7,1 は可能なコマンドの一覧です。 '''表 7.1 ログインスクリプトコマンド''' ,機能,コマンド,パラメータ,例 ,送信,"{{span style='color:blue;font-family:monospace;',s}}",文字列,"{{span style='color:blue;font-family:monospace;',s go PPP}}" ,待機,"{{span style='color:blue;font-family:monospace;',w}}",文字列,"{{span style='color:blue;font-family:monospace;',w password:}}" ,遅延,"{{span style='color:blue;font-family:monospace;',d}}",秒,"{{span style='color:blue;font-family:monospace;',d 1}}" ,IP の取得,"{{span style='color:blue;font-family:monospace;',g}}",,"{{span style='color:blue;font-family:monospace;',g}}" ,プロンプト,"{{span style='color:blue;font-family:monospace;',a}}",文字列,"{{span style='color:blue;font-family:monospace;',a Enter Name:}}" ,プロンプトの待機","{{span style='color:blue;font-family:monospace;',f }}",文字列,"{{span style='color:blue;font-family:monospace;',f ID:}}" ,CR の送信,"{{span style='color:blue;font-family:monospace;',s}}",文字列,"{{span style='color:blue;font-family:monospace;',s ^M}}" ,ユーザ IDの送信,"{{span style='color:blue;font-family:monospace;',s}}",文字列,"{{span style='color:blue;font-family:monospace;',s jdoe }}" ,パスワードの送信,"{{span style='color:blue;font-family:monospace;',s}}",文字列,"s ''mypassword''" ,プラグインコマンド{{sup ※1}},"{{span style='color:blue;font-family:monospace;',sp}}",文字列,"sp ''plugin'':''cmd'':''arg''" ※1:「ネットワークログインスクリプトサポートの拡張」を参照 送信（ {{span style='color:blue;font-family:monospace;',s}} ）コマンドのパラメータ文字列は、表 7.2 に示すエスケープシーケンスを含むことができます。 '''表 7.2 送信コマンドエスケープシーケンス''' ,エスケープ{{br}}シーケンス,内容 ,$USERID,ユーザ名 ,$PASSWORD,パスワード ,$DBUSERID,ダイヤルバックユーザ名 ,$DBPASSWORD,ダイヤルバックパスワード ,^c,"if c is '@' -> '_', then byte value 0 -> 31 {{br}}else if c is 'a' -> 'z', then byte value 1 -> 26{{br}}else c" ,,キャリッジリターン (0x0D) ,,ラインフィード (0x0A) ,"\""","""" ,"\^","^" ,"\<","<" ,"\\","\" ログインスクリプトはデスクトップコンピュータ上に作成され、同期中にハンドリングにインストールされる、ということに注意して下さい。スクリプトコマンドは、ダイヤルアップネットワーク用の Windows ダイヤルアップスクリプトコマンド言語に似ています。Microsoft のドキュメントは、{{span style='color:blue;font-family:monospace;',Windows}} フォルダの {{span style='color:blue;font-family:monospace;',Script.doc}} ファイルを検索して下さい。Palm OS のネットワーク設定パネルは、以下のコマンドのサブセットをサポートします。 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'']" {{span style='color:blue;font-family:monospace;',plugin}} コマンドは、プラグインで定義されたコマンドを実行するのに使用される Palm OS 独自の拡張です。プラグインについて詳しくは「ネットワークログインスクリプトサポートの拡張」を参照して下さい。 拡張子を {{span style='color:blue;font-family:monospace;',.pnc}} または {{span style='color:blue;font-family:monospace;',.scp}} としてスクリプトファイルを作成し、そのファイルをユーザのインストールディレクトリに置きます。次の HotSync 操作時に、ネットワークコンジットがそのファイルをダウンロードします。各スクリプトファイルは 、サービス定義を 1 つだけ含みます。 !一般的なセッティング インターフェイス固有のセッティングに加えて、特定のインターフェイスには適用されないセッティングのクラスがあります。これらの一般的なセッティングは、{{span style='color:blue;font-family:monospace;',NetLibSettingSet}} コールを通してセットおよび検索されます。これらのコールはパラメータとして、セッティング ID・バッファポインタ・バッファサイズをとります。 !ネットワーク設定 Palm OS 3.2 以降では、ネットワーク設定をサポートします。'''設定''' はユーザがインターネットに接続する特定の方法を取り込みます。ネットライブラリは設定の配列を維持します。ネットライブラリが開いたときに、その設定配列の 1 つが接続のネットワークセッティングに提供されます。 設定は以下の情報を含みます。 *ネットライブラリが使用するネットワークインターフェイス。ネットライブラリが開いたとき、これらのネットワークインターフェイスが起動します。 *一般的なネットライブラリセッティング。これらは {{span style='color:blue;font-family:monospace;',NetLibSettingGet}} や {{span style='color:blue;font-family:monospace;',NetLibSettingSet}} 関数によってアクセスされるセッティングです。{{sup ※1}} ※1:トレースセッティングを除く。これらのセッティングはグローバルであり、別の設定と区別されない。 設定配列はソフトリセット後も変更されません。ハードリセット後に削除され、最初期化されます。設定配列のダイアグラムについては [[図 7.1]] を参照してください。 '''図 7.1 設定のアーキテクチャ''' {{img Configuration.gif}} 設定は'''エイリアス'''をとることができます。エイリアスは設定情報を含んでいません。かわりに、他の設定を指し示します。ネットライブラリは以下の各設定についてエイリアスを定義しています。 *一般的利用のデフォルト設定 *一般的利用の有線設定 *一般的利用の無線設定 *Palm.net プロクシサーバを利用した有線設定 *Palm.net プロクシサーバを利用した無線設定 API のどこででも、設定を指定するのにエイリアスを指定することができます。 設定配列の最初の設定に対するエイリアスの例は、'''デフォルト設定'''と呼ばれます。ネットライブラリを開くのに {{span style='color:blue;font-family:monospace;',NetLibOpen}} をコールしたとき、ネットライブラリはこの設定から接続セッティングを取得します。デフォルト設定は典型的に、{{span style='color:blue;font-family:monospace;',NetPanel}} と呼ばれる 6 つの設定（実際にセッティングを含む）を指し示します。そのため、{{span style='color:blue;font-family:monospace;',NetLibOpen}} をコールしたとき、ネットライブラリはそのセッティングを {{span style='color:blue;font-family:monospace;',NetPanel}} 設定から取得します。「ネットライブラリを開く」を参照してください。 ネットライブラリは、'''アクティブ設定'''と呼ばれる他の特殊な設定を維持します。この設定は、ネットライブラリが最後に開いたときに使用された設定のコピーです。ネットワークインターフェイスからアタッチ／デタッチしたとき、あるいは一般的ネットライブラリセッティングを変更したとき、アクティブ設定が変更されます。このようなアクティブ設定の変更は、保持された設定には影響を与えません。 :注:アクティブ設定内のセッティングによってネットライブラリを開くことはできません。ネットライブラリを開くためにそのセッティングを使用する前に、アクティブ設定を保存する必要があります。 ネットライブラリは設定を管理するための関数を提供します。これらの関数は {{span style='color:blue;font-family:monospace;',NetLibConfig}} で始まる名前を持っています。 *{{span style='color:blue;font-family:monospace;',NetLibConfigList}} は、全ての設定の一覧を名前で返します。利用可能な一覧を表示し、利用するものを選ばせるのにこれを使うことができます。 *{{span style='color:blue;font-family:monospace;',NetLibConfigIndexFromName}} は、名前から設定のインデックス番号を取得します。ほとんどの設定関数では、設定を参照するのに名前のかわりにインデックス番号を使用します。 *{{span style='color:blue;font-family:monospace;',NetLibConfigAliasGet}} は設定エイリアスの値を取得します。 *{{span style='color:blue;font-family:monospace;',NetLibConfigAliasSet}} は特定の設定を指定するためのエイリアスをセットします。 *{{span style='color:blue;font-family:monospace;',NetLibConfigSaveAs}} は新しい設定を定義し名前で保存します。 *{{span style='color:blue;font-family:monospace;',NetLibConfigDelete}} は一覧から設定を削除します。 :警告!:ネットワークパネルは設定をインターフェイスします。ユーザがネットワークパネルでサービスを修正してから終了したとき、ネットワークパネルは「{{span style='color:blue;font-family:monospace;',NetPanel}}」設定を上書きし、「{{span style='color:blue;font-family:monospace;',NetPanel}}」設定を指すようにデフォルト設定エイリアスをリセットします。 アプリケーションは無線通信を必要とするかもしれません。ユーザのデフォルト無線セットアップにアクセスし、以下の方法（ {{span style='color:blue;font-family:monospace;',netCfgNameDefWireless}} 定数はデフォルト無線設定エイリアスの名前を定義します）でネットライブラリを初期化するのにそれを使用します。 UInt16 configIndex, ifErr; Err err; err = NetLibConfigIndexFromName(ref, netCfgNameDefWireless, &configIndex); if (!err) err = NetLibOpenConfig(ref, configIndex, 0, &ifErr); Listing 7.1 は設定関数の別の利用例を示しています。カスタムネットワークインターフェイスを利用する設定をどのように作成するか、を示しています。また、{{span style='color:blue;font-family:monospace;',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; } !!ネットライブラリを開く {{span style='color:blue;font-family:monospace;',netErrNotOpen}} をコールしたエラーコードです。 err = NetLibOpen(AppNetRefnum, &ifErrs); if (err || ifErrs) {/* error handling here */} 複数のアプリケーションが一度にライブラリを開くことができます。そのため、{{span style='color:blue;font-family:monospace;',NetLibOpen}} がコールされるときにネットライブラリは既に開いているかもしれません。もしそうなら、関数はライブラリの'''オープンカウント'''を増やします。オープンカウントには、アクセス中アプリケーションの数が保持され、即座に返されます。（ {{span style='color:blue;font-family:monospace;',NetLibOpenCount}} 関数で、オープンカウントを検索することができます。） もしネットライブラリがまだ開かれていないなら、NetLibOpen はネットプロトコルスタックタスクを開始し、ネットライブラリが内部で使用するメモリをアロケートし、そしてネットワーク接続を開始します。たいてい、Palm Powerd ハンドヘルドが SLIP または PPP 接続をモデムを通して確立するようにユーザが設定しています。また、この種のセットアップでは、{{span style='color:blue;font-family:monospace;',NetLibOpen}} がモデムをダイヤルアップし戻る前に接続を確立します。 もしアタッチされたネットワークインターフェイス（ SLIP や PPP ）が繋がるのに失敗したら、問題のあった最初のインターフェイスのエラー番号が最後のパラメータ（上記の例における {{span style='color:blue;font-family:monospace;',ifErrs}}）に格納されます。 そして同様に、一つ以上のインターフェイスが（不正なモデムセッティングやサービスダウンなどによって）繋がるのに失敗しても、ネットライブラリは開かれます。そのため、もしエラーパラメータが非ゼロでも、アプリケーションは {{span style='color:blue;font-family:monospace;',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 以降では、特定のネットワーク設定によってネットライブラリを開くことができます（{{span style='color:blue;font-family:monospace;',NetLibOpenConfig}} を参照）。一般的に 、設定のエイリアスを指定します。例えば、アプリケーションが有線ネットワークを要求するなら、ユーザのデフォルト有線接続を指定するために {{span style='color:blue;font-family:monospace;',netCfgNameDefWireline}}設定でネットライブラリを開きます。Palm OS 3.2 以降では、{{span style='color:blue;font-family:monospace;',NetLibOpen}} は単純に {{span style='color:blue;font-family:monospace;',NetLibOpenConfig}} （ユーザのデフォルト設定を指定する）をコールするだけです。 !!ネットライブラリを閉じる アプリケーションが終了する前に、またはネットワーク I/O が必要なくなったら、{{span style='color:blue;font-family:monospace;',NetLibClose}} をコールするべきです。 err = NetLibClose(AppNetRefnum, false); {{span style='color:blue;font-family:monospace;',NetLibClose}} は単純にオープンカウントを減少させます。{{span style='color:blue;font-family:monospace;',false}} パラメータは、もしオープンカウントがゼロになったらネットライブラリをすぐに閉じるかどうかを指定します。かわりに、{{span style='color:blue;font-family:monospace;',NetLibClose}} は、タイマが期限切れになる前に他の {{span style='color:blue;font-family:monospace;',NetLibOpen}} が発行されない限りネットライブラリをシャットダウンするタイマをスケジュールします。ネットライブラリのオープンカウントがゼロだがタイマは期限切れになっていない場合、'''閉じ待ち状態'''として参照されます。 ネットライブラリが閉じるまでどれだけ待つかは、ユーザによってネットワーク設定パネルでのみセットされます。このタイムアウト値によって、他のネットワーク接続を確立するのを待たずに一定の時間以内であるネットワークアプリケーションを終了して別のアプリケーションを起動する、ということができます。 もし閉じるタイマが期限切れになる前に {{span style='color:blue;font-family:monospace;',NetLibOpen}} がコールされたなら、戻る前に、タイマはキャンセルされライブラリはオープンカウント 1 で完全に開いているものとしてマークされます。もし他の NetLibOpen が発行される前にタイマが期限切れになるなら、存在する全てのネットワーク接続は落とされ、ネットプロトコルスタックタスクは終了され、ネットライブラリが解放されたことによる全てのメモリは内部使用にアロケートされます。 ネットライブラリが閉じ待ち状態に入ることを許可することが推奨されます。しかし、もしネットライブラリがすぐに閉じる必要があるなら、2 つのうち 1 つを行なうことができます。 *{{span style='color:blue;font-family:monospace;',NetLibClose}} の第二パラメータを {{span style='color:blue;font-family:monospace;',true}} にセットします。このパラメータは、ライブラリがすぐに閉じるべきかどうかを指定します。 *{{span style='color:blue;font-family:monospace;',NetLibFinishCloseWait}} をコールします。この関数は、ネットライブラリが閉じ待ち状態にあるなら即座に閉じるためにネットライブラリをチェックします。 !!バージョンチェック ネットライブラリがインストールされているかどうかを決定するために {{span style='color:blue;font-family:monospace;',SysLibFind}} を使用するのに加えて、アプリケーションはライブラリバージョンフィーチャを参照することもできます。このフィーチャは、ネットライブラリがインストールされているときだけ存在します。このフィーチャは、ネットライブラリのバージョン番号を取得するために以下のように使用されます。 UInt32* version; err = FtrGet(netFtrCreator, netFtrNumVersion, &version); もしネットライブラリがインストールされていないなら、FtrGet がゼロ以外の結果コードを返します。 バージョン番号は {{span style='color:blue;font-family:monospace;',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コールを与えます。 *{{span style='color:blue;font-family:monospace;',Palm OS Examples}} ディレクトリ内の {{span style='color:blue;font-family:monospace;',NetSample}} サンプルアプリケーションは、Palm OS アプリケーションで Berkeley ソケット API を使う方法を示しています。 !!Berkeley ソケット API 関数 このセクションは、Berkeley ソケット API においてネットライブラリによってサポートされる関数の一覧表を提供します。いくつかの場合では、コールはソケットAPIの完全な実装に見られる機能性と比べて限定された機能性を持ちます。また、これらの制限はここで説明されます。 !ソケット関数 ,Berkeley ソケット関数,ネットライブラリ関数,詳細 ,accept,"{{span style='color:blue;font-family:monospace;',NetLibSocketAccept}}",ストリームベースソケットからの接続を受け入れます。 ,"{{span style='color:blue;font-family:monospace;',bind}}","{{span style='color:blue;font-family:monospace;',NetLibSocketBind}}",ソケットをローカルアドレスにバインドします。 ,"{{span style='color:blue;font-family:monospace;',close}}","{{span style='color:blue;font-family:monospace;',NetLibSocketClose}}",ソケットを閉じます。 ,"{{span style='color:blue;font-family:monospace;',connect}}","{{span style='color:blue;font-family:monospace;',NetLibSocketConnect}}",接続を確立するために、ソケットをリモートエンドポイントに接続します。 ,"{{span style='color:blue;font-family:monospace;',fcntl}}","{{span style='color:blue;font-family:monospace;',NetLibSocketOptionSet}}{{br}}{{span style='color:blue;font-family:monospace;',NetLibSocketOptionGet}}{{br}}{{span style='color:blue;font-family:monospace;',(...,netSocketOptSockNonBlocking,...)}}","ソケット {{span style='color:blue;font-family:monospace;',refnum}}でのみサポートされ、{{span style='color:blue;font-family:monospace;',F_SETFL}} と {{span style='color:blue;font-family:monospace;',F_GETFL}} コマンドのみサポートします。{{br}}コマンドは、{{span style='color:blue;font-family:monospace;',FNDELAY}} フラグ（flag in the argument parameter appropriately — all other flags are ignored）をセットすることでソケットを非ブロックモードにするのに使用されます。{{br}}{{span style='color:blue;font-family:monospace;',F_SETFL}}・{{span style='color:blue;font-family:monospace;',F_GETFL}}・{{span style='color:blue;font-family:monospace;',FNDELAY}} 定数は {{span style='color:blue;font-family:monospace;',}} 内で定義されています。" ,"{{span style='color:blue;font-family:monospace;',getpeername}}","{{span style='color:blue;font-family:monospace;',NetLibSocketAddr}}",接続のためのリモートソケットアドレスを取得します。 ,"{{span style='color:blue;font-family:monospace;',getsockname}}","{{span style='color:blue;font-family:monospace;',NetLibSocketAddr}}",接続のローカルソケットアドレスを取得します。 ,"{{span style='color:blue;font-family:monospace;',getsockopt}}","{{span style='color:blue;font-family:monospace;',NetLibSocketOptionGet}}","ソケットのコントロールオプションを取得します。{{br}}以下のオプションだけが実装されています。{{br}}・{{span style='color:blue;font-family:monospace;',TCP_NODELAY}}{{br}}アプリケーションに TCP 出力バッファリングアルゴリズムを無効にさせ、それによって TCP はできる限りすぐに小さいパケットを送信します。{{br}}この定数は {{span style='color:blue;font-family:monospace;',}}で定義されています。{{br}}・{{span style='color:blue;font-family:monospace;',TCP_MAXSEG}}TCP 最大セグメントサイズを取得します。{{br}}この定数は {{span style='color:blue;font-family:monospace;',}}で定義されています。{{br}}・{{span style='color:blue;font-family:monospace;',SO_KEEPALIVE}}{{br}}接続で交換されたデータが無いときに調査セグメントの定期的な転送を可能にします。{{br}}もしリモートエンドポイントが反応しないなら、接続は壊れていると判断され、{{span style='color:blue;font-family:monospace;',so_error}} が {{span style='color:blue;font-family:monospace;',ETIMEOUT}} にセットされます。{{br}}・{{span style='color:blue;font-family:monospace;',SO_LINGER}}{{br}}ソケットが閉じられたときに未送信データをどうするか指定します。{{br}}{{span style='color:blue;font-family:monospace;',}} で定義された {{span style='color:blue;font-family:monospace;',linger}} 構造体を使用します。{{br}}・{{span style='color:blue;font-family:monospace;',SO_ERROR}}{{br}}{{span style='color:blue;font-family:monospace;',so_error}} 変数の値を返します。{{br}}これは {{span style='color:blue;font-family:monospace;',}} で定義されています。{{br}}・{{span style='color:blue;font-family:monospace;',SO_TYPE}}呼び出し元にソケットタイプを返します。" ,"{{span style='color:blue;font-family:monospace;',listen}}","{{span style='color:blue;font-family:monospace;',NetLibSocketListen}}","ソケットが自分への接続要求を受け入れるようにセットアップします。{{br}}キューサイズは 1 に限定されます。{{br}}1 より大きい値は無視されます。" ,"{{span style='color:blue;font-family:monospace;',read,recv,recvmsg,recvfrom}}","{{span style='color:blue;font-family:monospace;',NetLibReceive}}{{br}}{{span style='color:blue;font-family:monospace;',NetLibReceivePB}}","ソケットからデータを読み取ります。{{br}}{{span style='color:blue;font-family:monospace;',recv}}、{{span style='color:blue;font-family:monospace;',recvmsg}}、{{span style='color:blue;font-family:monospace;',recvfrom}} コールは {{span style='color:blue;font-family:monospace;',MSG_PEEK}} フラグをサポートしますが {{span style='color:blue;font-family:monospace;',MSG_OOB}} や {{span style='color:blue;font-family:monospace;',MSG_DONTROUTE}} フラグはサポートしません。" ,"{{span style='color:blue;font-family:monospace;',select}}","{{span style='color:blue;font-family:monospace;',NetLibSelect}}","アプリケーションが複数の I/O イベントをブロックするようにします。{{br}}複数の I/O イベントが発生したときにシステムはアプリケーションプロセスを起動します。{{br}}この関数は、{{span style='color:blue;font-family:monospace;',}} で定義された {{span style='color:blue;font-family:monospace;',timeval}} 構造体と {{span style='color:blue;font-family:monospace;',sys/types.h}} で定義された {{span style='color:blue;font-family:monospace;',fd_set}} 構造体を使用します。{{br}}{{span style='color:blue;font-family:monospace;',}} で定義された以下の 4 つのマクロがこの関数に関連づけられます。{{br}}・{{span style='color:blue;font-family:monospace;',FD_ZERO}}*{{span style='color:blue;font-family:monospace;',FD_SET}}{{br}}・{{span style='color:blue;font-family:monospace;',FD_CLR}}{{br}}・{{span style='color:blue;font-family:monospace;',FD_ISSET}}{{br}}ソケット修飾子に加えて、この関数は「stdin」修飾子 {{span style='color:blue;font-family:monospace;',sysFileDescStdIn}} とともに機能します。{{br}}この修飾子は、ユーザまたはシステムイベントがイベントキュー内で利用可能であるときにはいつも入力の準備ができているものとしてマークされます。{{br}}これは、{{span style='color:blue;font-family:monospace;',EvtGetEvent}} で返されるあらゆるイベントを含みます。{{br}}{{span style='color:blue;font-family:monospace;',sysFileDescStdIn}} と {{span style='color:blue;font-family:monospace;',refnum}} ソケット以外の修飾子は許可されません。" ,"{{span style='color:blue;font-family:monospace;',send,sendmsg,sendto}}","{{span style='color:blue;font-family:monospace;',NetLibSend}}{{br}}{{span style='color:blue;font-family:monospace;',NetLibSendPB}}","これらの関数はデータをソケットに書き込みます。{{br}}これらのコールは、{{span style='color:blue;font-family:monospace;',recv}} コールとは異なり、{{span style='color:blue;font-family:monospace;',MSG_OOB}} フラグをサポート''します''。{{br}}{{span style='color:blue;font-family:monospace;',MSG_PEEK}} フラグは利用できません。{{br}}また、{{span style='color:blue;font-family:monospace;',MSG_DONTROUTE}} フラグはサポートされません。" ,"{{span style='color:blue;font-family:monospace;',setsockopt}}","{{span style='color:blue;font-family:monospace;',NetLibSocketOptionSet}}","この関数はソケットのコントロールオプションをセットします。{{br}}以下のオプションだけが許可されます。{{br}}・{{span style='color:blue;font-family:monospace;',TCP_NODELAY}}{{br}}・{{span style='color:blue;font-family:monospace;',SO_KEEPALIVE}}{{br}}・{{span style='color:blue;font-family:monospace;',SO_LINGER}}" ,"{{span style='color:blue;font-family:monospace;',shutdown}}","{{span style='color:blue;font-family:monospace;',NetLibSocketShutdown}}","{{span style='color:blue;font-family:monospace;',close()}} に似ています。{{br}}しかし、全二重接続をこえるコントロールを呼び出し元に与えます。" ,"{{span style='color:blue;font-family:monospace;',socket}}","{{span style='color:blue;font-family:monospace;',NetLibSocketOpen}}","通信のためのソケットを生成します。{{br}}有効なアドレスファミリは {{span style='color:blue;font-family:monospace;',AF_INET}} です。{{br}}{{span style='color:blue;font-family:monospace;',SOCK_STREAM}} と {{span style='color:blue;font-family:monospace;',SOCK_DGRAM}}だけが有効なソケットタイプです。{{br}}また、Palm OS バージョン 3.0 以降では、{{span style='color:blue;font-family:monospace;',SOCK_RAW}}も有効です。{{br}}プロトコルパラメータにはゼロをセットします。" ,"{{span style='color:blue;font-family:monospace;',write}}","{{span style='color:blue;font-family:monospace;',NetLibSend}}",ソケットにデータを書き込みます。 !サポートされるネットワークユーティリティ関数 ,Berkeley ソケット関数,ネットライブラリ関数,詳細 ,"{{span style='color:blue;font-family:monospace;',getdomainname}}","{{span style='color:blue;font-family:monospace;',NetLibSocketOptionGet}}{{br}}{{span style='color:blue;font-family:monospace;',netSettingDomainName,...)}}",ローカルホストのドメイン名を返します。 ,"{{span style='color:blue;font-family:monospace;',gethostbyaddr}}","{{span style='color:blue;font-family:monospace;',NetLibGetHostByAddr}}","ホストの IP アドレスから与えられるホスト情報を参照します。{{br}}{{span style='color:blue;font-family:monospace;',}} で定義された {{span style='color:blue;font-family:monospace;',hostent}} 構造体を返します。" ,"{{span style='color:blue;font-family:monospace;',gethostbyname}}","{{span style='color:blue;font-family:monospace;',NetLibGetHostByName}}","ホスト名から与えられるホスト情報を参照します。{{br}}{{span style='color:blue;font-family:monospace;',}}で定義された {{span style='color:blue;font-family:monospace;',hostent}} 構造体を返します。" ,"{{span style='color:blue;font-family:monospace;',gethostname}}","{{span style='color:blue;font-family:monospace;',NetLibSettingGet(netSettingHostName...)}}",ローカルホストの名前を返します。 ,"{{span style='color:blue;font-family:monospace;',getservbyname}}","{{span style='color:blue;font-family:monospace;',NetLibGetServByName}}","サービス名で与えられる {{span style='color:blue;font-family:monospace;',}} で定義された {{span style='color:blue;font-family:monospace;',servent}} 構造体を返します。" ,"{{span style='color:blue;font-family:monospace;',gettimeofday}}","{{span style='color:blue;font-family:monospace;',TimGetSeconds}} を使った glue コード",現在の日付と時刻を返します。 ,"{{span style='color:blue;font-family:monospace;',setdomainname}}","{{span style='color:blue;font-family:monospace;',NetLibSettingSet}}{{span style='color:blue;font-family:monospace;',(..,
netSettingDomainName,...)}}",ローカルホストのドメイン名をセットします。 ,"{{span style='color:blue;font-family:monospace;',sethostname}}","{{span style='color:blue;font-family:monospace;',NetLibSettingSet}}{{span style='color:blue;font-family:monospace;',(..,
netSettingHostName,
...)}}",ローカルホストの名前をセットします。 ,"{{span style='color:blue;font-family:monospace;',settimeofday}}","glue code using {{span style='color:blue;font-family:monospace;',TimSetSeconds}}",現在の日時をセットします。 !サポートされるバイト順マクロ バイト順マクロは で定義されています。それらは、整数のバイト順をネットワークバイト順とホストバイト順の間で変換します。 ,Berkeley ソケットマクロ,詳細 ,"{{span style='color:blue;font-family:monospace;',htonl}}",32 ビット整数を、ホストバイト順からネットワークバイト順に変換します。 ,"{{span style='color:blue;font-family:monospace;',htons}}",16 ビット整数を、ホストバイト順からネットワークバイト順に変換します。 ,"{{span style='color:blue;font-family:monospace;',ntohl}}",32 ビット整数を、ネットワークバイト順からホストバイト順に変換します。 ,"{{span style='color:blue;font-family:monospace;',ntohs}}",16 ビット整数を、ネットワークバイト順からホストバイト順に変換します。 !サポートされるネットワークアドレス変換関数 ネットワークアドレス変換関数は、{{span style='color:blue;font-family:monospace;',}} ヘッダファイル内で宣言されています。それらはネットワークアドレスをあるフォーマットから別のフォーマットに変換したり、ネットワークアドレスの一部を操作したりします。 ,Berkeley ソケット関数,ネットライブラリ関数,詳細 ,"{{span style='color:blue;font-family:monospace;',inet_addr}}","{{span style='color:blue;font-family:monospace;',NetLibAddrAToIN}}",IP アドレスを、ドット付き 10 進数フォーマットから 32 ビットバイナリフォーマットに変換します。 ,"{{span style='color:blue;font-family:monospace;',inet_network}}",glue code,IP ネットワーク番号を、ドット付き 10 進数フォーマットから 32 ビットバイナリフォーマットに変換します。 ,"{{span style='color:blue;font-family:monospace;',inet_makeaddr}}",glue code,"IP ネットワーク番号と IP ホスト番号によって与えられる {{span style='color:blue;font-family:monospace;',in_addr}} 構造体内の IP アドレスを、32 ビットバイナリフォーマットで返します。" ,"{{span style='color:blue;font-family:monospace;',inet_lnaof}}",glue code,IPアドレスのホスト番号部分を返します。 ,"{{span style='color:blue;font-family:monospace;',inet_netof}}",glue code,IPアドレスのネットワーク番号部分を返します。 ,"{{span style='color:blue;font-family:monospace;',inet_ntoa}}","{{span style='color:blue;font-family:monospace;',NetLibAddrINToA}}",IP アドレスを 32 ビットフォーマットからドット付き 10 進数フォーマットに変換します。 !!ネットワークログインスクリプトサポートの拡張 Palm OS 3.3 から、ネットワーク設定パネルで利用できるスクリプトコマンドの一覧を拡張するプラグインを書くことができます。例えば、以下の場合に書くことができます。 *あなたが企業の IT ショップ／システムインテグレータ／トークンカードベンダであり、認証サーバによって定義されたいくつかの接続シナリオに適切に反応するログインスクリプトを必要としている。 *あなたがトークンカードベンダであり、Palm OS 版パスワード生成ソフトウェアを作成したい。 *スクリプトの実行中に条件テストと分岐を行ないたい。 ログインスクリプト機能は、ネットワークライブラリをサポートする Palm Powered ハンドヘルド（つまり、PalmPilot{{sup TM}} Professional およびPalm OS 2.0 以降が動いている新しいデバイス）全てにインストールできます。インストールするには、{{span style='color:blue;font-family:monospace;',Network.prc}} という名前のファイルを、使用するネットワークインターフェイス（例えば PPP や SLIP ）用の PRC ファイルと一緒にインストールします。これらのファイルは新しいネットワーク設定パネルを提供します。このパネルは、新しいコマンドのサポートとスクリプトプラグインを書く能力のサポートを含みます。 以下のセクションでは、ログインスクリプトの基本的な書き方を説明します。プラグインを書くのに利用する API について詳しくは、「Palm OS Programmer's API Reference」の「スクリプトプラグイン」章を参照して下さい。 !ログインスクリプトプラグインを書く ログインスクリプトプラグインを書くには、通常と同様のプロジェクトを作成します。しかし、データベースタイプは {{span style='color:blue;font-family:monospace;','appl'}} ではなく {{span style='color:blue;font-family:monospace;','scpt'}} を指定します。もし Metrowerks CodeWarrior を使用しているなら、PalmRez ポストリンカパネルでデータベースタイプを指定します。 {{span style='color:blue;font-family:monospace;',PilotMain}} 関数において、プラグインは 2 つの起動コードに対応する必要があります。 *プラグインが実装するコマンドのネットワーク設定パネルを通知するための {{span style='color:blue;font-family:monospace;',scptLaunchCmdListCmds}}。 *コマンドを実行するための {{span style='color:blue;font-family:monospace;',scptLaunchCmdExecuteCmd}}。 !scptLaunchCmdListCmds に対応する ネットワーク設定パネルは、利用可能なコマンドのプルダウンリスト（これはスクリプトビューで表示されます）を構成するときに {{span style='color:blue;font-family:monospace;',scptLaunchCmdListCmds}} 起動コードを送信します。パネルはこの起動コードを、{{span style='color:blue;font-family:monospace;','scpt'}} タイプの全ての PRC に送信します。それはパラメータブロックとして {{span style='color:blue;font-family:monospace;',PluginInfoType}} タイプの空の構造体を渡します。プラグインは、構造体に以下の情報を埋めて返答する必要があります。 *プラグインの名前（ PRC ファイルの名前） *プラグインが実装するコマンドの数（{{span style='color:blue;font-family:monospace;',pluginMaxNumOfCmds}} が許すよりも多くならないこと） *プラグインが実装する各コマンドの名前を含む配列と、プラグインが引数をとるかどうかを示すブール値 与えられたハンドヘルドは、インストールされた複数のプラグインを持ちます。もしそうなら、結果のプルダウンリストはハンドヘルドにインストールされた全てのプラグインでサポートされる全てのコマンドの結合を含みます。このため、提供するコマンド名がユニークであるように気をつけるべきです。名前にはたった 15 キャラクタだけが許可されるので、名前はできるだけ短くするべきです。 !scptLaunchCmdExecuteCmdへの応答 {{span style='color:blue;font-family:monospace;',scptLaunchCmdExecuteCmd}} 起動コードは、ログインスクリプトが実行されているときに送信されます。 つまり、ネットワーク設定パネルで指定されたネットワークサービスにユーザが接続を試みた、そして認証のためにパネルがスクリプトを実行している、ということです。 {{span style='color:blue;font-family:monospace;',scptLaunchCmdExecuteCmd}} パラメータブロックは {{span style='color:blue;font-family:monospace;',PluginExecCmdType}} 型の構造体です。以下のものを含んでいます。 *実行されるコマンドの名前 *コマンドの引数（必要なら） *ネットワークインターフェイス関数へのポインタ *現在の接続を指定する情報へのハンドル プラグインは指定されたコマンドを実行するべきです。プラグインがこのコードで実行された場合、それはサブルーチンとして実行され、グローバル変数にはアクセスしません。プラグインが起動されたときにはネットワークライブラリと接続アプリケーション（ HotSync アプリケーションなど）は既に実行されている、ということにも気をつけて下さい。そのため、利用可能なメモリとスタックスペースはかなり限定されます。 プラグインコマンドの働きのほとんどを実行するためにはおそらく、選択されたネットワークサービスが指定するネットワークインターフェイス（ SLIP や PPP など）へのアクセスを必要とします。これにより、ネットワークインターフェイスによって定義されたコールバック関数へのポインタをプラグインが渡します。プラグインは、以下のタスクを実行する必要があるときにこの関数をコールするべきです。 *ネットワークからバイト数を読み取る *ネットワークにバイト数を書き込む *ユーザの名前とパスワードの情報を取得する *接続ログに文字列を書き込む *ユーザに情報を教える *ユーザがキャンセルボタンを押したかどうか確認する *フォームを表示する *シリアルライブラリへのアクセスを取得する コールバックのプロトタイプは {{span style='color:blue;font-family:monospace;',ScriptPluginSelectorProc}} によって定義されます。それが引数としてとるのは、起動コード内で渡された接続固有データのハンドル、ネットワークインターフェイスが行なうべき（ {{span style='color:blue;font-family:monospace;',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 つの選択肢があります。 *ネットワークインターフェイスは、ユーザに入力を促してその入力結果を返すことができます。また、ユーザが設定試行をキャンセルしたかどうかを確認するために、ネットワーク設定パネルに問い合わせをすることもできます。 *入力を促したりキャンセル状態を確認する以上のことをしたいなら、フォームを表示して独自のユーザインターフェイスルーチンをコールするためにコマンド {{span style='color:blue;font-family:monospace;',pluginNetLibCallUIProc}} を使用することができます。 {{span style='color:blue;font-family:monospace;',pluginNetLibCallUIProc}} を使うには、以下のようにします。, +生成したフォームリソースを使ってフォームを初期化します。 +フォームのハンドルおよびユーザインターフェイスルーチンで必要とするその他の値を含む構造体を生成します。 +ネットワークインターフェイスのコールバック関数を、 {{span style='color:blue;font-family:monospace;',pluginNetLibCallUIProc}} コマンド・フォームのハンドルとその他適切な情報・インターフェイスルーチンで実行される関数のプラグインにおけるアドレス、とともにコールします。この関数は一つの引数（ネットワークインターフェイスに渡した構造体）をとり、{{span style='color:blue;font-family:monospace;',void}} を返します。 +ネットワークインターフェイスのコールが返されたとき、フォームを閉じます。 {{span style='color:blue;font-family:monospace;',pluginNetLibCallUIProc}} の利用の例は、サンプルコード {{span style='color:blue;font-family:monospace;',ScriptPlugin.c}} 内の {{span style='color:blue;font-family:monospace;',WaitForData}} 関数と {{span style='color:blue;font-family:monospace;',promptUser}} 関数を参照して下さい。 !!ソケット予告 Palm OS Garnet バージョン 5.4 は、ソケットの状態が変わったときにアプリケーションが応答できるようにするメカニズムを導入しました。例えば、ソケットが閉じているかソケットが TCP データを受け取ったときです。このメカニズムは'''ソケット予告（ socket notice ）'''と呼ばれます。アプリケーションは通知タイプ（どの Palm OSがアプリケーションと通信したかの手段：例えば、通知の送信による）のコールによってソケット予告を登録します。 :注:Palm OS Garnet バージョン 5.4 では、ソケット予告がアプリケーションと通信できるのは通知（ notification ）を通してだけです。ソケット予告を受け取る他の手段は、現時点でサポートされていません。 !ソケット通知 「通知を送るソケット予告」を'''ソケット通知'''（ socket notification ）と呼びます。このセクションでは、アプリケーション内でソケット通知をどのように利用するかを説明します。 +ソケット通知定数（ 予告タイプ ）を定義します。この定数はアプリケーション内でユニークである必要があります。 +{{span style='color:blue;font-family:monospace;',SysNotifyRegister()}} のコールとソケット通知定数およびアプリケーションが通知をハンドルする必要のあるあらゆるデータへのパスによって、通知を登録します。パスする他のパラメータは、{{span style='color:blue;font-family:monospace;',sysAppLaunchCmdNotify}} 起動コードを通して通知を受信したのか、それともコールバック関数によって受信したのか、によって決定されます。 +{{span style='color:blue;font-family:monospace;',NetLibSocketOptionSet()}} をコールしてソケット予告システムを準備します。他のパラメータの間に、{{span style='color:blue;font-family:monospace;',NetSocketNoticeType}} タイプのオプション値へのポインタを渡します。この構造体は、以下の情報をネットライブラリに教えます。 **予告タイプ。通知を使用するソケット予告を識別するために、定数 {{span style='color:blue;font-family:monospace;',netSocketNoticeNotify }} を使用します。この定数は {{span style='color:blue;font-family:monospace;',NoticeTypeEnum}} で定義されています。 **通知タイプ。これはアプリケーションで定義されたソケット通知定数です。 **状態。どのソケットがあなたの興味があるものを変えたのかを示すフラグです。もし全てのソケット状態に興味があるなら、値 {{span style='color:blue;font-family:monospace;',0xFFFFFFFF}} を使用します。''Palm OS Programmer's API Reference'' の「ソケット予告トリガ状態」を参照して下さい。 +通知のハンドル。 **受け取ったパラメータブロックを {{span style='color:blue;font-family:monospace;',SysNotifyNetSocketType}} としてキャストします。この型について詳しくは、''Palm OS Programmer's API Reference'' の「ソケット通知指定データ」を参照して下さい。 **どの状態が通知を引き起こしたのかを見つけます。これを行なうには、{{span style='color:blue;font-family:monospace;',SysNotifyNetSocketType}} 構造体の {{span style='color:blue;font-family:monospace;',condition}} フィールドをチェックします。 **適切なアクションを行ないます。 +次の通知を受け取るために、ソケット予告システムを再準備します。通常は、通知ハンドラで {{span style='color:blue;font-family:monospace;',NetLibSocketOptionSet()}} をコールすることでそれを実行します。 !予告 vs 通知 '''予告 '''と '''通知 '''という用語は関係があるように見えますが、別々のものです。 '''ソケット予告 '''は、ソケット状態が変わったときにアプリケーションと通信するというネットライブラリ機能です。この通信が起こることには様々な手段があります。しかしその全てが実装されているわけではありません。現時点では、ネットライブラリによってシステムはアプリケーションに'''通知'''を送信します。しかし、将来、ネットライブラリがイベントキューにイベントをポストしたり特定のメールボックス ID にメッセージを送信したりできるかもしれません。 !NetMgr.h 内のサポートされないコード もし {{span style='color:blue;font-family:monospace;',NetMgr.h}} を精読しているなら、現時点ではサポートされていませんが将来の Palm OS バージョンでサポートされるかもしれないコードに遭遇するかもしれません。さしあたってそのようなコードは無視します。 *{{span style='color:blue;font-family:monospace;',NoticeTypeEnum}} 定義のほとんど。{{span style='color:blue;font-family:monospace;',netSocketNoticeNotify}} だけが現在使用できます。他の列挙定数（ {{span style='color:blue;font-family:monospace;',netSocketNoticeEvent}} や{{span style='color:blue;font-family:monospace;',netSocketNoticeCallback}} など）は、Palm OS Garnet バージョン5.4 では利用できません。 :注:''ソケット予告''コールバックは Palm OS Garnet バージョン5.4 ではサポートされません。''通知''コールバックと混同しないで下さい。それは「[[ソケット通知]]」で示されるように実装されています。 *{{span style='color:blue;font-family:monospace;',NetSocketNoticeEventType}}、{{span style='color:blue;font-family:monospace;',NetSocketNoticeMailboxType}}、{{span style='color:blue;font-family:monospace;',NetSocketNoticeCallbackPtr}} 定義。これらは現時点でサポートされていません。 *{{span style='color:blue;font-family:monospace;',NetSocketNoticeType}} 内の {{span style='color:blue;font-family:monospace;',notice}} 結合のほとんど。その結合内の{{span style='color:blue;font-family:monospace;',notify}} 構造体だけがサポートされます。{{span style='color:blue;font-family:monospace;',event}}、{{span style='color:blue;font-family:monospace;',mailbox}}、{{span style='color:blue;font-family:monospace;',callback}}、{{span style='color:blue;font-family:monospace;',wake}} 構造体はサポートされません。 !関係するセクション ソケット通知を実行するために、一般的な通知の働き方を理解する必要があるでしょう。そのために、以下のことを提案します。 *''Palm OS Programmer's Companion Volume I'' の[[第 2 章「アプリケーションの開始と終了」|Palm OS Programmer's Companion Volume I/2]] *''Palm OS Programmer's API Reference'' の第 3 章「通知」 *''Palm OS Programmer's API Reference'' の第 43 章「通知マネージャ」 　 ---- [[↑7 章トップへ|Palm OS Programmer's Companion Volume II/7]]　[[2 節に進む　→|Palm OS Programmer's Companion Volume II/7-2]]