jscripts/opensocial/opensocial.js

   1 /*
   2  * Licensed under the Apache License, Version 2.0 (the "License");
   3  * you may not use this file except in compliance with the License.
   4  * You may obtain a copy of the License at
   5  *
   6  *     http://www.apache.org/licenses/LICENSE-2.0
   7  *
   8  * Unless required by applicable law or agreed to in writing, software
   9  * distributed under the License is distributed on an "AS IS" BASIS,
  10  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  11  * See the License for the specific language governing permissions and
  12  * limitations under the License.
  13  */
  14
  15 /**
  16  * @fileoverview Browser environment for interacting with people.
  17  */
  18
  19
  20 /**
  21  * @static
  22  * @class
  23  * Namespace for top-level people functions.
  24  *
  25  * @name opensocial
  26  */
  27
  28 /**
  29  * Namespace for top level people functions.
  30  *
  31  * @private
  32  * @constructor (note: a constructor for JsDoc purposes)
  33  */
  34 var opensocial = function() {};
  35
  36
  37 /**
  38  * Requests the container to send a specific message to the specified users.
  39  *
  40  * <p>
  41  * The callback function is passed one parameter, an
  42  *    opensocial.ResponseItem. The error code will be set to reflect whether
  43  *    there were any problems with the request. If there was no error, the
  44  *    message was sent. If there was an error, you can use the response item's
  45  *    getErrorCode method to determine how to proceed. The data on the response
  46  *    item will not be set.
  47  * </p>
  48  *
  49  * <p>
  50  * If the container does not support this method
  51  * the callback will be called with an
  52  * opensocial.ResponseItem that has an error code of
  53  * NOT_IMPLEMENTED.
  54  * </p>
  55  *
  56  * @param {Array.&lt;String&gt; | String} recipients An ID, array of IDs, or a
  57  *     group reference; the supported keys are VIEWER, OWNER, VIEWER_FRIENDS,
  58  *    OWNER_FRIENDS, or a single ID within one of those groups
  59  * @param {opensocial.Message} message The message to send to the specified
  60  *     users
  61  * @param {Function} opt_callback The function to call once the request has been
  62  *    processed; either this callback will be called or the gadget will be
  63  *    reloaded from scratch
  64  * @param {opensocial.NavigationParameters} opt_params The optional parameters
  65  *     indicating where to send a user when a request is made, or when a request is
  66  *     accepted; options are of type
  67  *     <a href="opensocial.NavigationParameters.DestinationType.html">
  68  *     NavigationParameters.DestinationType</a>
  69  *
  70  * @member opensocial
  71  */
  72 opensocial.requestSendMessage = function(recipients, message, opt_callback,
  73     opt_params) {};
  74
  75
  76 /**
  77  * Requests the container to share this gadget with the specified users.
  78  *
  79  * <p>
  80  * The callback function is passed one parameter, an
  81  *    opensocial.ResponseItem. The error code will be set to reflect whether
  82  *    there were any problems with the request. If there was no error, the
  83  *    sharing request was sent. If there was an error, you can use the response
  84  *    item's getErrorCode method to determine how to proceed. The data on the
  85  *    response item will not be set.
  86  * </p>
  87  *
  88  * <p>
  89  * If the
  90  * container does not support this method the callback will be called with a
  91  * opensocial.ResponseItem. The response item will have its error code set to
  92  * NOT_IMPLEMENTED.
  93  * </p>
  94  *
  95  * @param {Array.&lt;String&gt; | String} recipients An ID, array of IDs, or a
  96  *     group reference; the supported keys are VIEWER, OWNER, VIEWER_FRIENDS,
  97  *    OWNER_FRIENDS, or a single ID within one of those groups
  98  * @param {opensocial.Message} reason The reason the user wants the gadget to
  99  *     share itself. This reason can be used by the container when prompting the
 100  *     user for permission to share the app. It may also be ignored.
 101  * @param {Function} opt_callback The function to call once the request has been
 102  *    processed; either this callback will be called or the gadget will be
 103  *    reloaded from scratch
 104  * @param {opensocial.NavigationParameters} opt_params The optional parameters
 105  *     indicating where to send a user when a request is made, or when a request is
 106  *     accepted; options are of type
 107  *     <a href="opensocial.NavigationParameters.DestinationType.html">
 108  *     NavigationParameters.DestinationType</a>
 109  *
 110  * @member opensocial
 111  */
 112 opensocial.requestShareApp = function(recipients, reason, opt_callback,
 113     opt_params) {};
 114
 115
 116 /**
 117  * Takes an activity and tries to create it,
 118  * without waiting for the operation to complete.
 119  * Optionally calls a function when the operation completes.
 120  * <p>
 121  * <b>See also:</b>
 122  * <a href="#newActivity">newActivity()</a>
 123  * </p>
 124  *
 125  * <p class="note">
 126  * <b>Note:</b>
 127  * If this is the first activity that has been created for the user and
 128  * the request is marked as HIGH priority then this call may open a user flow
 129  * and navigate away from your gadget.
 130  *
 131  * <p>
 132  * This callback will either be called or the gadget will be
 133  *    reloaded from scratch. This function will be passed one parameter, an
 134  *    opensocial.ResponseItem. The error code will be set to reflect whether
 135  *    there were any problems with the request. If there was no error, the
 136  *    activity was created. If there was an error, you can use the response
 137  *    item's getErrorCode method to determine how to proceed. The data on the
 138  *    response item will not be set.
 139  * </p>
 140  *
 141  * <p>
 142  * If the container does not support this method the callback will be called
 143  * with a opensocial.ResponseItem. The response item will have its error code
 144  * set to NOT_IMPLEMENTED.
 145  * </p>
 146  *
 147  * @param {opensocial.Activity} activity The <a href="opensocial.Activity.html">
 148  *    activity</a> to create
 149  * @param {opensocial.CreateActivityPriority} priority The
 150  *    <a href="opensocial.CreateActivityPriority.html">priority</a> for this
 151  *    request
 152  * @param {Function} opt_callback The function to call once the request has been
 153  *    processed.
 154  *
 155  * @member opensocial
 156  */
 157 opensocial.requestCreateActivity = function(activity, priority,
 158     opt_callback) {};
 159
 160
 161 /**
 162  * @static
 163  * @class
 164  * The priorities a create activity request can have.
 165  * <p><b>See also:</b>
 166  * <a href="opensocial.html#requestCreateActivity">
 167  * opensocial.requestCreateActivity()</a>
 168  * </p>
 169  *
 170  * @name opensocial.CreateActivityPriority
 171  */
 172 opensocial.CreateActivityPriority = {
 173   /**
 174    * If the activity is of high importance, it will be created even if this
 175    * requires asking the user for permission. This may cause the container to
 176    * open a user flow which may navigate away from your gagdet.
 177    * This field may be used interchangeably with the string 'HIGH'.
 178    * @member opensocial.CreateActivityPriority
 179    */
 180   HIGH : 'HIGH',
 181
 182   /**
 183    * If the activity is of low importance, it will not be created if the
 184    * user has not given permission for the current app to create activities.
 185    * With this priority, the requestCreateActivity call will never open a user
 186    * flow.
 187    * This field may be used interchangeably with the string 'LOW'.
 188    * @member opensocial.CreateActivityPriority
 189    */
 190   LOW : 'LOW'
 191 };
 192
 193
 194 /**
 195  * Returns true if the current gadget has access to the specified
 196  * permission. If the gadget calls opensocial.requestPermission and permissions
 197  * are granted then this function must return true on all subsequent calls.
 198  *
 199  * @param {opensocial.Permission} permission
 200  *    The <a href="opensocial.Permission.html">permission</a>
 201  * @return {Boolean}
 202  *    True if the gadget has access for the permission; false if it doesn't
 203  *
 204  * @member opensocial
 205  */
 206 opensocial.hasPermission = function(permission) {};
 207
 208
 209 /**
 210  * Requests the user to grant access to the specified permissions. If the
 211  * container does not support this method the callback will be called with a
 212  * opensocial.ResponseItem. The response item will have its error code set to
 213  * NOT_IMPLEMENTED.
 214  *
 215  * @param {Array.&lt;opensocial.Permission&gt;} permissions
 216  *    The <a href="opensocial.Permission.html">permissions</a> to request
 217  *    from the viewer
 218  * @param {String} reason Displayed to the user as the reason why these
 219  *    permissions are needed
 220  * @param {Function} opt_callback The function to call once the request has been
 221  *    processed; either this callback will be called or the gadget will be
 222  *    reloaded from scratch. This function will be passed one parameter, an
 223  *    opensocial.ResponseItem. The error code will be set to reflect whether
 224  *    there were any problems with the request. If there was no error, all
 225  *    permissions were granted. If there was an error, you can use
 226  *    opensocial.hasPermission to check which permissions are still denied. The
 227  *    data on the response item will be set. It will be an array of the
 228  *    opensocial.Permissions that were granted.
 229  *
 230  * @member opensocial
 231  */
 232 opensocial.requestPermission = function(permissions, reason, opt_callback) {};
 233
 234
 235 /**
 236  * @static
 237  * @class
 238  *
 239  * The permissions an app can ask for.
 240  *
 241  * <p>
 242  * <b>See also:</b>
 243  * <a href="opensocial.html#hasPermission">
 244  * <code>opensocial.hasPermission()</code></a>,
 245  * <a href="opensocial.html#requestPermission">
 246  * <code>opensocial.requestPermission()</code></a>
 247  *
 248  * @name opensocial.Permission
 249  */
 250 opensocial.Permission = {
 251   /**
 252    * Access to the viewer person object
 253    * This field may be used interchangeably with the string 'viewer'.
 254    * @member opensocial.Permission
 255    */
 256   VIEWER : 'viewer'
 257 };
 258
 259
 260 /**
 261  * Gets the current environment for this gadget. You can use the environment to
 262  * make queries such as what profile fields and surfaces are supported by this
 263  * container, what parameters were passed to the current gadget, and so on.
 264  *
 265  * @return {opensocial.Environment}
 266  *    The current <a href="opensocial.Environment.html">environment</a>
 267  *
 268  * @member opensocial
 269  */
 270 opensocial.getEnvironment = function() {};
 271
 272
 273 /**
 274  * Creates a data request object to use for sending and fetching data from the
 275  * server.
 276  *
 277  * @return {opensocial.DataRequest} The
 278  *    <a href="opensocial.DataRequest.html">request</a> object
 279  * @member opensocial
 280  */
 281 opensocial.newDataRequest = function() {};
 282
 283
 284 /**
 285  * Creates an activity object,
 286  * which represents an activity on the server.
 287  * <p>
 288  * <b>See also:</b>
 289  * <a href="#requestCreateActivity">requestCreateActivity()</a>,
 290  * </p>
 291  *
 292  * <p>It is only required to set one of TITLE_ID or TITLE. In addition, if you
 293  * are using any variables in your title or title template,
 294  * you must set TEMPLATE_PARAMS.</p>
 295  *
 296  * <p>Other possible fields to set are: URL, MEDIA_ITEMS, BODY_ID, BODY,
 297  * EXTERNAL_ID, PRIORITY, STREAM_TITLE, STREAM_URL, STREAM_SOURCE_URL,
 298  * and STREAM_FAVICON_URL.</p>
 299  *
 300  * <p>Containers are only required to use TITLE_ID or TITLE, and may choose to
 301  * ignore additional parameters.</p>
 302  *
 303  * <p>See <a href="opensocial.Activity.Field.html">Field</a> for
 304  * more details.</p>
 305  *
 306  * @param {Map.&lt;opensocial.Activity.Field, Object&gt;} params
 307  *    Parameters defining the activity
 308  * @return {opensocial.Activity} The new
 309  *    <a href="opensocial.Activity.html">activity</a> object
 310  * @member opensocial
 311  */
 312 opensocial.newActivity = function(params) {};
 313
 314
 315 /**
 316  * Creates a media item.
 317  * Represents images, movies, and audio.
 318  * Used when creating activities on the server.
 319  *
 320  * @param {String} mimeType
 321  *    <a href="opensocial.MediaItem.Type.html">MIME type</a> of the
 322  *    media
 323  * @param {String} url Where the media can be found
 324  * @param {Map.&lt;opensocial.MediaItem.Field, Object&gt;} opt_params
 325  *    Any other fields that should be set on the media item object;
 326  *    all of the defined
 327  *    <a href="opensocial.MediaItem.Field.html">Field</a>s
 328  *    are supported
 329  *
 330  * @return {opensocial.MediaItem} The new
 331  *    <a href="opensocial.MediaItem.html">media item</a> object
 332  * @member opensocial
 333  */
 334 opensocial.newMediaItem = function(mimeType, url, opt_params) {};
 335
 336
 337 /**
 338  * Creates a media item associated with an activity.
 339  * Represents images, movies, and audio.
 340  * Used when creating activities on the server.
 341  *
 342  * @param {String} body The main text of the message
 343  * @param {Map.&lt;opensocial.Message.Field, Object&gt;} opt_params
 344  *    Any other fields that should be set on the message object;
 345  *    all of the defined
 346  *    <a href="opensocial.Message.Field.html">Field</a>s
 347  *    are supported
 348  *
 349  * @return {opensocial.Message} The new
 350  *    <a href="opensocial.Message.html">message</a> object
 351  * @member opensocial
 352  */
 353 opensocial.newMessage = function(body, opt_params) {};
 354
 355
 356 /**
 357  * @static
 358  * @class
 359  * The types of escaping that can be applied to person data or fields.
 360  *
 361  * @name opensocial.EscapeType
 362  */
 363 opensocial.EscapeType = {
 364   /**
 365    * When used will HTML-escape the data.
 366    * This field may be used interchangeably with the string 'htmlEscape'.
 367    * @member opensocial.EscapeType
 368    */
 369   HTML_ESCAPE : 'htmlEscape',
 370   /**
 371    * When used will not escape the data.
 372    * This field may be used interchangeably with the string 'none'.
 373    * @member opensocial.EscapeType
 374    */
 375   NONE : 'none'
 376 };
 377
 378
 379 /**
 380  * Creates an IdSpec object.
 381  *
 382  * @param {Map.&lt;opensocial.IdSpec.Field, Object&gt;} parameters
 383  *     Parameters defining the id spec.
 384  * @return {opensocial.IdSpec} The new
 385  *     <a href="opensocial.IdSpec.html">IdSpec</a> object
 386  * @member opensocial
 387  */
 388 opensocial.newIdSpec = function(params) {};
 389
 390
 391 /**
 392  * Creates a NavigationParameters object.
 393  * <p>
 394  * <b>See also:</b>
 395  * <a href="#requestShareApp">requestShareApp()</a>
 396  * </p>
 397  *
 398  *
 399  * @param {Map.&lt;opensocial.NavigationParameters.Field, Object&gt;} parameters
 400  *     Parameters defining the navigation
 401  * @return {opensocial.NavigationParameters} The new
 402  *     <a href="opensocial.NavigationParameters.html">NavigationParameters</a>
 403  *     object
 404  * @member opensocial
 405  */
 406 opensocial.newNavigationParameters = function(params) {};