nsIWebProgressListener

このインターフェースは、nsIWebProgress インスタンスのコンテクストだけではなく、すべての子 nsIWebProgress インスタンスの、非同期リクエストの読み込みに関連する進捗を監視しようとするクライアントによって実装されています。
継承元: nsISupports 最終更新: Gecko 15 (Firefox 15 / Thunderbird 15 / SeaMonkey 2.12)

 

メソッド概要

void onLocationChange(in nsIWebProgress aWebProgress, in nsIRequest aRequest, in nsIURI aLocation);
void onProgressChange(in nsIWebProgress aWebProgress, in nsIRequest aRequest, in long aCurSelfProgress, in long aMaxSelfProgress, in long aCurTotalProgress, in long aMaxTotalProgress);
void onSecurityChange(in nsIWebProgress aWebProgress, in nsIRequest aRequest, in unsigned long aState);
void onStateChange(in nsIWebProgress aWebProgress, in nsIRequest aRequest, in unsigned long aStateFlags, in nsresult aStatus);
void onStatusChange(in nsIWebProgress aWebProgress, in nsIRequest aRequest, in nsresult aStatus, in wstring aMessage);

定数

遷移状態フラグ(State Transition Flags)

これらのフラグは、リクエストがロードされ、遷移しているさまざまな状態を表します。これらのフラグは排他的です。

リクエストが与えられる度、onStateChange() が呼び出されます。 STATE_START を伴って一回、STATE_TRANSFERRING フラグを伴ってゼロまたは数回、STATE_REDIRECTING と一回、最終的にSTATE_STOP を伴って一回、onStateChange() は呼び出されます。

註:ドキュメントのリクエストにおいて、2つ目の STATE_STOP が生成されます。(詳しくは STATE_IS_WINDOW の詳細を参照してください)
定数 詳細
STATE_START 0x00000001 このフラグはリクエストが開始されたことを表します。このフラグはリクエストが初期化された際に設定されます。開始されたリクエストは、STATE_STOP フラグを伴ってonStateChange() が呼び出された時に完了します。
STATE_REDIRECTING 0x00000002 このフラグはリクエストがリダイレクトされていることを表します。onStateChange() に通されたリクエストはリダイレクトされたものです。リダイレクトが発生したとき、その過程において自動的に新規リクエストが生成されます。新しいリクエストでも同様に STATE_START のイベントが発生し、リダイレクトされたリクエストは STATE_STOP を迎えると予想されます。
STATE_TRANSFERRING 0x00000004 このフラグは、リクエストしたデータがこちらへと転送されている状態にあることを表します。このフラグは、リクエストがつながり、ユーザーがリクエストに対応するコンテンツを見始めるようになることも意味します。
STATE_NEGOTIATING 0x00000008 このフラグは使用されません。
STATE_STOP 0x00000010 このフラグはリクエストが完了したことを表します。onStateChange() の aStatus パラメータは、リクエストの最終ステータスを表します。

状態種類フラグ(State Type Flags)

これらのフラグは、発生しているトランザクションの状態についての実態をより詳しく説明します。これらのフラグは排他的ではありません( onStateChange() イベントはこれらのフラグが組み合わさっていることを示すかもしれません。)

定数 詳細
STATE_IS_REQUEST 0x00010000 このフラグは、ドキュメントに限らないリクエストの遷移状態を表します。(下記のドキュメントのリクエストの詳細も参照してください) (例えば画像やスタイルシートといった)インラインコンテンツのような、他の種類のリクエストはの通常のリクエストとして見做されています。
STATE_IS_DOCUMENT 0x00020000

このフラグは、ドキュメントリクエストの遷移状態を表します。このフラグは STATE_IS_REQUEST を追加で設定します。ドキュメントリクエストは、 nsIChannel のサポートと、nsIChannel::LOAD_DOCUMENT_URI を含む、リクエストの loadFlags 属性を含んでいます。

ドキュメントに対応した読み込みに関連するリクエストの全てが完了するまで、ドキュメントリクエストは完了しません。これには、(たとえば HTML <iframe> 要素といった)他のドキュメントリクエストも含まれます。ドキュメントリクエストに対応しているドキュメントは、onStateChange() の aWebProgress パラメータの DOMWindow 属性を経由して取得できます。

STATE_IS_NETWORK 0x00040000

このフラグは、nsIWebProgress インスタンスによって表わされる活動の開始または停止に対応する遷移状態を表します。このフラグには、STATE_START または STATE_STOP の一方及びその他の状態種類フラグが付随しています。

STATE_IS_WINDOW とは異なり、このフラグは nsIWebProgress インスタンスのアクティビティが開始または停止していると通知された時にのみ設定されます。アクティビティが子 nsIWebProgress インスタンス でのみ発生した場合、そのアクテビティの開始または停止を示すためにこのフラグが設定されるでしょう。

例えば、HTML フレームセットの単体フレームのナビゲーションの場合、フレームセットウィンドウの nsIWebProgress に加えられた nsIWebProgressListener インスタンスは、ナビゲーションの開始と中止を設定された STATE_IS_NETWORK フラグとともに onStateChange() の呼び出しを受けます。言い換えれば、アクテビティが子ウィンドウに束縛された際には、外部ウィンドウのオブザーバーは開始または中止を 定義できるということです。

STATE_IS_WINDOW 0x00080000

このフラグは、nsIWebProgress インスタンスが示すアクティビティの開始と停止に対応する遷移状態を表します。このフラグは、STATE_START または STATE_STOP 、およびその他の状態種類フラグを伴います。

このフラグは、STATE_IS_DOCUMENT に類似しています。しかしながら、ドキュメントのリクエストが完了された時、生成された STATE_STOP と共に onStateChange() が2回呼び出されます。ドキュメントのリクエストはそれぞれの呼び出しの際に aRequest を渡します。最初の呼び出しでは STATE_IS_REQUEST および STATE_IS_DOCUMENT が設定され、2回目の呼び出しでは STATE_IS_WINDOW が設定されます。(加えて、可能であれば STATE_IS_NETWORK が設定されます。STATE_IS_NETWORK が設定される場合の詳細については上記の詳細を参照してください) この2つの STATE_STOP イベントは、ドキュメントのリクエストが完了した際に発生した作業を分別するのに有効とされます。

状態変更フラグ(State Modifier Flags)

これらのフラグは、発生しているトランザクションの状態についての実態をより詳しく説明します。これらのフラグは排他的ではありません( onStateChange() イベントはこれらのフラグが組み合わさっていることを示すかもしれません。)

定数 詳細
STATE_RESTORING 0x01000000 このフラグは、以前レンダリングされた表示結果の復元作業の開始または停止に相当する遷移状態を表します。このリクエストに関連するネットワーク・アクティビティはなく、読み込まれたオリジナルのドキュメントや表示に加えられた変更それ自体は、依然として存在しています。

セキュリティ状態フラグ(State Security Flags)

これらのフラグは onSecurityChange() が呼び出されることによって 報告されるセキュリティの状態について説明します。これらのフラグは排他的です。

定数 詳細
STATE_IS_INSECURE 0x00000004 このフラグは、リクエストに対応するデータが安全ではないチャンネルを経由して受信されたことを表します。
STATE_IS_BROKEN 0x00000001 このフラグは未知のセキュリティの状態であることを表します。これは、ページ中の一部のコンテンツのリクエストが、安全ではないチャンネルを経由して読み込まれていることを意味するかもしれません。
STATE_IS_SECURE 0x00000002 このフラグは、リクエストに対応するデータが安全なチャンネルを経由して受信されたことを表します。セキュリティの程度については、STATE_SECURE_HIGHSTATE_SECURE_MED、または STATE_SECURE_LOW によって表現されます。

セキュリティ強度フラグ(Security Strength Flags)

これらのフラグは、セキュリティの強度と、onSecurityChange() メソッドの呼び出しに伴う STATE_IS_SECURE について説明します。これらのフラグは排他的です。

これらのフラグは、データ転送のセキュリティについて厳密な詳細を提供することを意味しません。これらは代わりに、セキュリティ通知の色区分や、その他ユーザー向けの基本的なデータ転送のフィードバックなどのような、簡易的なインジケータで使用されることを意図しています。

定数 詳細
STATE_SECURE_HIGH 0x00040000 このフラグは高レベルのセキュリティにあることを示します。
STATE_SECURE_MED 0x00010000 このフラグは中レベルのセキュリティにあることを示します。
STATE_SECURE_LOW 0x00020000 このフラグは低レベルのセキュリティにあることを示します。

アイデンティティ状態フラグ(State identity flags)

これらのフラグは、onSecurityChange() メソッドの呼び出しにおける、身元検証のレベルについて説明します。

定数 詳細
STATE_IDENTITY_EV_TOPLEVEL 0x00100000

ステータスビットにおける EV とは Extended Validation すなわち High Assurance であり、高く保証されていることを意味します。

最高位のドキュメントには EV 証明書が使用されています。

ロケーション変更状態フラグ (Location Change flags)

定数 詳細
LOCATION_CHANGE_SAME_DOCUMENT 0x00000001 このフラグは、aWebProgress が新たにドキュメントを読み込まなかったときのものです。例としては、アンカーによるスクロールや pushState/popState/replaceState によるロケーションの変更が挙げられます。

メソッド

onLocationChange()

変更を監視されているウィンドウのロケーションが変更された際に呼び出されます。読み込みがリクエストされたときではなく、与えられたウィンドウにおいて読み込みが発生しようとしているの一度確認された際に呼び出されます。たとえば、ウィンドウに於いて開始した読み込みが、新しいサイトに向けてプログレスとステータスメッセージを送信していたとしても、新たなページが読み込まれていると私たちが確認するまでは、onLocationChange は呼び出されないでしょう。別の例として、ブラウザの中でドキュメントが読み込まれているのではなく、サードパーティのツールへとドキュメントが渡された場合、PDFやフラッシュの読み込みでは onLocationChange は呼び出されないでしょう。

void onLocationChange(
  in nsIWebProgress aWebProgress,
  in nsIRequest aRequest,
  in nsIURI aLocation
  [optional] in unsigned long aFlags
);
引数
aWebProgress
通知が発生した nsIWebProgress インスタンス。
aRequest
関連する nsIRequest 。いくつかの場合では、この値は null かもしれません。
aLocation
読み込まれているロケーションの URI 。
aFlags
オプション:この値は、ロケーションが変更された状況や理由について表します。 Optional from Gecko 10

onProgressChange()

aWebProgress に関連するリクエストのひとつの変更されたプログレスを通知します。(STATE_STOPSTATE_IS_WINDOW フラグを含む aStateFlags を伴って呼び出された onStateChange() に対応する) aWebProgress の全てのリクエストが完了したとき、プログレス全体はゼロへとリセットされます。

註:プログレスの値が未知である、または長整数型の最大値を上回る場合、プログレスの値は -1 によって置き換えられます。
註:オブジェクトが nsIWebProgressListener2 を実装しており、尚且つ呼び出し側がそのインターフェースを知っている場合、この関数は呼び出されません。その場合、代わりに nsIWebProgressListener2.onProgressChange64() が呼び出されます。
void onProgressChange(
  in nsIWebProgress aWebProgress,
  in nsIRequest aRequest,
  in long aCurSelfProgress,
  in long aMaxSelfProgress,
  in long aCurTotalProgress,
  in long aMaxTotalProgress
);
引数
aWebProgress
通知が発生した nsIWebProgress インスタンス。
aRequest
新しいプログレスを持つ nsIRequest
aCurSelfProgress
リクエストの現在のプログレス。
aMaxSelfProgress
リクエストの最大のプログレス。
aCurTotalProgress
aWebProgress に関連する全てのリクエストにおける、現在のプログレス。
aMaxTotalProgress
aWebProgress に関連する全てのリクエストにおける、全体のプログレス。

onSecurityChange()

セキュリティプログレスを通知します。このメソッドは (例えば HTTP -> HTTPS または HTTP, FOO -> HTTPS といった)セキュリティの遷移に応じて、およびドキュメントの読み込みの完了と共に呼び出されます。ネットワーク読み込みの間にエラーが発生した場合でも、同様に呼び出されます。

註:セキュリティパッケージを導入している場合、これらの通知は一度しか発生しません。
void onSecurityChange(
  in nsIWebProgress aWebProgress,
  in nsIRequest aRequest,
  in unsigned long aState
);
引数
aWebProgress
通知が発生した nsIWebProgress インスタンス。
aRequest
新しいセキュリティ状態の nsIRequest
aState
上述のセキュリティ状態フラグセキュリティ強度フラグによって構成された値。将来的には未定義なビット列を受け取ることになるかもしれません。

onStateChange()

aWebProgress に関連するリクエストのいずれかの状態が変更されたことを通知します。

void onStateChange(
  in nsIWebProgress aWebProgress,
  in nsIRequest aRequest,
  in unsigned long aStateFlags,
  in nsresult aStatus
);
引数
aWebProgress
通知が発生した nsIWebProgress インスタンス。
aRequest
状態が変更した nsIRequest 。この引数は null である場合があります。
aStateFlags
新しい状態のフラグを表します。この値は、上述した遷移状態フラグのひとつと、状態種類フラグのひとつ、または複数によって構成されています。将来的には未定義なビット列を受け取ることになるかもしれません。
aStatus

状態の変更に関連するエラーステータスコードです。この引数は aStateFlag が STATE_STOP ビットを含まない限りは無視されます。ステータスコードは状態の変更に関連するリクエストの成功または失敗を示します。

註:HTTP 404 File Not Found エラーのようなサーバー側で発生したエラーに対しても、成功したとのコードを示すかもしれません。こうした場合において、リクエスト自体のエラー情報については、(HTTPリクエストについては nsIHttpChannel を参照するなど)拡張されたエラー情報を問い合わせるべきです。

onStatusChange()

リクエストのステータスが変更されたことを通知します。ステータスメッセージは、ブラウザのステータスバーなどといった、ユーザーへの表示を意図されています。

void onStatusChange(
  in nsIWebProgress aWebProgress,
  in nsIRequest aRequest,
  in nsresult aStatus,
  in wstring aMessage
);
引数
aWebProgress
通知が発火した nsIWebProgress
aRequest
新たなステータスを持つ nsIRequest
aStatus

この値はエラーコードではありません。その代わり、現在のリクエストのステータスを示す数値になります。このインターフェースはステータスコードの設定が可能なようには定義されていません。

註:いくつかのステータス値は、nsITransport および nsISocketTransportで定義されています
aMessage
aStatus に対応するローカライズされたテキスト。

タブごとへの nsIWebProgressListener:

gBrowser.mProgressListeners (上で述べたようにタブ毎の nsIWebProgressListener によって起動される):

 

Document Tags and Contributors

Contributors to this page: saneyuki_s, hiiragi77, Taken
最終更新者: hiiragi77,