netwerk/protocol/websocket/nsIWebSocketListener.idl

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* vim: set sw=4 ts=4 et tw=80 : */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsISupports.idl"
   8
   9 /**
  10  * nsIWebSocketListener: passed to nsIWebSocketChannel::AsyncOpen. Receives
  11  * websocket traffic events as they arrive.
  12  */
  13 [scriptable, uuid(d74c96b2-65b3-4e39-9e39-c577de5d7a73)]
  14 interface nsIWebSocketListener : nsISupports
  15 {
  16     /**
  17      * Called to signify the establishment of the message stream.
  18      *
  19      * Unlike most other networking channels (which use nsIRequestObserver
  20      * instead of this class), we do not guarantee that OnStart is always
  21      * called: OnStop is called without calling this function if errors occur
  22      * during connection setup.  If the websocket connection is successful,
  23      * OnStart will be called before any other calls to this API.
  24      *
  25      * @param aContext user defined context
  26      */
  27     [must_use] void onStart(in nsISupports aContext);
  28
  29     /**
  30      * Called to signify the completion of the message stream.
  31      * OnStop is the final notification the listener will receive and it
  32      * completes the WebSocket connection: after it returns the
  33      * nsIWebSocketChannel will release its reference to the listener.
  34      *
  35      * Note: this event can be received in error cases even if
  36      * nsIWebSocketChannel::Close() has not been called.
  37      *
  38      * @param aContext user defined context
  39      * @param aStatusCode reason for stopping (NS_OK if completed successfully)
  40      */
  41     [must_use] void onStop(in nsISupports aContext,
  42                            in nsresult aStatusCode);
  43
  44     /**
  45      * Called to deliver text message.
  46      *
  47      * @param aContext user defined context
  48      * @param aMsg the message data
  49      */
  50     [must_use] void onMessageAvailable(in nsISupports aContext,
  51                                        in AUTF8String aMsg);
  52
  53     /**
  54      * Called to deliver binary message.
  55      *
  56      * @param aContext user defined context
  57      * @param aMsg the message data
  58      */
  59     [must_use] void onBinaryMessageAvailable(in nsISupports aContext,
  60                                              in ACString aMsg);
  61
  62     /**
  63      * Called to acknowledge message sent via sendMsg() or sendBinaryMsg.
  64      *
  65      * @param aContext user defined context
  66      * @param aSize number of bytes placed in OS send buffer
  67      */
  68     [must_use] void onAcknowledge(in nsISupports aContext, in uint32_t aSize);
  69
  70     /**
  71      * Called to inform receipt of WebSocket Close message from server.
  72      * In the case of errors onStop() can be called without ever
  73      * receiving server close.
  74      *
  75      * No additional messages through onMessageAvailable(),
  76      * onBinaryMessageAvailable() or onAcknowledge() will be delievered
  77      * to the listener after onServerClose(), though outgoing messages can still
  78      * be sent through the nsIWebSocketChannel connection.
  79      *
  80      * @param aContext user defined context
  81      * @param aCode the websocket closing handshake close code.
  82      * @param aReason the websocket closing handshake close reason
  83      */
  84     [must_use] void onServerClose(in nsISupports aContext,
  85                                   in unsigned short aCode,
  86                                   in AUTF8String aReason);
  87
  88     /**
  89      * Called to inform an error is happened. The connection will be closed
  90      * when this is called.
  91      */
  92     [must_use] void OnError();
  93
  94 };