WebSocket

WebSocket オブジェクトは、サーバーへの WebSocket 接続の作成と管理を行う API を提供します。また、接続を通してデータの送受信も行えます。

WebSocket コンストラクタは、次に示す1つの必須引数と1つのオプション引数を取ります。

WebSocket WebSocket(
  in DOMString url,
  in optional DOMString protocols
);

WebSocket WebSocket(
  in DOMString url,
  in optional DOMString[] protocols
);

url

接続する URL です。WebSocket サーバーがレスポンスを返す URL でなければなりません。

protocols Optional

1つのプロトコル文字列またはプロトコル文字列の配列を指定します。これらの文字列はサブプロトコル (sub-protocols) を指定するために使用します。1つのサーバーが複数の WebSocket サブプロトコルを実装している場合があるためです (たとえば、1つのサーバーで protocol で異なる種類のインタラクションをハンドリングできるようにしたいかもしれません)。プロトコル文字列を指定しなかった場合、空文字列が与えられたものとされます。

コンストラクタは次の例外を発生することができます。

SECURITY_ERR

接続を試みていた対象のポートがブロックされたとき。

メソッドの概要

属性

定数

Ready state 定数

これらの定数は、WebSocket 接続の状態を記述するために、readyState 属性によって使用されます。

メソッド

close()

WebSocket の接続または接続の試行を閉じます。接続がすでに CLOSED ならば、このメソッドは何もしません。

void close(
  in optional unsigned short code,
  in optional DOMString reason
);

パラメータ

code Optional

接続が閉じられた理由を表すステータスコードを数値で与えます。このパラメータが指定されなかった場合、デフォルト値の 1000 (通常の "transaction complete" を表す) が指定されたとみなします。使用できる値については、詳しくは CloseEvent ページのステータスコード一覧を読んでください。

reason Optional

接続が閉じられた理由を説明する、ヒューマンリーダブルな文字列。この文字列は、UTF-8 テキストで 123 バイト (123 文字ではない) を超えてはいけません。

発生する例外

INVALID_ACCESS_ERR

無効な code が指定された。

SYNTAX_ERR

reason 文字列が長すぎるか、サロゲートのペアが足りない。

send()

指定されたデータをエンキューし、WebSocket の接続を通してサーバーに送信します。その際、データに含めるバイト数に応じて bufferedAmount の値を増加させます。データが送信できない場合 (例えば、バッファーしたいが、バッファーがいっぱいな場合) 、ソケットは自動的に閉じられます。

void send(
  in DOMString data
);

void send(
  in ArrayBuffer data
);

void send(
  in Blob data
); 

パラメータ

data

サーバーに送信するデータです。次のどれかに当てはまります。

USVString

テキスト文字列です。文字列は UTF-8 形式でバッファーに追加されます。bufferedAmount の値は UTF-8 の文字列を表すのに必要なバイト数に応じて増加します。

ArrayBuffer

型付き配列オブジェクトで使われる基本的なバイナリデータを送信することができます。そのバイナリデータの中身はバッファーの中にキューされ、bufferedAmount の値は必要なバイト数に応じて増加します。

Blob

ブロブの生データをエンキューする Blob を指定し、バイナリフレームに送信します。bufferedAmount の値は生データのサイズに応じて増加します。

ArrayBufferView

あらゆるJavaScript の型付き配列オブジェクトをバイナリフレームとして送信することができます。バイナリデータの中身はバッファーにエンキューされます。bufferedAmount の値は必要なバイト数に応じて増加します。

 

発生する例外

INVALID_STATE_ERR

現在、接続が OPEN になっていません。

SYNTAX_ERR

ペアでないサロゲートを含んだ文字列が渡されています。

コード例

// WebSocket を作成
const socket = new WebSocket('ws://localhost:8080');

// 接続を開く
socket.addEventListener('open', function (event) {
    socket.send('Hello Server!');
});

// メッセージを Listen する
socket.addEventListener('message', function (event) {
    console.log('Message from server', event.data);
});

仕様

ブラウザーの互換性

[1] Starting in Gecko 6.0 (Firefox 6.0 / Thunderbird 6.0 / SeaMonkey 2.3), the constructor is prefixed; you will need to use MozWebSocket(): var mySocket = new MozWebSocket("http://www.example.com/socketserver");

Gecko では、Gecko 8.0 までは extensions 属性がサポートされていませんでした。

Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8) 以前では、send() メソッドを使用した outbound メッセージは 16 MB に制限されていました。現在は、最大 2 GB のサイズまで送信できます。

関連項目

• Writing WebSocket client applications