Join MDN and developers like you at Mozilla's View Source conference, 12-14 September in Berlin, Germany. Learn more at https://viewsourceconf.org

nsIAsyncInputStream

Please add a summary to this article.
継承元: nsIInputStream 最終更新: Gecko 1.7

 

ノンブロッキングな入力ストリームは、読み込みの際にNS_BASE_STREAM_WOULD_BLOCKを返すことがあります。この場合、呼び出し元では、ストリームに読み取り対象のデータが到着するまで待機する必要があります。もしもストリームがnsIAsyncInputStreamを実装していれば、呼び出し元はこのインタフェースを使って、( AsyncWait() メソッドを介して)、ストリームが読み取り可能になるか閉じたときに、非同期で通知するよう要求できます。

このインタフェースはもっぱらノンブロッキングなストリームに対して使用されますが、 nsIInputStream.isNonBlocking() は必ずしもtrueを返す必要はありません。ノンブロッキングな nsIInputStream がnsIAsyncInputStreamを必ず実装している必要もありません。
 

Method overview

void asyncWait(in nsIInputStreamCallback aCallback, in unsigned long aFlags, in unsigned long aRequestedCount, in nsIEventTarget aEventTarget);
void closeWithStatus(in nsresult aStatus);

Constants

Constant Value Description
WAIT_CLOSURE_ONLY (1<<0)

asyncWait() に渡すと、このフラグはデフォルトの挙動を上書きし、OnInputStreamReadyによる通知がストリームが閉じるまで抑制されるようになります( closeWithStatusかcloseがストリームに対して呼ばれるか、おそらくストリーム内の何らかのエラーが原因で閉じられるまで抑制されます)。

Methods

asyncWait()

ストリームが読み取り可能になるか閉じられるのを、非同期に待ち受けます。通知は1度だけ、つまりasyncWaitの呼び出しごとにちょうど一度だけcallbackによる通知が行われます。OnInputStreamReady イベントが送信されると、ストリームは nsIInputStreamCallback イベントへの参照を解放します。この通知イベントのハンドラの中で再びasyncWaitを呼び出しても安全です。

このメソッドは任意のタイミングで(まだ読み出しが行われていない場合ですら)呼び出される可能性があります。言い換えればこれは、ストリームに既に読み取り対象のデータがある場合に呼び出される可能性もあるということです。ストリームが閉じているときに呼び出される可能性もあります。asyncWaitが呼び出された時にストリームが既に読み取り可能または閉じていた場合、 nsIInputStreamCallback.onInputStreamReady() イベントはただちに送信されます。それ以外の場合、ストリームが読み取り可能になるまたは閉じるのを待って、イベントは送信されます。

 

void asyncWait(
  in nsIInputStreamCallback aCallback,
  in unsigned long aFlags,
  in unsigned long aRequestedCount,
  in nsIEventTarget aEventTarget
);
Parameters
aCallback
ストリームの準備が整うと呼び出されるオブジェクトです。既存のコールバックをクリアするためにnullをセットすることもできます。
aFlags
このメソッドの動作を設定するために渡すフラグを、オプションで指定します。何も指定しない場合は0を渡してください。
aRequestedCount
指定されたバイト数以上データが読み込み可能になるまで待機します。このパラメータは実際のストリームに対する提案にすぎず、実際には無視されるかもしれません。特に指定が無い場合は0を渡すとよいでしょう。
aEventTarget
nullを指定すると、通知を任意のスレッドで受け取ります(呼び出し元スレッド上で再帰的に受け取り、同期呼び出しになる可能性もあります)。特定のイベントターゲットを指定すると、そこに通知されるようになります。  

closeWithStatus()

このメソッドは、ストリームを閉じて内部ステータスをセットします。ストリームが既に閉じられている場合、このメソッドの呼び出しは無視されます。いったんストリームが閉じられると、ストリームのステータスを変更することはできません。成功ステータスをこのメソッドに渡した場合はNS_BASE_STREAM_CLOSEDとして扱われ、これはnsIInputStream.close()と同等の効果があります。

註: このメソッドは、入力側と出力側を持ったパイプをサポートするために存在しているようなところがあります。パイプの入力側が閉じられると、パイプの出力側への書き込みは失敗するようになります。"壊れた"パイプに書き込もうとした時に返ってくるエラーコードが、パイプの入力側を閉じたときに渡されたステータスコードに相当します。これにより、パイプの取り扱いが非常に簡単になるケースがあります。

void closeWithStatus(
  in nsresult aStatus
);
Parameters
aStatus
閉じられたストリームがアクセスされた場合に返るエラーです。

ドキュメントのタグと貢献者

 このページの貢献者: NozomiIto
 最終更新者: NozomiIto,