mozilla
Your Search Results

    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
    閉じられたストリームがアクセスされた場合に返るエラーです。

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

    Contributors to this page: NozomiIto
    最終更新者: NozomiIto,