メインコンテンツまでスキップ
バージョン: 20 R10

WebSocket

WebSocket クラスを使用すると、サーバーとの WebSocket クライアント接続を開いて、データを送受信し、接続を閉じることができます。

WebSocketクライアント接続は、たとえばリアルタイムで財務データを受信したり、チャットでメッセージを送受信したりするのに便利です。

履歴
リリース内容
20 R2追加

例題​

この例題では、基本的な WebSocketクライアントを作成します。

  1. WebSocket イベントコールバックを処理するためのコールバック関数を含む WSConnectionHandler ユーザークラスを作成します:
// WSConnectionHandler クラス

Class constructor

Function onMessage($ws : 4D.WebSocket; $event : Object)
   ALERT($event.data)

Function onTerminate($ws : 4D.WebSocket; $event : Object)
   ALERT("接続を終了しました")
  1. 4D.WebSocket をインスタンス化して、4Dフォームから WebSocketサーバーに接続します:
Form.webSocket:=4D.WebSocket.new($wssUrl; cs.WSConnectionHandler.new())
  1. 4Dフォームから WebSocketサーバーにメッセージを送るには、次のように書きます:
Form.webSocket.send("Hello world")

WebSocket オブジェクト​

WebSocketオブジェクトは、以下のプロパティと機能を提供します:

.dataType : Text
レスポンス本文のデータ型です
.handler : Object
接続を開始するのに使用された connectionHandler オブジェクトを取得するアクセサーを格納します
.id : Integer
接続の一意な識別子を格納します
.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 R3connectionHandler で headers プロパティをサポート

4D.WebSocket.new( url : Text { ; connectionHandler : Object } ) : 4D.WebSocket

引数型説明
urlText->接続先の URL
connectionHandlerObject->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 は有効です。
プロパティ型説明
onMessageFunctionWebSocket データ用のコールバック関数。 WebSocket がデータを受信するたびに呼び出されます。 コールバックは以下の引数を受け取ります:
  • $1: WebSocket オブジェクト
  • $2: Object
    • $2.type (text): 常に "message"
    • $2.data (text, BLOB, または object。dataType 参照): 受信データ
    onErrorFunction実行エラー用のコールバック関数。 コールバックは以下の引数を受け取ります:
  • $1: WebSocket オブジェクト
  • $2: オブジェクト
    • $2.type (text): 常に "error"
    • $2.errors: 実行エラーの場合、4D エラースタックのコレクション
      • [].errCode (number): 4D エラーコード
      • [].message (text): 4D エラーの詳細
      • [].componentSignature (text): エラーを返した内部コンポーネントの署名
    onTerminateFunctionWebSocket が終了した時のコールバック関数。 コールバックは以下の引数を受け取ります:
  • $1: WebSocket オブジェクト
  • $2: Object
    • $2.code (number、読み取り専用): 符号なし短整数型で、サーバーから送られたクローズコードを格納します。
    • $2.reason (text、読み取り専用): サーバーが接続を切断した理由。 これは、対象のサーバーとサブプロトコルに固有のものです。
    onOpenFunctionWebSocket が開始した時のコールバック関数。 コールバックは以下の引数を受け取ります:
  • $1: WebSocket オブジェクト
  • $2: Object
    • $2.type (text): 常に "open"
    dataTypeText受信または送信されたデータの型。 可能な値: "text" (デフォルト), "blob", "object"。 "text" = utf-8
    headersObjectWebSocket のヘッダー。
  • 標準的な key 割り当てのシンタックス: headers.*key*:=*value* (同じ key を複数指定する場合、value にコレクションを使用できます)
  • Cookie割り当てのシンタックス (特定の場合): headers.Cookie:="*name*=*value* {; *name2*=*value2*{; ... } }"

    • 以下は、コールバック呼び出しの流れです:

    1. onOpen は 1回実行されます。
    2. onMessage が 0回以上実行されます。
    3. onError が 0回または 1回実行されます (処理を停止します)。
    4. 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 : Integer

    説明​

    .id プロパティは、接続の一意な識別子を格納します。

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

    .send()​

    .send( message : Text )
    .send( message : Blob )
    .send( message : Object )

    引数型説明
    messageText, Blob, Object->送信するメッセージ

    説明​

    .send() 関数は、定義されたデータ型 (Text、Blob、または Object) で、WebSocket サーバーに message を送信します。

    メッセージ の型によって、以下の内容が送信されます:

    型内容
    TextUTF-8 のテキスト
    BLOBバイナリデータ
    ObjectJSON UTF-8 形式のテキスト(JSON Stringify と同じ結果になります)

    .status​

    .status : Text

    説明​

    .status プロパティは、現在の接続ステータスを格納します ("Connecting"、"Closing"、"Closed"、"Connected" のいずれか)。

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

    .terminate()​

    .terminate( { code : Integer { ; reason : Text } } )

    引数型説明
    codeInteger->接続が切断される理由を示すステータスコード
    reasonText->接続が切断される理由を説明するテキスト

    説明​

    .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 と同じです。

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