src/chrome/common/extensions/api/cast_channel.idl

   1 // Copyright 2013 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     // Unspecified error.
  46     unknown
  47   };
  48
  49   // Describes the state of a channel to a Cast receiver.
  50   dictionary ChannelInfo {
  51     // Id for the channel.
  52     long channelId;
  53
  54     // The URL to the receiver.  The URL should be of the form:
  55     // cast://<IP>:<port> (for an unauthenticated channel) or
  56     // casts://<IP>:<port> (for an authenticated channel).  Name resolution is
  57     // not currently supported for cast:// URLs, but may be added in the future.
  58     DOMString url;
  59
  60     // The current state of the channel.
  61     ReadyState readyState;
  62
  63     // If set, the last error condition encountered by the channel.
  64     ChannelError? errorState;
  65   };
  66
  67   // Describes a message sent or received over the channel.  Currently only
  68   // string messages are supported, although ArrayBuffer and Blob types may be
  69   // supported in the future.
  70   dictionary MessageInfo {
  71     // The message namespace.  A namespace is a URN of the form
  72     // urn:cast-x:<namespace> that is used to interpret and route Cast messages.
  73     DOMString namespace_;
  74
  75     // source and destination ids identify the origin and destination of the
  76     // message.  They are used to route messages between endpoints that share a
  77     // device-to-device channel.
  78     //
  79     // For messages between applications:
  80     //   - The sender application id is a unique identifier generated on behalf
  81     //     of the sender application.
  82     //   - The receiver id is always the the session id for the application.
  83     //
  84     // For messages to or from the sender or receiver platform, the special ids
  85     // 'sender-0' and 'receiver-0' can be used.
  86     //
  87     // For messages intended for all endpoints using a given channel, the
  88     // wildcard destination_id '*' can be used.
  89     DOMString sourceId;
  90     DOMString destinationId;
  91
  92     // The content of the message.  Must be either a string or an ArrayBuffer.
  93     any data;
  94   };
  95
  96   // Callback holding the result of a channel operation.
  97   callback ChannelInfoCallback = void (ChannelInfo result);
  98
  99   interface Functions {
 100     // Opens a new channel to the Cast receiver specified by the URL.  Only one
 101     // channel may be connected to the same URL from the same extension at a
 102     // time.  If the open request is successful, the callback will be invoked
 103     // with a ChannelInfo with readyState == 'connecting'.  If unsuccessful, the
 104     // callback will be invoked with a ChannelInfo with channel.readyState ==
 105     // 'closed' and channel.errorState will be set to the error condition.
 106     static void open(DOMString url,
 107                      ChannelInfoCallback callback);
 108
 109     // Sends a message on the channel and invokes callback with the resulting
 110     // channel status.  The channel must be in readyState == 'open'.  If
 111     // unsuccessful, channel.readyState will be set to 'closed',
 112     // channel.errorState will be set to the error condition.
 113     static void send(ChannelInfo channel,
 114                      MessageInfo message,
 115                      ChannelInfoCallback callback);
 116
 117     // Requests that the channel be closed and invokes callback with the
 118     // resulting channel status.  The channel must be in readyState == 'open' or
 119     // 'connecting'.  If successful, onClose will be fired with readyState ==
 120     // 'closed'.  If unsuccessful, channel.readyState will be set to 'closed',
 121     // and channel.errorState will be set to the error condition.
 122     static void close(ChannelInfo channel,
 123                       ChannelInfoCallback callback);
 124   };
 125
 126   // Events on the channel.
 127   interface Events {
 128     // Fired when a message is received on an open channel.
 129     static void onMessage(ChannelInfo channel,
 130                           MessageInfo message);
 131
 132     // Fired when an error occurs as a result of a channel method or a network
 133     // event.
 134     static void onError(ChannelInfo channel);
 135   };
 136 };