extensions/common/api/cast_channel.idl

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // API for communicating with a Google Cast device over an authenticated
   6 // channel.
   7 namespace cast.channel {
   8
   9   // The state of the channel.
  10   enum ReadyState {
  11     // The channel is connecting.
  12     connecting,
  13     // The channel is open and available for messaging.
  14     open,
  15     // The channel is closing.
  16     closing,
  17     // The channel is closed.
  18     closed
  19   };
  20
  21   // Error conditions that the channel may encounter.  All error conditions
  22   // are terminal.  When an error condition is encountered the API will:
  23   // (1) Transition the channel to readyState == 'closed'.
  24   // (2) Set ChannelInfo.lastError to the error condition.
  25   // (3) Fire an onError event with the error condition.
  26   // (4) Fire an onClose event.
  27   enum ChannelError {
  28     // cast.channel.send() was called when ChannelInfo.readyState != 'open'.
  29     channel_not_open,
  30     // Authentication was requested and the receiver could not be
  31     // authenticated (invalid signature, invalid handhake, TLS error, etc.)
  32     authentication_error,
  33     // A new channel could not be created for reasons unrelated to
  34     // authentication (e.g., there is already an open channel to the same URL).
  35     connect_error,
  36     // There was an error writing or reading from the underlying socket.
  37     socket_error,
  38     // A transport level occurred (like an unparseable message).
  39     transport_error,
  40     // The client attempted to send an unsupported message type through the
  41     // channel.
  42     invalid_message,
  43     // An invalid channel id was passed.
  44     invalid_channel_id,
  45     // The connection could not be established before timing out.
  46     connect_timeout,
  47     // Unspecified error.
  48     unknown
  49   };
  50
  51   // Authentication methods that may be required to connect to a Cast receiver.
  52   enum ChannelAuthType {
  53     // SSL over TCP.
  54     ssl,
  55     // SSL over TCP with challenge and receiver signature verification.
  56     ssl_verified
  57   };
  58
  59   // Describes the information needed to connect to a Cast receiver.
  60   // This replaces the prior use of cast:// and casts:// URLs.
  61   dictionary ConnectInfo {
  62     // The IPV4 address of the Cast receiver, e.g. '198.1.0.2'.
  63     // TODO(mfoltz): Investigate whether IPV6 addresses "just work."
  64     DOMString ipAddress;
  65
  66     // The port number to connect to, 0-65535.
  67     long port;
  68
  69     // The amount of time to wait in milliseconds before stopping the
  70     // connection process. Timeouts are disabled if the value is zero.
  71     // The default timeout is 8000ms.
  72     long? timeout;
  73
  74     // The authentication method required for the channel.
  75     ChannelAuthType auth;
  76   };
  77
  78   // Describes the state of a channel to a Cast receiver.
  79   dictionary ChannelInfo {
  80     // Id for the channel.
  81     long channelId;
  82
  83     // DEPRECATED: The URL to the receiver.  This field will be removed in a
  84     // future release.
  85     DOMString url;
  86
  87     // Connection information that was used to establish the channel to the
  88     // receiver.
  89     ConnectInfo connectInfo;
  90
  91     // The current state of the channel.
  92     ReadyState readyState;
  93
  94     // If set, the last error condition encountered by the channel.
  95     ChannelError? errorState;
  96   };
  97
  98   // Describes a message sent or received over the channel.  Currently only
  99   // string messages are supported, although ArrayBuffer and Blob types may be
 100   // supported in the future.
 101   dictionary MessageInfo {
 102     // The message namespace.  A namespace is a URN of the form
 103     // urn:cast-x:<namespace> that is used to interpret and route Cast messages.
 104     DOMString namespace_;
 105
 106     // source and destination ids identify the origin and destination of the
 107     // message.  They are used to route messages between endpoints that share a
 108     // device-to-device channel.
 109     //
 110     // For messages between applications:
 111     //   - The sender application id is a unique identifier generated on behalf
 112     //     of the sender application.
 113     //   - The receiver id is always the the session id for the application.
 114     //
 115     // For messages to or from the sender or receiver platform, the special ids
 116     // 'sender-0' and 'receiver-0' can be used.
 117     //
 118     // For messages intended for all endpoints using a given channel, the
 119     // wildcard destination_id '*' can be used.
 120     DOMString sourceId;
 121     DOMString destinationId;
 122
 123     // The content of the message.  Must be either a string or an ArrayBuffer.
 124     any data;
 125   };
 126
 127   // Describes a terminal error encountered by the channel with details of the
 128   // error that caused the channel to be closed.  One or more of the optional
 129   // fields may be set with specific error codes from the underlying
 130   // implementation.
 131   dictionary ErrorInfo {
 132     // The type of error encountered by the channel.
 133     ChannelError errorState;
 134
 135     // The event that was occurring when the error happened.  Values are defined
 136     // in the enum EventType in logging.proto.
 137     long? eventType;
 138
 139     // An error encountered when processing the authentication handshake.
 140     // Values are defined in the enum ChallengeReplyErrorType in logging.proto.
 141     long? challengeReplyErrorType;
 142
 143     // A return value from the underlying net:: socket libraries. Values are
 144     // defined in net/base/net_error_list.h.
 145     long? netReturnValue;
 146
 147     // An error code returned by NSS. Values are defined in secerr.h.
 148     long? nssErrorCode;
 149   };
 150
 151   // Callback holding the result of a channel operation.
 152   callback ChannelInfoCallback = void (ChannelInfo result);
 153
 154   // Callback from <code>getLogs</code> method.
 155   // |log|: compressed serialized raw bytes containing the logs.
 156   // The log is formatted using protocol buffer.
 157   // See extensions/browser/api/cast_channel/logging.proto for definition.
 158   // Compression is in gzip format.
 159   callback GetLogsCallback = void (ArrayBuffer log);
 160
 161   interface Functions {
 162     // Opens a new channel to the Cast receiver specified by connectInfo.  Only
 163     // one channel may be connected to same receiver from the same extension at
 164     // a time.  If the open request is successful, the callback will be invoked
 165     // with a ChannelInfo with readyState == 'connecting'.  If unsuccessful, the
 166     // callback will be invoked with a ChannelInfo with channel.readyState ==
 167     // 'closed', channel.errorState will be set to the error condition, and
 168     // onError will be fired with error details.
 169     //
 170     // TODO(mfoltz): Convert 'any' to ConnectInfo once all clients are updated
 171     // to not send URLs.
 172     static void open(any connectInfo,
 173                      ChannelInfoCallback callback);
 174
 175     // Sends a message on the channel and invokes callback with the resulting
 176     // channel status.  The channel must be in readyState == 'open'.  If
 177     // unsuccessful, channel.readyState will be set to 'closed',
 178     // channel.errorState will be set to the error condition, and onError will
 179     // be fired with error details.
 180     static void send(ChannelInfo channel,
 181                      MessageInfo message,
 182                      ChannelInfoCallback callback);
 183
 184     // Requests that the channel be closed and invokes callback with the
 185     // resulting channel status.  The channel must be in readyState == 'open' or
 186     // 'connecting'.  If successful, onClose will be fired with readyState ==
 187     // 'closed'.  If unsuccessful, channel.readyState will be set to 'closed',
 188     // and channel.errorState will be set to the error condition.
 189     static void close(ChannelInfo channel,
 190                       ChannelInfoCallback callback);
 191
 192     // Get logs in compressed serialized format. See GetLogsCallback for
 193     // details.
 194     // |callback|: If successful, |callback| is invoked with data. Otherwise,
 195     // an error will be raised.
 196     static void getLogs(GetLogsCallback callback);
 197   };
 198
 199   // Events on the channel.
 200   interface Events {
 201     // Fired when a message is received on an open channel.
 202     static void onMessage(ChannelInfo channel,
 203                           MessageInfo message);
 204
 205     // Fired when an error occurs as a result of a channel operation or a
 206     // network event. |error| contains details of the error.
 207     static void onError(ChannelInfo channel, ErrorInfo error);
 208   };
 209 };