extensions/common/api/cast_channel.idl - platform/external/chromium_org - Git at Google

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 // API for communicating with a Google Cast device over an authenticated
 // channel.
 namespace cast.channel {

   // The state of the channel.
   enum ReadyState {
     // The channel is connecting.
     connecting,
     // The channel is open and available for messaging.
     open,
     // The channel is closing.
     closing,
     // The channel is closed.
     closed
   };

   // Error conditions that the channel may encounter.  All error conditions
   // are terminal.  When an error condition is encountered the API will:
   // (1) Transition the channel to readyState == 'closed'.
   // (2) Set ChannelInfo.lastError to the error condition.
   // (3) Fire an onError event with the error condition.
   // (4) Fire an onClose event.
   enum ChannelError {
     // cast.channel.send() was called when ChannelInfo.readyState != 'open'.
     channel_not_open,
     // Authentication was requested and the receiver could not be
     // authenticated (invalid signature, invalid handhake, TLS error, etc.)
     authentication_error,
     // A new channel could not be created for reasons unrelated to
     // authentication (e.g., there is already an open channel to the same URL).
     connect_error,
     // There was an error writing or reading from the underlying socket.
     socket_error,
     // A transport level occurred (like an unparseable message).
     transport_error,
     // The client attempted to send an unsupported message type through the
     // channel.
     invalid_message,
     // An invalid channel id was passed.
     invalid_channel_id,
     // The connection could not be established before timing out.
     connect_timeout,
     // Unspecified error.
     unknown
   };

   // Authentication methods that may be required to connect to a Cast receiver.
   enum ChannelAuthType {
     // SSL over TCP.
     ssl,
     // SSL over TCP with challenge and receiver signature verification.
     ssl_verified
   };

   // Describes the information needed to connect to a Cast receiver.
   // This replaces the prior use of cast:// and casts:// URLs.
   dictionary ConnectInfo {
     // The IPV4 address of the Cast receiver, e.g. '198.1.0.2'.
     // TODO(mfoltz): Investigate whether IPV6 addresses "just work."
     DOMString ipAddress;

     // The port number to connect to, 0-65535.
     long port;

     // The amount of time to wait in milliseconds before stopping the
     // connection process. Timeouts are disabled if the value is zero.
     // The default timeout is 8000ms.
     long? timeout;

     // The authentication method required for the channel.
     ChannelAuthType auth;
   };

   // Describes the state of a channel to a Cast receiver.
   dictionary ChannelInfo {
     // Id for the channel.
     long channelId;

     // DEPRECATED: The URL to the receiver.  This field will be removed in a
     // future release.
     DOMString url;

     // Connection information that was used to establish the channel to the
     // receiver.
     ConnectInfo connectInfo;

     // The current state of the channel.
     ReadyState readyState;

     // If set, the last error condition encountered by the channel.
     ChannelError? errorState;
   };

   // Describes a message sent or received over the channel.  Currently only
   // string messages are supported, although ArrayBuffer and Blob types may be
   // supported in the future.
   dictionary MessageInfo {
     // The message namespace.  A namespace is a URN of the form
     // urn:cast-x:<namespace> that is used to interpret and route Cast messages.
     DOMString namespace_;

     // source and destination ids identify the origin and destination of the
     // message.  They are used to route messages between endpoints that share a
     // device-to-device channel.
     //
     // For messages between applications:
     //   - The sender application id is a unique identifier generated on behalf
     //     of the sender application.
     //   - The receiver id is always the the session id for the application.
     //
     // For messages to or from the sender or receiver platform, the special ids
     // 'sender-0' and 'receiver-0' can be used.
     //
     // For messages intended for all endpoints using a given channel, the
     // wildcard destination_id '*' can be used.
     DOMString sourceId;
     DOMString destinationId;

     // The content of the message.  Must be either a string or an ArrayBuffer.
     any data;
   };

   // Describes a terminal error encountered by the channel with details of the
   // error that caused the channel to be closed.  One or more of the optional
   // fields may be set with specific error codes from the underlying
   // implementation.
   dictionary ErrorInfo {
     // The type of error encountered by the channel.
     ChannelError errorState;

     // The event that was occurring when the error happened.  Values are defined
     // in the enum EventType in logging.proto.
     long? eventType;

     // An error encountered when processing the authentication handshake.
     // Values are defined in the enum ChallengeReplyErrorType in logging.proto.
     long? challengeReplyErrorType;

     // A return value from the underlying net:: socket libraries. Values are
     // defined in net/base/net_error_list.h.
     long? netReturnValue;

     // An error code returned by NSS. Values are defined in secerr.h.
     long? nssErrorCode;
   };

   // Callback holding the result of a channel operation.
   callback ChannelInfoCallback = void (ChannelInfo result);

   // Callback from <code>getLogs</code> method.
   // |log|: compressed serialized raw bytes containing the logs.
   // The log is formatted using protocol buffer.
   // See extensions/browser/api/cast_channel/logging.proto for definition.
   // Compression is in gzip format.
   callback GetLogsCallback = void (ArrayBuffer log);

   interface Functions {
     // Opens a new channel to the Cast receiver specified by connectInfo.  Only
     // one channel may be connected to same receiver from the same extension at
     // a time.  If the open request is successful, the callback will be invoked
     // with a ChannelInfo with readyState == 'connecting'.  If unsuccessful, the
     // callback will be invoked with a ChannelInfo with channel.readyState ==
     // 'closed', channel.errorState will be set to the error condition, and
     // onError will be fired with error details.
     //
     // TODO(mfoltz): Convert 'any' to ConnectInfo once all clients are updated
     // to not send URLs.
     static void open(any connectInfo,
                      ChannelInfoCallback callback);

     // Sends a message on the channel and invokes callback with the resulting
     // channel status.  The channel must be in readyState == 'open'.  If
     // unsuccessful, channel.readyState will be set to 'closed',
     // channel.errorState will be set to the error condition, and onError will
     // be fired with error details.
     static void send(ChannelInfo channel,
                      MessageInfo message,
                      ChannelInfoCallback callback);

     // Requests that the channel be closed and invokes callback with the
     // resulting channel status.  The channel must be in readyState == 'open' or
     // 'connecting'.  If successful, onClose will be fired with readyState ==
     // 'closed'.  If unsuccessful, channel.readyState will be set to 'closed',
     // and channel.errorState will be set to the error condition.
     static void close(ChannelInfo channel,
                       ChannelInfoCallback callback);

     // Get logs in compressed serialized format. See GetLogsCallback for
     // details.
     // |callback|: If successful, |callback| is invoked with data. Otherwise,
     // an error will be raised.
     static void getLogs(GetLogsCallback callback);
   };

   // Events on the channel.
   interface Events {
     // Fired when a message is received on an open channel.
     static void onMessage(ChannelInfo channel,
                           MessageInfo message);

     // Fired when an error occurs as a result of a channel operation or a
     // network event. |error| contains details of the error.
     static void onError(ChannelInfo channel, ErrorInfo error);
   };
 };
	// Copyright 2014 The Chromium Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	// API for communicating with a Google Cast device over an authenticated
	// channel.
	namespace cast.channel {

	// The state of the channel.
	enum ReadyState {
	// The channel is connecting.
	connecting,
	// The channel is open and available for messaging.
	open,
	// The channel is closing.
	closing,
	// The channel is closed.
	closed
	};

	// Error conditions that the channel may encounter. All error conditions
	// are terminal. When an error condition is encountered the API will:
	// (1) Transition the channel to readyState == 'closed'.
	// (2) Set ChannelInfo.lastError to the error condition.
	// (3) Fire an onError event with the error condition.
	// (4) Fire an onClose event.
	enum ChannelError {
	// cast.channel.send() was called when ChannelInfo.readyState != 'open'.
	channel_not_open,
	// Authentication was requested and the receiver could not be
	// authenticated (invalid signature, invalid handhake, TLS error, etc.)
	authentication_error,
	// A new channel could not be created for reasons unrelated to
	// authentication (e.g., there is already an open channel to the same URL).
	connect_error,
	// There was an error writing or reading from the underlying socket.
	socket_error,
	// A transport level occurred (like an unparseable message).
	transport_error,
	// The client attempted to send an unsupported message type through the
	// channel.
	invalid_message,
	// An invalid channel id was passed.
	invalid_channel_id,
	// The connection could not be established before timing out.
	connect_timeout,
	// Unspecified error.
	unknown
	};

	// Authentication methods that may be required to connect to a Cast receiver.
	enum ChannelAuthType {
	// SSL over TCP.
	ssl,
	// SSL over TCP with challenge and receiver signature verification.
	ssl_verified
	};

	// Describes the information needed to connect to a Cast receiver.
	// This replaces the prior use of cast:// and casts:// URLs.
	dictionary ConnectInfo {
	// The IPV4 address of the Cast receiver, e.g. '198.1.0.2'.
	// TODO(mfoltz): Investigate whether IPV6 addresses "just work."
	DOMString ipAddress;

	// The port number to connect to, 0-65535.
	long port;

	// The amount of time to wait in milliseconds before stopping the
	// connection process. Timeouts are disabled if the value is zero.
	// The default timeout is 8000ms.
	long? timeout;

	// The authentication method required for the channel.
	ChannelAuthType auth;
	};

	// Describes the state of a channel to a Cast receiver.
	dictionary ChannelInfo {
	// Id for the channel.
	long channelId;

	// DEPRECATED: The URL to the receiver. This field will be removed in a
	// future release.
	DOMString url;

	// Connection information that was used to establish the channel to the
	// receiver.
	ConnectInfo connectInfo;

	// The current state of the channel.
	ReadyState readyState;

	// If set, the last error condition encountered by the channel.
	ChannelError? errorState;
	};

	// Describes a message sent or received over the channel. Currently only
	// string messages are supported, although ArrayBuffer and Blob types may be
	// supported in the future.
	dictionary MessageInfo {
	// The message namespace. A namespace is a URN of the form
	// urn:cast-x:<namespace> that is used to interpret and route Cast messages.
	DOMString namespace_;

	// source and destination ids identify the origin and destination of the
	// message. They are used to route messages between endpoints that share a
	// device-to-device channel.
	//
	// For messages between applications:
	// - The sender application id is a unique identifier generated on behalf
	// of the sender application.
	// - The receiver id is always the the session id for the application.
	//
	// For messages to or from the sender or receiver platform, the special ids
	// 'sender-0' and 'receiver-0' can be used.
	//
	// For messages intended for all endpoints using a given channel, the
	// wildcard destination_id '*' can be used.
	DOMString sourceId;
	DOMString destinationId;

	// The content of the message. Must be either a string or an ArrayBuffer.
	any data;
	};

	// Describes a terminal error encountered by the channel with details of the
	// error that caused the channel to be closed. One or more of the optional
	// fields may be set with specific error codes from the underlying
	// implementation.
	dictionary ErrorInfo {
	// The type of error encountered by the channel.
	ChannelError errorState;

	// The event that was occurring when the error happened. Values are defined
	// in the enum EventType in logging.proto.
	long? eventType;

	// An error encountered when processing the authentication handshake.
	// Values are defined in the enum ChallengeReplyErrorType in logging.proto.
	long? challengeReplyErrorType;

	// A return value from the underlying net:: socket libraries. Values are
	// defined in net/base/net_error_list.h.
	long? netReturnValue;

	// An error code returned by NSS. Values are defined in secerr.h.
	long? nssErrorCode;
	};

	// Callback holding the result of a channel operation.
	callback ChannelInfoCallback = void (ChannelInfo result);

	// Callback from <code>getLogs</code> method.
	// \|log\|: compressed serialized raw bytes containing the logs.
	// The log is formatted using protocol buffer.
	// See extensions/browser/api/cast_channel/logging.proto for definition.
	// Compression is in gzip format.
	callback GetLogsCallback = void (ArrayBuffer log);

	interface Functions {
	// Opens a new channel to the Cast receiver specified by connectInfo. Only
	// one channel may be connected to same receiver from the same extension at
	// a time. If the open request is successful, the callback will be invoked
	// with a ChannelInfo with readyState == 'connecting'. If unsuccessful, the
	// callback will be invoked with a ChannelInfo with channel.readyState ==
	// 'closed', channel.errorState will be set to the error condition, and
	// onError will be fired with error details.
	//
	// TODO(mfoltz): Convert 'any' to ConnectInfo once all clients are updated
	// to not send URLs.
	static void open(any connectInfo,
	ChannelInfoCallback callback);

	// Sends a message on the channel and invokes callback with the resulting
	// channel status. The channel must be in readyState == 'open'. If
	// unsuccessful, channel.readyState will be set to 'closed',
	// channel.errorState will be set to the error condition, and onError will
	// be fired with error details.
	static void send(ChannelInfo channel,
	MessageInfo message,
	ChannelInfoCallback callback);

	// Requests that the channel be closed and invokes callback with the
	// resulting channel status. The channel must be in readyState == 'open' or
	// 'connecting'. If successful, onClose will be fired with readyState ==
	// 'closed'. If unsuccessful, channel.readyState will be set to 'closed',
	// and channel.errorState will be set to the error condition.
	static void close(ChannelInfo channel,
	ChannelInfoCallback callback);

	// Get logs in compressed serialized format. See GetLogsCallback for
	// details.
	// \|callback\|: If successful, \|callback\| is invoked with data. Otherwise,
	// an error will be raised.
	static void getLogs(GetLogsCallback callback);
	};

	// Events on the channel.
	interface Events {
	// Fired when a message is received on an open channel.
	static void onMessage(ChannelInfo channel,
	MessageInfo message);

	// Fired when an error occurs as a result of a channel operation or a
	// network event. \|error\| contains details of the error.
	static void onError(ChannelInfo channel, ErrorInfo error);
	};
	};