matlab.net.http.io.MultipartConsumer クラス

名前空間: matlab.net.http.io
スーパークラス: matlab.net.http.io.GenericConsumer

HTTP メッセージ内のマルチパート コンテンツ タイプのヘルパー

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

説明

このコンシューマーはマルチパート HTTP 応答メッセージを処理します。マルチパート メッセージは、その Content-Type ヘッダー フィールドに "multipart" が指定されていて、本文には 1 つ以上の部分が含まれているものです。各部分には、部分を記述する独自のヘッダー フィールドのセットが含まれていますが、それらで最も重要なものは Content-Type フィールドです。

matlab.net.http.io.MultipartConsumer クラスは handle クラスです。

サブクラスの作成

独自の ContentConsumer を作成している場合、これが最上位のコンシューマー (RequestMessage.send メソッドの 3 番目の引数として指定されている) でもマルチパート メッセージのパート (MultipartConsumer コンストラクターの呼び出しの "デリゲート" として指定されている場合) でも機能します。MultipartConsumer により、各デリゲートが応答メッセージ全体を処理しているように見えますが、実際には、結果を組み立てて、返された response.Body.Data プロパティに格納される ResponseMessages の配列に設定しています。

次に、MultipartConsumer の動作について説明します。

この MultipartConsumer がサーバーから完全なメッセージのパートを受信する場合、このパート内にヘッダーがあれば、これを解析して、このパート内の Content-Type フィールドに適したデリゲート コンシューマーを呼び出します。このパートに Content-Type フィールドがない場合、タイプは text/plain であると想定されます。このタイプを処理できるデリゲートがない場合、GenericConsumer の記述に従って、Content-Type に基づいてパートの既定の処理を使用します。

MultipartConsumer は、完全なパートを受信するまでデリゲートを呼び出しません。MultipartConsumer は、パートのデータをバッファーして、パートの受信の最後には、ContentConsumer の表示されているプロパティすべてをこのコンシューマーからデリゲートにコピーします。デリゲートの Response.Body をクリアし、デリゲートの Header をパートのヘッダーに設定してから、デリゲートの initialize メソッドおよび start メソッドを呼び出します。その後、パートのペイロードを含むデリゲートの putData メソッドが 1 回以上呼び出され、データ終了を示す putData(uint8.empty) の呼び出しが続きます。デリゲートの initialize メソッドが、パートを処理しないことを示すために false を返す場合、パートのペイロードは、GenericConsumer の記述に従って、パートの Content-Type の既定の動作を使用して処理されます。

デリゲートの start メソッドが、目的の最大バッファー サイズがないことを示すために [] を返す場合、MultipartConsumer は、パートのペイロード全体を提供する putData への呼び出しを一度だけ行い、データ終了呼び出しが続きます。それ以外の場合は、バッファー サイズの単位内のペイロード全体を提供するために十分な回数 putData を呼び出します。

デリゲートの putData メソッドが、さらにデータを必要としないことを示すために STOP 戻り値を true に設定する場合、MultipartConsumer はメッセージが終了していたかのように転送を終了するために接続を閉じます。このように、デリゲートは元のメッセージの残りを処理するかどうかを制御します。putData が [] の SIZE を返す場合、メッセージも終了しますが、RequestMessage.send の呼び出し元に例外がスローされます。

パートのコンシューマーが ContentConsumer インスタンスではなく関数ハンドルとして指定されている場合、関数はコンシューマーが最初に必要になったときにのみ呼び出され、同じ応答メッセージの後続の該当するパートに対してはいずれも同じコンシューマー インスタンスが使用されます。関数ハンドルで処理されたパートについては、関数からは ResponseMessage の本文にアクセスできないため、Response.Body.Data の対応する ResponseMessage にパートのヘッダーのみが格納されます。

デリゲートされたコンシューマーは MyDelegator プロパティを通してこのコンシューマーとそのプロパティにアクセスできますが、この処理が必要になることはほとんどありません。

作成

説明

consumer = MultipartConsumer(types,consumer) は、MultipartConsumer を構築し、対応する consumer を使用して指定された types を処理します。引数ペアは、types1,consumer1,...,typesN,consumerN のように任意の順序で複数指定できます。MATLAB® は types を出現する順序で検索し、最初に一致するものを使用します。指定されたタイプに一致するものがない場合、MATLAB はコンシューマーの既定のセットを使用しますが、これはタイプによって異なります。

consumer = MultipartConsumer(puthandle) は、このコンシューマーの putData メソッドの呼び出しごとに puthandle によって指定される関数を呼び出す ContentConsumer を構築します。

入力引数

すべて展開する

コンテンツ タイプ。string 配列、文字ベクトルまたは文字ベクトルの cell 配列として指定します。types は、構文 "type/subtype" を使用してコンテンツ タイプを指定します。詳細については、matlab.net.http.io.GenericConsumer を参照してください。

コンテンツ コンシューマー。指定されたタイプを処理できる matlab.net.http.io.ContentConsumer オブジェクト、またはこれらのタイプを処理できる ContentConsumer を返す関数へのハンドルとして指定します。

次の ContentConsumer.putData 構文をもつ関数 putData へのハンドル。

[length,stop] = putData(data)

data は uint8 配列であり length はその配列の長さです。

この構文を使用して、サーバーが返すデータ型がわかっている場合に、1 つの関数を使用してサーバーからのすべての入力を処理します。関数は、ResponseMessage またはこのコンシューマーに関する情報にはアクセスできません。

プロパティ

すべて展開する

パブリック プロパティ

最初の境界区切り記号までのマルチパート メッセージのパート (存在する場合)。uint8 として指定します。コンシューマーは、デリゲートの start メソッドを呼び出す前に Preamble を設定します。一度設定されると、Preamble 値が変更されることはありません。

属性:

GetAccess
public
SetAccess
private

最後の境界区切り記号 (存在する場合) に続くマルチパート メッセージの一部。uint8 として指定します。メッセージが終了するときは、デリゲートへのすべての呼び出しの後で、コンシューマーは Epilogue を設定します。メッセージの終了前にデリゲートが転送を停止する場合、これは設定されません。転送の完了後 (たとえば、RequestMessage.send が返すときなど) に、このプロパティを確認できます。

属性:

GetAccess
public
SetAccess
private

推奨されるバッファー サイズ。uint64 として指定されます。AllocationLength は、MATLAB により、putData に渡されるデータの予測されるバッファー サイズに設定されます。実際のサイズは、これよりも小さくなることも大きくなることもあります。パフォーマンスを向上させるために、この値を使用して、コンシューマーでデータを処理するためのスペースを事前に割り当てることができます。

このプロパティは、サブクラスで利用できるように、start メソッドを呼び出す前に MATLAB で設定されます。

属性:

GetAccess
public
SetAccess
public

想定されるペイロードの長さ。uint64 として指定されます。このプロパティは通常、Header プロパティにおける matlab.net.http.field.ContentLengthField の Value プロパティになります。

ContentLength が空の場合、長さは不明です。ペイロードは putData(uint8.empty) が呼び出された時点で終了します。

このプロパティは、サブクラスでデータの長さを確認できるように、initialize を呼び出す前に MATLAB で設定されます。

この ContentConsumer が最上位のコンシューマーのデリゲートである場合、ContentLength の値が最上位のコンシューマーの ContentLength と異なる値になることがあります。

例: numel(someData)。ここで、someData は uint8 型です。

属性:

GetAccess
public
SetAccess
public

ペイロードのメディア タイプ。matlab.net.http.MediaType オブジェクトとして指定します。このプロパティは通常、Header プロパティにおける matlab.net.http.field.ContentTypeField の Value プロパティになります。ContentType プロパティが空の場合、ContentTypeField は空または存在しません。

このプロパティは、サブクラスで MediaType を確認できるように、initialize を呼び出す前に MATLAB で設定されます。データから別の MediaType であることがわかった場合は、サブクラスでこのプロパティを設定できます。

この値は、転送の終了時に MATLAB によって Response.Body.ContentType プロパティにコピーされます。

例: 'application/octet-stream'

属性:

GetAccess
public
SetAccess
public

現在処理中のペイロードのヘッダー。matlab.net.http.HeaderField オブジェクトとして指定されます。

コンシューマーは、このヘッダーを使用して、送られてくるペイロードの処理方法を決定します。最上位のコンシューマーの場合、この値は Response.Header と同じになります。デリゲートの場合は値が異なることがあります。たとえば、MultipartConsumer で処理されるマルチパート メッセージの場合は、そのデリゲートで処理中のパートのヘッダーになります。デリゲートは引き続き Response.Header で元のメッセージのヘッダーを確認できます。

このプロパティは、サブクラスで利用できるように、initialize を呼び出す前に MATLAB で設定されます。

属性:

GetAccess
public
SetAccess
public

送信が完了した RequestMessage。matlab.net.http.RequestMessage オブジェクトとして指定します。これは、すべてのリダイレクトが完了した最終的な RequestMessage であり、send メソッドからの completedrequest 戻り値です。

このプロパティは、サブクラスで利用できるように、initialize を呼び出す前に MATLAB で設定されます。

属性:

GetAccess
public
SetAccess
public

処理中の ResponseMessage。matlab.net.http.ResponseMessage オブジェクトとして指定します。

Response プロパティは、initialize を呼び出す前に MATLAB で設定されます。この値は、ヘッダーの受信まで完了し、ペイロードを受信する前の ResponseMessage になります。応答メッセージの処理の開始時 (マルチパート メッセージの場合はパートの開始時) に、ResponseMesssage.Body プロパティは、Data プロパティと Payload プロパティが空の MessageBody オブジェクトになります。受信したデータを格納するために、コンシューマーはデータ転送中に Response プロパティと MessageBody.Data プロパティを変更できます。通常、コンシューマーはデータセット Response.Body.Data を処理してから処理済みのペイロードに格納しますが、これは必須ではありません。転送が完了すると、この Response が MATLAB から send の呼び出し元に返されます。Response の Header や StatusLine などの他のプロパティは、コンシューマーで変更しないでください。これらを変更した場合、その変更が send の呼び出し元に返されます。

Response.Body.Payload プロパティは転送中は空であり、コンシューマーで変更してはなりません。HTTPOptions.SavePayload プロパティが設定されると、次に MATLAB は、メッセージまたはパートの転送終了時 (putData(uint8.empty) の呼び出し後)、または例外の発生時に、受信したペイロードに Payload を設定します。

メッセージの処理中にコンシューマーで例外が発生した場合は、MATLAB から HTTPException オブジェクトがスローされます。History プロパティにはこの Response 値が含まれます。

コンシューマーがマルチパート メッセージのパートを処理するデリゲートの場合、Response.Header にメッセージ全体のヘッダーが格納され、各パートの ContentConsumer を呼び出す前に Response.Body の Payload プロパティと Data プロパティがクリアされます。各パートの最後で、元の応答の Body.Data にある ResponseMessage オブジェクトの配列の末尾に、このオブジェクトの Header およびこのプロパティの Body を含む、新しい ResponseMessage が追加されます。次のデリゲートでは、前のデリゲートの MessageBody ではなく空の MessageBody を含む新規の Response が確認されます。

属性:

GetAccess
public
SetAccess
public
Dependent
true

処理中の要求の送信先。matlab.net.URI オブジェクトとして指定されます。この値は、send で決定される元の送信先 URI の値になります。プロキシの URI やリダイレクト後の最終的な URI ではありません。

このプロパティは、サブクラスで利用できるように、initialize を呼び出す前に MATLAB で設定されます。

属性:

GetAccess
public
SetAccess
public

保護プロパティ

デリゲートの putData メソッド。関数ハンドルとして指定するか、CurrentDelegate が設定されている場合は [] として指定します。

属性:

GetAccess
protected
SetAccess
protected

データを追加するために putData メソッドで呼び出される関数。関数ハンドルとして指定されます。このクラスの putData メソッドは、data 引数で受け取ったデータを応答メッセージの既存のデータに追加するために関数 AppendFcn を呼び出します。この関数のシグネチャは次のとおりでなければなりません。

AppendFcn(consumer,newdata)

newdata は、consumer.Response.Body.Data の配列に追加されるデータです。このメソッドは、Data の新しい長さに合わせて consumer.CurrentLength を更新する必要があります。newdata が空の場合はストリームの末尾を示し、関数により Response.Body.Data が最終的な値に更新されます。

既定の動作では、このプロパティが空の場合、Data を任意の値の配列として扱う、関数 horzcat に対応した内部関数が使用されます。この関数では、スペースを事前に割り当てることで効率的に newdata が追加され、格納されたデータの実際の長さが CurrentLength に反映されます。メッセージの最後に、Response.Body.Data が CurrentLength の値までで切り捨てられます。

horzcat が追加処理に適さない場合は、このプロパティをサブクラスで変更できます。たとえば、StringConsumer でスカラー string を作成する場合は、string への追加に関数 horzcat ではなく関数 plus を使用することがあります。

データを追加する ContentConsumer.putData を呼び出さない場合やデータを追加する際の horzcat の動作に問題がない場合は、サブクラスでこのプロパティを無視することができます。

例: @customAppend。@customAppend はコンシューマーによって定義されます。

属性:

GetAccess
protected
SetAccess
protected

このコンシューマーによるデリゲート先の ContentConsumer。matlab.net.http.io.ContentConsumer オブジェクトとして指定します。呼び出し元のコンシューマー (デリゲーター) の delegateTo メソッドによって CurrentDelegate プロパティが設定されます。現在のデリゲーションがない場合、値は [] です。

MATLAB は initialize を呼び出す前に CurrentDelegate を [] に設定します。

属性:

GetAccess
protected
SetAccess
protected

Response.Body.Data プロパティの現在のデータの長さ。uint64 として指定されます。

このプロパティは、Response.Body.Data に事前に割り当てられたサイズが現在格納されている実際のデータの量よりも大きい場合に、格納されているデータの長さを示すために使用されます。このプロパティが空の場合は、すべての Response.Body.Data にデータが格納されているか、ContentConsumer サブクラスで Response.Body.Data に格納する以外の何らかの方法でデータが破棄されていることを示します。

このプロパティは、この基底クラスの putData メソッドで、AppendFcn プロパティが空の場合に使用および設定されます。putData を呼び出すサブクラスで既に格納されているデータを確認したり、AppendFcn の任意の実装で Response.Body.Data に結果を反映したりするのに使用できます。

putData を使用するサブクラスでは、このプロパティを変更してデータが格納されるバッファーの位置をリセットすることもできます。たとえば、既定の関数 AppendFcn を使用している場合、putData の呼び出しごとにすべての Response.Body.Data を処理するサブクラスで元のデータが不要になったときは、CurrentLength プロパティを 1 にリセットすることで次の putData の呼び出し時に新しいデータでバッファーを上書きできます。新しいデータの末尾を越えてバッファーの要素をクリアする必要はありません。

putData を呼び出さないサブクラスでは、このプロパティを独自のデータの追跡に使用できます。使用しない場合は未設定 (空) のままにしておいてかまいません。ここで設定できる値に関して、MATLAB にはいかなる制約もありません。また、この値は、既定の AppendFcn でデータの次のバッファーを格納する位置とメッセージの末尾のデータを切り捨てる位置を特定するためにのみ使用され、それ以外の目的には使用されません。データが切り捨てられないようにするには、putData(uint8.empty) の最後の呼び出しの前にこのプロパティを空に設定します。

このプロパティは、initialize の各呼び出しの前に MATLAB で空に設定されます。

属性:

GetAccess
protected
SetAccess
protected

このコンシューマーのデリゲート元の ContentConsumer。matlab.net.http.io.ContentConsumer オブジェクトとして指定されます。このコンシューマーが GenericConsumer や MultipartConsumer などの別のコンシューマーから呼び出されたデリゲートである場合、これは呼び出し側のコンシューマーを示します。send の呼び出しで指定された最上位のコンシューマーの場合は空になります。

デリゲートは、このプロパティを使用してデリゲーターのプロパティにアクセスし、デリゲート元のコンシューマーなどを確認できます。

属性:

GetAccess
protected
SetAccess
protected

メソッド

すべて展開する

詳細

すべて展開する

バージョン履歴

R2018a で導入

参考

| | | | | | |