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

[Daniel Erat, 2014/08/06 22:59:37]

nit: "... to communicate with other nearby devices using Google's copresence
service."

(capitalize "Copresence" if that's how it's written publicly)

[rkc, 2014/08/07 02:18:34]

We don't use Copresence for branding (at least yet) so I tend to use it lower
case most places.
Done.

+// close by, using Google's copresence service.
+namespace copresence {
+  // 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;
+  };
+
+  dictionary Message {
+    // The type of message that we're publishing. Cannot be empty.

[Daniel Erat, 2014/08/06 22:59:38]

nit: s/that we're publishing/being published/

[rkc, 2014/08/07 02:18:34]

Done.

+    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.

[Daniel Erat, 2014/08/06 22:59:38]

nit: s/people/devices/

[rkc, 2014/08/07 02:18:34]

Done.

+    // 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.

[Daniel Erat, 2014/08/06 22:59:37]

nit: s/we default to 5 minutes/a default of 5 minutes is used/

[rkc, 2014/08/07 02:18:34]

Done.

+    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.

[Daniel Erat, 2014/08/06 22:59:38]

nit: s/we default to 5 minutes/a default of 5 minutes is used/

[rkc, 2014/08/07 02:18:34]

Done.

+    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

[Daniel Erat, 2014/08/06 22:59:37]

nit: s/id/ID/ here and elsewhere in this file

[rkc, 2014/08/07 02:18:34]

Done.

+    // is 'unpublish'.
+    DOMString unpublishId;
+  };
+
+  [noinline_doc] dictionary UnsubscribeOperation {
+    // The id of a subscription to cancel. Required if the operation type
+    // is 'unsubscribe'.
+    DOMString unsubscribeId;
+  };
+
+  // Only one of these can be set.
+  [noinline_doc] dictionary Operation {
+    // 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.
+  enum ExecuteStatus {
+    // 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.
+  enum Status {
+    // 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 ExecuteCallback = void(ExecuteStatus status);
+
+  interface Functions {
+    // Sets the API key to use with our app. This parameter only needs to be

[Daniel Erat, 2014/08/06 22:59:37]

nit: s/our app/the app/

[rkc, 2014/08/07 02:18:34]

Done.

+    // set if we need to communicate with apps on other platforms. Once we set

[Daniel Erat, 2014/08/06 22:59:38]

nit: "set to communicate with apps on other platforms"

[rkc, 2014/08/07 02:18:34]

Done.

+    // the api key, apps on any platform that are using this API key can

[Daniel Erat, 2014/08/06 22:59:37]

nit: s/api/API/, also change to "Once the API key is set, ..."

[rkc, 2014/08/07 02:18:34]

Done.

+    // 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 execute(Operation[] operations, ExecuteCallback callback);
+  };
+
+  interface Events {
+    // Fired when new messages arrive.
+    static void onMessagesReceived(DOMString subscriptionId,
+                                   Message[] messages);
+                                   
+    // Fired when we have a new status update for copresence.

[Daniel Erat, 2014/08/06 22:59:37]

nit: Fired when a new Copresence status update is available.

[rkc, 2014/08/07 02:18:34]

Done.

+    static void onStatusUpdated(Status status);
+  };
+};
+