// 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: 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 getLogs 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); }; };