matlab.net.http.io.ContentProvider 类

命名空间: matlab.net.http.io
超类: handle, matlab.mixin.Heterogeneous

HTTP 消息有效负载的 ContentProvider

描述

发送消息时，ContentProvider 为 HTTP RequestMessage 提供数据。简单的提供程序将数据从 MATLAB^® 类型转换为字节流。更复杂的提供程序可将数据以流方式传输给服务器，在发送数据的同时获取或生成数据，从而不需要在开始发送消息之前将所有数据保存到内存中。

通常，向 Web 服务发送数据时（通常是在 PUT 或 POST 请求中），您会创建一个 RequestMessage，并以 MessageBody 对象形式将数据插入到 RequestMessage.Body 属性中。当您使用 RequestMessage.send 发送该消息时，MATLAB 会根据消息的 Content-Type 以及 Body.Data 中的数据类型将该数据转换为要发送给服务器的字节流。有关这些转换规则的详细信息，请参阅 MessageBody.Data。

如果不想在 RequestMessage.Body 属性中插入 MessageBody 对象，则可以创建并插入 ContentProvider 对象。这样，当您发送消息时，MATLAB 会调用 ContentProvider 中的方法，在发送消息的同时获取要发送的数据缓冲区。

无论您在消息中插入 MessageBody 还是 ContentProvider，在整个消息发送完毕并且收到响应之前或者在发生错误之前，对 RequestMessage.send 的调用都不会返回（即被阻止）。但是，对于 ContentProvider，MATLAB 会在发送被阻止期间对提供程序进行周期性回调，以获取要发送的数据缓冲区。在这些回调中，您的 ContentProvider 可从任何来源获取数据，例如文件、MATLAB 数组、硬件传感器、MATLAB 函数等。提供程序的作用是以 uint8 缓冲区的形式将这些数据转换成可以发送到 Web 上的字节流。

ContentProvider 是一个抽象类，借助这个抽象类，类编写者可以使用自己的数据生成器或转换器来创建子类，也可以直接使用（或子类化）可从各来源生成数据的 MATLAB 提供程序之一，而不用自己编写子类。这些提供程序有很多选项，可以让您灵活地控制获取和转换数据的方式，比直接将数据插入 MessageBody 时发生的自动转换更灵活。可以使用下列 ContentProvider 子类之一：

即使您不需要以流方式传输数据，使用这些提供程序之一也可以简化某些内容类型的发送过程，因为它们可将数据从内部形式转换为 uint8 数据流。例如，FormProvider 允许您将表单响应发送给服务器，在服务器上，您可以很方便地将数据表示为 QueryParameter 对象数组。MultipartFormProvider 允许您发送 Multipart 表单响应，从而简化 Multipart 表单响应的创建。要使用任何 ContentProvider，您需要了解服务器期望您发送的内容类型。

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

子类编写者须知

最简单的、可能的 ContentProvider 只需实现一个 getData 方法，按 MATLAB 的要求提供数据缓冲区。要使用您的提供程序，请将其插入到 RequestMessage 的 Body 属性中。在此示例中，RequestMessage 构造函数的第三个参量 MyProvider 对象插入到 Body 中：

provider = MyProvider;
req = matlab.net.http.RequestMessage('put', headers, provider);
resp = req.send(uri);

这是 MyProvider 类的示例，它从作为参量传递给构造函数的文件名中读取信息并发送到 Web 上。我们在最后或在删除此提供程序时还会关闭此文件。

    classdef MyProvider < matlab.net.http.io.ContentProvider
        properties
            FileID double
        end
 
        methods
            function obj = MyProvider(name)
                obj.FileID = fopen(name);
            end
 
            function [data, stop] = getData(obj, length)
                [data, len] = fread(obj.FileID, length, '*uint8');
                stop = len < length;
                if (stop)
                    fclose(obj.FileID);
                    obj.FileID = [];
                end
            end
 
            function delete(obj)
                if ~isempty(obj.FileID)
                    fclose(obj.FileID);
                    obj.FileID = [];
                end
            end
        end
    end

当提供程序产生要发送的新消息时，MATLAB 会调用提供程序的 complete 方法。目的是允许提供程序准备新消息并为消息添加任何必要的标头字段。在准备好发送数据时（但在第一次调用 getData 之前），MATLAB 会调用提供程序的 start 方法。

属性

全部展开

公共属性

`Header` — 消息或组成部分的标头字段
`matlab.net.http.HeaderField.empty` (默认) | `matlab.net.http.HeaderField`

消息或组成部分的标头字段，指定为由一个或多个 matlab.net.http.HeaderField 对象组成的向量。

此属性仅供子类编写者使用。MATLAB 在调用提供程序的 complete 方法之前设置此属性。对于非 Multipart 消息，MATLAB 将此属性初始化为 Request.Header 的内容减去任何 matlab.net.http.field.GenericFields 或空值字段。ContentProvider 使用此属性添加对要发送数据进行描述的标头字段，或者向消息中已有的标头字段中添加参数。在 MultipartProvider 的代理中，MATLAB 将此属性初始化为委托方提供程序打算为该部分插入的标头字段。代理可以修改或更改这些字段。

从提供程序的 complete 方法返回时，如果这不是 Multipart 消息，则 MATLAB 会读取此属性并将其内容与 Request 的标头合并。此 Header 中 Names 未出现在 Request.Header 中的字段将被添加到 Request.Header 的末尾。如果此 Header 中的某个字段与 Request.Header 中的某个字段具有相同的 Name，而且都具有非空 Values，则：

如果 Request.Header 中的字段是 GenericField，则忽略 Header 中的字段。
如果 Request.Header 中的字段不是 GenericField，则将其替换为 Header 中的字段。

如果两个字段或其中之一具有空 Value，则将该字段从 Request.Header 中删除，且不会添加为正常的完整消息的一部分。

如果这是 MultipartProvider 的代理，则将此 Header 的全部内容用作该部分的标头。Multipart 代理绝不能假定 Request.Header 包含的任何字段与自己的 Header 相关。提供程序可以通过检查 MyDelegator 是否为 MultipartProvider 来确定它是否为 Multipart 代理，尽管需要进行这种检验的可能性并不大。

MATLAB 仅在调用提供程序的 complete 方法返回时读取此属性。一旦 MATLAB 调用 start，对此数组所做的更改将被忽略。

类编写者应该明白，在超类中调用 complete 之前，子类可能已经向此 Header 中添加字段（在子类的 complete 方法中）。最好保留这些字段，而且不要添加同名字段。但是，为字段添加参数是可以的。例如，超类可以为没有字符集参数的现有 Content-Type 字段添加一个字符集参数。

属性：

`GetAccess`	`public`
`SetAccess`	`public`

`ForceChunked` — 指示是否强制进行分块传输编码
`false` (默认) | `true`

指示是否强制进行分块传输编码，指定为布尔值。此属性仅对子类编写者有用，并且仅适用于不是作为 Multipart 代理的提供程序。子类通过设置 ForceChunked 来控制是否应使用分块传输编码发送内容。如果为 false（默认值），MATLAB 将根据消息待发送时是否了解消息的内容长度来决定是否发送分块内容：

如果 MATLAB 知道内容长度（例如，消息中包含 Content-Length 字段，或者此提供程序的 expectedContentLength 方法返回一个数字），则由 MATLAB 决定是否发送分块消息。
如果 MATLAB 不知道内容长度（标头中没有 Content-Length 字段而且 expectedContentLength 返回空），则 MATLAB 始终发送分块消息。

如果 ForceChunked 为 true，则无论 MATLAB 是否知道内容长度都会发送分块消息，除非已知长度小于块大小。如果此属性为 true，则消息中不能包含 Content-Length 字段，因为 HTTP 不允许分块消息具有 Content-Length 字段。但是，如果您希望 MATLAB 验证您返回的是预期的数据长度，则仍可以在 expectedContentLength 方法中返回非零值。

当 MATLAB 选择发送分块消息时，每个块的大小等于 getData 返回的数据长度。

MATLAB 在调用 complete 方法之后、调用 start 之前读取此值。它不会设置此字段。

属性：

`GetAccess`	`public`
`SetAccess`	`public`

`Request` — 要发送的请求消息
`matlab.net.http.RequestMessage`

要发送的请求消息，指定为 matlab.net.http.RequestMessage 对象。

此属性仅由子类编写者使用。在调用此使用程序中的其他方法之前，以及在添加其他标头字段或验证消息之前，RequestMessage.send 和 RequestMessage.complete 方法将此属性设置为此提供程序原来所在的 Body 的 RequestMessage。提供程序可以检查此消息，以查看原始请求中包含的内容。

代理与委托方看到的此属性值是相同的。ContentProviders 应该明白，如果它们是代理，则不一定提供请求消息的完整主体，因此不应该假定此 Request 中的标头字段与它们提供的数据相关。通常，代理应忽略此请求中与数据相关的标头字段，例如 Content-Type。

如果提供程序希望为此消息添加任何标头字段或修改现有标头字段，应在其 complete 方法中将这些字段添加到 Header 属性中。complete 的调用方（RequestMessage 或委托方提供程序）决定如何处理这些字段。RequestMessage.send 和 RequestMessage.complete 始终将这些字段复制到 RequestMessage 的 Header 中。委托方提供程序可将这些字段复制到自己的 Header 属性中，或者将它们插入到消息中（就像在 MultipartProvider 中那样）。有关详细信息，请参阅 Header 属性。

此属性是只读的。

属性：

`GetAccess`	`public`
`SetAccess`	`matlab.net.http.RequestMessage`

受保护的属性

`CurrentDelegate` — 接受此提供程序委托的 `ContentProvider`
`matlab.net.http.io.ContentProvider` | 空

接受此提供程序委托的 ContentProvider，指定为 matlab.net.http.io.ContentProvider 对象。此属性在调用方提供程序（委托方）中由 delegateTo 方法设置，以指示当前接受委托的提供程序。如果当前没有委托，则此值为空。

complete 方法将此属性设置为空。

属性：

`GetAccess`	`protected`
`SetAccess`	`protected`

`MyDelegator` — 向此提供程序进行委托的 `ContentProvider`
`matlab.net.http.io.ContentProvider.empty` (默认) | `matlab.net.http.io.ContentProvider`

向此提供程序进行委托的 ContentProvider，指定为 matlab.net.http.io.ContentProvider 对象。

如果 ContentProvider 将发送全部或部分消息数据的责任委托给另一个提供程序，则此属性向代理标识委托方提供程序。例如，MultipartProvider 将消息的各个部分委托给其他提供程序，因此它会在每个代理中插入自己的句柄。否则，MyDelegator 为空。delegateTo 方法在代理中设置此属性。

属性：

`GetAccess`	`protected`
`SetAccess`	`protected`

方法

全部展开

公共方法

`string`	以字符串形式显示 ContentProvider
`show`	显示 ContentProvider 信息

受保护方法

`complete`	完成 ContentProvider 的 HTTP 标头
`preferredBufferSize`	ContentProvider 的首选缓冲区大小
`expectedContentLength`	ContentProvider 的内容长度
`start`	开始从 ContentProvider 进行数据传输
`restartable`	指示 ContentProvider 是否可重启
`reusable`	指示 ContentProvider 是否可重用
`delegateTo`	委托给另一个提供程序

抽象方法

getData HTTP 请求消息中要从 ContentProvider 发送的下一个数据缓冲区

详细信息

全部展开

可重启性和可重用性

提供程序可以是可重启和/或可重用的。可重启意味着提供程序可以多次重复发送相同的消息，每次 MATLAB 调用 start 都发送相同的数据流，即使上一次使用没有正常完成。此行为是有必要的，因为服务器可以将消息重定向到不同的服务器，这样就意味着需要重新传输数据。在这种情况下，MATLAB 会调用 start 而不再调用 complete。MATLAB 调用 restartable 方法来确定提供程序是否可重启。如果为 false，若 MATLAB 需要对已启动的提供程序调用 start，而且中间没有调用 complete（只有新消息才会发生），则会引发异常。

可重用意味着每次 MATLAB 调用提供程序的 complete 方法时，可将提供程序重用于不同（或相同的）的消息。MATLAB 调用 reusable 方法来确定提供程序是否可以重用。如果为 false，若 MATLAB 需要对已启动的提供程序调用 complete，则会引发异常。如果提供程序可重用，则假定下一次调用 start 应该成功，即使提供程序可以重启。

ContentProvider 为 restartable 和 reusable 都返回 false，因此如果您直接使用可重启或可重用提供程序扩展此基础类，则应覆盖这两个方法或其中之一，以返回 true。matlab.net.http.io 命名空间中 ContentProvider 的所有具体子类都是既可重启又可重用的，因此它们对这两个方法都返回 true。如果您使用不可重用也不可重启的提供程序扩展这些子类之一，则需要覆盖这两个方法或其中之一，以返回 false。

此示例中的 MyProvider 类不可重启也不可重用，因为提供程序在消息结束时关闭文件。要使其可重用，应在 complete 方法而不是构造函数中进行 fopen 调用，从而将提供程序的状态还原为用于某个消息之前的状态。

     classdef MyProvider < matlab.net.http.io.ContentProvider
        properties
            FileID double
            Name string
        end
 
        methods
            function obj = MyProvider(name)
                obj.Name = name;
            end
 
            function [data, stop] = getData(obj, length)
                ...as above...
            end
 
            function complete(obj, uri)
                obj.FileID = fopen(name);
                obj.complete@matlab.net.http.io.ContentProvider();
            end
 
            function tf = reusable(~)
                tf = true;
            end
            
            function delete(obj)
                ...as above...
            end
        end
      end

要使提供程序可重启，请添加 restartable 和 start 方法，并在 start 中发出 fseek 以使文件“倒带”：

            function start(obj)
                obj.start@matlab.net.http.io.ContentProvider();
                fseek(obj.FileID, 0, -1);
            end
 
            function tf = restartable(~)
                tf = true;
            end

当您对主体中包含 ContentProvider 的 RequestMessage 调用 complete 或 send 时，MATLAB 会在添加自动字段之前将提供程序中的 Request 属性设置为提供程序所在的 RequestMessage，并将 Header 属性设置为 Request 中的标头。然后按以下顺序调用提供程序中的以下方法：

complete - 在消息完成时调用，通常每个消息发生一次（在您调用 RequestMessage.send 或 RequestMessage.complete 时）。提供程序应将其 Header 属性设置为要添加到特定于提供程序的消息中的任何标头字段。如果 MATLAB 之后再调用此方法，提供程序应假定要将它用于新消息。大多数提供程序都需实现此方法来添加标头，然后，如果它们不是此抽象类的直接子类，则应该调用超类的 complete 来调用其他任何默认行为。MATLAB 在一个提供程序中调用 complete 的次数不会超过一次，除非其 reusable 方法返回 true。此抽象类默认情况下是不可重用的，但 matlab.net.http.io 命名空间中的所有具体提供程序都是可重用的。
preferredBufferSize/expectedContentLength - 从 RequestMessage.send 中调用，有时在 complete 之后、调用 start 之前。大多数提供程序都不需要实现这些方法，因为默认行为就是合适的。但是，提供程序可以覆盖此方法以支持 force 参量。

从这些方法返回后，MATLAB 将 RequestMessage 的标头发送给服务器。当准备好发送主体时，MATLAB 会调用这些方法。

start - 从 RequestMessage.send 中调用，有时在调用前面的方法之后，在 MATLAB 已经确定服务器已准备好接收请求消息的主体时调用。如果 MATLAB 之后再调用此方法（中间没有调用 complete），则提供程序应假定这是要求它再次重新发送同一个消息的主体（使用相同的标头）。自最后一次调用 complete 之后，MATLAB 调用 start 的次数不会超过一次，除非提供程序的 restartable 方法返回 true。此抽象类默认情况下是不可重启的，但 matlab.net.http.io 命名空间中的所有具体提供程序都是可重启的。
getData - 在调用 start 之后而 RequestMessage.send 被阻止时多次调用，每当 MATLAB 确定服务器已准备好接收新的数据缓冲区时就会调用一次。此方法必须返回 uint8 数据向量。提供程序通过返回 stop 指示符来指示数据结束。所有提供程序都必须实现此方法。

在 getData 返回 stop 指示符后，MATLAB 将结束请求消息并等待服务器的响应。

委托

插入到 RequestMessage.Body 中的 ContentProvider 可以委托另外一个或多个提供程序来提供消息的全部或部分数据。例如，MultipartProvider 创建一个由多个部分组成的消息，每一部分由指定给 MultipartProvider 构造函数的其他的提供程序来提供。在这种情况下，MultipartProvider 就是委托方，其他提供程序就是代理，每个代理被依次调用，以提供各自的标头字段和该部分数据。

提供程序通过调用 delegateTo 委托给另一个提供程序（即代理），此方法将 CurrentDelegate 设置为该代理，并将该代理的 MyDelegator 设置为当前提供程序（即委托方），然后调用该代理的 complete 和 start 方法，并返回 GetDataFcn 函数句柄。然后，委托方的 getData 方法调用代理的 GetDataFcn 以获取数据，可能会在返回给 MATLAB 之前更改数据。提供程序通常不需要检查它们是否为代理，或者是谁委托给它们。

类层次结构

版本历史记录

在 R2018a 中推出

另请参阅

matlab.net.http.io.ContentProvider 类

描述

子类编写者须知

属性

公共属性

Header — 消息或组成部分的标头字段 matlab.net.http.HeaderField.empty (默认) | matlab.net.http.HeaderField

属性：

ForceChunked — 指示是否强制进行分块传输编码 false (默认) | true

属性：

Request — 要发送的请求消息 matlab.net.http.RequestMessage

受保护的属性

CurrentDelegate — 接受此提供程序委托的 ContentProvider matlab.net.http.io.ContentProvider | 空

属性：

MyDelegator — 向此提供程序进行委托的 ContentProvider matlab.net.http.io.ContentProvider.empty (默认) | matlab.net.http.io.ContentProvider

属性：

方法

公共方法

受保护方法

抽象方法

详细信息

可重启性和可重用性

委托

类层次结构

版本历史记录

另请参阅

WeChat

`Header` — 消息或组成部分的标头字段
`matlab.net.http.HeaderField.empty` (默认) | `matlab.net.http.HeaderField`

`ForceChunked` — 指示是否强制进行分块传输编码
`false` (默认) | `true`

`Request` — 要发送的请求消息
`matlab.net.http.RequestMessage`

`CurrentDelegate` — 接受此提供程序委托的 `ContentProvider`
`matlab.net.http.io.ContentProvider` | 空

`MyDelegator` — 向此提供程序进行委托的 `ContentProvider`
`matlab.net.http.io.ContentProvider.empty` (默认) | `matlab.net.http.io.ContentProvider`