/* * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * @fileoverview Provides remote content retrieval facilities. * Available to every gadget. */ /** * @static * @class Provides remote content retrieval functions. * @name gadgets.io */ gadgets.io = function() { return /** @scope gadgets.io */ { /** * Fetches content from the provided URL and feeds that content into the * callback function. * Example: * 
     * var params = {};
     * params[[]gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.TEXT;
     * gadgets.io.makeRequest(url, callback, params);
     *
* *

Signed authorization

* *

* If opt_params[[]gadgets.io.RequestParameters.AUTHORIZATION] is set to * gadgets.io.AuthorizationType.SIGNED, * the container needs to vouch * for the user's identity to * the destination server. * The container does this by doing the following: *

* *
    *

  1. * Removing any request parameters with names that begin with oauth, xoauth, * or opensocial (case insensitive).

    2. *

  2. * Adding the following parameters to the request query string:

    *
    *
    * opensocial_viewer_id
    *
    Optional.
    * The ID of the current viewer, which * matches the getId() value on the viewer person object.
    * opensocial_owner_id
    *
    Required.
    * The ID of the current owner, which * matches the getId() value on the owner person object.
    *
    * opensocial_app_url
    *
    Required.
    * The URL of the application making the * request. Containers may alias multiple application URLs to a single * canonical application URL in the case where an application changes * URLs.
    *
    * opensocial_instance_id
    *
    Optional.
    * An opaque identifier * used to distinguish between multiple instances of the same application * in a single container. If a container does not allow multiple * instances of the same application to coexist, this parameter may be * omitted. The combination of opensocial_app_url and * opensocial_instance_id * uniquely identify an instance of an * application in a container.
    *
    * opensocial_app_id
    *
    Optional.
    * An opaque identifier for the * application, unique to a particular container. * Containers that wish to maintain backwards compatibility * with the opensocial-0.7 specification may include this parameter. *
    * xoauth_public_key
    *
    Optional.
    * An opaque identifier for the * public key used to sign the request. This parameter may be omitted by * containers that do not use public keys to sign requests, or if the * container arranges other means of key distribution with the target of * the request.
    *
    *

  3. * Signing the resulting request according to section 9 of the * OAuth * specification.

    *
    4. * * *

    * Key management for gadgets.io.AuthorizationType.SIGNED *

    * *

    * If a container uses public keys to sign requests, * the container may choose to * use either self-signed certificates * or certificates signed by a well-known * certificate authority. * If a container does not distribute its OAuth signing * key over HTTPS, it should use a certificate signed by a well-known * certificate authority. *

    * *

    * The commonName attribute of the certificate should match the * hostname of the container server, and should also match the value of * the oauth_consumer_key parameter specified in the request. *

    * *

    * The container should make its public key available for download * at a well-known location. The location * https://container-hostname/opensocial/certificates/xoauth_public_keyvalue * is recommended. *

    * *

    * Recipients of signed requests must verify that the signature on * the request is correct, and that the timestamp on the request is * within a reasonable time window. A time window of * 5 minutes before and after * the current time is recommended. *

    * *

    * Recipients of signed requests may use the oauth_consumer_key and * xoauth_public_key parameters to automatically detect when a container * deploys new certificates. If the container deploys certificates at a * well-known location, the recipient may automatically download the new * certificate. Recipients that automatically download new certificates * should cache the resulting certificates. *

    * *

    * If a container's certificate is not downloaded from * https://container-hostname, the recipient should verify that the * certificate is signed by a well-known certificate authority before * trusting the certificate. *

    * *

    OAuth authorization

    * *

    * If opt_params[[]gadgets.io.RequestParameters.AUTHORIZATION] is set * to gadgets.io.AuthorizationType.OAUTH, * the container needs to use OAuth to gain access to * the resource specified in the request. * This may require that the gadget obtain the user's content by * directing the user to the service provider to gain access. *

    * *

    Additional parameters

    *

    * The following additional parameters may be specified in opt_params: *

    * *
    *
    * gadgets.io.RequestParameters.OAUTH_SERVICE_NAME *
    *
    * The nickname the gadget uses to refer to the OAuth <Service> * element from its XML spec. If unspecified, defaults to "". *
    * *
    * gadgets.io.RequestParameters.OAUTH_TOKEN_NAME *
    *
    * The nickname the gadget uses to refer to an OAuth token granting * access to a particular resources. If unspecified, defaults to "". * Gadgets can use multiple token names if they have access to * multiple resources from the same service provider. For example, a * gadget with access to a contact list and a calendar might use a token * name of "contacts" to use the contact list token, and a contact list * of "calendar" to use the calendar token. *
    * *
    * gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN *
    *
    * A service provider may be able to automatically provision a * gadget with a request token that is preapproved for access to a * resource. The gadget can use that token with the OAUTH_REQUEST_TOKEN * parameter. This parameter is optional. *
    * *
    * gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN_SECRET *
    *
    * The secret corresponding to a preapproved request token. This * parameter is optional. *
    *
    * *

    * If OAuth is used, the container should execute the OAuth protocol on * behalf of the gadget. If the gadget has not registered a consumer key * for use with this service provider, the container may choose to use a * default RSA signing key corresponding to a well-known certificate to sign * requests. If the container uses a default consumer key, it will include * an additional OAuth parameter xoauth_app_url that identifies the gadget * making the request. *

    * *

    The callback parameter

    * *

    * The makeRequest() callback parameter * is passed a javascript object with * several OAuth-specific fields in addition to the normal values returned * by makeRequest(): *

    * *
    *
    * "oauthApprovalUrl"
    *
    * If this value is specified, the user needs to * visit an external page to approve the gadget's request to access * data. Use of a pop-up window to direct the user to the external * page is recommended. Once the user has approved access, the gadget * can repeat the makeRequest call to retrieve the data. *
    * *
    * "oauthError"
    *
    * If this value is specified, it indicates an OAuth-related * error occurred. The value will be one of a set of string * constants that can be used for programmatically detecting errors. * The constants are undefined for opensocial-0.8, but implementers * should attempt to agree on a set of useful constant values for * standardization in opensocial-0.9. *
    * *
    * "oauthErrorText"
    *
    If this value is specified, it indicates an * OAuth-related error occurred. The value is free-form text that * can be used to provide debugging information for gadget developers. *
    *
    * * @param {String} url The URL where the content is located * @param {Function} callback The function to call with the data from the * URL once it is fetched * @param {Map.<gadgets.io.RequestParameters, Object>} opt_params * Additional * request parameters or * proxy * request parameters * * @member gadgets.io */ makeRequest : function (url, callback, opt_params) {}, /** * Converts an input object into a URL-encoded data string. * (key=value&...) * * @param {Object} fields The post fields you wish to encode * @return {String} The processed post data; this includes a trailing * ampersand (&) * * @member gadgets.io */ encodeValues : function (fields) {}, /** * Gets the proxy version of the passed-in URL. * * @param {String} url The URL to get the proxy URL for * @param {Map<String, String>} opt_params Additional optional * parameters * to pass to the request * @return {String} The proxied version of the URL * * @member gadgets.io */ getProxyUrl : function (url, opt_params) {} }; }(); /** * @static * @class * Used by the * * gadgets.io.makeRequest() method. * @name gadgets.io.RequestParameters */ gadgets.io.RequestParameters = { /** * The method to use when fetching content from the URL; * defaults to MethodType.GET. * Valid values are specified by * MethodType. * This field may be used interchangeably with the string 'METHOD'. * @member gadgets.io.RequestParameters */ METHOD : 'METHOD', /** * The type of content that lives at the URL; * defaults to ContentType.TEXT. * Specified as a * * ContentType. * This field may be used interchangeably with the string 'CONTENT_TYPE'. * @member gadgets.io.RequestParameters */ CONTENT_TYPE : "CONTENT_TYPE", /** * The data to send to the URL using the POST method; * defaults to null. * Specified as a String. * This field may be used interchangeably with the string 'POST_DATA'. * @member gadgets.io.RequestParameters */ POST_DATA : "POST_DATA", /** * The HTTP headers to send to the URL; * defaults to null. * Specified as a Map.<String,String>. * This field may be used interchangeably with the string 'HEADERS'. * @member gadgets.io.RequestParameters */ HEADERS : "HEADERS", /** * The type of authentication to use when fetching the content; * defaults to AuthorizationType.NONE. * Specified as an * * AuthorizationType. * This field may be used interchangeably with the string 'AUTHORIZATION'. * @member gadgets.io.RequestParameters */ AUTHORIZATION : 'AUTHORIZATION', /** * If the content is a feed, the number of entries to fetch; * defaults to 3. * Specified as a Number. * This field may be used interchangeably with the string 'NUM_ENTRIES'. * @member gadgets.io.RequestParameters */ NUM_ENTRIES : 'NUM_ENTRIES', /** * If the content is a feed, whether to fetch summaries for that feed; * defaults to false. * Specified as a Boolean. * This field may be used interchangeably with the string 'GET_SUMMARIES'. * @member gadgets.io.RequestParameters */ GET_SUMMARIES : 'GET_SUMMARIES', /** * Explicitly sets the lifespan of cached content. The Refresh Interval is * the number of seconds the container should cache the given response. By * default, the HTTP caching headers will be respected for fetched content. * If the refresh interval is set, this value will take precedence over any * HTTP cache headers. If this value is not set and there are no HTTP * caching headers specified, this value will default to 3600 (one hour). * Note that Signed requests and objects with POST_DATA present will * generally not be cached. * This field may be used interchangeably with the string 'REFRESH_INTERVAL'. * @member gadgets.io.RequestParameters */ REFRESH_INTERVAL : 'REFRESH_INTERVAL' }; /** * @static * @class * Defines values for * * RequestParameters.METHOD. * @name gadgets.io.MethodType */ gadgets.io.MethodType = { /** * The default type. * This field may be used interchangeably with the string 'GET'. * @member gadgets.io.MethodType */ GET : 'GET', /** * Container support for this method type is OPTIONAL. * This field may be used interchangeably with the string 'POST'. * @member gadgets.io.MethodType */ POST : 'POST', /** * Container support for this method type is OPTIONAL. * This field may be used interchangeably with the string 'PUT'. * @member gadgets.io.MethodType */ PUT : 'PUT', /** * Container support for this method type is OPTIONAL. * This field may be used interchangeably with the string 'DELETE'. * @member gadgets.io.MethodType */ DELETE : 'DELETE', /** * Container support for this method type is OPTIONAL. * This field may be used interchangeably with the string 'HEAD'. * @member gadgets.io.MethodType */ HEAD : 'HEAD' }; /** * @static * @class * Used by * * RequestParameters. * @name gadgets.io.ContentType */ gadgets.io.ContentType = { /** * Returns text; used for fetching HTML. * This field may be used interchangeably with the string 'TEXT'. * @member gadgets.io.ContentType */ TEXT : 'TEXT', /** * Returns a DOM object; used for fetching XML. * This field may be used interchangeably with the string 'DOM'. * @member gadgets.io.ContentType */ DOM : 'DOM', /** * Returns a JSON object. * This field may be used interchangeably with the string 'JSON'. * @member gadgets.io.ContentType */ JSON : 'JSON', /** * Returns a JSON representation of an RSS or Atom feed. * This field may be used interchangeably with the string 'FEED'. * @member gadgets.io.ContentType */ FEED : 'FEED' }; /** * @static * @class * Used by * * RequestParameters. * @name gadgets.io.AuthorizationType */ gadgets.io.AuthorizationType = { /** * No authorization. * This field may be used interchangeably with the string 'NONE'. * @member gadgets.io.AuthorizationType */ NONE : 'NONE', /** * The request will be signed by the container. * This field may be used interchangeably with the string 'SIGNED'. * @member gadgets.io.AuthorizationType */ SIGNED : 'SIGNED', /** * The container will use OAuth for authentication. * This field may be used interchangeably with the string 'OAUTH'. * @member gadgets.io.AuthorizationType */ OAUTH : 'OAUTH' }; /** * @static * @class * Used by * * gadgets.io.getProxyUrl() method. * @name gadgets.io.ProxyUrlRequestParameters */ gadgets.io.ProxyUrlRequestParameters = { /** * Explicitly sets the lifespan of cached content. The Refresh Interval is * the number of seconds the container should cache the given response. By * default, the HTTP caching headers will be respected for fetched content. * If the refresh interval is set, this value will take precedence over any * HTTP cache headers. If this value is not set and there are no HTTP * caching headers specified, this value will default to 3600 (one hour). * Note that Signed requests and objects with POST_DATA present will * generally not be cached. * This field may be used interchangeably with the string 'REFRESH_INTERVAL'. * @member gadgets.io.ProxyUrlRequestParameters */ REFRESH_INTERVAL : 'REFRESH_INTERVAL' };