Add the Copresence API.

chrome/common/extensions/api/copresence.idl

+// 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.
+
+// Use the <code>chrome.copresence</code> API to communicate with other devices
+// close by, using Google's copresence service.
+namespace copresence {
+  // The set of supported copresence operations.
+  enum OperationType {
+    publish, subscribe, unpublish, unsubscribe
+  };
+
+  // Suggestions to copresence on how to do the publication and subscription.
+  // Note: These are only suggestions. Actual behavior may not always match
+  // what is requested.
+  dictionary Strategy {
+    // Attempt to use low power mode. Defaults to false.
+    boolean? lowPower;
+    // Attempt to only broadcast. Using this with onlyScan can result in both
+    // being ignored. Defaults to false.
+    boolean? onlyBroadcast;
+    // Attempt to only scan. Using this with onlyBroadcast can result in both
+    // being ignored. Defaults to false.
+    boolean? onlyScan;
+    // Attempt to use audible audio. Defaults to false.
+    boolean? audible;
+  };
+
+  [inline_doc] dictionary Message {

[not at google - send to devlin, 2014/08/05 21:05:38]

it will automatically inline since it's only used in 1 place

[rkc, 2014/08/05 22:25:22]

Done.

+    // The type of message that we're publishing. Cannot be empty.
+    DOMString type;
+    // The message payload, in raw bytes.
+    ArrayBuffer payload;
+  };
+
+  dictionary MessageFilter {
+    // The type of messages to subscribe to. Cannot be empty.
+    DOMString type;
+  };
+
+  [noinline_doc] dictionary AccessPolicy {
+    // Only send this message to people within hearing range.
+    // Defaults to false.
+    boolean? onlyEarshot;
+  };
+
+  [noinline_doc] dictionary PublishOperation {
+    // A unique ID that identifies this publish.
+    DOMString id;
+    // The message to publish.
+    Message message;
+    // The number of milliseconds for which this publication will be active.
+    // This is capped at 24 hours. If not provided, we default to 5 minutes.
+    long? timeToLiveMillis;
+    // A policy specifying who can get the message.
+    AccessPolicy? policy;
+    // A set of strategies to use when publishing the message. These
+    // strategies are suggestions to copresence that may or may not be followed.
+    Strategy? strategies;
+  };
+
+  [noinline_doc] dictionary SubscribeOperation {
+    // A unique ID that identifies this subscription.
+    DOMString id;
+    // Filter that defines which messages we want to subscribe to.
+    MessageFilter filter;
+    // The number of milliseconds for which this subscription will be active.
+    // This is capped at 24 hours. If not provided, we default to 5 minutes.
+    long? timeToLiveMillis;
+    // A set of strategies to use when subscribing with this filter. These
+    // strategies are suggestions to copresence that may or may not be followed.
+    Strategy? strategies;
+  };
+
+  [noinline_doc] dictionary UnpublishOperation {
+    // The id of a message to unpublish. Required if the operation type
+    // is 'unpublish'.
+    DOMString unpublishId;
+  };
+
+  [noinline_doc] dictionary UnsubscribeOperation {
+    // The id of a subscription to cancel. Required if the operation type
+    // is 'unsubscribe'.
+    DOMString unsubscribeId;
+  };
+
+  [noinline_doc] dictionary Operation {
+    // Type of operation. An operation object matching the type must be a
+    // part of this object.
+    OperationType type;

[not at google - send to devlin, 2014/08/05 21:05:39]

why do you need the OperationType? it can be determined from which property was
set (publish|subscribe|unpublish|unsubscribe).

[rkc, 2014/08/05 22:25:23]

Done.

+
+    // Publication details. Required if the operation type is 'publish'.
+    PublishOperation? publish;
+    // Subscription details. Required if the operation type is 'subscribe'.
+    SubscribeOperation? subscribe;
+
+    // Unpublish details. Required if the operation type is 'unpublish'.
+    UnpublishOperation? unpublish;
+    // Unsubscribe details. Required if the operation type is 'unsubscribe'.
+    UnsubscribeOperation? unsubscribe;
+  };
+
+  // Indicates whether a batchExecute() call succeeded or encountered errors.
+  [inline_doc] enum BatchExecuteStatus {

[not at google - send to devlin, 2014/08/05 21:05:39]

it will automatically inline since it's only used in 1 place

[rkc, 2014/08/05 22:25:22]

Done.

+    // All operations sent to batchExecute succeeded.
+    success,
+    // One of the operations sent to batchExecute failed.
+    failed,
+    // Contacting the Copresence server failed.
+    serverError,
+    // Initializing Copresence failed.
+    initFailed
+  };
+
+  // Specifies an asynchronous status event sent to the app.
+  [inline_doc] enum Status {

[not at google - send to devlin, 2014/08/05 21:05:38]

it will automatically inline since it's only used in 1 place

[rkc, 2014/08/05 22:25:23]

Done.

+    // We attempted to broadcast audio but weren't able to.
+    audioFailed,
+    // Contacting the Copresence server failed.
+    serverError
+  };
+
+  // Callback to return the status of a completed batchExecute() call.
+  callback BatchExecuteCallback = void(BatchExecuteStatus status);
+
+  interface Functions {
+    // Sets the API key to use with our app. This parameter only needs to be
+    // set if we need to communicate with apps on other platforms. Once we set
+    // the api key, apps on any platform that are using this API key can

[not at google - send to devlin, 2014/08/05 21:05:39]

what's to stop some MyRandomApp from setting the same API key and listening to
messages?

[rkc, 2014/08/05 22:25:23]

This isn't a security feature, it is a scoping feature. In an unauthenticated
API, there is literally no way we can prevent one app from getting messages from
any other app. For example, if we scoped by app ID, one could simply install a
local app, set the key: manifest field and masquerade its app id.

The API key is used as a simple scoping mechanism since it allows multiple apps
across platforms to be associated with one single 'key' value.

[not at google - send to devlin, 2014/08/05 22:38:14]

I see. out of curiosity why isn't this a message filter?

[rkc, 2014/08/05 23:06:29]

We don't want an app to keep setting arbitrary keys based on which app it wants
messages from. Putting this in the message filter indicates that we should be
using this key to filter on, while we really want an app to use the API key only
if it wants to associate the current app with other apps on other platforms.

It is a way to say "this app is the same as all the other apps that are using an
API key from the same project". It is not meant to be "give me messages from app
x, y and z". For the latter, we want to eventually provide a clear way to do so
(if enough people actually ask for it; as of now, no one has).

+    // publish/subscribe to each other.
+    static void setApiKey(DOMString apiKey);
+    
+    // Executes a set of copresence operations in one batch. They will either
+    // all be executed, or none will be executed (due to an error in one or
+    // more of them). Publish/Subscribe operations are executed in the order
+    // that they exist in the array. Unpublish and Unsubscribe are processsed
+    // at the end, again, in the order that they exist in the array.
+    static void batchExecute(Operation[] operations,

[not at google - send to devlin, 2014/08/05 21:05:39]

IMO this should just be "execute" because the fact it batches is rather obvious,
and there's no other option other than batch. But IIRC you called it
"batchExecute" for consistency with other platforms?

[rkc, 2014/08/05 22:25:23]

Yes, but execute is fine too.
Changed this and all other references to [B|b]atchExecute
Done.

+        BatchExecuteCallback callback);
+  };
+
+  interface Events {
+    // Fired when we new messages arrive.

[xiyuan, 2014/08/05 21:02:35]

nit: get rid of "we"

[rkc, 2014/08/05 22:25:23]

Done.

+    static void onMessagesReceived(DOMString subscriptionId,
+                                   Message[] messages);
+                                   
+    // Fired when we have a new status update for copresence.
+    static void onStatusReceived(Status status);

[not at google - send to devlin, 2014/08/05 21:05:39]

onStatusUpdated?

[rkc, 2014/08/05 22:25:22]

Done.

+  };
+};
+