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
。此属性指示纳格算法对于连接是打开还是关闭。
如果此属性为 true
,客户端将收集小段未完成的数据,并在收到来自服务器的确认 (ACK) 时以单个数据包的形式发送这些小数据段。如果要立即向网络发送数据,请将此属性设置为 false
。如果网络较慢,您可以通过启用传输延迟来改善其性能。然而,在快速网络中,确认会很快完成,启用或禁用传输延迟之间的差异可以忽略不计。
此属性只能在创建对象时设置。
示例: t = tcpclient("144.212.130.17",80,"EnableTransferDelay",false)
将禁用传输延迟。
数据类型: logical
Tag
— 用于标识连接的标签
""
(默认) | 字符串
自 R2024a 起
用于标识连接的标签,指定为字符串。使用 Tag
将标签应用于连接,您可以稍后使用 tcpclientfind
访问该连接。当您在一个函数中打开连接并使用另一个函数对该连接执行操作时,这样做非常有用。它对于定位和访问 App 回调中的连接也很有用。
示例: t = tcpclient("144.212.130.17",80,"Tag","Sensor")
使用标签 "Sensor"
创建一个 TCP/IP 客户端。
数据类型: string
读取和写入属性
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 与远程主机的通信清空缓冲区 |
delete | 删除句柄对象 |
clear | 从工作区中删除项目、释放系统内存 |
示例
使用主机名连接到 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")
断开与单个 TCP/IP 客户端的连接
当您在脚本中或在 MATLAB 命令行中使用 tcpclient
时,结果是由 MATLAB 工作区中的对象表示的连接。
t = tcpclient("192.168.1.2",10000,Timeout=2,Tag="Receive");
t = tcpclient with properties: Address: '192.168.1.2' Port: 10000 Tag: "Receive" NumBytesAvailable: 0
当其他变量中不存在对该同一连接的引用时,可以通过清除工作区变量来断开与 TCP/IP 客户端的连接。
clear(t)
使用 tcpclientfind
确认连接已关闭。
tcpclientfind
ans = []
在函数或 App 回调中断开与 TCP/IP 客户端的连接
当一个 tcpclient
连接存在于 MATLAB 工作区中或保存为类属性或 App 属性时,可能无法在不同函数或 App 回调中访问 tcpclient
对象。在这种情况下,您可以使用 tcpclientfind
查找和删除该连接。
T = tcpclientfind
T = tcpclient with properties: Address: '198.51.100.255' Port: 80 Tag: "" NumBytesAvailable: 0
要关闭此连接,请删除 T
。
delete(T)
此命令删除 tcpclient
对象并断开与客户端的连接。如果您随后要重新连接到主机,您必须使用 tcpclient
创建一个新客户端接口。
在删除后,调用 tcpclientfind
确认没有现有连接。
tcpclientfind
ans = []
请注意,变量 T
仍存在于工作区中,但它现在是无效句柄。
T
N = handle to deleted tcpclient
由于 tcpclient
是句柄对象,因此该变量在删除接口后仍存在。(有关这种类型的对象的详细信息,请参阅句柄对象行为。)您可以使用 clear
从工作区中删除无效的句柄。
clear T
扩展功能
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 中推出R2024a: 新的 Tag
属性
使用新的 Tag
属性将标签应用于连接,您可以稍后使用 tcpclientfind
访问该连接。
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)