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) は、リモート ホスト address とリモート ポート port に関連付けられているサーバーに接続する TCP/IP クライアントを作成します。address の値は、リモート ホスト名またはリモート ホストの IP アドレスのいずれかになります。port の値は、1 ～ 65535 の間の数値でなければなりません。入力 address は Address プロパティを設定し、入力 port は Port プロパティを設定します。

無効なアドレスまたはポートを指定した場合、TCP/IP サーバーが実行されないか、サーバーに対する接続が確立されず、オブジェクトが作成されずに MATLAB はエラーをスローします。

例

t = tcpclient(address,port,Name,Value) は、接続を作成し、1 つ以上の名前と値のペアの引数を使用して追加のプロパティを設定します。名前と値のペアの引数を使用して、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 秒に設定されます。

例

プロパティ

すべて展開する

オブジェクト作成プロパティ

リモート ホスト名または IP アドレス。文字ベクトルまたは string スカラーとして指定します。このプロパティは、オブジェクトの作成時にのみ設定できます。

例: 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

リモート ホスト ポート。1 ～ 65535 の数値として指定します (上下限値を含む)。このプロパティは、オブジェクトの作成時にのみ設定できます。

例: t = tcpclient("www.mathworks.com",80) は、www.mathworks.com のポート 4012 への TCP/IP クライアント接続を作成します。

データ型: double

読み取り操作と書き込み操作の完了までの許容時間 (秒単位)。数値として指定します。名前と値のペアの引数を使用して、オブジェクトの作成時にこのプロパティを設定します。ドット表記を使用して、オブジェクトを作成した後にプロパティを変更することもできます。

例: t = tcpclient("144.212.130.17",80,"Timeout",20) は、読み取り/書き込みのタイムアウト期間を 20 秒に設定します。

データ型: double

リモート ホストへの接続までの許容時間 (秒単位)。数値として指定します。このプロパティは、指定したリモート ホストへの接続要求が成功または失敗するまで待機する最大時間を指定します。このプロパティは、オブジェクトの作成時にのみ設定できます。

例: t = tcpclient("144.212.130.17",80,"ConnectTimeout",30) は、接続タイムアウト期間を 30 秒に設定します。

データ型: double

サーバーからの肯定応答の遅延を許可。logical の true または false として指定します。このプロパティは、Nagle アルゴリズムが接続に対してオンとオフのどちらであるかを示します。

このプロパティが true の場合、クライアントは未処理データの小さなセグメントを集め、肯定応答 (ACK) がサーバーから到着すると単一のパケットで送信します。データを直ちにネットワークに送信する場合は、このプロパティを false に設定します。ネットワークが遅い場合は、転送遅延を有効にすることでパフォーマンスを改善できます。ただし、高速のネットワークでは ACK がすぐに到着し、転送遅延を有効にした場合と無効にした場合の差はごくわずかです。

このプロパティは、オブジェクトの作成時にのみ設定できます。

例: t = tcpclient("144.212.130.17",80,"EnableTransferDelay",false) は、転送遅延を無効にします。

データ型: logical

R2024a 以降

接続を識別するためのラベル。string として指定します。Tag は、後で tcpclientfind を使用して接続にアクセスするときに使用できるラベルを接続に適用するために使用します。これを行うと、いずれかの関数で接続を開いているときに、別の関数を使用して接続の操作を実行する場合に役立つことがあります。また、アプリのコールバックで接続を特定してアクセスするのにも便利です。

例: t = tcpclient("144.212.130.17",80,"Tag","Sensor") は、"Sensor" というラベルをもつ TCP/IP クライアントを作成します。

データ型: string

読み取りと書き込みのプロパティ

この プロパティ は読み取り専用です。

読み取り可能なバイト数。数値として返されます。

例: t.NumBytesAvailable は読み込みに使用できるバイト数を返します。

データ型: double

この プロパティ は読み取り専用です。

リモート ホストに書き込まれたバイトの合計数。数値として返されます。

例: t.NumBytesWritten は書き込まれたバイト数を返します。

データ型: double

大きい数値に複数のバイトを配置する順序。"little-endian" または "big-endian" として指定します。

このプロパティ値は、uint16、int16、uint32、int32、single、double などのマルチバイト データ型の読み取りおよび書き込み時に設定します。このプロパティ値は、tcpclient に接続されたリモート ホストの構成に一致する必要があります。リモート ホストやその他のアプリケーションにおける既定のバイト順はビッグエンディアンである場合がありますが、このプロパティの既定値は little-endian です。

例: t.ByteOrder = "big-endian" は、バイト順をビッグエンディアンに設定します。

データ型: char | string

ASCII 終端データの読み取りと書き込みの終端文字。"LF"、"CR"、"CR/LF"、または 0 ～ 255 の数値として返されます。読み取りおよび書き込み終端文字が異なる場合、Terminator は、これらの値の 1 行 2 列の cell 配列として返されます。このプロパティは、関数 configureTerminator を使用して設定します。

例: configureTerminator(t,"CR") は、読み取りと書き込み両方の終端文字を "CR" に設定します。

例: configureTerminator(t,"CR",10) は、読み取り終端文字を "CR" に、書き込み終端文字を 10 に設定します。

データ型: double | char | string

コールバック プロパティ

使用可能なバイト数のコールバック トリガー モード。"off"、"byte" または "terminator" として返されます。この設定では、コールバックをオフにするか、BytesAvailableFcnCount で指定されたバイト数でトリガーするか、または Terminator で指定された終端文字でトリガーするかを決定します。このプロパティは、関数 configureCallback を使用して設定します。

例: configureCallback(t,"byte",50,@callbackFcn) は、新しいデータの 50 バイトが読み取り可能になるたびに callbackFcn コールバックがトリガーするように設定します。

例: configureCallback(t,"terminator",@callbackFcn) は、終端文字が読み取り可能なときにトリガーするように、callbackFcn コールバックを設定します。

例: configureCallback(dev,"off") はコールバックをオフにします。

データ型: char | string

BytesAvailableFcn で指定されたコールバックをトリガーするデータのバイト数。double として返されます。この値は、BytesAvailableFcnMode プロパティが "byte" である場合にのみ使用されます。これらのプロパティは、関数 configureCallback を使用して設定します。

例: configureCallback(t,"byte",50,@callbackFcn) は、新しいデータの 50 バイトが読み取り可能になるたびに callbackFcn コールバックがトリガーするように設定します。

データ型: double

バイト利用可能なイベントでトリガーされるコールバック関数。関数ハンドルとして返されます。バイト利用可能なイベントは、特定のバイト数または終端文字を受信して生成されます。このプロパティは、関数ハンドルを割り当てるまでは空です。このプロパティは、関数 configureCallback を使用して設定します。

例: configureCallback(t,"byte",50,@callbackFcn) は、新しいデータの 50 バイトが読み取り可能になるたびに callbackFcn コールバックがトリガーするように設定します。

データ型: function_handle

エラー イベントによりトリガーされるコールバック関数。関数ハンドルとして返されます。非同期の読み取りまたは書き込みエラーが発生すると、エラー イベントが生成されます。このプロパティは、関数ハンドルを割り当てるまでは空です。

例: t.ErrorOccurredFcn = @myErrorFcn

データ型: function_handle

ユーザー データの汎用プロパティ。任意の MATLAB データ型として返されます。たとえば、このプロパティを使用すると、コールバック関数からイベントがトリガーされるときにデータを保存できます。

例: t.UserData

オブジェクト関数

readTCP/IP を介したリモート ホストからのデータの読み取り
readlineTCP/IP を介したリモート ホストからの ASCII 文字列データ行の読み取り
writeTCP/IP を介したリモート ホストへのデータの書き込み
writelineTCP/IP を介したリモート ホストへの ASCII データ行の書き込み
configureTerminatorTCP/IP を介したリモート ホストとの ASCII 文字列通信用に終端文字を設定
configureCallbackTCP/IP を介してリモート ホストと通信するためのコールバック関数とトリガー条件の設定
flushTCP/IP を介したリモート ホストとの通信のバッファーをクリア
deleteハンドル オブジェクトの削除
clearワークスペースからアイテムを削除し、システムメモリを解放

例

すべて折りたたむ

ライブ スクリプトを開く

次に示すホスト アドレスとポート 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 アドレスとポート 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
ライブ スクリプトを開く

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

出力にはプロパティの変更が反映されます。

ライブ スクリプトを開く

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

出力にはプロパティの変更が反映されます。

ライブ スクリプトを開く

t という TCP/IP クライアント接続を作成します。TCP/IP エコー サーバーにポート 4000 で接続します。そのためには、echotcpip サーバーをポート 4000 で実行していなければなりません。

echotcpip("on",4000)
t = tcpclient("localhost",4000)
t = 
  tcpclient with properties:

              Address: 'localhost'
                 Port: 4000
    NumBytesAvailable: 0

  Show all properties, functions

関数 write は、t に接続されたリモート ホストにデータを同期的に書き込みます。まずデータを指定し、次にデータを書き込みます。指定された数の値がリモート ホストに書き込まれるまで、MATLAB の実行は一時停止されます。

10 バイトの uint8 データを変数 data に割り当てます。

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")

スクリプトや 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 =

     []

tcpclient 接続が MATLAB ワークスペースに存在しているか、クラスのプロパティやアプリのプロパティとして保存されている場合、別の関数やアプリのコールバックで 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
T = 

  handle to deleted tcpclient

この変数がインターフェイスの削除後も残るのは、tcpclient が "ハンドル オブジェクト" であるためです。(このタイプのオブジェクトの詳細については、ハンドル オブジェクトの動作を参照してください。)無効なハンドルは clear を使用してワークスペースから削除できます。

clear T

拡張機能

すべて展開する

バージョン履歴

R2014b で導入

すべて展開する

参考

トピック