elemental.html.WebSocket Maven / Gradle / Ivy

Go to download
/*
 * Copyright 2012 Google Inc.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package elemental.html;
import elemental.events.EventListener;
import elemental.events.EventTarget;
import elemental.events.Event;

import elemental.events.*;
import elemental.util.*;
import elemental.dom.*;
import elemental.html.*;
import elemental.css.*;
import elemental.stylesheets.*;

import java.util.Date;

/**
  * This is an experimental feature
Because this feature is still in development in some browsers, check the compatibility table for the proper prefixes to use in various browsers.

The WebSocket object provides the API for creating and managing a WebSocket connection to a server, as well as for sending and receiving data on the connection.
  */
public interface WebSocket extends EventTarget {

  /**
    * The connection is closed or couldn't be opened.
    */

    static final int CLOSED = 3;

  /**
    * The connection is in the process of closing.
    */

    static final int CLOSING = 2;

  /**
    * The connection is not yet open.
    */

    static final int CONNECTING = 0;

  /**
    * The connection is open and ready to communicate.
    */

    static final int OPEN = 1;

  String getURL();


  /**
    * A string indicating the type of binary data being transmitted by the connection. This should be either "blob" if DOM Blob
 objects are being used or "arraybuffer" if ArrayBuffer objects are being used.
    */
  String getBinaryType();

  void setBinaryType(String arg);


  /**
    * The number of bytes of data that have been queued using calls to  but not yet transmitted to the network. This value does not reset to zero when the connection is closed; if you keep calling , this will continue to climb. Read only.
    */
  int getBufferedAmount();


  /**
    * The extensions selected by the server. This is currently only the empty string or a list of extensions as negotiated by the connection.
    */
  String getExtensions();


  /**
    * An event listener to be called when the WebSocket connection's readyState changes to CLOSED. The listener receives a CloseEvent named "close".
    */
  EventListener getOnclose();

  void setOnclose(EventListener arg);


  /**
    * An event listener to be called when an error occurs. This is a simple event named "error".
    */
  EventListener getOnerror();

  void setOnerror(EventListener arg);


  /**
    * An event listener to be called when a message is received from the server. The listener receives a MessageEvent named "message".
    */
  EventListener getOnmessage();

  void setOnmessage(EventListener arg);


  /**
    * An event listener to be called when the WebSocket connection's readyState changes to OPEN; this indicates that the connection is ready to send and receive data. The event is a simple one with the name "open".
    */
  EventListener getOnopen();

  void setOnopen(EventListener arg);


  /**
    * A string indicating the name of the sub-protocol the server selected; this will be one of the strings specified in the protocols parameter when creating the WebSocket object.
    */
  String getProtocol();


  /**
    * The current state of the connection; this is one of the Ready state constants. Read only.
    */
  int getReadyState();


  /**
    * The URL as resolved by the constructor. This is always an absolute URL. Read only.
    */
  String getUrl();

  EventRemover addEventListener(String type, EventListener listener);

  EventRemover addEventListener(String type, EventListener listener, boolean useCapture);


  /**
    * Closes the WebSocket connection or connection attempt, if any. If the connection is already CLOSED, this method does nothing.

Parameters
 code 
Optional
 A numeric value indicating the status code explaining why the connection is being closed. If this parameter is not specified, a default value of 1000 (indicating a normal "transaction complete" closure) is assumed. See the list of status codes on the CloseEvent page for permitted values.
 reason 
Optional
 A human-readable string explaining why the connection is closing. This string must be no longer than 123 UTF-8 characters.

Exceptions thrown
 INVALID_ACCESS_ERR
 An invalid code was specified.
 SYNTAX_ERR
 The reason string is too long or contains unpaired surrogates.


    */
  void close();


  /**
    * Closes the WebSocket connection or connection attempt, if any. If the connection is already CLOSED, this method does nothing.

Parameters
 code 
Optional
 A numeric value indicating the status code explaining why the connection is being closed. If this parameter is not specified, a default value of 1000 (indicating a normal "transaction complete" closure) is assumed. See the list of status codes on the CloseEvent page for permitted values.
 reason 
Optional
 A human-readable string explaining why the connection is closing. This string must be no longer than 123 UTF-8 characters.

Exceptions thrown
 INVALID_ACCESS_ERR
 An invalid code was specified.
 SYNTAX_ERR
 The reason string is too long or contains unpaired surrogates.


    */
  void close(int code);


  /**
    * Closes the WebSocket connection or connection attempt, if any. If the connection is already CLOSED, this method does nothing.

Parameters
 code 
Optional
 A numeric value indicating the status code explaining why the connection is being closed. If this parameter is not specified, a default value of 1000 (indicating a normal "transaction complete" closure) is assumed. See the list of status codes on the CloseEvent page for permitted values.
 reason 
Optional
 A human-readable string explaining why the connection is closing. This string must be no longer than 123 UTF-8 characters.

Exceptions thrown
 INVALID_ACCESS_ERR
 An invalid code was specified.
 SYNTAX_ERR
 The reason string is too long or contains unpaired surrogates.


    */
  void close(int code, String reason);

  boolean dispatchEvent(Event evt);

  void removeEventListener(String type, EventListener listener);

  void removeEventListener(String type, EventListener listener, boolean useCapture);


  /**
    * Transmits data to the server over the WebSocket connection.

Parameters
 data
 A text string to send to the server.

Exceptions thrown
 INVALID_STATE_ERR
 The connection is not currently OPEN.
 SYNTAX_ERR
 The data is a string that has unpaired surrogates.

Remarks
 
Gecko 6.0 note(Firefox 6.0 / Thunderbird 6.0 / SeaMonkey 2.3)

 Gecko's implementation of the send() method differs somewhat from the specification in Gecko 6.0; Gecko returns a boolean indicating whether or not the connection is still open (and, by extension, that the data was successfully queued or transmitted); this is corrected in Gecko 8.0 (Firefox 8.0 / Thunderbird 8.0 / SeaMonkey 2.5)
. In addition, at this time, Gecko does not support ArrayBuffer or Blob
 data types.


    */
  boolean send(String data);
}