tcpclient
创建与 TCP/IP 服务器的 TCP/IP 客户端连接
说明
tcpclient
对象表示从 MATLAB® 到远程主机和远程端口的连接,用于读写数据。远程主机可以是支持 TCP/IP 通信的服务器或硬件,并且必须已存在。tcpclient
对象始终是客户端,不能用作服务器。有关创建 TCP/IP 服务器的信息,请参阅Communicate Using TCP/IP Server Sockets (Instrument Control Toolbox)。
创建对象
描述
使用一个或多个名称-值对组参数创建连接并设置其他属性。使用名称-值对组参数设置 t
= tcpclient(address
,port
,Name,Value
)Timeout
、ConnectTimeout
和 EnableTransferDelay
属性。将每个属性名称用引号括起来,后跟属性值。
示例: t = tcpclient("144.212.130.17",80,"Timeout",20,"ConnectTimeout",30)
在 IP 地址 144.212.130.17 的端口 80 上创建到 TCP/IP 服务器的 TCP/IP 客户端连接。它将超时期限设置为 20 秒,将连接超时设置为 30 秒。
属性
对象的创建属性
Address
— 远程主机名或 IP 地址
字符向量 | 字符串标量
远程主机名或 IP 地址,指定为字符向量或字符串标量。此属性只能在创建对象时设置。
示例: t = tcpclient("www.mathworks.com",80)
创建到 www.mathworks.com 上的端口 80 的 TCP/IP 客户端连接。
示例: t = tcpclient("144.212.130.17",80)
在 IP 地址 144.212.130.17 的端口 80 上创建到 TCP/IP 服务器的 TCP/IP 客户端连接。
数据类型: char
| string
Port
— 远程主机端口
数值
远程主机端口,指定为 1 到 65535 之间(包括两者)的一个数字。此属性只能在创建对象时设置。
示例: t = tcpclient("www.mathworks.com",80)
创建到 www.mathworks.com 上的端口 4012 的 TCP/IP 客户端连接。
数据类型: double
Timeout
— 允许的完成操作的时间
10 (默认) | 数值
允许的完成读写操作的时间(以秒为单位),指定为数值。使用名称-值对组参数在创建对象时设置此属性。您也可以在创建对象后使用圆点表示法更改它。
示例: t = tcpclient("144.212.130.17",80,"Timeout",20)
将读取/写入超时期限设置为 20 秒。
数据类型: double
ConnectTimeout
— 连接到远程主机的允许时间
Inf
(默认) | 数值
连接到远程主机的允许时间(以秒为单位),指定为数值。此属性指定等待对指定远程主机的连接请求是成功还是失败的最长时间。此属性只能在创建对象时设置。
示例: t = tcpclient("144.212.130.17",80,"ConnectTimeout",30)
将连接超时期限设置为 30 秒。
数据类型: double
EnableTransferDelay
— 允许来自服务器的延迟确认
true
或 1
(默认) | false
或 0
允许来自服务器的延迟确认,指定为逻辑值 true
或 false
。此属性指示 Nagle 算法对于连接是打开还是关闭。
如果此属性为 true
,客户端将收集小段未完成的数据,并在收到来自服务器的确认 (ACK) 时以单个数据包的形式发送这些小数据段。如果要立即向网络发送数据,请将此属性设置为 false
。如果网络较慢,您可以通过启用传输延迟来改善其性能。然而,在快速网络中,确认会很快完成,启用或禁用传输延迟之间的差异可以忽略不计。
此属性只能在创建对象时设置。
示例: t = tcpclient("144.212.130.17",80,"EnableTransferDelay",false)
将禁用传输延迟。
数据类型: logical
读取和写入属性
NumBytesAvailable
— 可供读取的字节数
数值
此 属性 为只读。
可供读取的字节数,以数值形式返回。
示例: t.NumBytesAvailable
返回可供读取的字节数。
数据类型: double
NumBytesWritten
— 写入远程主机的总字节数
0 (默认) | 数值
此 属性 为只读。
写入远程主机的总字节数,以数值形式返回。
示例: t.NumBytesWritten
返回写入的字节数。
数据类型: double
ByteOrder
— 字节的顺序
"little-endian"
(默认) | "big-endian"
字节排列成较大数值的顺序,指定为 "little-endian"
或 "big-endian"
。
在读取和写入例如 uint16
、int16
、uint32
、int32
、single
或 double
多字节数据类型时设置此属性的值。此属性的值必须与连接到 tcpclient
的远程主机的配置匹配。远程主机或其他应用程序的默认字节顺序可能是 big-endian,而此属性的默认值为 little-endian
。
示例: t.ByteOrder = "big-endian"
将字节顺序设置为 big-endian。
数据类型: char
| string
Terminator
— 数据的终止符字符
"LF"
(默认) | "CR"
| "CR/LF"
| 0 至 255
用于读取和写入以 ASCII 字符结尾的数据的终止符字符,返回为 "LF"
、"CR"
、"CR/LF"
,或从 0 到 255(包括两者)的数字。如果读取终止符和写入终止符不同,则 Terminator
以这些值的 1×2 元胞数组形式返回。使用 configureTerminator
函数设置此属性。
示例: configureTerminator(t,"CR")
将读取终止符和写入终止符都设置为 "CR"
。
示例: configureTerminator(t,"CR",10)
将读取终止符设置为 "CR"
,将写入终止符设置为 10
。
数据类型: double
| char
| string
回调属性
BytesAvailableFcnMode
— 字节可用回调触发模式
"off"
(默认) | "byte"
| "terminator"
字节可用回调触发模式,返回为 "off"
、"byte"
或 "terminator"
。此设置确定回调是关闭、由 BytesAvailableFcnCount
指定的字节数触发还是由 Terminator
指定的终止符触发。使用 configureCallback
函数设置此属性。
示例: configureCallback(t,"byte",50,@callbackFcn)
将 callbackFcn
回调设置为每当有 50 个字节的新数据可供读取时触发。
示例: configureCallback(t,"terminator",@callbackFcn)
将 callbackFcn
回调设置为当终止符可供读取时触发。
示例: configureCallback(dev,"off")
关闭回调。
数据类型: char
| string
BytesAvailableFcnCount
— 触发回调的数据字节数
64 (默认) | 数值
由 BytesAvailableFcn
指定的触发回调的数据字节数,以双精度形式返回。仅当 BytesAvailableFcnMode
属性为 "byte"
时,才使用此值。使用 configureCallback
函数设置这些属性。
示例: configureCallback(t,"byte",50,@callbackFcn)
将 callbackFcn
回调设置为每当有 50 个字节的新数据可供读取时触发。
数据类型: double
BytesAvailableFcn
— 由字节可用事件触发的回调函数
函数句柄
由字节可用事件触发的回调函数,以函数句柄形式返回。接收到一定数量的字节或终止符会生成字节可用事件。在分配函数句柄之前,此属性为空。使用 configureCallback
函数设置此属性。
示例: configureCallback(t,"byte",50,@callbackFcn)
将 callbackFcn
回调设置为每当有 50 个字节的新数据可供读取时触发。
数据类型: function_handle
ErrorOccurredFcn
— 由错误事件触发的回调函数
函数句柄
由错误事件触发的回调函数,以函数句柄形式返回。发生异步读取或写入错误时,会生成错误事件。在分配函数句柄之前,此属性为空。
示例: t.ErrorOccurredFcn = @myErrorFcn
数据类型: function_handle
UserData
— 用户数据的通用属性
任意类型
用户数据的通用属性,以任何 MATLAB 数据类型形式返回。例如,当回调函数触发事件时,可以使用此属性存储数据。
示例: t.UserData
对象函数
read | 通过 TCP/IP 读取远程主机上的数据 |
readline | 通过 TCP/IP 从远程主机读取 ASCII 字符串数据行 |
write | 通过 TCP/IP 向远程主机写入数据 |
writeline | 通过 TCP/IP 向远程主机写入 ASCII 数据行 |
configureTerminator | 为通过 TCP/IP 与远程主机进行的 ASCII 字符串通信设置终止符 |
configureCallback | 为通过 TCP/IP 与远程主机的通信设置回调函数和触发条件 |
flush | 为通过 TCP/IP 与远程主机的通信清空缓冲区 |
示例
使用主机名连接到 TCP/IP 远程主机
使用所示的主机地址和端口 80
创建 TCP/IP 对象 t
。
t = tcpclient("www.mathworks.com",80)
t = tcpclient with properties: Address: 'www.mathworks.com' Port: 80 NumBytesAvailable: 0 Show all properties, functions
当您使用主机名(如指定的 Web 地址或 'localhost
)连接时,IP 地址默认为 IPv6 格式。如果您要连接的服务器需要 IPv4 格式,连接将失败。对于 IPv4,您可以通过指定显式 IP 地址而不是主机名来创建连接。
使用 IP 地址连接到 TCP/IP 远程主机
使用所示的 IP 地址和端口 80
创建一个名为 t
的 TCP/IP 客户端连接。
t = tcpclient("144.212.130.17",80)
t = tcpclient with properties: Address: '144.212.130.17' Port: 80 NumBytesAvailable: 0 Show all properties, functions
连接到 TCP/IP 远程主机并设置超时期限
创建一个名为 t
的 TCP/IP 客户端连接,并将超时期限设置为 20 秒。
t = tcpclient("144.212.130.17",80,"Timeout",20)
t = tcpclient with properties: Address: '144.212.130.17' Port: 80 NumBytesAvailable: 0 Show all properties, functions
ans = 20
请查看 Timeout
的值。
t.Timeout
输出会反映属性更改。
连接到 TCP/IP 远程主机并设置连接超时期限
创建一个名为 t
的 TCP/IP 客户端连接,并将 ConnectTimeout
属性设置为 30 秒。
t = tcpclient("144.212.130.17",80,"ConnectTimeout",30)
t = tcpclient with properties: Address: '144.212.130.17' Port: 80 NumBytesAvailable: 0 Show all properties, functions
请查看 ConnectTimeout
的值。
t.ConnectTimeout
ans = 30
输出会反映属性更改。
向远程主机写入和从中读取 uint8 数据
创建一个名为 t
的 TCP/IP 客户端连接,使用端口 4000 连接到 TCP/IP 回显服务器。为此,您必须有在端口 4000 上运行的 echotcpip
服务器。
echotcpip("on",4000) t = tcpclient("localhost",4000)
t = tcpclient with properties: Address: 'localhost' Port: 4000 NumBytesAvailable: 0 Show all properties, functions
write
函数以同步方式将数据写入连接到 t
的远程主机。首先指定数据,然后写入该数据。此函数将暂停 MATLAB 的执行,直到指定数量的值写入远程主机。
为变量 data
分配 10 个字节的 uint8
数据。
data = uint8(1:10)
data = 1×10 uint8 row vector
1 2 3 4 5 6 7 8 9 10
查看数据。
whos data
Name Size Bytes Class Attributes data 1x10 10 uint8
将数据写入回显服务器。
write(t,data)
通过查看 NumBytesAvailable
属性确认写入操作成功。
t.NumBytesAvailable
ans = 10
由于客户端连接到回显服务器,您写入服务器的数据将返回到客户端。读取所有可用的数据类型。
read(t)
ans = 1×10 uint8 row vector
1 2 3 4 5 6 7 8 9 10
如果使用不带任何参数的 read
函数,则会从连接到远程主机的 t
中读取所有可用字节数据,并返回这些数据。读取的值的数目由 NumBytesAvailable
属性确定,即输入缓冲区中可用的字节数。
通过清除 TCP/IP 客户端关闭该对象与远程主机之间的连接。关闭 echotcpip
服务器。
clear t echotcpip("off")
扩展功能
C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。
用法说明和限制:
仅桌面平台(Windows®、macOS、Linux®)和 Raspberry Pi® 支持特定于平台的代码生成。
以下
tcpclient
属性不支持代码生成:NumBytesAvailable
NumBytesWritten
ByteOrder
Terminator
BytesAvailableFcnMode
BytesAvailableFcnCount
BytesAvailableFcn
ErrorOccurredFcn
UserData
仅支持
Address
、Port
、Timeout
、ConnectTimeout
和EnableTransferDelay
。以下
tcpclient
对象函数不支持代码生成:readline
readbinblock
writeline
writebinblock
writeread
configureTerminator
configureCallback
flush
仅支持 read
和 write
。
版本历史记录
在 R2014b 中推出
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)