chrome/common/extensions/api/copresence.idl

   1 // Copyright 2014 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 // Use the <code>chrome.copresence</code> API to communicate with other nearby
   6 // devices using Google's copresence service.
   7 namespace copresence {
   8   // Suggestions to copresence on how to do the publication and subscription.
   9   // Note: These are only suggestions. Actual behavior may not always match
  10   // what is requested.
  11   dictionary Strategy {
  12     // Attempt to use low power mode. Defaults to false.
  13     boolean? lowPower;
  14     // Attempt to only broadcast. Using this with onlyScan can result in both
  15     // being ignored. Defaults to false.
  16     boolean? onlyBroadcast;
  17     // Attempt to only scan. Using this with onlyBroadcast can result in both
  18     // being ignored. Defaults to false.
  19     boolean? onlyScan;
  20     // Attempt to use audible audio. Defaults to false.
  21     boolean? audible;
  22   };
  23
  24   dictionary Message {
  25     // The type of message being published. Cannot be empty.
  26     DOMString type;
  27     // The message payload, in raw bytes.
  28     ArrayBuffer payload;
  29   };
  30
  31   dictionary MessageFilter {
  32     // The type of messages to subscribe to. Cannot be empty.
  33     DOMString type;
  34   };
  35
  36   [noinline_doc] dictionary AccessPolicy {
  37     // Only send this message to devices within hearing range.
  38     // Defaults to false.
  39     boolean? onlyEarshot;
  40   };
  41
  42   [noinline_doc] dictionary PublishOperation {
  43     // A unique ID that identifies this publish.
  44     DOMString id;
  45     // The message to publish.
  46     Message message;
  47     // The number of milliseconds for which this publication will be active.
  48     // This is capped at 24 hours. If not provided, a default of 5 minutes is
  49     // used.
  50     long? timeToLiveMillis;
  51     // A policy specifying who can get the message.
  52     AccessPolicy? policy;
  53     // A set of strategies to use when publishing the message. These
  54     // strategies are suggestions to copresence that may or may not be followed.
  55     Strategy? strategies;
  56   };
  57
  58   [noinline_doc] dictionary SubscribeOperation {
  59     // A unique ID that identifies this subscription.
  60     DOMString id;
  61     // Filter that defines which messages we want to subscribe to.
  62     MessageFilter filter;
  63     // The number of milliseconds for which this subscription will be active.
  64     // This is capped at 24 hours. If not provided, a default of 5 minutes is
  65     // used.
  66     long? timeToLiveMillis;
  67     // A set of strategies to use when subscribing with this filter. These
  68     // strategies are suggestions to copresence that may or may not be followed.
  69     Strategy? strategies;
  70   };
  71
  72   [noinline_doc] dictionary UnpublishOperation {
  73     // The ID of a message to unpublish. Required if the operation type
  74     // is 'unpublish'.
  75     DOMString unpublishId;
  76   };
  77
  78   [noinline_doc] dictionary UnsubscribeOperation {
  79     // The ID of a subscription to cancel. Required if the operation type
  80     // is 'unsubscribe'.
  81     DOMString unsubscribeId;
  82   };
  83
  84   // Only one of these can be set.
  85   [noinline_doc] dictionary Operation {
  86     // Publication details. Required if the operation type is 'publish'.
  87     PublishOperation? publish;
  88     // Subscription details. Required if the operation type is 'subscribe'.
  89     SubscribeOperation? subscribe;
  90     // Unpublish details. Required if the operation type is 'unpublish'.
  91     UnpublishOperation? unpublish;
  92     // Unsubscribe details. Required if the operation type is 'unsubscribe'.
  93     UnsubscribeOperation? unsubscribe;
  94   };
  95
  96   // Indicates whether a batchExecute() call succeeded or encountered errors.
  97   enum ExecuteStatus {
  98     // All operations sent to batchExecute succeeded.
  99     success,
 100     // One of the operations sent to batchExecute failed.
 101     failed,
 102     // Contacting the Copresence server failed.
 103     serverError,
 104     // Initializing Copresence failed.
 105     initFailed
 106   };
 107
 108   // Specifies an asynchronous status event sent to the app.
 109   enum Status {
 110     // We attempted to broadcast audio but weren't able to.
 111     audioFailed,
 112     // Contacting the Copresence server failed.
 113     serverError
 114   };
 115
 116   // Callback to return the status of a completed batchExecute() call.
 117   callback ExecuteCallback = void(ExecuteStatus status);
 118
 119   interface Functions {
 120     // Sets the API key to use with the app. This parameter only needs to be
 121     // set to communicate with apps on other platforms. Once the API key is set,
 122     // apps on any platform that are using this API key can publish/subscribe to
 123     // each other.
 124     [nodoc] static void setApiKey(DOMString apiKey);
 125
 126     // Temporary call to enable authenticated copresence
 127     // with an externally provided OAuth token.
 128     // TODO(ckehoe): Replace this with a proper API.
 129     [nodoc] static void setAuthToken(DOMString token);
 130
 131     // Executes a set of copresence operations in one batch. They will either
 132     // all be executed, or none will be executed (due to an error in one or
 133     // more of them). Publish/Subscribe operations are executed in the order
 134     // that they exist in the array. Unpublish and Unsubscribe are processsed
 135     // at the end, again, in the order that they exist in the array.
 136     static void execute(Operation[] operations, ExecuteCallback callback);
 137   };
 138
 139   interface Events {
 140     // Fired when new messages arrive.
 141     static void onMessagesReceived(DOMString subscriptionId,
 142                                    Message[] messages);
 143
 144     // Fired when a new copresence status update is available.
 145     static void onStatusUpdated(Status status);
 146   };
 147 };
 148