matlab.net.http.io.FileConsumer 类
命名空间: matlab.net.http.io
超类: matlab.net.http.io.ContentConsumer
HTTP 消息中的文件使用程序
描述
FileConsumer
类为从 Web 服务中下载文件或者将从 Web 上收到的数据保存到文件中提供了一种便捷方式。您可以指定文件的名称,也可以让 MATLAB® 根据服务器发送的信息或者 URI 中指定的文件来确定文件名。
matlab.net.http.io.FileConsumer
类是一个 handle
类。
创建对象
描述
consumer = FileConsumer(
构造一个 filename
,permission
,machineformat
,encoding
)FileConsumer
,它使用服务器响应的有效负载来创建或覆盖文件。这些参数的含义与 fopen
函数的参数相同,而且都是可选参数。
consumer = FileConsumer(
将 FID
)FileIdentifier
属性设置为 FID
并写入该文件。FID
必须是您打开要写入的文件的标识符。MATLAB 在文件中的当前位置指示符处写入,因此如果您使用 'a+'
等权限打开现有文件,MATLAB 会将信息追加到该文件中。传输完成后,MATLAB 会将位置指示符留在文件末尾,并且不关闭文件。
输入参量
filename
— 文件或文件夹名称
字符向量 | 字符串标量
文件或文件夹名称,包括完整路径和可选的扩展名,指定为字符向量或字符串标量。要确定 MATLAB 创建的文件的名称,请参阅 Filename
属性。
如果 filename
指定现有文件夹中的文件,MATLAB 将:
使用
fopen(filename,permission,...)
打开该文件。如果未指定
permission
,将使用fopen(filename,'w+')
打开该文件。如果
filename
不包含扩展名,MATLAB 将根据收到的消息中的 Content-Type 和/或 Content-Disposition 标头字段,或者根据请求的 URI 中的文件名的扩展名(如果有)添加一个扩展名。
如果 filename
指定现有可写文件夹,MATLAB 将在该文件夹中创建一个文件,文件名从响应中的 Content-Disposition 标头字段或请求的 URI 派生而来,如果该名称不包含扩展名,可能还会基于 Content-Type 添加一个扩展名。
如果 filename
缺失或为空,MATLAB 将在当前文件夹中创建一个文件。这与 filename
= '.'
等效。当前文件夹是指创建 FileConsumer
时的文件夹,而不是在 send
请求中使用此使用程序时的文件夹。
示例: 'myTextFile.txt'
数据类型: char
| string
permission
— 文件访问类型
w+
(默认) | u+
| u
| T
| fopen
函数允许的值
文件访问类型,指定为字符串。如果指定 permission
,则它必须允许写访问。默认值为 'w+'
,它会打开或创建一个文件进行读取和写入,并丢弃现有内容(如果有)。
permission
可以是 fopen
函数允许的任何值。还支持以下 permission
值:
| 与 例如,如果 |
| 追加到权限时,其行为与文本模式 |
在所有情况下,对于 'w'
和 'w+'
权限(或者未指定 permission
),MATLAB 都不会覆盖现有文件,除非文件名与 filename
完全匹配。
示例: 'a'
'w+T'
数据类型: char
| string
machineformat
— 读取或写入字节或位的顺序
fopen
允许的任何值
读取或写入字节或位的顺序,指定为 fopen
函数允许的任何值。
数据类型: char
| string
encoding
— 字符编码
fopen
允许的任何值
字符编码,指定为 fopen
函数允许的任何值。
数据类型: char
| string
属性
公共属性
FileIdentifier
— 文件标识符
双精度值
正在写入的文件的标识符 (FID),指定为双精度值。如果使用程序是用 FID 参量构造的,则此属性就是标识符。数据写入到与此标识符关联的当前文件位置指示符处,因此子类在使用此标识符时应小心,避免误改位置。传输结束时,文件保持打开状态,并且位置保留在文件末尾。
如果调用构造函数时带有 filename
参量,或者不带任何参量,则此属性是该文件的只读文件标识符。这允许子类在传输过程中读取文件,而不会干扰用于写入的位置指示符。当传输结束时,将关闭此标识符。
属性:
GetAccess | public |
SetAccess | private |
Filename
— 文件路径名称
string.empty
(默认) | 字符串
正在写入的文件的完整路径名称,指定为字符串。如果使用程序是使用 FID 参量构造的,则此属性就是该文件的名称。否则,MATLAB 在接收响应消息期间,在开始写入文件之前可能不会设置此值,因为在收到所有标头之前,不一定能够确定文件名。可以使用此属性确定已写入的文件。Filename
还存储在 Response.Body.Data
属性中。
属性:
GetAccess | public |
SetAccess | private |
ContentLength
— 有效负载的预期长度
uint64
| 空
有效负载的预期长度,指定为 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 |
ContentType
— 有效负载的媒体类型
matlab.net.http.MediaType
| 空
有效负载的媒体类型,指定为 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 |
Header
— 当前正在处理的有效负载的标头
matlab.net.http.HeaderField
当前正在处理的有效负载的标头,指定为 matlab.net.http.HeaderField
对象。
使用程序根据此标头确定如何处理发送给它们的有效负载。对于顶层使用程序,此值与 Response.Header
相同。对于代理来说,值可能不同。例如,在 MultipartConsumer
处理的 multipart 消息中,它是此代理正在处理的那一部分的标头。代理仍然可以检查 Response.Header
以获得原始消息的标头。
MATLAB 在调用 initialize
之前设置此属性,从而为子类提供方便。
属性:
GetAccess | public |
SetAccess | public |
Request
— 发送的已完成的 RequestMessage
matlab.net.http.RequestMessage
发送的已完成的 RequestMessage
,指定为 matlab.net.http.RequestMessage
对象。这是所有重定向之后的最后一个 RequestMessage
,它是来自 send
方法的 completedrequest
返回值。
MATLAB 在调用 initialize
之前设置此属性,从而为子类提供方便。
属性:
GetAccess | public |
SetAccess | public |
Response
— 正在处理的 ResponseMessage
matlab.net.http.ResponseMessage
正在处理的 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 |
URI
— 正在处理的请求的目标
matlab.net.URI
正在处理的请求的目标,指定为 matlab.net.URI
对象。此值是由 send
确定的原始目标 URI。它不是代理的 URI 或重定向后的最终 URI。
MATLAB 在调用 initialize
之前设置此属性,从而为子类提供方便。
属性:
GetAccess | public |
SetAccess | public |
受保护的属性
AppendFcn
— putData
为了追加附加数据而调用的函数
函数句柄
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 |
CurrentDelegate
— 接受此使用程序委托的 ContentConsumerContentConsumer
matlab.net.http.io.ContentConsumer
| []
接受此使用程序委托的 ContentConsumer
,指定为 matlab.net.http.io.ContentConsumer
对象。主调使用程序(委托方)的 delegateTo
方法设置 CurrentDelegate
属性。如果当前没有委托,则值为 []
。
在调用 initialize
之前,MATLAB 将 CurrentDelegate
设置为 []
。
属性:
GetAccess | protected |
SetAccess | protected |
CurrentLength
— 当前 Response.Body.Data
中的数据的长度
uint64.empty
(默认) | uint64
当前 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 |
MyDelegator
— 向此使用程序进行委托的 ContentConsumer
matlab.net.http.io.ContentConsumer
| 空
向此使用程序进行委托的 ContentConsumer
,指定为 matlab.net.http.io.ContentConsumer
对象。如果此使用程序是一个代理,由另一个使用程序(例如 GenericConsumer
或 MultipartConsumer
)调用,则此使用程序就是主调使用程序。在调用 send
时指定的顶层使用程序中为空。
代理可以使用此属性访问委托方的属性,例如,为了确定哪些使用程序向它们进行了委托。
属性:
GetAccess | protected |
SetAccess | protected |
方法
公共方法
initialize | 配置使用程序以处理新的 HTTP 有效负载 |
start | 开始向 FileConsumer 传输文件 |
putData | 将 FileConsumer 的下一个数据缓冲区保存到文件中 |
delegateTo | 委托给另一个使用程序 |
详细信息
类层次结构
版本历史记录
在 R2018a 中推出
MATLAB 命令
您点击的链接对应于以下 MATLAB 命令:
请在 MATLAB 命令行窗口中直接输入以执行命令。Web 浏览器不支持 MATLAB 命令。
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)