putData

类: matlab.net.http.io.ContentConsumer
命名空间: matlab.net.http.io

处理或保存 ContentConsumer 的下一个数据缓冲区

语法

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

说明

[size,stop] = putData(consumer,data) 为从服务器读取到 consumer 的 data 提供一个缓冲区。

MATLAB^® 调用 putData。子类使用程序可以覆盖此方法来接收以流方式传输的数据。您的使用程序应在 size 中返回实际处理的数据长度，在 stop 中返回 true/false 指示，以指定是否希望接收来自此消息的更多数据。

当 MATLAB 调用具有空 data 参量的 putData 时，即表示消息或 Multipart 消息中的一部分已结束。

如果您为实现此方法的使用程序创建子类，则您的 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) 时），将根据 CurrentLength 截断 Response.Body.Data。您可以定义自己的 AppendFcn 来实现其他追加方法。

默认情况下，此方法返回的 size 始终等于 numel(data)，stop 始终等于 false。

如果您打算使用此方法来存储数据，并且您知道要存储的数据的最大长度，则您应该在第一次调用此方法之前将 Response.Body.Data 设置为具有所需大小并用默认值（例如零值）填充的向量。此方法开始在数据区的开头处存储数据，并在消息结束时根据数据的长度截断，以维护 CurrentLength 中存储的数据长度。

调用此基类中的此方法通过增量方式存储数据的使用程序可以提供支持 horzcat 或 vertcat 的任何类型的 data，包括结构体和元胞数组。如果您提供元胞数组，现有数据将转换为元胞数组（如果尚未转换），并将元胞数组的元素插入到现有元胞数组中从 CurrentLength+1 开始的线性索引处。

如果您在 ContentConsumer 中调用此方法来存储数据，则应该让此方法管理 Response.Body.Data 或 CurrentLength，而不是直接修改它们。

在超类中调用此方法的 ContentConsumers 应准备好执行清理操作，例如，在超类引发异常时关闭窗口或删除临时文件。

输入参数

全部展开

`consumer` — 内容使用程序
`matlab.net.http.io.ContentConsumer`

内容使用程序，指定为 matlab.net.http.io.ContentConsumer 对象。

`data` — `ResponseMessage` 中的原始数据缓冲区
非空 `uint8` 向量 | `uint8.empty` | `[]`（空双精度值）

matlab.net.http.ResponseMessage 对象中的原始数据缓冲区，指定为下列选项之一：

非空 uint8 向量 - 从服务器读取的正常数据缓冲区。
uint8.empty - 数据结束。这是 MATLAB 指示响应消息已结束的正常方式。这是告诉使用程序执行清理操作（例如，删除临时文件或根据当前长度截断响应数据）并为将来可能的调用做好准备以便为后续消息进行初始化的信号。作为响应，使用程序应返回 stop=true 和 size=0，表示该处理已成功完成，未处理任何新字节。如果使用程序返回 size=[]，则说明使用程序在完成数据时遇到问题，MATLAB 会向 RequestMessage.send 的调用方返回 HTTPException。
[]（空双精度值）- 由服务器、网络问题或用户（使用 Ctrl+C）终止传输。使用程序通常应该像收到 uint8.empty 那样进行清理，但有些使用程序可能会删除任何已收到的不完整数据。从 putData 返回该数据后，MATLAB 会引发 HTTPException，其 History.Response 包含使用程序在其 Response 属性中存储的任何数据。

大多数不关心 [] 和 uint8.empty 区别的使用程序可以简单地检查 isempty(data) 并进行适当的清理。在 data 为空的所有情况下，使用程序必须使用相同的空值来调用它们的超类 putData，即使它们并未使用超类 putData 来存储数据，因为这是通知超类进行清理的唯一方法。在接收到空值 data 后，所有的实现都必须忽略对 putData 的后续空值调用，直到下一次调用 start 为止。通常，它们应为后续调用返回 stop=false 和 size=0，而不执行任何额外的处理。

输出参量

全部展开

`size` — 已处理的数据的长度
双精度值 | `[]`（空双精度值）

已处理的数据的长度，以双精度值或空双精度值形式返回。如果 size 的值符合以下情况：

size >= 0, size <= length(data) - 此次调用 putData 处理的 data 字节数。使用的数字只是为了让此使用程序的子类知道处理了多少数据，不影响将来对 putData 的调用。如果 data 为空，则忽略 size。
size < 0 - abs(size) 的结果是指已处理的字节数。与上一种情况相同，但除此之外，MATLAB 还会以静默方式跳过其余数据，在数据结尾处再次调用 putData(uint8.empty)。如果未使用 MultipartConsumer，除了最后再次调用 putData 外，这与返回 stop=true 类似。如果使用了 MultipartConsumer，则负值 size 只结束该部分，不影响对消息后续部分的处理，因此在到达消息的下一部分或结尾之前，连接不会关闭。
size = []（空双精度值）- 使用程序已经确定传输出现问题，应终止来自服务器的进一步传输。这与 stop=true 的情况类似，但被认为是错误，导致向 RequestMessage.send 的调用方返回标准 HTTPException，表明使用程序中断连接。在这种情况下，调用方获得部分处理的 ResponseMessage 的唯一方法是通过 HTTPException.History。
作为返回 size=[] 以引发标准异常的替代方法，您的 putData 方法可以直接引发自己的异常，MATLAB 将其作为原因包装在返回给 RequestMessage.send 调用方的 HTTPException 中。

`stop` — 指示是否接收更多数据
`false` (默认) | `true`

指示是否接收来自此消息的更多数据，指定为 true 或 false。如果 stop 为 true，MATLAB 将停止处理消息的其余数据（包括 MultipartConsumer 正在处理的 Multipart 消息的后续部分），以静默方式继续下一步操作，就好像已经到达消息末尾一样，即使消息中还有更多数据。这会立即关闭服务器连接，并且不向 RequestMessage.send 的调用方返回任何错误。这种情况不被视为错误，而是被视为终止接收任意长度的数据流的正常方式。如果 stop=true 而 data 尚未为空，则 MATLAB 用空 data 再次调用 putData。无论 data 是否为空，都可能会设置 stop=true。