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。此属性指示 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 中推出

tcpclient

说明

创建对象

语法

描述

属性

对象的创建属性

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

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

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

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

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

读取和写入属性

`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 数据

扩展功能

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

版本历史记录

另请参阅

主题

tcpclient

说明

创建对象

语法

描述

属性

对象的创建属性

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

Port — 远程主机端口 数值

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

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

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

读取和写入属性

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 数据

扩展功能

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

版本历史记录

另请参阅

主题

WeChat

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

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

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

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

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

`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++ 代码。