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
6 * http://www.apache.org/licenses/LICENSE-2.0
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.
16 * @fileoverview Browser environment for interacting with people.
23 * Namespace for top-level people functions.
29 * Namespace for top level people functions.
32 * @constructor (note: a constructor for JsDoc purposes)
34 var opensocial = function() {};
38 * Requests the container to send a specific message to the specified users.
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.
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
56 * @param {Array.<String> | 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
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>
72 opensocial.requestSendMessage = function(recipients, message, opt_callback,
77 * Requests the container to share this gadget with the specified users.
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.
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
95 * @param {Array.<String> | 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>
112 opensocial.requestShareApp = function(recipients, reason, opt_callback,
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.
122 * <a href="#newActivity">newActivity()</a>
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.
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.
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.
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
152 * @param {Function} opt_callback The function to call once the request has been
157 opensocial.requestCreateActivity = function(activity, priority,
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>
170 * @name opensocial.CreateActivityPriority
172 opensocial.CreateActivityPriority = {
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
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
187 * This field may be used interchangeably with the string 'LOW'.
188 * @member opensocial.CreateActivityPriority
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.
199 * @param {opensocial.Permission} permission
200 * The <a href="opensocial.Permission.html">permission</a>
202 * True if the gadget has access for the permission; false if it doesn't
206 opensocial.hasPermission = function(permission) {};
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
215 * @param {Array.<opensocial.Permission>} permissions
216 * The <a href="opensocial.Permission.html">permissions</a> to request
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.
232 opensocial.requestPermission = function(permissions, reason, opt_callback) {};
239 * The permissions an app can ask for.
243 * <a href="opensocial.html#hasPermission">
244 * <code>opensocial.hasPermission()</code></a>,
245 * <a href="opensocial.html#requestPermission">
246 * <code>opensocial.requestPermission()</code></a>
248 * @name opensocial.Permission
250 opensocial.Permission = {
252 * Access to the viewer person object
253 * This field may be used interchangeably with the string 'viewer'.
254 * @member opensocial.Permission
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.
265 * @return {opensocial.Environment}
266 * The current <a href="opensocial.Environment.html">environment</a>
270 opensocial.getEnvironment = function() {};
274 * Creates a data request object to use for sending and fetching data from the
277 * @return {opensocial.DataRequest} The
278 * <a href="opensocial.DataRequest.html">request</a> object
281 opensocial.newDataRequest = function() {};
285 * Creates an activity object,
286 * which represents an activity on the server.
289 * <a href="#requestCreateActivity">requestCreateActivity()</a>,
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>
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>
300 * <p>Containers are only required to use TITLE_ID or TITLE, and may choose to
301 * ignore additional parameters.</p>
303 * <p>See <a href="opensocial.Activity.Field.html">Field</a> for
306 * @param {Map.<opensocial.Activity.Field, Object>} params
307 * Parameters defining the activity
308 * @return {opensocial.Activity} The new
309 * <a href="opensocial.Activity.html">activity</a> object
312 opensocial.newActivity = function(params) {};
316 * Creates a media item.
317 * Represents images, movies, and audio.
318 * Used when creating activities on the server.
320 * @param {String} mimeType
321 * <a href="opensocial.MediaItem.Type.html">MIME type</a> of the
323 * @param {String} url Where the media can be found
324 * @param {Map.<opensocial.MediaItem.Field, Object>} opt_params
325 * Any other fields that should be set on the media item object;
327 * <a href="opensocial.MediaItem.Field.html">Field</a>s
330 * @return {opensocial.MediaItem} The new
331 * <a href="opensocial.MediaItem.html">media item</a> object
334 opensocial.newMediaItem = function(mimeType, url, opt_params) {};
338 * Creates a media item associated with an activity.
339 * Represents images, movies, and audio.
340 * Used when creating activities on the server.
342 * @param {String} body The main text of the message
343 * @param {Map.<opensocial.Message.Field, Object>} opt_params
344 * Any other fields that should be set on the message object;
346 * <a href="opensocial.Message.Field.html">Field</a>s
349 * @return {opensocial.Message} The new
350 * <a href="opensocial.Message.html">message</a> object
353 opensocial.newMessage = function(body, opt_params) {};
359 * The types of escaping that can be applied to person data or fields.
361 * @name opensocial.EscapeType
363 opensocial.EscapeType = {
365 * When used will HTML-escape the data.
366 * This field may be used interchangeably with the string 'htmlEscape'.
367 * @member opensocial.EscapeType
369 HTML_ESCAPE : 'htmlEscape',
371 * When used will not escape the data.
372 * This field may be used interchangeably with the string 'none'.
373 * @member opensocial.EscapeType
380 * Creates an IdSpec object.
382 * @param {Map.<opensocial.IdSpec.Field, Object>} parameters
383 * Parameters defining the id spec.
384 * @return {opensocial.IdSpec} The new
385 * <a href="opensocial.IdSpec.html">IdSpec</a> object
388 opensocial.newIdSpec = function(params) {};
392 * Creates a NavigationParameters object.
395 * <a href="#requestShareApp">requestShareApp()</a>
399 * @param {Map.<opensocial.NavigationParameters.Field, Object>} parameters
400 * Parameters defining the navigation
401 * @return {opensocial.NavigationParameters} The new
402 * <a href="opensocial.NavigationParameters.html">NavigationParameters</a>
406 opensocial.newNavigationParameters = function(params) {};