Main Content

putData

クラス: matlab.net.http.io.ContentConsumer
名前空間: matlab.net.http.io

ContentConsumer のデータの次のバッファーを処理または保存

このページをすべて展開する

構文

[size,stop] = putData(consumer,data)

説明

[size,stop] = putData(consumer,data) はサーバーから読み取った data のバッファーを consumer に提供します。

MATLAB® によって putData が呼び出されます。サブクラスのコンシューマーはこのメソッドをオーバーライドして、ストリーム データを受信することができます。コンシューマーは、実際に処理したデータの長さを size で、このメッセージから以降のデータを受信するかどうかを指定する true/false の指標を stop で返します。

MATLAB によって空の data 引数で putData が呼び出されるときは、メッセージまたはメッセージ パート (マルチパート メッセージの場合) が終了したことを意味します。

このメソッドを実装するコンシューマーのサブクラスを作成する場合、putData メソッドでそのスーパークラス putData を呼び出して、スーパークラスが実装する任意の変換や処理を利用することができます。

MATLAB では、data バッファーのサイズが start メソッドによって返された bufsize の値、または bufsize が [] である場合は内部バッファーのサイズに制限されます。また、サーバーがチャンクエンコードされたメッセージを送信する場合、putData の特定の呼び出しによって複数のチャンクが提供されることはありません。これにより、bufsize がチャンク サイズよりかなり大きい場合でも、コンシューマーはゆっくり到着するチャンクを適時な方法で取得できます。

この基底クラスにおける putData() の既定の動作は次のとおりです。

サブクラス コンシューマーには、変換された可能性のあるコンテンツを段階的または一度にすべて Response.Body.Data に直接格納したり、他の方法でそのコンテンツを破棄するオプションがあります。サブクラス コンシューマーは、データを格納するためにこの putData メソッドを呼び出す必要はありません。コンテンツを段階的に Response.Body.Data に格納するコンシューマーは、便宜上、このメソッドを呼び出して格納することができます。このメソッドは AppendFcn を使用して data を Response.Body.Data に付加し、容量を段階的に割り当てることで効率的に実行しようとします。格納されたデータの実際の長さは CurrentLength プロパティで維持されます。この長さは Response.Body.Data の実際の長さよりも小さくなる可能性があります。転送の最後に (たとえば、putData(consumer,[]) または putData(consumer,uint8.empty) が呼び出されたとき)、Response.Body.Data は CurrentLength で切り捨てられます。独自の AppendFcn を定義して、代替の付加メソッドを実装することができます。

既定では、このメソッドは常に numel(data) に等しい size と、false に等しい stop を返します。

このメソッドを使用してデータを格納する予定であり、格納されるデータの最大長がわかっている場合は、このメソッドをはじめて呼び出す前に、Response.Body.Data を既定の値 (たとえば 0) で満たされた目的のサイズのベクトルに設定する必要があります。このメソッドは、データ領域の先頭にデータを格納することを開始します。その後、メッセージの最後でデータの長さに切り捨て、CurrentLength に格納されるデータの長さを維持します。

この基底クラスでこのメソッドを呼び出してデータを段階的に格納するコンシューマーは、構造体や cell 配列を含む、horzcat または vertcat をサポートする任意の型の data を提供することができます。cell 配列を提供する場合、まだ変換されていない場合は既存のデータが cell 配列に変換され、cell 配列の要素は CurrentLength+1 で始まる線形インデックスの既存の cell 配列に挿入されます。

ContentConsumer でこのメソッドを呼び出してデータを格納する場合、直接変更するのではなく、このメソッドによって Response.Body.Data または CurrentLength を管理する必要があります。

スーパークラスでこのメソッドを呼び出す ContentConsumers は、ウィンドウを閉じたり、一時ファイルを削除するなど、スーパークラスが例外をスローした場合のクリーンアップの実施を準備する必要があります。

入力引数

すべて展開する

コンテンツ コンシューマー。matlab.net.http.io.ContentConsumer オブジェクトとして指定します。

matlab.net.http.ResponseMessage オブジェクトの生データのバッファー。次のいずれかとして指定します。

  • 空でない uint8 ベクトル - サーバーから読み取ったデータの標準バッファー。

  • uint8.empty - データの最後。これは、MATLAB によって応答メッセージの終了が示される標準的な方法です。後続のメッセージに備えて初期化するために、コンシューマーに対してクリーンアップの実施と (一時ファイルを削除したり、応答データを現在の長さに切り捨てるなど)、可能性のある将来の呼び出しに向けた準備を指示しています。これに応じて、コンシューマーは、処理が成功し、処理すべき新しいバイトが存在しないことを示すために stop=true と size=0 を返します。コンシューマーが size=[] を返す場合、そのコンシューマーはデータの完了に関する問題を抱えており、MATLAB によって RequestMessage.send の呼び出し元に HTTPException がスローされます。

  • [] (空の double) - サーバー、ネットワークの問題、または (Ctrl+C キーを使用して) ユーザーによって転送が中断されました。通常、コンシューマーは uint8.empty が受信された場合とまったく同じようにクリーンアップする必要がありますが、一部のコンシューマーは既に受信済みの不完全なデータを削除してしまう可能性があります。putData から戻ると、MATLAB によって HTTPException がスローされ、その History.Response にはコンシューマーが Response プロパティに格納したあらゆるデータが含まれています。

[] と uint8.empty の差異を考慮しない大部分のコンシューマーは、単純に isempty(data) をチェックして、適切にクリーンアップすることができます。data が空であるすべてのケースにおいて、コンシューマーは、データを格納するためにスーパークラス putData を使用していない場合であっても、同じ空の値でスーパークラス putData を呼び出さなければなりません。これは、クリーンアップすることをスーパークラスが認識する唯一の方法であるためです。空の値の data を受信したら、実装では、次の start の呼び出しまで、空の値を使用した後続の putData の呼び出しを無視しなければなりません。通常は後続の呼び出し時に stop=false と size=0 が返され、追加の処理は実行されません。

出力引数

すべて展開する

処理したデータの長さ。double または空の double として返されます。size の値に関する説明は次のとおりです。

  • size >= 0, size <= length(data) - この putData の呼び出しによって処理された data のバイト数。この数値は、このコンシューマーのサブクラスが処理されたデータ量を把握できるという利点のためだけに使用されます。以降の putData の呼び出しには影響しません。data が空である場合、size は無視されます。

  • size < 0 - abs(size) の結果は処理されたバイト数です。さらに、前のケースと同じように、MATLAB では残りのデータがそのままスキップされ、データの最後で putData(uint8.empty) がもう 1 度呼び出されます。MultipartConsumer が使用されていない場合、最後の putData の追加呼び出しを除いて、これは stop=true を返すことに似ています。MultipartConsumer が使用されている場合、負の値の size はそのパートのみを終了させ、メッセージの後続のパートの処理には影響しません。そのため、メッセージの次のパートまたは最後に到達するまで接続は閉じられません。

  • size = [] (空の double) - コンシューマーは転送で何らかのエラーが発生していると判断したため、サーバーからの後続の転送を終了しなければなりません。これは stop=true に似ていますが、エラーと見なされ、コンシューマーが接続を中断したことを示す標準の HTTPException が RequestMessage.send の呼び出し元にスローされます。この場合、呼び出し元が部分的に処理された ResponseMessage を取得できる唯一の方法は HTTPException.History を使用することです。

    size=[] を返して標準の例外をスローする代わりに、putData メソッドは独自の例外を直接スローすることができます。MATLAB では、RequestMessage.send の呼び出し元に返される HTTPException にこの例外が原因としてラップされます。

このメッセージの以降のデータを受信するかどうかを示します。true または false として指定されます。stop が true である場合、MATLAB では、メッセージの残り (MultipartConsumer によって処理されているマルチパート メッセージの後続のパートを含む) の処理が停止され、メッセージにデータが残っている場合でも、メッセージの終端に到達したかのようにそのまま処理されます。これにより、サーバーへの接続が即座に閉じられ、RequestMessage.send の呼び出し元にはエラーが返されません。これはエラー状況とは見なされず、任意の長さのストリームの受信を適切に終了する標準的な方法です。stop=true と data が既に空でない場合、MATLAB によって、空の data を使用した putData の呼び出しが 1 つ追加されます。stop=true は data が空であるかどうかにかかわらず設定される可能性があります。

通常、コンシューマーは data の最後に stop=true を設定してはなりません。なぜなら、コンシューマーがマルチパート デリゲートである場合、残りのメッセージの処理が打ち切られてしまうからです。メッセージの独自の部分に対する処理のみを終了するには、その部分のさらなるデータ受信を行わないことを示すために、コンシューマーは size < 0 を返す必要があります。

属性

Accesspublic

バージョン履歴

R2018a で導入

参考

| | | | | | | |