gecko/content/base/public/nsIWebSocket.idl
2012-05-21 12:12:37 +01:00

96 lines
3.6 KiB
Plaintext

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set sw=2 ts=8 et tw=80 : */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#include "nsISupports.idl"
interface nsIDOMEventListener;
interface nsIPrincipal;
interface nsIScriptContext;
interface nsPIDOMWindow;
interface nsIDOMDOMStringList;
interface nsIVariant;
%{C++
#include "nsTArray.h"
class nsString;
%}
[ref] native nsStringTArrayRef(nsTArray<nsString>);
/**
* The nsIWebSocket interface enables Web applications to maintain
* bidirectional communications with server-side processes as described in:
*
* http://dev.w3.org/html5/websockets/
*
*/
[scriptable, uuid(e59c8c65-df29-485c-a00b-8fac3dc1573a)]
interface nsIWebSocket : nsISupports
{
readonly attribute DOMString url;
readonly attribute DOMString extensions;
readonly attribute DOMString protocol;
//ready state
const unsigned short CONNECTING = 0;
const unsigned short OPEN = 1;
const unsigned short CLOSING = 2;
const unsigned short CLOSED = 3;
readonly attribute unsigned short readyState;
readonly attribute unsigned long bufferedAmount;
// "blob" by default: can set to "blob" or "arraybuffer": setting to other
// values will throw SYNTAX_ERR exception.
attribute DOMString binaryType;
// event handler attributes
attribute nsIDOMEventListener onopen;
attribute nsIDOMEventListener onmessage;
attribute nsIDOMEventListener onerror;
attribute nsIDOMEventListener onclose;
/**
* Transmits data to other end of the connection.
* @param data The data to be transmitted. Arraybuffers and Blobs are sent as
* binary data. Strings are sent as UTF-8 text data. Other types are
* converted to a String and sent as a String.
* @return if the connection is still established and the data was queued or
* sent successfully.
*/
[implicit_jscontext] void send(in nsIVariant data);
/**
* Closes the Web Socket connection or connection attempt, if any.
* If the connection is already closed, it does nothing.
*/
[optional_argc] void close([optional] in unsigned short code,
[optional] in DOMString reason);
/**
* Initialize the object for use from C++ code with the principal, script
* context, and owner window that should be used.
*
* @param principal The principal to use for the request. This must not be
* null.
* @param scriptContext The script context to use for the request. May be
* null.
* @param ownerWindow The associated window for the request. May be null.
* @param url The url for opening the socket. This must not be empty, and
* must have an absolute url, using either the ws or wss schemes.
* @param protocol Specifies array of sub-protocols acceptable to the client.
* If the length of the array is at least one, the server
* must select one of the listed sub-protocols for the
* connection to be successful. If empty, no sub-protocol is
* specified. The server selected sub-protocol can be read
* from the protocol attribute after connection.
*/
[noscript] void init(in nsIPrincipal principal,
in nsIScriptContext scriptContext,
in nsPIDOMWindow ownerWindow,
in DOMString url,
in nsStringTArrayRef protocol);
};