Call a 3rd-party Web service using an authorized (i.e., signed) call. This is similar to openmail.Application.callWebService, but will add any authorization information needed to make the call.

Sample Use:

Here is an example of how to call an OAuth service:

...
<script>
var statusURL = "http://social.yahooapis.com/v1/user/{guid}/presence/presence";
var oauth = openmail.Application.getAuthService({profile:'oauth'});
function loadStatus() {
oauth.callWebService( 
{ 
url: statusURL.replace('{guid}',guid),
method: "GET",
parameters: {format: 'json'}

},
function (response) {
alert(response.data);

});

}

</script>
...
<button onclick='loadStatus()'>load status</button>
...

Parameters:

service < Object >

service may include the following:
url: String Target URL
method: String "GET" or "POST"
parameters: Object A map of key/value pairs to use as the query string or the POST body
handler: function A callback function

Returns: Object

If call is successful, the Object contains the HTTP body returned by the Web service.
If call fails, the Object contains an error message describing the failure.

Note: The return value is always passed to the handler function.

Retrieves the current authorization status of the user with respect to the Web service.

Sample Use:

Here is how getStatus() is used to decide whether logging in is required.

<script>
...
var oauth = openmail.Application.getAuthService({profile:'oauth'});
oauth.getStatus( function(args) {
if (args.error) {
// handle error

}
if (args.data.status == 'ok') {
// ready to make calls

} else if (args.data.status == 'authorization required') {
// kick off authorization flow

}

...
</script>

Parameters:

handler < function > A callback function

Returns: Object

An object containing information about the authorization status.
The object has the following members:
status : One of following: 'ok', 'failed', or 'authorization required'.
info : If status is 'ok', depending on the profile type, data holds some additional information.

Retrieves the redirection URL that is needed by the user to continue the authorization process.

Sample Use:

Here is how getUserAuthorizationURL() is used to 'redirect' the user.

<script>
...
// handleSignIn needs to provide a way for the user to signal that she has completed
// authorization on the 3rd party site.
function handleSignIn() {...}
...
var oauth = openmail.Application.getAuthService({profile:'oauth'});
oauth.getStatus( function(args) {
if (args.error) {//handle error}
if (args.data.status == 'ok') {
// ready to make calls

} else if (args.data.status == 'authorization required') {
oauth.getUserAuthorizationURL({request:{},authorization:{permissions:'write'}},
function(response) {
if (response.error) {...} //handle errror
YAHOO.util.Dom.get("oauth_signin").href = response.data.url;
YAHOO.util.Event.addListener("oauth_signin", "click", handleSignIn);

});

}

...
</script>
...
<a href="javascript:void(0);" id="oauth_signin" target="_blank">Authorize!</a>

Parameters:

params < Object > An object containing the configuration of the auth service requested. The object has the following members:

request: The properties of the request object will be added to the call for the request token
authorization: The properties of the request object will be added to the authorization url

handler < function > A callback function

Returns: Object

An object containing the authorization URL and the following members:
url : The authorization URL.

Tells the authorization service that the user has completed the authorization process. This will initiate the retrieval of the authorization token from the 3rd-party service.

Sample Use:

Here is how notifyAuthorizationReceived() is used to continue the authorization flow.

<script>
...
var oauth = openmail.Application.getAuthService({profile:'oauth'});
...
function completeAuth() {
oauth.notifyAuthorizationReceived(function (response) {
if (response.error) {
// handle error

} else {
// handle completion. 
//response.data.info contains additional data from the service

}

});

...
</script>
<button onclick='completeAuth()'>Authorization Complete!</button>

Parameters:

handler < function > A callback function

Returns: Object

An object contains the status of the token retrieval and the following members:
info : Additional information is returned by the service.

Removes all authorization tokens and reverts back to initial state.

Sample Use:

Here is how removeAuthorization() is used to log out.

<script>
...
var oauth = openmail.Application.getAuthService({profile:'oauth'});
...
function logout() {
oauth.removeAuthorization(function (response) {
if (response.error) {//handle error}

});

...
</script>
<button onclick='logout()'>Log out!</button>

Parameters:

handler < function > A callback function

Returns: Object

An empty object.