michael@0: /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
michael@0: /* vim: set sw=4 ts=4 et tw=80 : */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: /**
michael@0:  * nsIWebSocketListener: passed to nsIWebSocketChannel::AsyncOpen. Receives
michael@0:  * websocket traffic events as they arrive.
michael@0:  */
michael@0: [scriptable, uuid(d74c96b2-65b3-4e39-9e39-c577de5d7a73)]
michael@0: interface nsIWebSocketListener : nsISupports
michael@0: {
michael@0:     /**
michael@0:      * Called to signify the establishment of the message stream.
michael@0:      * 
michael@0:      * Unlike most other networking channels (which use nsIRequestObserver
michael@0:      * instead of this class), we do not guarantee that OnStart is always
michael@0:      * called: OnStop is called without calling this function if errors occur
michael@0:      * during connection setup.  If the websocket connection is successful,
michael@0:      * OnStart will be called before any other calls to this API.
michael@0:      *
michael@0:      * @param aContext user defined context
michael@0:      */
michael@0:     void onStart(in nsISupports aContext);
michael@0: 
michael@0:     /**
michael@0:      * Called to signify the completion of the message stream.
michael@0:      * OnStop is the final notification the listener will receive and it
michael@0:      * completes the WebSocket connection: after it returns the
michael@0:      * nsIWebSocketChannel will release its reference to the listener.
michael@0:      * 
michael@0:      * Note: this event can be received in error cases even if
michael@0:      * nsIWebSocketChannel::Close() has not been called.
michael@0:      *
michael@0:      * @param aContext user defined context
michael@0:      * @param aStatusCode reason for stopping (NS_OK if completed successfully)
michael@0:      */
michael@0:     void onStop(in nsISupports aContext,
michael@0:                 in nsresult aStatusCode);
michael@0: 
michael@0:     /**
michael@0:      * Called to deliver text message.
michael@0:      *
michael@0:      * @param aContext user defined context
michael@0:      * @param aMsg the message data
michael@0:      */
michael@0:     void onMessageAvailable(in nsISupports aContext,
michael@0:                             in AUTF8String aMsg);
michael@0: 
michael@0:     /**
michael@0:      * Called to deliver binary message.
michael@0:      *
michael@0:      * @param aContext user defined context
michael@0:      * @param aMsg the message data
michael@0:      */
michael@0:     void onBinaryMessageAvailable(in nsISupports aContext,
michael@0:                                   in ACString aMsg);
michael@0: 
michael@0:     /**
michael@0:      * Called to acknowledge message sent via sendMsg() or sendBinaryMsg.
michael@0:      *
michael@0:      * @param aContext user defined context
michael@0:      * @param aSize number of bytes placed in OS send buffer
michael@0:      */
michael@0:     void onAcknowledge(in nsISupports aContext, in uint32_t aSize);
michael@0: 
michael@0:     /**
michael@0:      * Called to inform receipt of WebSocket Close message from server.
michael@0:      * In the case of errors onStop() can be called without ever
michael@0:      * receiving server close.
michael@0:      *
michael@0:      * No additional messages through onMessageAvailable(),
michael@0:      * onBinaryMessageAvailable() or onAcknowledge() will be delievered
michael@0:      * to the listener after onServerClose(), though outgoing messages can still
michael@0:      * be sent through the nsIWebSocketChannel connection.
michael@0:      *
michael@0:      * @param aContext user defined context
michael@0:      * @param aCode the websocket closing handshake close code.
michael@0:      * @param aReason the websocket closing handshake close reason
michael@0: 
michael@0:      */
michael@0:     void onServerClose(in nsISupports aContext, in unsigned short aCode,
michael@0:                        in AUTF8String aReason);
michael@0:     
michael@0: };
michael@0: 
michael@0: