Main Content

matlab.net.http.io.MultipartConsumer 类

命名空间: matlab.net.http.io
超类: matlab.net.http.io.GenericConsumer

HTTP 消息中的 Multipart 内容类型的辅助函数

全页展开

描述

此使用程序处理 Multipart HTTP 响应消息。Multipart 消息是指 Content-Type 标头字段中指定 "multipart"、主体中包含一个或多个组成部分的消息。每一部分都包含一组描述该部分的标头字段，其中最重要的是 Content-Type 字段。

matlab.net.http.io.MultipartConsumer 类是一个 handle 类。

子类编写者须知

如果您编写自己的 ContentConsumer，不管是作为顶层使用程序（指定为 RequestMessage.send 方法的第三个参量），还是 Multipart 消息中的一部分（在 MultipartConsumer 构造函数调用中指定为“代理”），它通常都可以正常工作。MultipartConsumer 使得每个代理好像在处理整个响应消息，但实际上代理只是将结果汇集成一个 ResponseMessages 数组，存储在返回的 response.Body.Data 属性中。

下面介绍 MultipartConsumer 的行为：

此 MultipartConsumer 每次从服务器收到消息的一个完整部分时，它会解析该部分中的任何标头，然后根据该部分的 Content-Type 字段调用合适的代理使用程序。如果该部分没有 Content-Type 字段，则假定类型为 text/plain。如果没有能够处理该类型的代理，它将根据 Content-Type 对该部分使用默认处理，如 GenericConsumer 中所述。

MultipartConsumer 在收到一个完整的部分之前不会调用代理。MultipartConsumer 先缓冲该部分的数据，在完全收到该部分后，将 ContentConsumer 的所有可见属性从此使用程序复制给代理，清空代理的 Response.Body，将代理的 Header 设置为该部分的标头，然后调用代理的 initialize 和 start 方法，接着对代理中包含该部分有效负载的 putData 方法进行一次或多次调用，最后调用 putData(uint8.empty) 来表示数据结束。如果代理的 initialize 方法返回 false，指明它不想处理该部分，则使用适合该部分的 Content-Type 的默认行为来处理该部分的有效负载，如 GenericConsumer 中所述。

如果代理的 start 方法返回 []，指明缓冲区大小无上限，MultipartConsumer 将只会对提供该部分全部有效负载的 putData 进行一次调用，然后调用表示数据结束的方法。否则，它会对 putData 进行足够多次的调用，以缓冲区大小为单位提供整个有效负载。

如果代理的 putData 方法将 STOP 返回值设置为 true，指明它不想再接收任何数据，MultipartConsumer 将关闭连接以结束传输，就像消息已经结束一样。代理通过这种方式控制是否处理原始消息的剩余部分。如果 putData 返回的 SIZE 为 []，消息也会结束，但会向 RequestMessage.send 的调用方抛出异常。

如果某一部分的使用程序被指定为函数句柄而不是 ContentConsumer 实例，则该函数只在第一次需要该使用程序时调用，之后将使用该使用程序实例来处理同一个响应消息中任何适用的部分。对于由函数句柄处理的部分，Response.Body.Data 中对应的 ResponseMessage 只包含该部分的标头，因为该函数无权访问 ResponseMessage 主体。

代理使用程序可以通过 MyDelegator 属性访问此使用程序及其属性，但很少需要这样做。

创建对象

描述

consumer = MultipartConsumer(types,consumer) 构造一个 MultipartConsumer，以使用相应的 consumer 来处理指定的 types。您可以采用任意顺序指定多个对组参量，例如 types1,consumer1,...,typesN,consumerN。MATLAB® 按照它们出现的顺序搜索 types 并使用第一个匹配项。如果指定的类型中没有匹配项，MATLAB 将使用默认的一组使用程序（取决于类型）。

consumer = MultipartConsumer(puthandle) 构造一个 ContentConsumer，每次调用此使用程序的 putData 方法时，都会调用由 puthandle 指定的函数。

输入参量

全部展开

内容类型，指定为字符串数组、字符向量或字符向量元胞数组。types 使用语法 "type/subtype" 指定内容类型。有关详细信息，请参阅 matlab.net.http.io.GenericConsumer。

内容使用程序，指定为可以处理指定类型的 matlab.net.http.io.ContentConsumer 对象，或指定为函数的句柄，该函数返回能够处理这些类型的 ContentConsumer。

采用以下 ContentConsumer.putData 语法的 putData 函数的句柄：

[length,stop] = putData(data)

其中 data 是一个 uint8 数组，length 是该数组的长度。

当您知道服务器返回的数据类型时，可以按照此语法使用一个函数处理来自服务器的所有输入。此函数无权访问 ResponseMessage 或有关此使用程序的任何信息。

属性

全部展开

公共属性

Multipart 消息中第一个分界符之前的那一部分（如果有），指定为 uint8。使用程序在代理中调用 start 方法之前设置 Preamble。一旦设置，Preamble 值永远不变。

属性：

GetAccess
public
SetAccess
private

Multipart 消息中最后一个分界符之后的那一部分（如果有），指定为 uint8。当消息结束时，使用程序在完成对代理的所有调用之后设置 Epilogue。如果代理在消息结束之前终止传输，则不会设置此属性。传输完成后，例如返回 RequestMessage.send 时，您可以检查此属性。

属性：

GetAccess
public
SetAccess
private

建议的缓冲区大小，指定为 uint64。MATLAB 将 AllocationLength 设置为传递给 putData 的数据缓冲区的预计大小。实际大小可能更小，也可能更大。为了提高性能，使用程序可以根据此值预先分配处理数据需要的空间。

MATLAB 在调用 start 方法之前设置此属性，从而为子类提供方便。

属性：

GetAccess
public
SetAccess
public

有效负载的预期长度，指定为 uint64。此属性通常是 Header 属性中的 matlab.net.http.field.ContentLengthField 的 Value 属性。

如果 ContentLength 为空，则长度未知。当调用 putData(uint8.empty) 时，有效负载结束。

MATLAB 在调用 initialize 之前设置此属性，从而为子类提供方便（知道数据长度可能对子类有好处）。

如果此 ContentConsumer 是顶层使用程序的代理，则 ContentLength 的值可能与顶层使用程序的 ContentLength 值不同。

示例: numel(someData)，其中 someData 的类型为 uint8

属性：

GetAccess
public
SetAccess
public

有效负载的媒体类型，指定为 matlab.net.http.MediaType 对象。此属性通常是 Header 属性中的 matlab.net.http.field.ContentTypeField 的 Value 属性。如果 ContentType 属性为空，则 ContentTypeField 为空或不存在。

MATLAB 在调用 initialize 之前设置此属性，从而为可能需要检查 MediaType 的子类提供方便。如果子类根据数据确定它具有不同的 MediaType，则可以设置此属性。

当传输结束时，MATLAB 将此值复制到 Response.Body.ContentType 属性中。

示例: 'application/octet-stream'

属性：

GetAccess
public
SetAccess
public

当前正在处理的有效负载的标头，指定为 matlab.net.http.HeaderField 对象。

使用程序根据此标头确定如何处理发送给它们的有效负载。对于顶层使用程序，此值与 Response.Header 相同。对于代理来说，值可能不同。例如，在 MultipartConsumer 处理的 multipart 消息中，它是此代理正在处理的那一部分的标头。代理仍然可以检查 Response.Header 以获得原始消息的标头。

MATLAB 在调用 initialize 之前设置此属性，从而为子类提供方便。

属性：

GetAccess
public
SetAccess
public

发送的已完成的 RequestMessage，指定为 matlab.net.http.RequestMessage 对象。这是所有重定向之后的最后一个 RequestMessage，它是来自 send 方法的 completedrequest 返回值。

MATLAB 在调用 initialize 之前设置此属性，从而为子类提供方便。

属性：

GetAccess
public
SetAccess
public

正在处理的 ResponseMessage，指定为 matlab.net.http.ResponseMessage 对象。

MATLAB 在调用 initialize 之前设置 Response 属性。值是收到标头之后、接收有效负载之前的 ResponseMessage。在开始处理响应消息时（如果是 Multipart 消息，则是在开始处理其中一部分时），ResponseMesssage.Body 属性是具有空 Data 和 Payload 属性的 MessageBody 对象。为了存储收到的数据，使用程序可在数据传输过程中修改 Response 和 MessageBody.Data 属性。通常，处理并存储数据的使用程序将 Response.Body.Data 设置为它们处理的有效负载，但这并不是必需的。当传输完成时，MATLAB 将此 Response 返回给 send 的调用方。使用程序不应修改其他 Response 属性，如 Header 或 StatusLine，因为这些更改将返回给 send 的调用方。

Response.Body.Payload 属性在传输过程中为空，使用程序不应尝试修改它。如果设置了 HTTPOptions.SavePayload 属性，在消息或一部分传输结束时（调用 putData(uint8.empty) 之后）或在发生异常时，MATLAB 会将 Payload 设置为已收到的有效负载。

如果在处理消息期间使用程序中发生异常，MATLAB 将抛出 HTTPException 对象。History 属性包含此 Response 值。

如果使用程序是一个代理，负责处理 Multipart 消息中的一部分，则 Response.Header 包含整个消息的标头，而且在为每一部分调用 ContentConsumer 之前会清除 Response.Body 的 Payload 和 Data 属性。在每一部分结束时，新的 ResponseMessage 会添加到原始响应的 Body.Data（包含来自此对象的 Header 和来自此属性的 Body）中的 ResponseMessage 对象数组的末尾。下一个代理会看到一个全新的 Response，它具有一个空 MessageBody，而不是上一个代理的 MessageBody。

属性：

GetAccess
public
SetAccess
public
Dependent
true

正在处理的请求的目标，指定为 matlab.net.URI 对象。此值是由 send 确定的原始目标 URI。它不是代理的 URI 或重定向后的最终 URI。

MATLAB 在调用 initialize 之前设置此属性，从而为子类提供方便。

属性：

GetAccess
public
SetAccess
public

受保护的属性

代理的 putData 方法，指定为函数句柄，如果设置了 CurrentDelegate，则指定为 []。

属性：

GetAccess
protected
SetAccess
protected

putData 方法为追加附加数据而调用的函数，指定为函数句柄。此类中的 putData 方法调用 AppendFcn 函数，将它在 data 参量中收到的数据追加到响应消息中的现有数据之后。函数必须具有签名：

AppendFcn(consumer,newdata)

其中 newdata 是要追加到数组中 consumer.Response.Body.Data 位置的数据。此方法负责更新 consumer.CurrentLength 以反映 Data 的新长度。如果 newdata 为空，表示流传输结束，则函数应将 Response.Body.Data 更新为其最终值。

如果此属性为空，默认行为将使用内部函数，该函数将 Data 视为支持 horzcat 函数的任意值的数组。它通过预分配空间高效地添加 newdata，使 CurrentLength 保持为存储的数据的实际长度。在消息结束时，它根据 CurrentLength 截断 Response.Body.Data。

如果 horzcat 不适合追加过程，则子类可以更改此属性。例如，当 StringConsumer 构造标量字符串时，它将使用 plus 函数添加到字符串中，而不是使用 horzcat。

不通过调用 ContentConsumer.putData 来追加数据的子类或者对 horzcat 追加数据的行为感到满意的子类可以忽略此属性。

示例: @customAppend，其中 @customAppend 由使用程序定义

属性：

GetAccess
protected
SetAccess
protected

接受此使用程序委托的 ContentConsumer，指定为 matlab.net.http.io.ContentConsumer 对象。主调使用程序（委托方）的 delegateTo 方法设置 CurrentDelegate 属性。如果当前没有委托，则值为 []。

在调用 initialize 之前，MATLAB 将 CurrentDelegate 设置为 []。

属性：

GetAccess
protected
SetAccess
protected

当前 Response.Body.Data 属性中的数据的长度，指定为 uint64。

当为 Response.Body.Data 预分配的大小大于当前实际存储的数据量时，使用此属性指示存储的数据的长度。如果此属性为空，则说明所有 Response.Body.Data 包含存储的数据，或者 ContentConsumer 子类是以其他方式处理数据，而不是将数据存储在 Response.Body.Data 中。

当 AppendFcn 属性为空时，此属性由 putData 方法在此基类中使用和设置。对于调用 putData 并希望检查已存储数据的子类，以及/或者在 Response.Body.Data 中维护结果的 AppendFcn 的任何实现来说，此属性都很有用。

使用 putData 的子类也可以修改此属性，以重置缓冲区中存储数据的位置。例如，当使用默认的 AppendFcn 函数时，每次调用 putData 时处理所有 Response.Body.Data 的子类可能对原始数据不再有用，因此它可以将 CurrentLength 属性重置为 1，以便下一个 putData 调用用新数据覆盖缓冲区。在新数据结束后，不需要清理缓冲区中的元素。

不调用 putData 的子类可以使用此属性跟踪自己的数据，也可以保留不设置（为空）。MATLAB 对可以在这里设置的值没有任何限制，也不会将其用于其他目的，只是用来确定默认的 AppendFcn 应将下一个数据缓冲区存储在何处以及是否在消息结束时截断数据。在最后一次调用 putData(uint8.empty) 之前将此属性设置为空可以防止截断数据。

MATLAB 在每次调用 initialize 之前将此属性设置为空。

属性：

GetAccess
protected
SetAccess
protected

向此使用程序进行委托的 ContentConsumer，指定为 matlab.net.http.io.ContentConsumer 对象。如果此使用程序是一个代理，由另一个使用程序（例如 GenericConsumer 或 MultipartConsumer）调用，则此使用程序就是主调使用程序。在调用 send 时指定的顶层使用程序中为空。

代理可以使用此属性访问委托方的属性，例如，为了确定哪些使用程序向它们进行了委托。

属性：

GetAccess
protected
SetAccess
protected

方法

全部展开

详细信息

全部展开

版本历史记录

在 R2018a 中推出

另请参阅

| | | | | | |