Palm Programmer's Laboratory
Palm OS Programmer's Companion Volume II/7-2
7-2 インターネットライブラリ
インターネットライブラリは、World Wide Web ドキュメントへの容易なアクセスをアプリケーションに提供します。インターネットライブラリは、基本的なネットワークアクセスにはネットライブラリを使用します。また、http や https のような高レベルインターネットプロトコルにソケット的なAPIを提供するという、ネットライブラリのソケットコンセプトの頂点にあります。
インターネットライブラリを使って、たった 3 コール（ INetLibSockClose ）でアプリケーションは Web ページにアクセスすることができます。インターネットライブラリは、より良いコントロールを必要とするアプリケーションのために、より進んだ API も提供します。
- 注
- このセクションの情報は、Palm VII デバイスの Palm OS バージョン 3.2 以降でのみ適用されます。これらのフィーチャは、無線インターネットフィーチャセット?が存在する場合のみ実装されます。
- 警告!
- 将来の OS バージョンで、インターネットライブラリ API の後方互換性をサポートあるいは提供することを PalmSource 社は予定していません。
このセクションではインターネットライブラリをアプリケーションでどのように使用するかについて説明します。以下の内容がカバーされます。
- システム要件
- 初期化とセットアップ
- Web ページへのアクセス
- 非同期操作
- 低レベルコールの使用
- キャッシュの概要
- インターネットライブラリネットワーク設定
システム要件
インターネットライブラリは、Palm VII デバイスの Palm OS バージョン 3.2 以降のみで利用できます。インターネットライブラリコールを行う前に、インターネットライブラリが存在することを保証します。以下の FtrGet コールを利用することで、それが利用可能かどうかを確かめることができます。
err = FtrGet(inetLibFtrCreator, inetFtrNumVersion, &value);
インターネットライブラリがインストールされているなら、value パラメータはゼロ以外で、返されるエラーはゼロ（つまりエラー無し）でしょう。
インターネットライブラリが存在して実行中であるとき、およそ 1 KB の余分な RAM（ネットライブラリ以上です）が必要となります。もしセキュリティライブラリが使用されている（セキュアなサイトにアクセスしているとき）なら、セキュリティライブラリのためにさらに追加のメモリが使用されます。そしてキャッシュデータベースが使用されているなら、キャッシュデータベースを開くためにさらに追加のメモリが使用されます。
初期化とセットアップ
インターネットライブラリを使用する前に、ライブラリの参照番号を取得するために、アプリケーションは SysLibFind をコールする必要があります。以下のようにコールします。
err = SysLibFind("INet.lib", &libRefNum)
次に、inetH ハンドルをアロケートするために INetLibOpen をコールする必要があります。inetH ハンドルは全アプリケーション固有の環境セッティングを保持し、インターネットライブラリを使用する各アプリケーションは自身のプライベートな inetH ハンドルを得ます。インターネットライブラリの既定の振る舞いを変更するコールは、アプリケーション自身の inetH 構造体に保持されている環境セッティングに影響します。そしてこれらの変更は、同時にインターネットライブラリを使用するかもしれない他のアプリケーションには影響しません。
INetLibOpen もまた、アプリケーションのためにネットライブラリを開きます。更に、アプリケーションは INetLibOpen に好ましいネットワークサービスのタイプ（有線または無線）を伝えます。INetLibOpen は利用可能なネットワークインターフェイスを問い合わせ、要求されたサービスのタイプに合ったインターフェイスにアタッチします。アプリケーションが「インターネットライブラリネットワーク設定?」をコールしたときです。
インターネットライブラリは、システム設定データベースから既定の振る舞いのいくつかを取得します。また、その設定のいくつかは無線設定パネルを経由してユーザによってなされます。このパネルによってセットされた設定は、使用するプロキシサーバや、デバイスIDが送信されるときにユーザに警告するかどうかを決める設定を含んでいます。設定データベースに含まれる他の設定は、インターネットライブラリネットワーク設定（ INetLibSettingSet コールを参照）から来ます。しかし、アプリケーションによってなされた変更は、システム設定には保存されません。しかし inetH ハンドルが開いている間だけは影響を与えます。
Web ページへのアクセス
Palm.Net 環境において、全ての HTML 文書は Palm Powered ハンドヘルドに転送される前に Palm Web クリッピングプロキシサーバによって動的に圧縮されます。
ネットワークからページを読み取る手続きは以下のように操作します。最初に、ソケットを閉じるために、アプリケーションは要求された URL を INetLibSockClose に渡します。
すぐに読めるデータが無い場合は、データの少なくとも 1 バイトが読めるようになるまで INetLibSockRead がブロックする、ということに注意して下さい。イベントを使った非同期操作を実装するには、次の非同期操作セクション?を参照して下さい。
もしアプリケーションが操作を越えたより良いコントロールを要求するなら、INetLibURLOpen コールを他の低レベルインターネットライブラリコール（低レベルコールの利用?）に置き換えることができます。
非同期操作
インターネットアプリケーションを書くことにおける主要な挑戦は、良いユーザインターフェイス反応を提供する間の遅いネットワークの内容へのアクセスのタスクを扱うことです。例えば、ユーザはスクロール・メニューの選択・またはWebページダウンロードの途中でキャンセルボタンのタップができなくてはいけません。
この種の機能を簡単に利用できるようにするに、インターネットライブラリは INetLibGetEvent コールを提供しています。このコールは、伝統的で非ネットワーク Palm OS アプリケーションの全 てが使用する EvtGetEvent コールを置き換えるように設計されています。INetLibGetEvent コールは、処理すべき次のイベントをフェッチします。そのイベントがスクリーンのタップなどのユーザインターフェイスイベントでも、リモートホストから読み取るべきデータが到着するなどのネットワークイベントでも、です。もし準備のできたイベントが存在しなければ、INetLibGetEvent は Palm Powered ハンドヘルドを自動的に低電力モードにします。また、次のイベントの発生までブロックします。
INetLibGetEvent の利用はネットワーク入出力を行なう望ましい方法です。電池寿命を延ばし、ユーザインターフェイスの敏感さを向上させます。
INetLibGetEvent を使うと、Web ページへのアクセス処理はかなり複雑になります。INetLibURLOpen 直後の INetLibSockReadコールのかわりに、アプリケーションはそのイベントループを返し次のイベントを待つべきです。データがソケットで準備できているというネットワークイベントを受け取ったなら、INetLibSockReadをコールすべきです。
標準ユーザインターフェイスイベントに加えて、INetLibGetEvent が返すことのできる 2 種類のネットワークイベントがあります。最初のイベントはステータス変更イベント（ inetSockStatusChangeEvent ）です。このイベントは、ソケットのステータスが変化してアプリケーションがそのユーザインターフェイスを更新しようとするかもしれない、ということを示しています。例えば、http サーバへのアクセスに INetLibURLOpen をコールしたとき、ソケットのステータスは「ホストを検索中（finding host）」から「ホストと接続中（connecting with host）」、「データを待機中（waiting for data）」、「データ読み取り中（reading data）」などに変化します。この種のイベントに関連づけられたイベント構造体は、ソケットハンドルと新しいステータスの両方を含んでいます。そのため、アプリケーションはユーザインターフェイスを更新することができます。
イベントの第二のタイプ INetLibGetEvent は、データが準備できたイベント（ inetSockReadyEvent ）を返すことができます。このイベントは、ソケットでデータが読み取り準備ができたときに返されます。このイベントは、INetLibSockRead をコールできてデータ到着を待機中にブロックをしないということを保証する、とアプリケーションに伝えます。
インターネットライブラリを使用するアプリケーションの一般的な流れは、ユーザコマンドの応答で、INetLibURLOpen を使って URL を開きます。そしてユーザインターフェイスと INetLibURLOpen によって返された新規作成ソケットの両方からのイベントを処理するために、 INetLibGetEvent が繰り返しコールされます。 inetSockStatusChangeEvent イベントへの応答で、ユーザに現在のステータス（ホストを検索中、ホストに接続中、データ読み取り中、など）を示すために、アプリケーションはユーザインターフェイスを更新します。inetSockReadyEvent イベントへの応答で、アプリケーションは INetLibSockRead を使ってソケットからデータを読み取ります。最後に、利用可能な全てのデータが読み取られた（ INetLibSockRead が 0 バイトの読み取りを返した）とき、アプリケーションは INetLibSockClose を使ってソケットを閉じます。
最後に、アプリケーションがソケットハンドルのステータスを問い合わせることができるように、便利なコール INetLibSockStatus が提供されます。このコールはネットワーク入出力でブロックされません。よって、いつコールしても安全です。それはソケットの現在のステータスを返すだけでなく、読み書きの準備ができているかどうかも返します。それは、inetSockReadyEvent および inetSockStatusChangeEventイベントを経由して伝達されたものと本質的に同じ情報を返します。INetLibGetEvent を利用しないアプリケーションは、入出力のステータス変化および準備状態をチェックするために INetLibSockStatus を繰り返しポーリングします。しかしポーリングは推奨されません。
低レベルコールの使用
INetLibURLOpen が提供するよりも良いコントロールを必要とするアプリケーションは、インターネットライブラリの低レベルコールを使用することができます。それは INetLibSockhttpReqSend を含みます。
http リソースのための INetLibURLOpen 単一コールは、以下の連続と本質的に等価です。INetLibSockOpen 、INetLibSockConnect 、INetLibSockhttpReqCreate 、INetLibSockhttpReqSend です。これらの 4 つのコールは、サーバの非標準ポートへのアクセス（許可されるなら）、デフォルト http リクエストヘッダの修正、http の PUTおよび POST 操作、といった能力をアプリケーションに提供します。実際にネットワーク入出力を行なうコールは、INetLibSockConnect（リモートホストとの TCP 接続を確立する）と INetLibSockhttpReqSend（サーバに http リクエストを送る）だけです。
INetLibSockhttpAttrSet は、INetLibSockhttpReqCreate が生成したデフォルト http リクエストヘッダをアプリケーションが追加または修正ができるようにするために提供されています。
INetLibSockSettingSet は、アプリケーションにソケットセッティングのより良いコントロールを提供します。
最後に、IINetLibURLCrack ルーチンは、URL を構成部品に分割するのに便利なように提供されています。
キャッシュの概要
インターネットライブラリは、ダウンロード済のドキュメントのキャッシュデータベースを維持しています。これは LRU（最も昔に使われた：Least Recently Used ）キャッシュです。これは、キャッシュが一杯になったときに最も昔に使われた項目がフラッシュされます。検索されたページがキャッシュされているかどうかは、ソケットにセットされたフラグ（ inetOpenURLFlagKeepInCache ）または INetLibURLOpen によって決定されます。他のフラグ（ inetOpenURLFlagLookInCache ）は、URL 検索時にインターネットライブラリがまずキャッシュをチェックするべきかどうかを決定します。
インターネットライブラリを利用するアプリケーションはどれでも、同じキャッシュデータベースを使うことができます。そのため、各アプリケーションは事前にフェッチされたドキュメントの同一プールを共有することができます。また、アプリケーションは異なるキャッシュデータベースを使用することもできます。使用するキャッシュデータベースは、INetLibOpen コールで指定されます。
一般的に、キャッシュされた項目は 1 つ以上のデータベースレコードにサーバから受け取ったのと同じフォーマットで保管されます。
Web クリッピングアプリケーションビューアアプリケーションで使用されるキャッシュにおいて、各レコードは項目の「マスタ」URL を含むフィールドを含んでいます。このフィールドはアクティブな PQA の URL がセットされています。ある PQA からリンクされているすべてのページは、同じマスタ URL を持っています。この機能性は、履歴リストを構築するための階層構造におけるすべてのページに見られます。
インターネットライブラリは、キャッシュ内に項目のリストを維持します。INetLibCacheGetObject のコールによって、このリストから項目を探すことも、リスト全体を繰り返すこともできます。
URL がキャッシュされているかどうかを、INetLibURLGetInfo のコールによりチェックすることができます。
インターネットライブラリネットワーク設定
インターネットライブラリはネットワーク設定をサポートします。設定 とは、特定のインターネットライブラリ設定（ INetSettingEnum タイプから）値のセットのことです。
インターネットライブラリは利用できる設定のリストとそのエイリアスを保持しています。3 つのビルトイン設定があります。
- Palm.Net 無線システムおよび Palm Web クリッピングプロキシサーバを使用する無線設定
- ネットワーク設定パネルおよび Palm Web クリッピングプロキシサーバで指定された有線ネットワーク設定を使用する有線設定
- ネットワーク設定パネルで指定されるがプロキシサーバでは指定されない有線ネットワーク設定を使用するジェネリック設定
既存の設定を修正して別名で保存すれば、独自の設定を定義することもできます。
インターネットライブラリは、いくつかの設定エイリアス（ INetLibConfigAliasGet を参照）も定義しています。
例えば、インターネットライブラリを使ってある種の接続のデフォルト設定を変更するために、適切な値をセットアップし、設定を保存し、カスタム設定を指し示すインターネットライブラリデフォルトエイリアス設定をセットします。どの設定を使用するかをアプリケーションが指定するとき、もしエイリアスを指定したなら、カスタムセッティングが使用されます。
もし設定を使用するなら、INetLibOpen 経由でインターネットライブラリを開くときに特定の設定を指定するべきでしょう。インターネットライブラリは、アプリケーション内で設定を操作するための API を含んでいますが、そのようなことはまれです。利用できる設定を一覧にすることができます（ INetLibConfigDelete ）。
設定関数は主に設定パネルによる設定の編集および保存のために提供されます。一般的な手順は以下の通りです。編集する設定をアクティブにし、セッティングを適切にセットし、INetLibConfigSaveAs を使ってセッティングを保存します。設定変更は、INetLibConfigSaveAs をコールしない限り、インターネットライブラリが閉じた後には保存されない、ということに注意して下さい。
