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)

t = tcpclient(address,port,Name,Value)

描述

t = tcpclient(address,port) 创建一个 TCP/IP 客户端，该客户端连接到与远程主机 address 和远程端口 port 相关联的服务器。address 的值可以是远程主机名或远程主机 IP 地址。port 的值必须是 1 到 65535 之间的一个数字。输入 address 设置 Address 属性，输入 port 设置 Port 属性。

如果您指定了无效的地址或端口、TCP/IP 服务器没有运行或无法建立到服务器的连接，则不会创建对象，并且 MATLAB 会抛出错误。

示例

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 = 

  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 访问该连接。

另请参阅

tcpclientfind

tcpclient

说明

创建对象

语法

描述

属性

对象的创建属性

Address — 远程主机名或 IP 地址 字符向量 | 字符串标量

Port — 远程主机端口 数值

Timeout — 允许的完成操作的时间 10 (默认) | 数值

ConnectTimeout — 连接到远程主机的允许时间 Inf (默认) | 数值

EnableTransferDelay — 允许来自服务器的延迟确认 true 或 1 (默认) | false 或 0

Tag — 用于标识连接的标签 "" (默认) | 字符串

读取和写入属性

NumBytesAvailable — 可供读取的字节数 只读: 数值

NumBytesWritten — 写入远程主机的总字节数 只读: 0 (默认) | 数值

ByteOrder — 字节的顺序 "little-endian" (默认) | "big-endian"

Terminator — 数据的终止符字符 "LF" (默认) | "CR" | "CR/LF" | 0 至 255

回调属性

BytesAvailableFcnMode — 字节可用回调触发模式 "off" (默认) | "byte" | "terminator"

BytesAvailableFcnCount — 触发回调的数据字节数 64 (默认) | 数值

BytesAvailableFcn — 由字节可用事件触发的回调函数 函数句柄

ErrorOccurredFcn — 由错误事件触发的回调函数 函数句柄

UserData — 用户数据的通用属性 任意类型

对象函数

示例

使用主机名连接到 TCP/IP 远程主机

使用 IP 地址连接到 TCP/IP 远程主机

连接到 TCP/IP 远程主机并设置超时期限

连接到 TCP/IP 远程主机并设置连接超时期限

向远程主机写入和从中读取 uint8 数据

断开与单个 TCP/IP 客户端的连接

在函数或 App 回调中断开与 TCP/IP 客户端的连接

扩展功能

C/C++ 代码生成 使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

版本历史记录

R2024a: 新的 Tag 属性

另请参阅

主题

`Address` — 远程主机名或 IP 地址
字符向量 | 字符串标量

`Port` — 远程主机端口
数值

`Timeout` — 允许的完成操作的时间
10 (默认) | 数值

`ConnectTimeout` — 连接到远程主机的允许时间
`Inf` (默认) | 数值

`EnableTransferDelay` — 允许来自服务器的延迟确认
`true` 或 `1` (默认) | `false` 或 `0`

`Tag` — 用于标识连接的标签
`""` (默认) | 字符串

`NumBytesAvailable` — 可供读取的字节数
只读: 数值

`NumBytesWritten` — 写入远程主机的总字节数
只读: 0 (默认) | 数值

`ByteOrder` — 字节的顺序
`"little-endian"` (默认) | `"big-endian"`

`Terminator` — 数据的终止符字符
`"LF"` (默认) | `"CR"` | `"CR/LF"` | 0 至 255

`BytesAvailableFcnMode` — 字节可用回调触发模式
`"off"` (默认) | `"byte"` | `"terminator"`

`BytesAvailableFcnCount` — 触发回调的数据字节数
64 (默认) | 数值

`BytesAvailableFcn` — 由字节可用事件触发的回调函数
函数句柄

`ErrorOccurredFcn` — 由错误事件触发的回调函数
函数句柄

`UserData` — 用户数据的通用属性
任意类型

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

R2024a: 新的 `Tag` 属性