WebSocket
WebSocket
クラスを使用すると、サーバーとの WebSocket クライアント接続を開いて、データを送受信し、接続を閉じることができます。
WebSocketクライアント接続は、たとえばリアルタイムで財務データを受信したり、チャットでメッセージを送受信したりするのに便利です。
履歴
リリース | 内容 |
---|---|
20 R2 | 追加 |
例題
この例題では、基本的な WebSocketクライアントを作成します。
- WebSocket イベントコールバックを処理するためのコールバック関数を含む
WSConnectionHandler
ユーザークラスを作成します:
// WSConnectionHandler クラス
Class constructor
Function onMessage($ws : 4D.WebSocket; $event : Object)
ALERT($event.data)
Function onTerminate($ws : 4D.WebSocket; $event : Object)
ALERT("接続を終了しました")
- 4D.WebSocket をインスタンス化して、4Dフォームから WebSocketサーバーに接続します:
Form.webSocket:=4D.WebSocket.new($wssUrl; cs.WSConnectionHandler.new())
- 4Dフォームから WebSocketサーバーにメッセージを送るには、次のように書きます:
Form.webSocket.send("Hello world")
WebSocket オブジェクト
WebSocketオブジェクトは、以下のプロパティと機能を提供します:
.dataType : Text レスポンス本文のデータ型です |
.handler : Object 接続を開始するのに使用された connectionHandler オブジェクトを取得するアクセサーを格納します |
.id : Longint 接続の一意な識別子を格納します |
.send( message : Text ) .send( message : Blob ) .send( message : Object ) 定義されたデータ型 (Text、Blob、または Object) で、WebSocket サーバーに message を送信します |
.status : Text 現在の接続ステータスを格納します ("Connecting"、"Closing"、"Closed"、"Connected" のいずれか) |
.terminate( { code : Integer { ; reason : Text } } ) 任意の code および reason 引数とともに、WebSocket 接続を閉じます |
.url : Text WebSocket が接続した URL を格納します |
4D.WebSocket.new()
履歴
リリース | 内容 |
---|---|
20 R3 | connectionHandler で headers プロパティをサポート |
4D.WebSocket.new( url : Text { ; connectionHandler : Object } ) : 4D.WebSocket
引数 | 型 | 説明 | |
---|---|---|---|
url | Text | -> | 接続先の URL |
connectionHandler | Object | -> | WebSocket用コールバックを宣言しているオブジェクト |
戻り値 | 4D.WebSocket | <- | 新しい WebSocket オブジェクト |
4D.WebSocket.new()
関数は、url で指定したアドレスの WebSocketサーバーに接続された新しい 4D.WebSocket
オブジェクト を作成して返します。 4D.WebSocket
オブジェクトは、サーバーとの WebSocket接続の作成と管理、およびデータの送受信のための API を提供します。
urlには、WebSocketサーバーが応答する URL を渡します。 以下の URLパターンが使用できます:
- 標準接続用:
ws://host[:port]path[?query]
- TLSセキュア接続用:
wss://host[:port]path[?query]
接続できない場合、null
オブジェクトが返され、エラーが生成されます (このエラーは ON ERR CALL
で実装したメソッドによってインターセプトできます)。
connectionHandler パラメーター
connectionHandler には、接続イベントに応じて呼び出されるコールバック関数のほか、処理するデータ型やヘッダーを含むオブジェクトを渡すことができます。
- コールバックは、接続を開始したフォームまたはワーカーのコンテキストで自動的に呼び出されます。
- フォームまたはワーカーが閉じられていない限り、WebSocket は有効です。
プロパティ | 型 | 説明 |
---|---|---|
onMessage | Function | WebSocket データ用のコールバック関数。 WebSocket がデータを受信するたびに呼び出されます。 コールバックは以下の引数を受け取ります:$1 : WebSocket オブジェクト$2 : Object
|
onError | Function | 実行エラー用のコールバック関数。 コールバックは以下の引数を受け取ります:$1 : WebSocket オブジェクト$2 : Object
|
onTerminate | Function | WebSocket が終了した時のコールバック関数。 コールバックは以下の引数を受け取ります:$1 : WebSocket オブジェクト$2 : Object
|
onOpen | Function | WebSocket が開始した時のコールバック関数。 コールバックは以下の引数を受け取ります:$1 : WebSocket オブジェクト$2 : Object
|
dataType | Text | 受信または送信されたデータの型。 可能な値: "text" (デフォルト), "blob", "object"。 "text" = utf-8 |
headers | Object | WebSocket のヘッダー。 headers.*key*:=*value* (同じ key を複数指定する場合、value にコレクションを使用できます)headers.Cookie:="*name*=*value* {; *name2*=*value2*{; ... } }" |
以下は、コールバック呼び出しの流 れです:
onOpen
は 1回実行されます。onMessage
が 0回以上実行されます。onError
が 0回または 1回実行されます (処理を停止します)。onTerminate
は常に実行されます。
例題
WSConnectionHandler
ユーザークラスでヘッダーを設定します:
// WSConnectionHandler クラス
Class constructor($myToken:Text)
// サーバーに送信するヘッダーを作成します
This.headers:=New object("x-authorization";$myToken)
// 2つの Cookie を設定します
This.headers.Cookie:="yummy_cookie=choco; tasty_cookie=strawberry"
...
.dataType
.dataType : Text
説明
.dataType
プロパティは、レスポンス本文のデータ型です。 "text"、"blob"、"object" のいずれかです。
このプロパティは 読み取り専用 です。
.handler
.handler : Object
説明
.handler
プロパティは、接続を開始するのに使用された connectionHandler
オブジェクトを取得するアクセサーを格納します。
このプロパティは 読み取り専用 です。
.id
.id : Longint
説明
.id
プロパティは、接続の一意な識別子を格納します。
このプロパティは 読み取り専用 です。
.send()
.send( message : Text )
.send( message : Blob )
.send( message : Object )
引数 | 型 | 説明 | |
---|---|---|---|
message | Text, Blob, Object | -> | 送信するメッセージ |
説明
.send()
関数は、定義されたデータ型 (Text、Blob、または Object) で、WebSocket サ ーバーに message を送信します。
メッセージ の型によって、以下の内容が送信されます:
型 | 内容 |
---|---|
Text | UTF-8 のテキスト |
BLOB | バイナリデータ |
Object | JSON UTF-8 のテキスト (JSON Stringify と同じ結果)。 |
.status
.status : Text
説明
.status
プロパティは、現在の接続ステータスを格納します ("Connecting"、"Closing"、"Closed"、"Connected" のいずれか)。
このプロパティは 読み取り専用 です。
.terminate()
.terminate( { code : Integer { ; reason : Text } } )
引数 | 型 | 説明 | |
---|---|---|---|
code | Integer | -> | 接続が切断される理由を示すステータスコード |
reason | Text | -> | 接続が切断される理由を説明するテキスト |
説明
.terminate()
関数は、任意の code および reason 引数とともに、WebSocket 接続を閉じます。
code には、接続を閉じる理由を説明するステータスコードを渡すことができます (RFC6455 の WebSocket Connection Close Code も参照ください):
- 指定しなかった場合、接続のクローズコードは自動的に設定されます: 通常終了の場合は 1000、そうでない場合は、接続が切断された実際の理由を示す 1001〜1015 の標準値。
- 指定された場合、この code パラメーターの値は自動設定の値をオーバーライドします。 値は整数でなくてはなりません。 1000、または 3000-4999 の範囲のカスタムコードが利用できます。 code を指定する場合は、reason の値も指定する必要があります。
reason には、接続を閉じる理由を説明するテキストを渡すことができます。
.url
.url : Text
説明
.url
プロパティは、WebSocket が接続した URL を格納します。 これは、new()
関数に渡した URL と同じです。
このプロパティは 読み取り専用 です。