From 164a05643383e998c4e7636d4d65f3d7eca76587 Mon Sep 17 00:00:00 2001 From: efeener Date: Fri, 21 Sep 2012 11:00:18 -0400 Subject: [PATCH 01/11] Initial commit of blackberry_user_identity doc --- api/blackberry_user_identity.js | 229 ++++++++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 api/blackberry_user_identity.js diff --git a/api/blackberry_user_identity.js b/api/blackberry_user_identity.js new file mode 100644 index 0000000000..6d312570f9 --- /dev/null +++ b/api/blackberry_user_identity.js @@ -0,0 +1,229 @@ +/* +* Copyright 2010-2011 Research In Motion Limited. +* +* 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. +*/ + +/** +* @toc {User Identity} User Identity +* @BB10X +* @RIPPLE +* @namespace The User Identity object contains information regarding the user's identity and accounts on a BlackBerry smartphone. +* +*

Identity Service SDK Overview - interfaces for using Identity +* Services from 3rd Party applications


+* +*

What functionality does this Identity Service SDK provide to apps? +* +*

This SDK provides a series of functions that enable an application to choose an +* identity provider(s) for their application, and to request authentication tokens +* from that provider, as well as information about the user. +* +*

At present, the only Identity Provider available is BlackBerry ID. As more +* identity providers become available, this SDK will provide access to those +* providers. +* +* +*

Why integrate with Identity Service? +* +*

If your app needs to interact with an off-device service that requires user +* authentication, you can integrate with Identity Service to provide seamless +* access to the off-device service. The interaction from the app to the off-device +* service is 'seamless' because the user is not prompted within the app for the +* username and password required by the off-device service. Instead, BlackBerry ID +* can pass back a 'token' that authenticates the user's identity, and that token +* can be read and understood by the off-service device, thus allowing the user +* access to that off-device content WITHOUT requiring user interaction for +* authentication. +* +*

Fictitious Example: Imagine an app called 'MyPics' that has a user's +* photo content stored off-device, and the content is accessible from the web and +* from BlackBerry devices. If 'MyPics' is integrated with BlackBerry ID +* (i.e. we've created a token specifically for them), the app can request a token +* from BlackBerry ID to confirm the user's identity. The app can send that token +* to the off-device content service for 'MyPics', as a way of 'signing in' that +* user to their MyPics account WITHOUT requiring the user to enter a username and +* password within the 'MyPics' app. The result is a seamless user experience for +* the app; the user will get their photos on the device without having to sign in +* to the 'MyPics' service. Since they are already signed in to their device with +* their BlackBerry ID, and since the app is integrated with BlackBerry ID to use +* tokens, it all happens without any user annoyance of being prompted to 'sign in' +* to MyPics. +* +*

Even if your app doesn't need to communicate with off-device services using +* tokens, there are other useful APIs in this SDK that provide access the user's +* account information (first name, last name, screen name, or username). +* +*

The next section provides a more detailed technical overview of the APIs that +* provide this functionality.
+* +* +*

Identity Service SDK functionality - API overview +* +*

This Identity Service WebWorks SDK provides an interface for applications to make +* use of BlackBerry ID functionality from within their app. +* +*

The APIs provided in this SDK enable apps to do the following: +* - retrieve the account information of the user who is signed in with their +* BlackBerry ID on the BB10 device. The API getProperties() can be +* used to retrieve the user's first name, last name, username, and screenname. +* +*

- retrieve tokens that prove the user's identity for off-device services +* (known as 'relying parties', because they are relying on BlackBerry ID +* to confirm the user's identity), so that the user can have seamless access +* to that off-device service without being required to enter their username and +* password. These tokens are used by the off-device service (relying party) to +* confirm the identity of the user. NOTE: The APIs getToken() and +* clearToken() can only be used if the relying party has gone through +* integration process with RIM to have tokens defined for that relying party. +* +*

- for background services where it doesn't make sense to show any screens to the +* user (i.e. background services that do not have any UI), suppress the ability +* for the Identity Service to pop up an authentication/password confirmation +* dialog box. The API setOption() is provided to ensure that the +* Identity Service does not present a pop up screen for authentication/password +* verification within background services where that wouldn't make sense. +* +*

Important: There is never a need for an application to present a +* "sign in" screen to the user. All the IDS APIs listed above will check to see if +* their is a BlackBerry ID associated with the device, and if there isn't one, +* they will pop an authentication (sign in) screen on the device (unless the +* calling app runs in the background and has 'set_GUI_allowed = False' to +* specifically prevent this from happening.) +* +*

About Callback functions +* +*

Several IDS APIs have the following 2 parameters: +* - Success callback function +* - Failure callback function +* +*

The Identity Service responds asynchronously to API calls made by an +* application. Upon detection of a response, the IDS library will parse the +* response (which will either be success or failure), and invoke the corresponding +* callback function that the app has provided for the success or failure case. +* +*

So the callback functions are a mechanism for IDS library to pass the parsed +* response from the daemon back to the calling application. The callback functions +* cannot be NULL; the app must specify what to do in both the success and failure +* scenarios. +* +*

Integrating an application with IDS APIs +* +* +*

The calling app uses the function registerProvider() which will +* connect the app to an Identity Service. This step must be done +* before the app calls any of the IDS APIs described above +* (getToken(), clearToken(), etc). After the app makes an API call to +* one of the IDS APIs listed above (i.e. getToken), the IDS library will +* asynchronously process that request, and call the success/failure callback provided. +* +* @featureID blackberry.user.identity +* @permission access_bbid_pii Permits your app to access user identity information. +*/ +blackberry.user.identity = { + +/** + * The getVersion() function retrieves the version of the IDS library + * that your application is using. + * @BB10X + * @returns {The version of IDS library} + * "1000000" + * @example +* <script type="text/javascript"> +* alert("Identity Service version is:" + blackberry.user.identity.getVersion()); +* </script> */ +getVersion : function(){}, + +/** + * Applications use this function to register which Identity Provider(s) that + * they want to use. Once the application has initialized the library, it can + * register for each of the identity providers it is interested in. + * @param {String} name The name of the identity provider that the application wants to + * use for retrieving user identity information (only BlackBerry ID is supported + * at this time). + * @returns {int} result + * @BB10X + * @RIPPLE +*/ +registerProvider : function(name) { }, + + +/** + * Applications use this function to register which Identity Provider(s) that + * they want to use. Once the application has initialized the library, it can + * register for each of the identity providers it is interested in. +* @returns {ids_result_t} +* @BB10X +* @RIPPLE +*/ +setOption : function(option, value) { }, + +/** + * Applications use this function to register which Identity Provider(s) that + * they want to use. Once the application has initialized the library, it can + * register for each of the identity providers it is interested in. +* @returns {ids_result_t} +* @BB10X +* @RIPPLE +*/ +getToken : function(idsProvider, tokenType, appliesTo, successCallback, failureCallback) { }, + +/** + * Issue a clear token request. In cases where the token seems to be invalid or + * too close to expiry to be deemed useful, an application can clear out the + * currently cached token in order to retrieve a newly generated token in the + * next getToken() call. + * + * @param {String} provider The identity provider to send this request to. + * @param {String} tokenType A token type. It must be NOT NULL + * and 32 characters >= tokenType > 0 character + * @param {String} appliesTo The application or service to which the token applies. It + * must be NOT NULL and 96 characters >= applies_to > 0 character + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * + * Error Handling:
+ * Requests that do not complete successfully will result in the failure + * callback being called with one of the following result codes: + * - 49999: An internal error has occurred attempting to process + * the request. + * - 50009: The appliesTo value is not valid. + * - 50008: The tokenType value is not valid. + * - 50010: There are not enough resources available to + * process the request. + * - 50003: The account is currently locked, token + * access is unavailable while locked. + * - 50004: The user could not be + * authenticated. + + + + * @returns {ids_result_t} +* @BB10X +* @RIPPLE +*/ +clearToken : function(idsProvider, tokenType, appliesTo, successCallback, failureCallback) { }, + +/** + * Applications use this function to register which Identity Provider(s) that + * they want to use. Once the application has initialized the library, it can + * register for each of the identity providers it is interested in. +* @returns {ids_result_t} +* @BB10X +* @RIPPLE +*/ +getProperties : function(idsProvider, userProperties, successCallback, failureCallback) { }; + +}; \ No newline at end of file From 4db1526d81707efd5b7a13dce3b881e7e1076161 Mon Sep 17 00:00:00 2001 From: efeener Date: Fri, 21 Sep 2012 14:17:00 -0400 Subject: [PATCH 02/11] Updating user.identity API doc --- api/blackberry_user_identity.js | 214 +++++++++++++++++++++++++++----- 1 file changed, 180 insertions(+), 34 deletions(-) diff --git a/api/blackberry_user_identity.js b/api/blackberry_user_identity.js index 6d312570f9..0fa008be5f 100644 --- a/api/blackberry_user_identity.js +++ b/api/blackberry_user_identity.js @@ -17,7 +17,6 @@ /** * @toc {User Identity} User Identity * @BB10X -* @RIPPLE * @namespace The User Identity object contains information regarding the user's identity and accounts on a BlackBerry smartphone. * *

Identity Service SDK Overview - interfaces for using Identity @@ -136,7 +135,7 @@ blackberry.user.identity = { * The getVersion() function retrieves the version of the IDS library * that your application is using. * @BB10X - * @returns {The version of IDS library} + * @returns {int} * "1000000" * @example * <script type="text/javascript"> @@ -153,28 +152,110 @@ getVersion : function(){}, * at this time). * @returns {int} result * @BB10X - * @RIPPLE + * @example + * <script type="text/javascript"> + var registerResult = blackberry.user.identity.registerProvider("ids:rim:bbid"); + if( registerResult.errorDescription ) { + alert("IDS register provider error: " + registerResult.result + " with description: " + registerResult.errorDescription); + } + * </script> */ registerProvider : function(name) { }, /** - * Applications use this function to register which Identity Provider(s) that - * they want to use. Once the application has initialized the library, it can - * register for each of the identity providers it is interested in. -* @returns {ids_result_t} -* @BB10X -* @RIPPLE -*/ + * Configure an option in the Identity Services library. These options allow an + * application to modify the default behavior of the IDS library as well as + * configure the way the library and application integrate together. + *

Available options are: + *

Set GUI Allowed (option = 0, value = true/false) + *

Option to set whether or not GUI allowed flag is set. Value is "true" or + * "false". By default, in cases where user input is required, the Identity + * Service performs the user interaction on behalf of the calling + * application. If this has been set to false, and user input is required, + * the API will return an error. If no user interaction is required to + * complete the API, this setting has no effect. + *

Set Group ID (option = 1, value = groupId) + *

Set the group ID of the calling application for UI dialogs. String + * version of UI group id. This is required in cases where the Identity + * Service requires user input from the user and must open an interface in + * the context of the calling application. + *

Set Verbosity (option = 2, value = {"Silent", "Normal", "Verbose") + *

Set the library logging verbosity level. Useful during application + * development to allow developers to be able to increase logging for + * diagnostics. Note that IDS logs are generated on stderr, and so should be + * captured in the application's log file. + * @param {int} option The option to be modified. + * @param {String} value The new string value to set + * @returns {int} + * @BB10X + * @example + * <script type="text/javascript"> + var setOptionResult = blackberry.user.identity.setOption(0, true); + if( setOptionResult.errorDescription ) { + alert("IDS set option error: " + setOptionResult.result + " with description: " + setOptionResult.errorDescription); + } + * </script> + */ setOption : function(option, value) { }, /** - * Applications use this function to register which Identity Provider(s) that - * they want to use. Once the application has initialized the library, it can - * register for each of the identity providers it is interested in. -* @returns {ids_result_t} -* @BB10X -* @RIPPLE + * Issue a get token request. + * + * @param {String} provider The identity provider to send this request to. + * @param {String} tokenType A token type. It must be NOT NULL + * and 32 characters >= tokenType > 0 character + * @param {String} appliesTo The application or service to which the token applies. It + * must be NOT NULL and 96 characters >= applies_to > 0 character + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {JSON} successCallback.tokenResult A JSON object containing a token and it's information in the form below: + * 

{
+     * "token": "ghdaj23i8rghaepeghk;a",
+	 * "params": ["name":"TOKEN_SECRET","value":"oguireqhge"]
+     * }
+ * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *
{
+	* "result":"50009",
+	* "errorDescription":"The appliesTo value is not valid"
+	* }
+ * + *

Error Handling:
+ * Requests that do not complete successfully will result in the failure + * callback being called with one of the following result codes: + *

- 49999: An internal error has occurred attempting to process + * the request. + *

- 50009: The appliesTo value is not valid. + *

- 50008: The tokenType value is not valid. + *

- 50010: There are not enough resources available to + * process the request. + *

- 50003: The account is currently locked, token + * access is unavailable while locked. + *

- 50004: The user could not be authenticated. + *

- 50011: The service is currently offline and + * and cannot retreive the requested token. + *

- 50012: An error occurred communicating with + * the service. + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function getTokenSuccess(tokenResult) { + alert("Received token: " + tokenResult.token); + for( param in tokenResult.tokenParams ) { + alert("Token param: " + tokenResult.tokenParams[param].name + " and value: " + tokenResult.tokenParams[param].value); + } + } + + function getTokenFailure(result) { + alert("Failed to retrieve token - result is: " + result.result + " with description: " + result.errorDescription); + } + + blackberry.user.identity.registerProvider("ids:rim:bbid"); + blackberry.user.identity.getToken("ids:rim:bbid", "MyTokenType", "urn:token:myapplication", getTokenSuccess, getTokenFailure); + * </script> */ getToken : function(idsProvider, tokenType, appliesTo, successCallback, failureCallback) { }, @@ -191,38 +272,103 @@ getToken : function(idsProvider, tokenType, appliesTo, successCallback, failureC * must be NOT NULL and 96 characters >= applies_to > 0 character * @callback {Function} successCallback Function which is invoked upon successful operation of this * method. + * @callback {JSON} successCallback.result A JSON object containing the in the form below: + * 

{
+     * "result": true
+     * }
* @callback {Function} failureCallback Function which is invoked when this method fails. This * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *
{
+	* "result":"50009",
+	* "errorDescription":"The appliesTo value is not valid"
+	* }
* - * Error Handling:
+ *

Error Handling:
* Requests that do not complete successfully will result in the failure * callback being called with one of the following result codes: - * - 49999: An internal error has occurred attempting to process + *

- 49999: An internal error has occurred attempting to process * the request. - * - 50009: The appliesTo value is not valid. - * - 50008: The tokenType value is not valid. - * - 50010: There are not enough resources available to + *

- 50009: The appliesTo value is not valid. + *

- 50008: The tokenType value is not valid. + *

- 50010: There are not enough resources available to * process the request. - * - 50003: The account is currently locked, token + *

- 50003: The account is currently locked, token * access is unavailable while locked. - * - 50004: The user could not be + *

- 50004: The user could not be * authenticated. + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function clearTokenSuccess(clearTokenResult) { + alert("Token cleared: " + clearTokenResult.cleared); + } + + function clearTokenFailure(result) { + alert("Failed to clear token - result is: " + result.result + " with description: " + result.errorDescription); + } - - - * @returns {ids_result_t} -* @BB10X -* @RIPPLE + blackberry.user.identity.registerProvider("ids:rim:bbid"); + blackberry.user.identity.clearToken("ids:rim:bbid", "MyTokenType", "urn:token:myapplication", clearTokenSuccess, clearTokenFailure); + * </script> */ clearToken : function(idsProvider, tokenType, appliesTo, successCallback, failureCallback) { }, /** - * Applications use this function to register which Identity Provider(s) that - * they want to use. Once the application has initialized the library, it can - * register for each of the identity providers it is interested in. -* @returns {ids_result_t} -* @BB10X -* @RIPPLE + * Issue a request for a property. + * + * @param {String} provider The identity provider to send this request to. + * @param {String} propertyList A comma separated string listing each of the properties + * requested + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {JSON} successCallback.result A JSON object containing the in the form below: + * 

{[
+ * 		{"uri":"urn:bbid:firstname":"value":"john"},
+		{"uri":"urn:bbid:lastname":"value":"doe"}
+     * }
+ * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *
{
+	* "result":"50004",
+	* "errorDescription":"The user could not be authenticated."
+	* }
+ *

Error Handling:
+ * Requests that do not complete successfully will result in the failure + * callback being called with one of the following result codes: + *

- 49999: An internal error has occurred attempting to process + * the request. + *

- 50010: There are not enough resources available to + * process the request. + *

- 50003: The account is currently locked, token + * access is unavailable while locked. + *

- 50004: The user could not be authenticated. + *

- 50011: The service is currently offline and + * and cannot retreive the requested token. + *

- 50002: The length of a property name in the list exceeds + * the maximum name length (32). + *

- 50017: The application does not have access to + * one of the requested properties. + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function getPropertiesSuccess(properties) { + alert("Get properties returned the following user properties:"); + for( prop in properties ) { + alert("Property: " + properties[prop].uri + " value: " + properties[prop].value); + } + } + + function getPropertiesFailure(result) { + alert("Failed to retrieve user properties: " + result.result + " details: " + result.failureInfo); + } + + blackberry.user.identity.registerProvider("ids:rim:bbid"); + blackberry.user.identity.getProperties("ids:rim:bbid", "urn:bbid:firstname,urn:bbid:lastname", getPropertiesSuccess, getPropertiesFailure); + * </script> */ getProperties : function(idsProvider, userProperties, successCallback, failureCallback) { }; From c2051ca295a500990cbbc78a9ac1c9f66f3089fd Mon Sep 17 00:00:00 2001 From: efeener Date: Wed, 20 Feb 2013 15:47:08 -0500 Subject: [PATCH 03/11] Updating to include information for profile service calls --- api/blackberry_user_identity.js | 171 +++++++++++++++++++++++++++++++- 1 file changed, 167 insertions(+), 4 deletions(-) diff --git a/api/blackberry_user_identity.js b/api/blackberry_user_identity.js index 0fa008be5f..826b1ed67e 100644 --- a/api/blackberry_user_identity.js +++ b/api/blackberry_user_identity.js @@ -75,7 +75,9 @@ *

The APIs provided in this SDK enable apps to do the following: * - retrieve the account information of the user who is signed in with their * BlackBerry ID on the BB10 device. The API getProperties() can be -* used to retrieve the user's first name, last name, username, and screenname. +* used to retrieve the user's first name, last name, username, and screenname. The +* createProperty, setProperty, and deleteProperty are used to +* store and manage data that an application would like to store about a user. * *

- retrieve tokens that prove the user's identity for off-device services * (known as 'relying parties', because they are relying on BlackBerry ID @@ -127,8 +129,15 @@ * asynchronously process that request, and call the success/failure callback provided. * * @featureID blackberry.user.identity -* @permission access_bbid_pii Permits your app to access user identity information. +* @permission access_bbid_pii Permits your app to access user identity information including +* tokens, core user properties, and the ability to store secondary user properties. +* @permission _sys_access_identity_services_second_party Permits your app to access user +* identity information including core user properties and the ability to store secondary +* user properties. +* @permission _sys_access_identity_services_third_party Permits your app to access user +* identity information including the ability to store secondary user properties. */ + blackberry.user.identity = { /** @@ -319,6 +328,9 @@ clearToken : function(idsProvider, tokenType, appliesTo, successCallback, failur * Issue a request for a property. * * @param {String} provider The identity provider to send this request to. + * @param type The type of properties contained in the @c propertyList + * parameter. Each provider may have a unique set of types that it is able to + * handle. See the documentation for the provider for details on valid values. * @param {String} propertyList A comma separated string listing each of the properties * requested * @callback {Function} successCallback Function which is invoked upon successful operation of this @@ -367,9 +379,160 @@ clearToken : function(idsProvider, tokenType, appliesTo, successCallback, failur } blackberry.user.identity.registerProvider("ids:rim:bbid"); - blackberry.user.identity.getProperties("ids:rim:bbid", "urn:bbid:firstname,urn:bbid:lastname", getPropertiesSuccess, getPropertiesFailure); + blackberry.user.identity.getProperties("ids:rim:bbid", 0, "urn:bbid:firstname,urn:bbid:lastname", getPropertiesSuccess, getPropertiesFailure); + * </script> +*/ +getProperties : function(idsProvider, 0, userProperties, successCallback, failureCallback) { }; + +/** + * Issue a request to set a property + * + * @param {String} provider The identity provider to send this request to. + * @param {int} type The type of property contained in @c property + * parameter. Each provider may have a unique set of types that it is able to + * handle. See the documentation for the provider for details on valid values. + * @param {String} propertyName The property identifier + * @param {String} propertyValue The content of the property + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *

{
+	* "result":"50004",
+	* "errorDescription":"The user could not be authenticated."
+	* }
+ *

Error Handling:
+ * Requests that do not complete successfully will result in the failure + * callback being called with one of the following result codes: + *

- 49999: An internal error has occurred attempting to process + * the request. + *

- 50010: There are not enough resources available to + * process the request. + *

- 50003: The account is currently locked, token + * access is unavailable while locked. + *

- 50004: The user could not be authenticated. + *

- 50107: The value of the propertyName must not be empty + *

- 50002: The length of a property name in the list exceeds + * the maximum name length (32). + *

- 50017: The application does not have access to the + * requested property. + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function setPropertySuccess() { + alert("Set property was successful"); + } + + function setPropertyFailure(result) { + alert("Failed to set user property: " + result.result + " details: " + result.failureInfo); + } + + blackberry.user.identity.registerProvider("ids:rim:bbid"); + blackberry.user.identity.setProperty("ids:rim:bbid", 1, "urn:myapp:usershandle", "johndoe123", setPropertySuccess, setPropertyFailure); + * </script> +*/ +setProperty : function(idsProvider, 0, propertyName, propertyValue, successCallback, failureCallback) { }; + +/** + * Issue a request to create a property + * + * @param {String} provider The identity provider to send this request to. + * @param {int} type The type of property contained in @c property + * parameter. Each provider may have a unique set of types that it is able to + * handle. See the documentation for the provider for details on valid values. + * @param {String} propertyName The property identifier + * @param {String} propertyValue The content of the property + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *

{
+	* "result":"50004",
+	* "errorDescription":"The user could not be authenticated."
+	* }
+ *

Error Handling:
+ * Requests that do not complete successfully will result in the failure + * callback being called with one of the following result codes: + *

- 49999: An internal error has occurred attempting to process + * the request. + *

- 50010: There are not enough resources available to + * process the request. + *

- 50003: The account is currently locked, token + * access is unavailable while locked. + *

- 50004: The user could not be authenticated. + *

- 50107: The value of the propertyName must not be empty + *

- 50002: The length of a property name in the list exceeds + * the maximum name length (32). + *

- 50017: The application does not have access to the + * requested property. + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function createPropertySuccess() { + alert("Create property was successful"); + } + + function createPropertyFailure(result) { + alert("Failed to create user property: " + result.result + " details: " + result.failureInfo); + } + + blackberry.user.identity.registerProvider("ids:rim:bbid"); + blackberry.user.identity.createProperty("ids:rim:bbid", 1, "urn:myapp:usershandle", "johndoe123", createPropertySuccess, createPropertyFailure); * </script> */ -getProperties : function(idsProvider, userProperties, successCallback, failureCallback) { }; +createProperty : function(idsProvider, 0, propertyName, propertyValue, successCallback, failureCallback) { }; + +/** + * Issue a request to delete a property + * + * @param {String} provider The identity provider to send this request to. + * @param {int} type The type of property contained in @c property + * parameter. Each provider may have a unique set of types that it is able to + * handle. See the documentation for the provider for details on valid values. + * @param {String} propertyName The property identifier + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *

{
+	* "result":"50004",
+	* "errorDescription":"The user could not be authenticated."
+	* }
+ *

Error Handling:
+ * Requests that do not complete successfully will result in the failure + * callback being called with one of the following result codes: + *

- 49999: An internal error has occurred attempting to process + * the request. + *

- 50010: There are not enough resources available to + * process the request. + *

- 50003: The account is currently locked, token + * access is unavailable while locked. + *

- 50004: The user could not be authenticated. + *

- 50107: The value of the propertyName must not be empty + *

- 50002: The length of a property name in the list exceeds + * the maximum name length (32). + *

- 50017: The application does not have access to the + * requested property. + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function deletePropertySuccess() { + alert("Delete property was successful"); + } + + function deletePropertyFailure(result) { + alert("Failed to delete user property: " + result.result + " details: " + result.failureInfo); + } + blackberry.user.identity.registerProvider("ids:rim:bbid"); + blackberry.user.identity.deleteProperty("ids:rim:bbid", 1, "urn:myapp:usershandle", deletePropertySuccess, deletePropertyFailure); + * </script> +*/ +deleteProperty : function(idsProvider, 0, propertyName, successCallback, failureCallback) { }; }; \ No newline at end of file From 2be78753db04147f998dcc2256fd3dceb89b50c9 Mon Sep 17 00:00:00 2001 From: efeener Date: Wed, 20 Feb 2013 15:56:36 -0500 Subject: [PATCH 04/11] Removing first and second party permission descriptions --- api/blackberry_user_identity.js | 5 ----- 1 file changed, 5 deletions(-) diff --git a/api/blackberry_user_identity.js b/api/blackberry_user_identity.js index 826b1ed67e..9fc9c8083e 100644 --- a/api/blackberry_user_identity.js +++ b/api/blackberry_user_identity.js @@ -129,11 +129,6 @@ * asynchronously process that request, and call the success/failure callback provided. * * @featureID blackberry.user.identity -* @permission access_bbid_pii Permits your app to access user identity information including -* tokens, core user properties, and the ability to store secondary user properties. -* @permission _sys_access_identity_services_second_party Permits your app to access user -* identity information including core user properties and the ability to store secondary -* user properties. * @permission _sys_access_identity_services_third_party Permits your app to access user * identity information including the ability to store secondary user properties. */ From c2fb9874d017eb002cf7070b36c3a779e24293d0 Mon Sep 17 00:00:00 2001 From: efeener Date: Thu, 28 Feb 2013 16:49:51 -0500 Subject: [PATCH 05/11] Adding deleteLocal to docs --- api/blackberry_user_identity.js | 110 ++++++++++++++++++++++++++------ 1 file changed, 91 insertions(+), 19 deletions(-) diff --git a/api/blackberry_user_identity.js b/api/blackberry_user_identity.js index 9fc9c8083e..4a2721f6fb 100644 --- a/api/blackberry_user_identity.js +++ b/api/blackberry_user_identity.js @@ -352,12 +352,23 @@ clearToken : function(idsProvider, tokenType, appliesTo, successCallback, failur *

- 50003: The account is currently locked, token * access is unavailable while locked. *

- 50004: The user could not be authenticated. - *

- 50011: The service is currently offline and - * and cannot retreive the requested token. + *

- 50107: The value of @c count must be greater than 1 and + * match the number of properties in the @c propertyList. + *

- 50005: Too many properties were requested. See @c + * IDS_MAX_PROPERTY_COUNT. *

- 50002: The length of a property name in the list exceeds - * the maximum name length (32). + * the maximum name length @c IDS_MAX_PROPERTY_NAME_LEN. *

- 50017: The application does not have access to * one of the requested properties. + *

- 50007: Property does not exist. + *

- 50100: Invalid property name. + *

- 50015: Null or invalid parameter. + *

- 50160: Property does not exist. + *

- 50158: Server error. + *

- 50107: Property value is too large. + *

- 50153: Get failed. + + * @returns {void} * @BB10X * @example @@ -407,11 +418,15 @@ getProperties : function(idsProvider, 0, userProperties, successCallback, failur *

- 50003: The account is currently locked, token * access is unavailable while locked. *

- 50004: The user could not be authenticated. - *

- 50107: The value of the propertyName must not be empty - *

- 50002: The length of a property name in the list exceeds - * the maximum name length (32). - *

- 50017: The application does not have access to the - * requested property. + *

- 50017: The application does not have access to set + * the requested property. + *

- 50100: Invalid property name. + *

- 50015: Null or invalid parameter. + *

- 50160: Property does not exist. + *

- 50158: Server error. + *

- 50162: Set failed. + *

- 50154: Set failed. + *

- 50159: Property exists but cannot be overwritten. * @returns {void} * @BB10X * @example @@ -457,12 +472,14 @@ setProperty : function(idsProvider, 0, propertyName, propertyValue, successCallb * process the request. *

- 50003: The account is currently locked, token * access is unavailable while locked. - *

- 50004: The user could not be authenticated. - *

- 50107: The value of the propertyName must not be empty - *

- 50002: The length of a property name in the list exceeds - * the maximum name length (32). - *

- 50017: The application does not have access to the - * requested property. + *

- 50004: The user could not be + * authenticated. + *

- 50017: The application does not have access to set + * the requested property. + *

- 50015: Null or invalid parameter. + *

- 50158: Server error. + *

- 50152: Create failed. + *

- 50159: Property already exists. * @returns {void} * @BB10X * @example @@ -508,11 +525,13 @@ createProperty : function(idsProvider, 0, propertyName, propertyValue, successCa *

- 50003: The account is currently locked, token * access is unavailable while locked. *

- 50004: The user could not be authenticated. - *

- 50107: The value of the propertyName must not be empty - *

- 50002: The length of a property name in the list exceeds - * the maximum name length (32). - *

- 50017: The application does not have access to the - * requested property. + *

- 50017: The application does not have access to set + * the requested property. + *

- 50015: Null or invalid parameter. + *

- 50158: Server error. + *

- 50155: Delete failed. + *

- 50160: Property does not exist. + *

- 50100: Invalid property name. * @returns {void} * @BB10X * @example @@ -530,4 +549,57 @@ createProperty : function(idsProvider, 0, propertyName, propertyValue, successCa * </script> */ deleteProperty : function(idsProvider, 0, propertyName, successCallback, failureCallback) { }; + +/** + * Issue a request to delete a property locally only (device only) + * + * @param {String} provider The identity provider to send this request to. + * @param {int} type The type of property contained in @c property + * parameter. Each provider may have a unique set of types that it is able to + * handle. See the documentation for the provider for details on valid values. + * @param {String} propertyName The property identifier + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *

{
+	* "result":"50004",
+	* "errorDescription":"The user could not be authenticated."
+	* }
+ *

Error Handling:
+ * Requests that do not complete successfully will result in the failure + * callback being called with one of the following result codes: + *

- 49999: An internal error has occurred attempting to process + * the request. + *

- 50010: There are not enough resources available to + * process the request. + *

- 50003: The account is currently locked, token + * access is unavailable while locked. + *

- 50004: The user could not be authenticated. + *

- 50017: The application does not have access to set + * the requested property. + *

- 50015: Null or invalid parameter. + *

- 50158: Server error. + *

- 50155: Delete failed. + *

- 50160: Property does not exist. + *

- 50100: Invalid property name. + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function deletePropertySuccess() { + alert("Delete property was successful"); + } + + function deletePropertyFailure(result) { + alert("Failed to delete user property: " + result.result + " details: " + result.failureInfo); + } + + blackberry.user.identity.registerProvider("ids:rim:bbid"); + blackberry.user.identity.deleteLocalProperty("ids:rim:bbid", 1, "urn:myapp:usershandle", deletePropertySuccess, deletePropertyFailure); + * </script> +*/ +deleteLocalProperty : function(idsProvider, 0, propertyName, successCallback, failureCallback) { }; + }; \ No newline at end of file From f3407a9af390df822c0fba31432f137a8434b0b4 Mon Sep 17 00:00:00 2001 From: efeener Date: Mon, 13 May 2013 16:08:41 -0400 Subject: [PATCH 06/11] Updating Identity Service docs to include new calls --- api/blackberry_user_identity.js | 467 ++++++++++++++++---------------- 1 file changed, 237 insertions(+), 230 deletions(-) diff --git a/api/blackberry_user_identity.js b/api/blackberry_user_identity.js index 4a2721f6fb..6d95dfc9f7 100644 --- a/api/blackberry_user_identity.js +++ b/api/blackberry_user_identity.js @@ -1,5 +1,5 @@ /* -* Copyright 2010-2011 Research In Motion Limited. +* Copyright 2013 Research In Motion Limited. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -17,120 +17,98 @@ /** * @toc {User Identity} User Identity * @BB10X -* @namespace The User Identity object contains information regarding the user's identity and accounts on a BlackBerry smartphone. -* -*

Identity Service SDK Overview - interfaces for using Identity -* Services from 3rd Party applications


-* -*

What functionality does this Identity Service SDK provide to apps? -* -*

This SDK provides a series of functions that enable an application to choose an -* identity provider(s) for their application, and to request authentication tokens -* from that provider, as well as information about the user. -* -*

At present, the only Identity Provider available is BlackBerry ID. As more -* identity providers become available, this SDK will provide access to those -* providers. -* -* -*

Why integrate with Identity Service? -* -*

If your app needs to interact with an off-device service that requires user -* authentication, you can integrate with Identity Service to provide seamless -* access to the off-device service. The interaction from the app to the off-device -* service is 'seamless' because the user is not prompted within the app for the -* username and password required by the off-device service. Instead, BlackBerry ID -* can pass back a 'token' that authenticates the user's identity, and that token -* can be read and understood by the off-service device, thus allowing the user -* access to that off-device content WITHOUT requiring user interaction for -* authentication. -* -*

Fictitious Example: Imagine an app called 'MyPics' that has a user's -* photo content stored off-device, and the content is accessible from the web and -* from BlackBerry devices. If 'MyPics' is integrated with BlackBerry ID -* (i.e. we've created a token specifically for them), the app can request a token -* from BlackBerry ID to confirm the user's identity. The app can send that token -* to the off-device content service for 'MyPics', as a way of 'signing in' that -* user to their MyPics account WITHOUT requiring the user to enter a username and -* password within the 'MyPics' app. The result is a seamless user experience for -* the app; the user will get their photos on the device without having to sign in -* to the 'MyPics' service. Since they are already signed in to their device with -* their BlackBerry ID, and since the app is integrated with BlackBerry ID to use -* tokens, it all happens without any user annoyance of being prompted to 'sign in' -* to MyPics. -* -*

Even if your app doesn't need to communicate with off-device services using -* tokens, there are other useful APIs in this SDK that provide access the user's -* account information (first name, last name, screen name, or username). -* -*

The next section provides a more detailed technical overview of the APIs that -* provide this functionality.
-* -* -*

Identity Service SDK functionality - API overview -* -*

This Identity Service WebWorks SDK provides an interface for applications to make -* use of BlackBerry ID functionality from within their app. -* -*

The APIs provided in this SDK enable apps to do the following: -* - retrieve the account information of the user who is signed in with their -* BlackBerry ID on the BB10 device. The API getProperties() can be -* used to retrieve the user's first name, last name, username, and screenname. The -* createProperty, setProperty, and deleteProperty are used to -* store and manage data that an application would like to store about a user. -* -*

- retrieve tokens that prove the user's identity for off-device services -* (known as 'relying parties', because they are relying on BlackBerry ID -* to confirm the user's identity), so that the user can have seamless access -* to that off-device service without being required to enter their username and -* password. These tokens are used by the off-device service (relying party) to -* confirm the identity of the user. NOTE: The APIs getToken() and -* clearToken() can only be used if the relying party has gone through -* integration process with RIM to have tokens defined for that relying party. -* -*

- for background services where it doesn't make sense to show any screens to the -* user (i.e. background services that do not have any UI), suppress the ability -* for the Identity Service to pop up an authentication/password confirmation -* dialog box. The API setOption() is provided to ensure that the -* Identity Service does not present a pop up screen for authentication/password -* verification within background services where that wouldn't make sense. -* -*

Important: There is never a need for an application to present a -* "sign in" screen to the user. All the IDS APIs listed above will check to see if -* their is a BlackBerry ID associated with the device, and if there isn't one, -* they will pop an authentication (sign in) screen on the device (unless the -* calling app runs in the background and has 'set_GUI_allowed = False' to -* specifically prevent this from happening.) +* @namespace Identity Service library SDK - The Identity Service library offers +* a framework for data storage and retrieval, access to the user's personal +* information stored in the Identity Provider's account system, and user +* authentication/authorization to access the Identity Provider's apps and +* services. + * -*

About Callback functions +*

Identity Service library


* -*

Several IDS APIs have the following 2 parameters: -* - Success callback function -* - Failure callback function +*

Developers can make use of the Identity Service library APIs to enhance their app in several ways: +* - Data storage and retrieval +* - User authentication and authorization to access apps and off-device services offered by the Identity Provider (without prompting for credentials) +* - Access to the user's personal information stored in the Identity Provider's account system +* +*

These capabilities are described further in the sections below, and the specific implementation will vary for each Identity Provider. For example, the data storage and retrieval APIs might +* provide off-device data storage, or on-device data storage - that could differ between one Identity Provider and another. Similarly, the personal information that can be retrieved with the +* getProperties() API call will differ based on what information each Identity Provider stores in their account system. * -*

The Identity Service responds asynchronously to API calls made by an -* application. Upon detection of a response, the IDS library will parse the -* response (which will either be success or failure), and invoke the corresponding -* callback function that the app has provided for the success or failure case. +*

As such, this document gives an overview of the Identity Service library APIs that are available, and this information must be used in conjunction with the Identity Provider's specific Identity +* Service API overview to confirm the specifics of their implementation of each of these APIs. * -*

So the callback functions are a mechanism for IDS library to pass the parsed -* response from the daemon back to the calling application. The callback functions -* cannot be NULL; the app must specify what to do in both the success and failure -* scenarios. +*

DataStorage_section Data storage and retrieval APIs +* +*

Applications can make use of APIs in the IDS library to store and retrieve data. +*

APIs are provided for: +* - initial storage of the data (createData()) +* - retrieving the data (getData()) +* - updating the data (setData()) +* - removing the data (deleteData()) +* - listing the stored data (istData()) + +*

UserAuth_Section User authentication without prompting for credentials +* +*

Developers can use the Identity Services user authentication APIs in this library to avoid the need to implement user name and password management for their app. With these APIs, once the user is signed in using their account with the Identity Provider on the device, the user is automatically signed in to the app as well. +* - Users won't need to create or remember a username and password for the app. +* - Users won't need to specifically log in to the app, thus improving the ease of use of the app. +* * -*

Integrating an application with IDS APIs +*

OffDeviceAuth_Section User authorization to access apps and off-device services offered by the Identity Provider +* +*

If your app interacts with an off-device service that requires user authentication (for example, a web site that requires the user to sign in with a username and password), +* you can use the Identity Service APIs to perform the off-device authentication/authorization using tokens, instead of prompting the user for credentials. Your app and the off-device service interact seamlessly. +* +* +*

PII_Section Access to the user's personal information associated with their account +* +*

The user's personal information that is available to the app will depend on what information is available from the Identity Provider's account system. +* +*

For example, if the app uses BlackBerry ID as the Identity Provider, the app can access the following personal information (provided that the user gives the app their consent): +* - first name +* - last name +* - screen name +* - username +* +*

For other Identity Providers, the personal information available will depend on what that provider stores in their identity account system. +* +*

ids_callback_sec About Callback functions +* +*

Many of the IDS APIs have the following three parameters: +* - Success callback function +* - Failure callback function +* +*

When your app sends API calls using the IDS APIs, the Identity Provider +* service responds asynchronously. When an app receives a response, the +* corresponding callback function that your application had provided for the +* success or failure case is executed. +* +*

The Identity Provider service uses callback functions to pass the parsed response +* back to your app. Callback functions cannot be NULL. Your app must specify what +* to do in both the success and failure scenarios. +* +* +*

bbid_modes_sec Registering your app to use the IDS APIs +* +*

To register your app so that it can use the IDS APIs, call +* registerProvider() from your app for at least one identity provider. +* +*

After your app sends a request, the Identity Provider service will process the +* request asynchronously, and call the corresponding success/failure callback function. +* +*

For example, your app can call getProperties() and pass a success +* callback of myAppSuccessCallback and a failure callback of +* myAppFailureCallback. When a response is ready from the identity provider, the +* success or failure callback will execute based on the results of the call. * * -*

The calling app uses the function registerProvider() which will -* connect the app to an Identity Service. This step must be done -* before the app calls any of the IDS APIs described above -* (getToken(), clearToken(), etc). After the app makes an API call to -* one of the IDS APIs listed above (i.e. getToken), the IDS library will -* asynchronously process that request, and call the success/failure callback provided. * * @featureID blackberry.user.identity -* @permission _sys_access_identity_services_third_party Permits your app to access user +* @permission read_personally_identifiable_information Permits your app to access user * identity information including the ability to store secondary user properties. +* @permission access_internet Permits your app to use the internet to access user data +* in remote storage. */ blackberry.user.identity = { @@ -229,19 +207,20 @@ setOption : function(option, value) { }, *

Error Handling:
* Requests that do not complete successfully will result in the failure * callback being called with one of the following result codes: - *

- 49999: An internal error has occurred attempting to process + *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process * the request. - *

- 50009: The appliesTo value is not valid. - *

- 50008: The tokenType value is not valid. - *

- 50010: There are not enough resources available to + *

- IDS_UNKNOWN_APPLIES_TO: The appliesTo value is not valid. + *

- IDS_UNKNOWN_TOKEN_TYPE: The tokenType value is not valid. + *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to * process the request. - *

- 50003: The account is currently locked, token + *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token * access is unavailable while locked. - *

- 50004: The user could not be authenticated. - *

- 50011: The service is currently offline and - * and cannot retreive the requested token. - *

- 50012: An error occurred communicating with - * the service. + *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + *

- IDS_CANNOT_GET_TOKEN_WHILE_OFFLINE: The service is currently offline + * and cannot retrieve the requested token. + *

- IDS_ERROR_WHILE_CONTACTING_SERVICE: An error occurred communicating + * with the service. * @returns {void} * @BB10X * @example @@ -291,15 +270,15 @@ getToken : function(idsProvider, tokenType, appliesTo, successCallback, failureC *

Error Handling:
* Requests that do not complete successfully will result in the failure * callback being called with one of the following result codes: - *

- 49999: An internal error has occurred attempting to process + *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process * the request. - *

- 50009: The appliesTo value is not valid. - *

- 50008: The tokenType value is not valid. - *

- 50010: There are not enough resources available to + *

- IDS_UNKNOWN_APPLIES_TO: The @c applies_to value is not valid. + *

- IDS_UNKNOWN_TOKEN_TYPE: The @c token_type value is not valid. + *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to * process the request. - *

- 50003: The account is currently locked, token + *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token * access is unavailable while locked. - *

- 50004: The user could not be + *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be * authenticated. * @returns {void} * @BB10X @@ -345,30 +324,28 @@ clearToken : function(idsProvider, tokenType, appliesTo, successCallback, failur *

Error Handling:
* Requests that do not complete successfully will result in the failure * callback being called with one of the following result codes: - *

- 49999: An internal error has occurred attempting to process + *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process * the request. - *

- 50010: There are not enough resources available to + *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to * process the request. - *

- 50003: The account is currently locked, token + *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token * access is unavailable while locked. - *

- 50004: The user could not be authenticated. - *

- 50107: The value of @c count must be greater than 1 and - * match the number of properties in the @c propertyList. - *

- 50005: Too many properties were requested. See @c + *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + *

- IDS_TOO_MANY_NAMES_PASSED: Too many properties were requested. See * IDS_MAX_PROPERTY_COUNT. - *

- 50002: The length of a property name in the list exceeds - * the maximum name length @c IDS_MAX_PROPERTY_NAME_LEN. - *

- 50017: The application does not have access to + *

- IDS_NAME_TOO_LONG: The length of a property name in the list exceeds + * the maximum name length IDS_MAX_PROPERTY_NAME_LEN. + *

- IDS_PROPERTY_NOT_AUTHORIZED: The application does not have access to * one of the requested properties. - *

- 50007: Property does not exist. - *

- 50100: Invalid property name. - *

- 50015: Null or invalid parameter. - *

- 50160: Property does not exist. - *

- 50158: Server error. - *

- 50107: Property value is too large. - *

- 50153: Get failed. - - + *

- IDS_PROPERTY_DOES_NOT_EXIST: Property does not exist. + *

- IDS_BAD_PROPERTY_NAME: Invalid property name. + *

- IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter. + *

- IDS_NON_EXISTING_PROPERTY: Property does not exist. + *

- IDS_PROFILE_SERVER_ERROR: Server error. + *

- IDS_PROPERTY_VALUE_TOO_LARGE: Property value is too large. + *

- IDS_GET_FAIL: Get failed. + * * @returns {void} * @BB10X * @example @@ -391,14 +368,16 @@ clearToken : function(idsProvider, tokenType, appliesTo, successCallback, failur getProperties : function(idsProvider, 0, userProperties, successCallback, failureCallback) { }; /** - * Issue a request to set a property + * Issue a request to set data * * @param {String} provider The identity provider to send this request to. - * @param {int} type The type of property contained in @c property - * parameter. Each provider may have a unique set of types that it is able to + * @param {int} type The type of data. Each provider may have a unique set of types that it is able to * handle. See the documentation for the provider for details on valid values. - * @param {String} propertyName The property identifier - * @param {String} propertyValue The content of the property + * @param flags Special flags for the operation. Each provider may have a unique + * set of flags that it supports. See the documentation for the provider for + * details on valid values and their behaviour for this operation. + * @param {String} dataName The data identifier + * @param {String} dataValue The content of the data * @callback {Function} successCallback Function which is invoked upon successful operation of this * method. * @callback {Function} failureCallback Function which is invoked when this method fails. This @@ -411,49 +390,51 @@ getProperties : function(idsProvider, 0, userProperties, successCallback, failur *

Error Handling:
* Requests that do not complete successfully will result in the failure * callback being called with one of the following result codes: - *

- 49999: An internal error has occurred attempting to process + *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process * the request. - *

- 50010: There are not enough resources available to + *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to * process the request. - *

- 50003: The account is currently locked, token + *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token * access is unavailable while locked. - *

- 50004: The user could not be authenticated. - *

- 50017: The application does not have access to set - * the requested property. - *

- 50100: Invalid property name. - *

- 50015: Null or invalid parameter. - *

- 50160: Property does not exist. - *

- 50158: Server error. - *

- 50162: Set failed. - *

- 50154: Set failed. - *

- 50159: Property exists but cannot be overwritten. + *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + *

- IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter. + *

- IDS_DOES_NOT_EXIST: Entry with the given name does not exist. + *

- IDS_NOT_ALLOWED: Application is not allowed to perform this operation. + *

- IDS_ERROR_WHILE_CONTACTING_SERVICE: The provider was unable to + * communicate with it's service to perform operation. + *

- USER_RESOURCE_NAME_TOO_LONG: The name is longer than the maximum length + * allowed by the provider * @returns {void} * @BB10X * @example * <script type="text/javascript"> - function setPropertySuccess() { + function setDataSuccess() { alert("Set property was successful"); } - function setPropertyFailure(result) { - alert("Failed to set user property: " + result.result + " details: " + result.failureInfo); + function setDataFailure(result) { + alert("Failed to set data: " + result.result + " details: " + result.failureInfo); } - blackberry.user.identity.registerProvider("ids:rim:bbid"); - blackberry.user.identity.setProperty("ids:rim:bbid", 1, "urn:myapp:usershandle", "johndoe123", setPropertySuccess, setPropertyFailure); + blackberry.user.identity.registerProvider("ids:rim:profile"); + blackberry.user.identity.setData("ids:rim:profile", 1, "usershandle", "johndoe123", setDataSuccess, setDataFailure); * </script> */ -setProperty : function(idsProvider, 0, propertyName, propertyValue, successCallback, failureCallback) { }; +setData : function(idsProvider, 0, 0, dataName, dataValue, successCallback, failureCallback) { }; /** - * Issue a request to create a property + * Issue a request to create data * * @param {String} provider The identity provider to send this request to. - * @param {int} type The type of property contained in @c property - * parameter. Each provider may have a unique set of types that it is able to + * @param {int} type The type of data. Each provider may have a unique set of types that it is able to * handle. See the documentation for the provider for details on valid values. - * @param {String} propertyName The property identifier - * @param {String} propertyValue The content of the property + * @param flags Special flags for the operation. Each provider may have a unique + * set of flags that it supports. See the documentation for the provider for + * details on valid values and their behaviour for this operation. + * + * @param {String} dataName The property identifier + * @param {String} dataValue The content of the property * @callback {Function} successCallback Function which is invoked upon successful operation of this * method. * @callback {Function} failureCallback Function which is invoked when this method fails. This @@ -466,46 +447,50 @@ setProperty : function(idsProvider, 0, propertyName, propertyValue, successCallb *

Error Handling:
* Requests that do not complete successfully will result in the failure * callback being called with one of the following result codes: - *

- 49999: An internal error has occurred attempting to process + *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process * the request. - *

- 50010: There are not enough resources available to + *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to * process the request. - *

- 50003: The account is currently locked, token + *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token * access is unavailable while locked. - *

- 50004: The user could not be + *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be * authenticated. - *

- 50017: The application does not have access to set - * the requested property. - *

- 50015: Null or invalid parameter. - *

- 50158: Server error. - *

- 50152: Create failed. - *

- 50159: Property already exists. + *

- IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter. + *

- IDS_ERROR_WHILE_CONTACTING_SERVICE: The provider was unable to + * communicate with it's service to perform operation. + *

- IDS_ALREADY_EXISTS: Entry with name already exists. + *

- IDS_NOT_ALLOWED: Application is not allowed to perform this operation. + *

- USER_RESOURCE_NAME_TOO_LONG: The name is longer than the maximum length + * allowed by the provider + * * @returns {void} * @BB10X * @example * <script type="text/javascript"> - function createPropertySuccess() { - alert("Create property was successful"); + function createDataSuccess() { + alert("Create Data was successful"); } - function createPropertyFailure(result) { - alert("Failed to create user property: " + result.result + " details: " + result.failureInfo); + function createDataFailure(result) { + alert("Failed to create data: " + result.result + " details: " + result.failureInfo); } - blackberry.user.identity.registerProvider("ids:rim:bbid"); - blackberry.user.identity.createProperty("ids:rim:bbid", 1, "urn:myapp:usershandle", "johndoe123", createPropertySuccess, createPropertyFailure); + blackberry.user.identity.registerProvider("ids:rim:profile"); + blackberry.user.identity.createData("ids:rim:profile", 1, "usershandle", "johndoe123", createDataSuccess, createDataFailure); * </script> */ -createProperty : function(idsProvider, 0, propertyName, propertyValue, successCallback, failureCallback) { }; +createData : function(idsProvider, 0, 0, dataName, dataValue, successCallback, failureCallback) { }; /** - * Issue a request to delete a property + * Issue a request to data * * @param {String} provider The identity provider to send this request to. - * @param {int} type The type of property contained in @c property - * parameter. Each provider may have a unique set of types that it is able to + * @param {int} type The type of data.Each provider may have a unique set of types that it is able to * handle. See the documentation for the provider for details on valid values. - * @param {String} propertyName The property identifier + * @param flags Special flags for the operation. Each provider may have a unique + * set of flags that it supports. See the documentation for the provider for + * details on valid values and their behaviour for this operation. + * @param {String} dataName The property identifier * @callback {Function} successCallback Function which is invoked upon successful operation of this * method. * @callback {Function} failureCallback Function which is invoked when this method fails. This @@ -518,46 +503,48 @@ createProperty : function(idsProvider, 0, propertyName, propertyValue, successCa *

Error Handling:
* Requests that do not complete successfully will result in the failure * callback being called with one of the following result codes: - *

- 49999: An internal error has occurred attempting to process + *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process * the request. - *

- 50010: There are not enough resources available to + *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to * process the request. - *

- 50003: The account is currently locked, token + *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, * access is unavailable while locked. - *

- 50004: The user could not be authenticated. - *

- 50017: The application does not have access to set - * the requested property. - *

- 50015: Null or invalid parameter. - *

- 50158: Server error. - *

- 50155: Delete failed. - *

- 50160: Property does not exist. - *

- 50100: Invalid property name. + *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + *

- IDS_NOT_ALLOWED: The application does not have access to delete + * the requested value. + *

- IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter. + *

- IDS_DOES_NOT_EXIST: Name specified does not exist. + *

- IDS_ERROR_WHILE_CONTACTING_SERVICE: The provider was unable to + * communicate with it's service to perform operation. + *

- USER_RESOURCE_NAME_TOO_LONG: The name is longer than the maximum length + * allowed by the provider * @returns {void} * @BB10X * @example * <script type="text/javascript"> - function deletePropertySuccess() { - alert("Delete property was successful"); + function deleteDataSuccess() { + alert("Delete data was successful"); } - function deletePropertyFailure(result) { - alert("Failed to delete user property: " + result.result + " details: " + result.failureInfo); + function deleteDataFailure(result) { + alert("Failed to delete data: " + result.result + " details: " + result.failureInfo); } - blackberry.user.identity.registerProvider("ids:rim:bbid"); - blackberry.user.identity.deleteProperty("ids:rim:bbid", 1, "urn:myapp:usershandle", deletePropertySuccess, deletePropertyFailure); + blackberry.user.identity.registerProvider("ids:rim:profile"); + blackberry.user.identity.deleteData("ids:rim:profile", 1, 0, "usershandle", deleteDataSuccess, deleteDataFailure); * </script> */ -deleteProperty : function(idsProvider, 0, propertyName, successCallback, failureCallback) { }; +deleteData : function(idsProvider, 0, 0, dataName, successCallback, failureCallback) { }; + /** - * Issue a request to delete a property locally only (device only) + * Issue a request to challenge for identity * * @param {String} provider The identity provider to send this request to. - * @param {int} type The type of property contained in @c property - * parameter. Each provider may have a unique set of types that it is able to - * handle. See the documentation for the provider for details on valid values. - * @param {String} propertyName The property identifier + * @param flags Special flags for the operation. Each provider may have a unique + * set of flags that it supports. See the documentation for the provider for + * details on valid values and their behaviour for this operation. * @callback {Function} successCallback Function which is invoked upon successful operation of this * method. * @callback {Function} failureCallback Function which is invoked when this method fails. This @@ -570,36 +557,56 @@ deleteProperty : function(idsProvider, 0, propertyName, successCallback, failure *

Error Handling:
* Requests that do not complete successfully will result in the failure * callback being called with one of the following result codes: - *

- 49999: An internal error has occurred attempting to process + * - @c IDS_DEFAULT_ERROR: An internal error has occurred attempting to process * the request. - *

- 50010: There are not enough resources available to + * - @c IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to * process the request. - *

- 50003: The account is currently locked, token + * - @c IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, * access is unavailable while locked. - *

- 50004: The user could not be authenticated. - *

- 50017: The application does not have access to set - * the requested property. - *

- 50015: Null or invalid parameter. - *

- 50158: Server error. - *

- 50155: Delete failed. - *

- 50160: Property does not exist. - *

- 50100: Invalid property name. + * - @c IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. * @returns {void} * @BB10X * @example * <script type="text/javascript"> - function deletePropertySuccess() { - alert("Delete property was successful"); + function challengeSuccess(level) { + alert("Challenge was successful: " + level); } - function deletePropertyFailure(result) { - alert("Failed to delete user property: " + result.result + " details: " + result.failureInfo); + function challengeFailure(result) { + alert("Challenge failed: " + result.result + " details: " + result.failureInfo); } blackberry.user.identity.registerProvider("ids:rim:bbid"); - blackberry.user.identity.deleteLocalProperty("ids:rim:bbid", 1, "urn:myapp:usershandle", deletePropertySuccess, deletePropertyFailure); + blackberry.user.identity.challenge("ids:rim:bbid", 0, challengeSuccess, challengeFailure); * </script> */ -deleteLocalProperty : function(idsProvider, 0, propertyName, successCallback, failureCallback) { }; +challenge : function(idsProvider, 0, successCallback, failureCallback) { }; + + +/** + * Register a callback function to be called when the named entry + * changes + * @param {String} provider The identity provider to send this request to. + * @param type The type of data referred to by name. + * @param flags Special flags for the operation. Each provider may have a unique + * set of flags that it supports. See the documentation for the provider for + * details on valid values and their behaviour for this operation. + * @param name The name of the entry to receive notifications for. + * @callback {Function} onChangeCallback The function that is invoked when a change is detected. + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function onChangeCb(type, name, notification) { + alert("Notification received: " + name + " with notification: " + notification); + } + + blackberry.user.identity.registerProvider("ids:rim:bbid"); + blackberry.user.identity.registerNotifier("ids:rim:bbid", 0, propertyName, onChangeCb); + * </script> +*/ +registerNotifier : function(idsProvider, 0, name, onChangeCallback) { }; + }; \ No newline at end of file From f77063b7f8fce97da0cf8ffe887a07d313ad5701 Mon Sep 17 00:00:00 2001 From: efeener Date: Wed, 26 Jun 2013 10:58:12 -0400 Subject: [PATCH 07/11] Adding docs for BlackBerryId and BlackBerryProfile providers --- api/blackberry_user_identity_blackberryid.js | 77 ++++++++++ ...ckberry_user_identity_blackberryprofile.js | 131 ++++++++++++++++++ 2 files changed, 208 insertions(+) create mode 100644 api/blackberry_user_identity_blackberryid.js create mode 100644 api/blackberry_user_identity_blackberryprofile.js diff --git a/api/blackberry_user_identity_blackberryid.js b/api/blackberry_user_identity_blackberryid.js new file mode 100644 index 0000000000..0648844478 --- /dev/null +++ b/api/blackberry_user_identity_blackberryid.js @@ -0,0 +1,77 @@ +/* +* Copyright 2013 Research In Motion Limited. +* +* 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. +*/ + +/** +* @toc {User Identity} User Identity - BlackBerry ID +* @BB10X +* @namespace Use BlackBerry ID as an identity provider for your application. +* +*

Using the BlackBerry ID service as an identity provider, you can enhance +* your app in several ways:
+* - Provide secure, off-device data storage and retrieval within the +* BlackBerry ecosystem.
+* - Provide user authentication within your app, without prompting for +* user credentials.
+* - Provide user authorization to access other BlackBerry apps and off-device +* services without prompting for user credentials.
+* - Provide access to users' personal information that is stored in the +* BlackBerry ID account system. User permission to access this information +* is required. + +* +*

User authentication without prompting for credentials


+* +*

Benefits of implementing BlackBerry ID user authentication:
+* - Eliminate the need to build your own username and password management.
+* - Automatically sign users in to your app after they sign in with their +* BlackBerry ID account on their devices. This makes your app easier to use.
+* - Eliminate the need for users to create and remember a username and +* password for your app. +* +*

User authorization to access other BlackBerry apps and off-device services


+* +*

If your app interacts with an off-device service that requires user +* authentication (for example, a website that requires the user to sign in +* with a username and password), you can use BlackBerry ID APIs to perform +* the off-device authentication/authorization using tokens, instead of +* prompting the user for credentials. Your app and the off-device service +* interact seamlessly. +* +*

Access personal information associated with BlackBerry ID accounts


+* +*

You can personalize the user experience of your app by incorporating your +* users' personal information in your app. Users must allow your app to +* access the information associated with their BlackBerry ID accounts before +* you can access it. The application must have the +* read_personally_identifiable_information permission included in their bar +* descriptor. The information that is available includes:
+* - first name
+* - last name
+* - screen name
+* - username (an email address)
+* +*

The getProperties() function can be used to retrieve personal +* information stored in the BlackBerry ID account system, with +* CORE_PROPERTY_TYPE passed as the type parameter. +* +* @featureID blackberry.user.identity +* @permission read_personally_identifiable_information Permits your app to access user +* identity information including the ability to store secondary user properties. +* @permission access_internet Permits your app to use the internet to access user data +* in remote storage. +*/ +blackberry.user.identity.blackberryid = { +}; \ No newline at end of file diff --git a/api/blackberry_user_identity_blackberryprofile.js b/api/blackberry_user_identity_blackberryprofile.js new file mode 100644 index 0000000000..632bfbb9a4 --- /dev/null +++ b/api/blackberry_user_identity_blackberryprofile.js @@ -0,0 +1,131 @@ +/* +* Copyright 2013 Research In Motion Limited. +* +* 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. +*/ + +/** +* @toc {User Identity} User Identity - BlackBerry Profile +* @BB10X +* @namespace Use BlackBerry profile as an identity provider, and provide +* off-device data storage. +* +*

BBProfile_Provider BlackBerry profile +* BlackBerry profile is an identity provider that allows access to +* off-device, encrypted storage space. The storage space is bound to the +* BlackBerry ID user that is currently logged in. The storage is accessible +* remotely from all devices logged in with the same BlackBerry ID user, +* allowing applications installed on multiple devices access to the same +* information. +* +* +*

User Identity API support


+* +*

BlackBerry profile supports the following Identity Service functions. Using +* BlackBerry profile with other functions will result in errors.
+* - createData()
+* - getData()
+* - setData()
+* - deleteData()
+* - listData()
+* - registerNotifier() +* +* +*

Off-device data storage and retrieval APIs


+* +*

Applications can use the APIs to securely store data in, and retrieve data +* from, the BlackBerry ecosystem. APIs are provided for storing data initially +* (createData()), retrieving the data (getData()), updating the data +* (setData()), and removing the data (deleteData()). +* +* +*

Permissions


+* +*

In order to store and retrieve data off of the device, wireless data is +* consumed. Applications using storage from BlackBerry profile must have +* the access_internet permission included in their bar descriptor file. +* +*

Limits to storage capacity


+* +*

There's a limit to the amount of off-device storage that is available to +* each of your users. Storage limits are set according to user and app +* vendor, and apply to all of the apps that a user might have with a +* single vendor. For example, if you have multiple apps that require +* off-device storage, and you have a user who makes use of three of those +* apps, that user's storage limit applies to the total amount of storage +* space that those three apps require. Users can have multiple storage +* allocations, one for each app vendor. +* +* +*

Caching


+* +*

In cases where the application may need data stored locally for quick or +* repeated access, the value can be cached securely on the device and +* retrieved on demand, even when not connected to the remote storage copy. +* The cache is synchronized with the remote copy so that the cache is always +* up to date while the device has appropriate data coverage. +* +* +*

Using profile storage


+* +*

Create - Store a new entry
+* Call createData() to store new profile entries.
+* - type is one of the "profile types".
+* - flags are one of CREATE_DATA_ constants.
+* +*

Set - Update an entry
+* Call setData() to update profile entries.
+* - type is one of the "profile types".
+* - flags are one of SET_DATA_ constants.
+* +*

Get - Retrieve an entry
+* Call getData() to retrieve profile entries.
+* - type is one of the "profile types".
+* - flags are one of GET_DATA_ constants.
+* +*

Delete - Remove an entry
+* Call deleteData() to remove profile entries.
+* - type is one of the "profile types".
+* - flags are one of DELETE_DATA_ constants.
+* +*

Get - List available entries
+* Call listData() to list profile entries.
+* - type is one of the "profile types".
+* - flags are one of LIST_DATA_ constants.
+* +* +*

Notifications


+* +*

Notifications can be registered for entries either before or after they have +* been created. In cases where the registration is done after creation, the +* application is notified each time the value changes so that it can +* perform any necessary operations. If registration is done before an entry +* is created, the application is notified upon creation of the value as +* if it were an update. Additionally, registered applications receive a +* change notification when an entry is deleted. +* +*

To register for profile entry change notifications, call +* registerNotifier().
+* - type is one of the "profile types".
+* - flags are one of NOTIFY_ constants.
+* +*

Each time a registered entry changes, the registered callback function is +* executed and the corresponding NOTIFICATION_ indicates the kind of change +* that occurred. +* +* @featureID blackberry.user.identity +* @permission access_internet Permits your app to use the internet to access user data +* in remote storage. +*/ +blackberry.user.identity.blackberryprofile = { +}; \ No newline at end of file From 3cbd40041684fe67670161e5d587d6beb3ed845f Mon Sep 17 00:00:00 2001 From: efeener Date: Wed, 10 Jul 2013 13:22:08 -0400 Subject: [PATCH 08/11] Adding Type to challenge() --- api/blackberry_user_identity.js | 1225 ++++++++++++++++--------------- 1 file changed, 614 insertions(+), 611 deletions(-) diff --git a/api/blackberry_user_identity.js b/api/blackberry_user_identity.js index 6d95dfc9f7..9a6107bd04 100644 --- a/api/blackberry_user_identity.js +++ b/api/blackberry_user_identity.js @@ -1,612 +1,615 @@ -/* -* Copyright 2013 Research In Motion Limited. -* -* 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. -*/ - -/** -* @toc {User Identity} User Identity -* @BB10X -* @namespace Identity Service library SDK - The Identity Service library offers -* a framework for data storage and retrieval, access to the user's personal -* information stored in the Identity Provider's account system, and user -* authentication/authorization to access the Identity Provider's apps and -* services. - -* -*

Identity Service library


-* -*

Developers can make use of the Identity Service library APIs to enhance their app in several ways: -* - Data storage and retrieval -* - User authentication and authorization to access apps and off-device services offered by the Identity Provider (without prompting for credentials) -* - Access to the user's personal information stored in the Identity Provider's account system -* -*

These capabilities are described further in the sections below, and the specific implementation will vary for each Identity Provider. For example, the data storage and retrieval APIs might -* provide off-device data storage, or on-device data storage - that could differ between one Identity Provider and another. Similarly, the personal information that can be retrieved with the -* getProperties() API call will differ based on what information each Identity Provider stores in their account system. -* -*

As such, this document gives an overview of the Identity Service library APIs that are available, and this information must be used in conjunction with the Identity Provider's specific Identity -* Service API overview to confirm the specifics of their implementation of each of these APIs. -* -*

DataStorage_section Data storage and retrieval APIs -* -*

Applications can make use of APIs in the IDS library to store and retrieve data. -*

APIs are provided for: -* - initial storage of the data (createData()) -* - retrieving the data (getData()) -* - updating the data (setData()) -* - removing the data (deleteData()) -* - listing the stored data (istData()) - -*

UserAuth_Section User authentication without prompting for credentials -* -*

Developers can use the Identity Services user authentication APIs in this library to avoid the need to implement user name and password management for their app. With these APIs, once the user is signed in using their account with the Identity Provider on the device, the user is automatically signed in to the app as well. -* - Users won't need to create or remember a username and password for the app. -* - Users won't need to specifically log in to the app, thus improving the ease of use of the app. -* -* -*

OffDeviceAuth_Section User authorization to access apps and off-device services offered by the Identity Provider -* -*

If your app interacts with an off-device service that requires user authentication (for example, a web site that requires the user to sign in with a username and password), -* you can use the Identity Service APIs to perform the off-device authentication/authorization using tokens, instead of prompting the user for credentials. Your app and the off-device service interact seamlessly. -* -* -*

PII_Section Access to the user's personal information associated with their account -* -*

The user's personal information that is available to the app will depend on what information is available from the Identity Provider's account system. -* -*

For example, if the app uses BlackBerry ID as the Identity Provider, the app can access the following personal information (provided that the user gives the app their consent): -* - first name -* - last name -* - screen name -* - username -* -*

For other Identity Providers, the personal information available will depend on what that provider stores in their identity account system. -* -*

ids_callback_sec About Callback functions -* -*

Many of the IDS APIs have the following three parameters: -* - Success callback function -* - Failure callback function -* -*

When your app sends API calls using the IDS APIs, the Identity Provider -* service responds asynchronously. When an app receives a response, the -* corresponding callback function that your application had provided for the -* success or failure case is executed. -* -*

The Identity Provider service uses callback functions to pass the parsed response -* back to your app. Callback functions cannot be NULL. Your app must specify what -* to do in both the success and failure scenarios. -* -* -*

bbid_modes_sec Registering your app to use the IDS APIs -* -*

To register your app so that it can use the IDS APIs, call -* registerProvider() from your app for at least one identity provider. -* -*

After your app sends a request, the Identity Provider service will process the -* request asynchronously, and call the corresponding success/failure callback function. -* -*

For example, your app can call getProperties() and pass a success -* callback of myAppSuccessCallback and a failure callback of -* myAppFailureCallback. When a response is ready from the identity provider, the -* success or failure callback will execute based on the results of the call. -* -* -* -* @featureID blackberry.user.identity -* @permission read_personally_identifiable_information Permits your app to access user -* identity information including the ability to store secondary user properties. -* @permission access_internet Permits your app to use the internet to access user data -* in remote storage. -*/ - -blackberry.user.identity = { - -/** - * The getVersion() function retrieves the version of the IDS library - * that your application is using. - * @BB10X - * @returns {int} - * "1000000" - * @example -* <script type="text/javascript"> -* alert("Identity Service version is:" + blackberry.user.identity.getVersion()); -* </script> */ -getVersion : function(){}, - -/** - * Applications use this function to register which Identity Provider(s) that - * they want to use. Once the application has initialized the library, it can - * register for each of the identity providers it is interested in. - * @param {String} name The name of the identity provider that the application wants to - * use for retrieving user identity information (only BlackBerry ID is supported - * at this time). - * @returns {int} result - * @BB10X - * @example - * <script type="text/javascript"> - var registerResult = blackberry.user.identity.registerProvider("ids:rim:bbid"); - if( registerResult.errorDescription ) { - alert("IDS register provider error: " + registerResult.result + " with description: " + registerResult.errorDescription); - } - * </script> -*/ -registerProvider : function(name) { }, - - -/** - * Configure an option in the Identity Services library. These options allow an - * application to modify the default behavior of the IDS library as well as - * configure the way the library and application integrate together. - *

Available options are: - *

Set GUI Allowed (option = 0, value = true/false) - *

Option to set whether or not GUI allowed flag is set. Value is "true" or - * "false". By default, in cases where user input is required, the Identity - * Service performs the user interaction on behalf of the calling - * application. If this has been set to false, and user input is required, - * the API will return an error. If no user interaction is required to - * complete the API, this setting has no effect. - *

Set Group ID (option = 1, value = groupId) - *

Set the group ID of the calling application for UI dialogs. String - * version of UI group id. This is required in cases where the Identity - * Service requires user input from the user and must open an interface in - * the context of the calling application. - *

Set Verbosity (option = 2, value = {"Silent", "Normal", "Verbose") - *

Set the library logging verbosity level. Useful during application - * development to allow developers to be able to increase logging for - * diagnostics. Note that IDS logs are generated on stderr, and so should be - * captured in the application's log file. - * @param {int} option The option to be modified. - * @param {String} value The new string value to set - * @returns {int} - * @BB10X - * @example - * <script type="text/javascript"> - var setOptionResult = blackberry.user.identity.setOption(0, true); - if( setOptionResult.errorDescription ) { - alert("IDS set option error: " + setOptionResult.result + " with description: " + setOptionResult.errorDescription); - } - * </script> - */ -setOption : function(option, value) { }, - -/** - * Issue a get token request. - * - * @param {String} provider The identity provider to send this request to. - * @param {String} tokenType A token type. It must be NOT NULL - * and 32 characters >= tokenType > 0 character - * @param {String} appliesTo The application or service to which the token applies. It - * must be NOT NULL and 96 characters >= applies_to > 0 character - * @callback {Function} successCallback Function which is invoked upon successful operation of this - * method. - * @callback {JSON} successCallback.tokenResult A JSON object containing a token and it's information in the form below: - * 

{
-     * "token": "ghdaj23i8rghaepeghk;a",
-	 * "params": ["name":"TOKEN_SECRET","value":"oguireqhge"]
-     * }
- * @callback {Function} failureCallback Function which is invoked when this method fails. This - * callback contains an errorCode parameter to specify the failure condition. - * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: - *
{
-	* "result":"50009",
-	* "errorDescription":"The appliesTo value is not valid"
-	* }
- * - *

Error Handling:
- * Requests that do not complete successfully will result in the failure - * callback being called with one of the following result codes: - *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process - * the request. - *

- IDS_UNKNOWN_APPLIES_TO: The appliesTo value is not valid. - *

- IDS_UNKNOWN_TOKEN_TYPE: The tokenType value is not valid. - *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to - * process the request. - *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token - * access is unavailable while locked. - *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be - * authenticated. - *

- IDS_CANNOT_GET_TOKEN_WHILE_OFFLINE: The service is currently offline - * and cannot retrieve the requested token. - *

- IDS_ERROR_WHILE_CONTACTING_SERVICE: An error occurred communicating - * with the service. - * @returns {void} - * @BB10X - * @example - * <script type="text/javascript"> - function getTokenSuccess(tokenResult) { - alert("Received token: " + tokenResult.token); - for( param in tokenResult.tokenParams ) { - alert("Token param: " + tokenResult.tokenParams[param].name + " and value: " + tokenResult.tokenParams[param].value); - } - } - - function getTokenFailure(result) { - alert("Failed to retrieve token - result is: " + result.result + " with description: " + result.errorDescription); - } - - blackberry.user.identity.registerProvider("ids:rim:bbid"); - blackberry.user.identity.getToken("ids:rim:bbid", "MyTokenType", "urn:token:myapplication", getTokenSuccess, getTokenFailure); - * </script> -*/ -getToken : function(idsProvider, tokenType, appliesTo, successCallback, failureCallback) { }, - -/** - * Issue a clear token request. In cases where the token seems to be invalid or - * too close to expiry to be deemed useful, an application can clear out the - * currently cached token in order to retrieve a newly generated token in the - * next getToken() call. - * - * @param {String} provider The identity provider to send this request to. - * @param {String} tokenType A token type. It must be NOT NULL - * and 32 characters >= tokenType > 0 character - * @param {String} appliesTo The application or service to which the token applies. It - * must be NOT NULL and 96 characters >= applies_to > 0 character - * @callback {Function} successCallback Function which is invoked upon successful operation of this - * method. - * @callback {JSON} successCallback.result A JSON object containing the in the form below: - * 

{
-     * "result": true
-     * }
- * @callback {Function} failureCallback Function which is invoked when this method fails. This - * callback contains an errorCode parameter to specify the failure condition. - * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: - *
{
-	* "result":"50009",
-	* "errorDescription":"The appliesTo value is not valid"
-	* }
- * - *

Error Handling:
- * Requests that do not complete successfully will result in the failure - * callback being called with one of the following result codes: - *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process - * the request. - *

- IDS_UNKNOWN_APPLIES_TO: The @c applies_to value is not valid. - *

- IDS_UNKNOWN_TOKEN_TYPE: The @c token_type value is not valid. - *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to - * process the request. - *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token - * access is unavailable while locked. - *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be - * authenticated. - * @returns {void} - * @BB10X - * @example - * <script type="text/javascript"> - function clearTokenSuccess(clearTokenResult) { - alert("Token cleared: " + clearTokenResult.cleared); - } - - function clearTokenFailure(result) { - alert("Failed to clear token - result is: " + result.result + " with description: " + result.errorDescription); - } - - blackberry.user.identity.registerProvider("ids:rim:bbid"); - blackberry.user.identity.clearToken("ids:rim:bbid", "MyTokenType", "urn:token:myapplication", clearTokenSuccess, clearTokenFailure); - * </script> -*/ -clearToken : function(idsProvider, tokenType, appliesTo, successCallback, failureCallback) { }, - -/** - * Issue a request for a property. - * - * @param {String} provider The identity provider to send this request to. - * @param type The type of properties contained in the @c propertyList - * parameter. Each provider may have a unique set of types that it is able to - * handle. See the documentation for the provider for details on valid values. - * @param {String} propertyList A comma separated string listing each of the properties - * requested - * @callback {Function} successCallback Function which is invoked upon successful operation of this - * method. - * @callback {JSON} successCallback.result A JSON object containing the in the form below: - * 

{[
- * 		{"uri":"urn:bbid:firstname":"value":"john"},
-		{"uri":"urn:bbid:lastname":"value":"doe"}
-     * }
- * @callback {Function} failureCallback Function which is invoked when this method fails. This - * callback contains an errorCode parameter to specify the failure condition. - * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: - *
{
-	* "result":"50004",
-	* "errorDescription":"The user could not be authenticated."
-	* }
- *

Error Handling:
- * Requests that do not complete successfully will result in the failure - * callback being called with one of the following result codes: - *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process - * the request. - *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to - * process the request. - *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token - * access is unavailable while locked. - *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be - * authenticated. - *

- IDS_TOO_MANY_NAMES_PASSED: Too many properties were requested. See - * IDS_MAX_PROPERTY_COUNT. - *

- IDS_NAME_TOO_LONG: The length of a property name in the list exceeds - * the maximum name length IDS_MAX_PROPERTY_NAME_LEN. - *

- IDS_PROPERTY_NOT_AUTHORIZED: The application does not have access to - * one of the requested properties. - *

- IDS_PROPERTY_DOES_NOT_EXIST: Property does not exist. - *

- IDS_BAD_PROPERTY_NAME: Invalid property name. - *

- IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter. - *

- IDS_NON_EXISTING_PROPERTY: Property does not exist. - *

- IDS_PROFILE_SERVER_ERROR: Server error. - *

- IDS_PROPERTY_VALUE_TOO_LARGE: Property value is too large. - *

- IDS_GET_FAIL: Get failed. - * - * @returns {void} - * @BB10X - * @example - * <script type="text/javascript"> - function getPropertiesSuccess(properties) { - alert("Get properties returned the following user properties:"); - for( prop in properties ) { - alert("Property: " + properties[prop].uri + " value: " + properties[prop].value); - } - } - - function getPropertiesFailure(result) { - alert("Failed to retrieve user properties: " + result.result + " details: " + result.failureInfo); - } - - blackberry.user.identity.registerProvider("ids:rim:bbid"); - blackberry.user.identity.getProperties("ids:rim:bbid", 0, "urn:bbid:firstname,urn:bbid:lastname", getPropertiesSuccess, getPropertiesFailure); - * </script> -*/ -getProperties : function(idsProvider, 0, userProperties, successCallback, failureCallback) { }; - -/** - * Issue a request to set data - * - * @param {String} provider The identity provider to send this request to. - * @param {int} type The type of data. Each provider may have a unique set of types that it is able to - * handle. See the documentation for the provider for details on valid values. - * @param flags Special flags for the operation. Each provider may have a unique - * set of flags that it supports. See the documentation for the provider for - * details on valid values and their behaviour for this operation. - * @param {String} dataName The data identifier - * @param {String} dataValue The content of the data - * @callback {Function} successCallback Function which is invoked upon successful operation of this - * method. - * @callback {Function} failureCallback Function which is invoked when this method fails. This - * callback contains an errorCode parameter to specify the failure condition. - * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: - *

{
-	* "result":"50004",
-	* "errorDescription":"The user could not be authenticated."
-	* }
- *

Error Handling:
- * Requests that do not complete successfully will result in the failure - * callback being called with one of the following result codes: - *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process - * the request. - *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to - * process the request. - *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token - * access is unavailable while locked. - *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be - * authenticated. - *

- IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter. - *

- IDS_DOES_NOT_EXIST: Entry with the given name does not exist. - *

- IDS_NOT_ALLOWED: Application is not allowed to perform this operation. - *

- IDS_ERROR_WHILE_CONTACTING_SERVICE: The provider was unable to - * communicate with it's service to perform operation. - *

- USER_RESOURCE_NAME_TOO_LONG: The name is longer than the maximum length - * allowed by the provider - * @returns {void} - * @BB10X - * @example - * <script type="text/javascript"> - function setDataSuccess() { - alert("Set property was successful"); - } - - function setDataFailure(result) { - alert("Failed to set data: " + result.result + " details: " + result.failureInfo); - } - - blackberry.user.identity.registerProvider("ids:rim:profile"); - blackberry.user.identity.setData("ids:rim:profile", 1, "usershandle", "johndoe123", setDataSuccess, setDataFailure); - * </script> -*/ -setData : function(idsProvider, 0, 0, dataName, dataValue, successCallback, failureCallback) { }; - -/** - * Issue a request to create data - * - * @param {String} provider The identity provider to send this request to. - * @param {int} type The type of data. Each provider may have a unique set of types that it is able to - * handle. See the documentation for the provider for details on valid values. - * @param flags Special flags for the operation. Each provider may have a unique - * set of flags that it supports. See the documentation for the provider for - * details on valid values and their behaviour for this operation. - * - * @param {String} dataName The property identifier - * @param {String} dataValue The content of the property - * @callback {Function} successCallback Function which is invoked upon successful operation of this - * method. - * @callback {Function} failureCallback Function which is invoked when this method fails. This - * callback contains an errorCode parameter to specify the failure condition. - * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: - *

{
-	* "result":"50004",
-	* "errorDescription":"The user could not be authenticated."
-	* }
- *

Error Handling:
- * Requests that do not complete successfully will result in the failure - * callback being called with one of the following result codes: - *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process - * the request. - *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to - * process the request. - *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token - * access is unavailable while locked. - *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be - * authenticated. - *

- IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter. - *

- IDS_ERROR_WHILE_CONTACTING_SERVICE: The provider was unable to - * communicate with it's service to perform operation. - *

- IDS_ALREADY_EXISTS: Entry with name already exists. - *

- IDS_NOT_ALLOWED: Application is not allowed to perform this operation. - *

- USER_RESOURCE_NAME_TOO_LONG: The name is longer than the maximum length - * allowed by the provider - * - * @returns {void} - * @BB10X - * @example - * <script type="text/javascript"> - function createDataSuccess() { - alert("Create Data was successful"); - } - - function createDataFailure(result) { - alert("Failed to create data: " + result.result + " details: " + result.failureInfo); - } - - blackberry.user.identity.registerProvider("ids:rim:profile"); - blackberry.user.identity.createData("ids:rim:profile", 1, "usershandle", "johndoe123", createDataSuccess, createDataFailure); - * </script> -*/ -createData : function(idsProvider, 0, 0, dataName, dataValue, successCallback, failureCallback) { }; - -/** - * Issue a request to data - * - * @param {String} provider The identity provider to send this request to. - * @param {int} type The type of data.Each provider may have a unique set of types that it is able to - * handle. See the documentation for the provider for details on valid values. - * @param flags Special flags for the operation. Each provider may have a unique - * set of flags that it supports. See the documentation for the provider for - * details on valid values and their behaviour for this operation. - * @param {String} dataName The property identifier - * @callback {Function} successCallback Function which is invoked upon successful operation of this - * method. - * @callback {Function} failureCallback Function which is invoked when this method fails. This - * callback contains an errorCode parameter to specify the failure condition. - * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: - *

{
-	* "result":"50004",
-	* "errorDescription":"The user could not be authenticated."
-	* }
- *

Error Handling:
- * Requests that do not complete successfully will result in the failure - * callback being called with one of the following result codes: - *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process - * the request. - *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to - * process the request. - *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, - * access is unavailable while locked. - *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be - * authenticated. - *

- IDS_NOT_ALLOWED: The application does not have access to delete - * the requested value. - *

- IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter. - *

- IDS_DOES_NOT_EXIST: Name specified does not exist. - *

- IDS_ERROR_WHILE_CONTACTING_SERVICE: The provider was unable to - * communicate with it's service to perform operation. - *

- USER_RESOURCE_NAME_TOO_LONG: The name is longer than the maximum length - * allowed by the provider - * @returns {void} - * @BB10X - * @example - * <script type="text/javascript"> - function deleteDataSuccess() { - alert("Delete data was successful"); - } - - function deleteDataFailure(result) { - alert("Failed to delete data: " + result.result + " details: " + result.failureInfo); - } - - blackberry.user.identity.registerProvider("ids:rim:profile"); - blackberry.user.identity.deleteData("ids:rim:profile", 1, 0, "usershandle", deleteDataSuccess, deleteDataFailure); - * </script> -*/ -deleteData : function(idsProvider, 0, 0, dataName, successCallback, failureCallback) { }; - - -/** - * Issue a request to challenge for identity - * - * @param {String} provider The identity provider to send this request to. - * @param flags Special flags for the operation. Each provider may have a unique - * set of flags that it supports. See the documentation for the provider for - * details on valid values and their behaviour for this operation. - * @callback {Function} successCallback Function which is invoked upon successful operation of this - * method. - * @callback {Function} failureCallback Function which is invoked when this method fails. This - * callback contains an errorCode parameter to specify the failure condition. - * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: - *

{
-	* "result":"50004",
-	* "errorDescription":"The user could not be authenticated."
-	* }
- *

Error Handling:
- * Requests that do not complete successfully will result in the failure - * callback being called with one of the following result codes: - * - @c IDS_DEFAULT_ERROR: An internal error has occurred attempting to process - * the request. - * - @c IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to - * process the request. - * - @c IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, - * access is unavailable while locked. - * - @c IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be - * authenticated. - * @returns {void} - * @BB10X - * @example - * <script type="text/javascript"> - function challengeSuccess(level) { - alert("Challenge was successful: " + level); - } - - function challengeFailure(result) { - alert("Challenge failed: " + result.result + " details: " + result.failureInfo); - } - - blackberry.user.identity.registerProvider("ids:rim:bbid"); - blackberry.user.identity.challenge("ids:rim:bbid", 0, challengeSuccess, challengeFailure); - * </script> -*/ -challenge : function(idsProvider, 0, successCallback, failureCallback) { }; - - -/** - * Register a callback function to be called when the named entry - * changes - * @param {String} provider The identity provider to send this request to. - * @param type The type of data referred to by name. - * @param flags Special flags for the operation. Each provider may have a unique - * set of flags that it supports. See the documentation for the provider for - * details on valid values and their behaviour for this operation. - * @param name The name of the entry to receive notifications for. - * @callback {Function} onChangeCallback The function that is invoked when a change is detected. - * @returns {void} - * @BB10X - * @example - * <script type="text/javascript"> - function onChangeCb(type, name, notification) { - alert("Notification received: " + name + " with notification: " + notification); - } - - blackberry.user.identity.registerProvider("ids:rim:bbid"); - blackberry.user.identity.registerNotifier("ids:rim:bbid", 0, propertyName, onChangeCb); - * </script> -*/ -registerNotifier : function(idsProvider, 0, name, onChangeCallback) { }; - - +/* +* Copyright 2013 Research In Motion Limited. +* +* 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. +*/ + +/** +* @toc {User Identity} User Identity +* @BB10X +* @namespace Identity Service library SDK - The Identity Service library offers +* a framework for data storage and retrieval, access to the user's personal +* information stored in the Identity Provider's account system, and user +* authentication/authorization to access the Identity Provider's apps and +* services. + +* +*

Identity Service library


+* +*

Developers can make use of the Identity Service library APIs to enhance their app in several ways: +* - Data storage and retrieval +* - User authentication and authorization to access apps and off-device services offered by the Identity Provider (without prompting for credentials) +* - Access to the user's personal information stored in the Identity Provider's account system +* +*

These capabilities are described further in the sections below, and the specific implementation will vary for each Identity Provider. For example, the data storage and retrieval APIs might +* provide off-device data storage, or on-device data storage - that could differ between one Identity Provider and another. Similarly, the personal information that can be retrieved with the +* getProperties() API call will differ based on what information each Identity Provider stores in their account system. +* +*

As such, this document gives an overview of the Identity Service library APIs that are available, and this information must be used in conjunction with the Identity Provider's specific Identity +* Service API overview to confirm the specifics of their implementation of each of these APIs. +* +*

DataStorage_section Data storage and retrieval APIs +* +*

Applications can make use of APIs in the IDS library to store and retrieve data. +*

APIs are provided for: +* - initial storage of the data (createData()) +* - retrieving the data (getData()) +* - updating the data (setData()) +* - removing the data (deleteData()) +* - listing the stored data (istData()) + +*

UserAuth_Section User authentication without prompting for credentials +* +*

Developers can use the Identity Services user authentication APIs in this library to avoid the need to implement user name and password management for their app. With these APIs, once the user is signed in using their account with the Identity Provider on the device, the user is automatically signed in to the app as well. +* - Users won't need to create or remember a username and password for the app. +* - Users won't need to specifically log in to the app, thus improving the ease of use of the app. +* +* +*

OffDeviceAuth_Section User authorization to access apps and off-device services offered by the Identity Provider +* +*

If your app interacts with an off-device service that requires user authentication (for example, a web site that requires the user to sign in with a username and password), +* you can use the Identity Service APIs to perform the off-device authentication/authorization using tokens, instead of prompting the user for credentials. Your app and the off-device service interact seamlessly. +* +* +*

PII_Section Access to the user's personal information associated with their account +* +*

The user's personal information that is available to the app will depend on what information is available from the Identity Provider's account system. +* +*

For example, if the app uses BlackBerry ID as the Identity Provider, the app can access the following personal information (provided that the user gives the app their consent): +* - first name +* - last name +* - screen name +* - username +* +*

For other Identity Providers, the personal information available will depend on what that provider stores in their identity account system. +* +*

ids_callback_sec About Callback functions +* +*

Many of the IDS APIs have the following three parameters: +* - Success callback function +* - Failure callback function +* +*

When your app sends API calls using the IDS APIs, the Identity Provider +* service responds asynchronously. When an app receives a response, the +* corresponding callback function that your application had provided for the +* success or failure case is executed. +* +*

The Identity Provider service uses callback functions to pass the parsed response +* back to your app. Callback functions cannot be NULL. Your app must specify what +* to do in both the success and failure scenarios. +* +* +*

bbid_modes_sec Registering your app to use the IDS APIs +* +*

To register your app so that it can use the IDS APIs, call +* registerProvider() from your app for at least one identity provider. +* +*

After your app sends a request, the Identity Provider service will process the +* request asynchronously, and call the corresponding success/failure callback function. +* +*

For example, your app can call getProperties() and pass a success +* callback of myAppSuccessCallback and a failure callback of +* myAppFailureCallback. When a response is ready from the identity provider, the +* success or failure callback will execute based on the results of the call. +* +* +* +* @featureID blackberry.user.identity +* @permission read_personally_identifiable_information Permits your app to access user +* identity information including the ability to store secondary user properties. +* @permission access_internet Permits your app to use the internet to access user data +* in remote storage. +*/ + +blackberry.user.identity = { + +/** + * The getVersion() function retrieves the version of the IDS library + * that your application is using. + * @BB10X + * @returns {int} + * "1000000" + * @example +* <script type="text/javascript"> +* alert("Identity Service version is:" + blackberry.user.identity.getVersion()); +* </script> */ +getVersion : function(){}, + +/** + * Applications use this function to register which Identity Provider(s) that + * they want to use. Once the application has initialized the library, it can + * register for each of the identity providers it is interested in. + * @param {String} name The name of the identity provider that the application wants to + * use for retrieving user identity information (only BlackBerry ID is supported + * at this time). + * @returns {int} result + * @BB10X + * @example + * <script type="text/javascript"> + var registerResult = blackberry.user.identity.registerProvider("ids:rim:bbid"); + if( registerResult.errorDescription ) { + alert("IDS register provider error: " + registerResult.result + " with description: " + registerResult.errorDescription); + } + * </script> +*/ +registerProvider : function(name) { }, + + +/** + * Configure an option in the Identity Services library. These options allow an + * application to modify the default behavior of the IDS library as well as + * configure the way the library and application integrate together. + *

Available options are: + *

Set GUI Allowed (option = 0, value = true/false) + *

Option to set whether or not GUI allowed flag is set. Value is "true" or + * "false". By default, in cases where user input is required, the Identity + * Service performs the user interaction on behalf of the calling + * application. If this has been set to false, and user input is required, + * the API will return an error. If no user interaction is required to + * complete the API, this setting has no effect. + *

Set Group ID (option = 1, value = groupId) + *

Set the group ID of the calling application for UI dialogs. String + * version of UI group id. This is required in cases where the Identity + * Service requires user input from the user and must open an interface in + * the context of the calling application. + *

Set Verbosity (option = 2, value = {"Silent", "Normal", "Verbose") + *

Set the library logging verbosity level. Useful during application + * development to allow developers to be able to increase logging for + * diagnostics. Note that IDS logs are generated on stderr, and so should be + * captured in the application's log file. + * @param {int} option The option to be modified. + * @param {String} value The new string value to set + * @returns {int} + * @BB10X + * @example + * <script type="text/javascript"> + var setOptionResult = blackberry.user.identity.setOption(0, true); + if( setOptionResult.errorDescription ) { + alert("IDS set option error: " + setOptionResult.result + " with description: " + setOptionResult.errorDescription); + } + * </script> + */ +setOption : function(option, value) { }, + +/** + * Issue a get token request. + * + * @param {String} provider The identity provider to send this request to. + * @param {String} tokenType A token type. It must be NOT NULL + * and 32 characters >= tokenType > 0 character + * @param {String} appliesTo The application or service to which the token applies. It + * must be NOT NULL and 96 characters >= applies_to > 0 character + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {JSON} successCallback.tokenResult A JSON object containing a token and it's information in the form below: + * 

{
+     * "token": "ghdaj23i8rghaepeghk;a",
+	 * "params": ["name":"TOKEN_SECRET","value":"oguireqhge"]
+     * }
+ * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *
{
+	* "result":"50009",
+	* "errorDescription":"The appliesTo value is not valid"
+	* }
+ * + *

Error Handling:
+ * Requests that do not complete successfully will result in the failure + * callback being called with one of the following result codes: + *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process + * the request. + *

- IDS_UNKNOWN_APPLIES_TO: The appliesTo value is not valid. + *

- IDS_UNKNOWN_TOKEN_TYPE: The tokenType value is not valid. + *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to + * process the request. + *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token + * access is unavailable while locked. + *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + *

- IDS_CANNOT_GET_TOKEN_WHILE_OFFLINE: The service is currently offline + * and cannot retrieve the requested token. + *

- IDS_ERROR_WHILE_CONTACTING_SERVICE: An error occurred communicating + * with the service. + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function getTokenSuccess(tokenResult) { + alert("Received token: " + tokenResult.token); + for( param in tokenResult.tokenParams ) { + alert("Token param: " + tokenResult.tokenParams[param].name + " and value: " + tokenResult.tokenParams[param].value); + } + } + + function getTokenFailure(result) { + alert("Failed to retrieve token - result is: " + result.result + " with description: " + result.errorDescription); + } + + blackberry.user.identity.registerProvider("ids:rim:bbid"); + blackberry.user.identity.getToken("ids:rim:bbid", "MyTokenType", "urn:token:myapplication", getTokenSuccess, getTokenFailure); + * </script> +*/ +getToken : function(idsProvider, tokenType, appliesTo, successCallback, failureCallback) { }, + +/** + * Issue a clear token request. In cases where the token seems to be invalid or + * too close to expiry to be deemed useful, an application can clear out the + * currently cached token in order to retrieve a newly generated token in the + * next getToken() call. + * + * @param {String} provider The identity provider to send this request to. + * @param {String} tokenType A token type. It must be NOT NULL + * and 32 characters >= tokenType > 0 character + * @param {String} appliesTo The application or service to which the token applies. It + * must be NOT NULL and 96 characters >= applies_to > 0 character + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {JSON} successCallback.result A JSON object containing the in the form below: + * 

{
+     * "result": true
+     * }
+ * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *
{
+	* "result":"50009",
+	* "errorDescription":"The appliesTo value is not valid"
+	* }
+ * + *

Error Handling:
+ * Requests that do not complete successfully will result in the failure + * callback being called with one of the following result codes: + *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process + * the request. + *

- IDS_UNKNOWN_APPLIES_TO: The @c applies_to value is not valid. + *

- IDS_UNKNOWN_TOKEN_TYPE: The @c token_type value is not valid. + *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to + * process the request. + *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token + * access is unavailable while locked. + *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function clearTokenSuccess(clearTokenResult) { + alert("Token cleared: " + clearTokenResult.cleared); + } + + function clearTokenFailure(result) { + alert("Failed to clear token - result is: " + result.result + " with description: " + result.errorDescription); + } + + blackberry.user.identity.registerProvider("ids:rim:bbid"); + blackberry.user.identity.clearToken("ids:rim:bbid", "MyTokenType", "urn:token:myapplication", clearTokenSuccess, clearTokenFailure); + * </script> +*/ +clearToken : function(idsProvider, tokenType, appliesTo, successCallback, failureCallback) { }, + +/** + * Issue a request for a property. + * + * @param {String} provider The identity provider to send this request to. + * @param type The type of properties contained in the @c propertyList + * parameter. Each provider may have a unique set of types that it is able to + * handle. See the documentation for the provider for details on valid values. + * @param {String} propertyList A comma separated string listing each of the properties + * requested + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {JSON} successCallback.result A JSON object containing the in the form below: + * 

{[
+ * 		{"uri":"urn:bbid:firstname":"value":"john"},
+		{"uri":"urn:bbid:lastname":"value":"doe"}
+     * }
+ * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *
{
+	* "result":"50004",
+	* "errorDescription":"The user could not be authenticated."
+	* }
+ *

Error Handling:
+ * Requests that do not complete successfully will result in the failure + * callback being called with one of the following result codes: + *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process + * the request. + *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to + * process the request. + *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token + * access is unavailable while locked. + *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + *

- IDS_TOO_MANY_NAMES_PASSED: Too many properties were requested. See + * IDS_MAX_PROPERTY_COUNT. + *

- IDS_NAME_TOO_LONG: The length of a property name in the list exceeds + * the maximum name length IDS_MAX_PROPERTY_NAME_LEN. + *

- IDS_PROPERTY_NOT_AUTHORIZED: The application does not have access to + * one of the requested properties. + *

- IDS_PROPERTY_DOES_NOT_EXIST: Property does not exist. + *

- IDS_BAD_PROPERTY_NAME: Invalid property name. + *

- IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter. + *

- IDS_NON_EXISTING_PROPERTY: Property does not exist. + *

- IDS_PROFILE_SERVER_ERROR: Server error. + *

- IDS_PROPERTY_VALUE_TOO_LARGE: Property value is too large. + *

- IDS_GET_FAIL: Get failed. + * + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function getPropertiesSuccess(properties) { + alert("Get properties returned the following user properties:"); + for( prop in properties ) { + alert("Property: " + properties[prop].uri + " value: " + properties[prop].value); + } + } + + function getPropertiesFailure(result) { + alert("Failed to retrieve user properties: " + result.result + " details: " + result.failureInfo); + } + + blackberry.user.identity.registerProvider("ids:rim:bbid"); + blackberry.user.identity.getProperties("ids:rim:bbid", 0, "urn:bbid:firstname,urn:bbid:lastname", getPropertiesSuccess, getPropertiesFailure); + * </script> +*/ +getProperties : function(idsProvider, 0, userProperties, successCallback, failureCallback) { }; + +/** + * Issue a request to set data + * + * @param {String} provider The identity provider to send this request to. + * @param {int} type The type of data. Each provider may have a unique set of types that it is able to + * handle. See the documentation for the provider for details on valid values. + * @param flags Special flags for the operation. Each provider may have a unique + * set of flags that it supports. See the documentation for the provider for + * details on valid values and their behaviour for this operation. + * @param {String} dataName The data identifier + * @param {String} dataValue The content of the data + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *

{
+	* "result":"50004",
+	* "errorDescription":"The user could not be authenticated."
+	* }
+ *

Error Handling:
+ * Requests that do not complete successfully will result in the failure + * callback being called with one of the following result codes: + *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process + * the request. + *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to + * process the request. + *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token + * access is unavailable while locked. + *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + *

- IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter. + *

- IDS_DOES_NOT_EXIST: Entry with the given name does not exist. + *

- IDS_NOT_ALLOWED: Application is not allowed to perform this operation. + *

- IDS_ERROR_WHILE_CONTACTING_SERVICE: The provider was unable to + * communicate with it's service to perform operation. + *

- USER_RESOURCE_NAME_TOO_LONG: The name is longer than the maximum length + * allowed by the provider + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function setDataSuccess() { + alert("Set property was successful"); + } + + function setDataFailure(result) { + alert("Failed to set data: " + result.result + " details: " + result.failureInfo); + } + + blackberry.user.identity.registerProvider("ids:rim:profile"); + blackberry.user.identity.setData("ids:rim:profile", 1, "usershandle", "johndoe123", setDataSuccess, setDataFailure); + * </script> +*/ +setData : function(idsProvider, 0, 0, dataName, dataValue, successCallback, failureCallback) { }; + +/** + * Issue a request to create data + * + * @param {String} provider The identity provider to send this request to. + * @param {int} type The type of data. Each provider may have a unique set of types that it is able to + * handle. See the documentation for the provider for details on valid values. + * @param flags Special flags for the operation. Each provider may have a unique + * set of flags that it supports. See the documentation for the provider for + * details on valid values and their behaviour for this operation. + * + * @param {String} dataName The property identifier + * @param {String} dataValue The content of the property + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *

{
+	* "result":"50004",
+	* "errorDescription":"The user could not be authenticated."
+	* }
+ *

Error Handling:
+ * Requests that do not complete successfully will result in the failure + * callback being called with one of the following result codes: + *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process + * the request. + *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to + * process the request. + *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, token + * access is unavailable while locked. + *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + *

- IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter. + *

- IDS_ERROR_WHILE_CONTACTING_SERVICE: The provider was unable to + * communicate with it's service to perform operation. + *

- IDS_ALREADY_EXISTS: Entry with name already exists. + *

- IDS_NOT_ALLOWED: Application is not allowed to perform this operation. + *

- USER_RESOURCE_NAME_TOO_LONG: The name is longer than the maximum length + * allowed by the provider + * + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function createDataSuccess() { + alert("Create Data was successful"); + } + + function createDataFailure(result) { + alert("Failed to create data: " + result.result + " details: " + result.failureInfo); + } + + blackberry.user.identity.registerProvider("ids:rim:profile"); + blackberry.user.identity.createData("ids:rim:profile", 1, "usershandle", "johndoe123", createDataSuccess, createDataFailure); + * </script> +*/ +createData : function(idsProvider, 0, 0, dataName, dataValue, successCallback, failureCallback) { }; + +/** + * Issue a request to data + * + * @param {String} provider The identity provider to send this request to. + * @param {int} type The type of data.Each provider may have a unique set of types that it is able to + * handle. See the documentation for the provider for details on valid values. + * @param flags Special flags for the operation. Each provider may have a unique + * set of flags that it supports. See the documentation for the provider for + * details on valid values and their behaviour for this operation. + * @param {String} dataName The property identifier + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *

{
+	* "result":"50004",
+	* "errorDescription":"The user could not be authenticated."
+	* }
+ *

Error Handling:
+ * Requests that do not complete successfully will result in the failure + * callback being called with one of the following result codes: + *

- IDS_DEFAULT_ERROR: An internal error has occurred attempting to process + * the request. + *

- IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to + * process the request. + *

- IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, + * access is unavailable while locked. + *

- IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + *

- IDS_NOT_ALLOWED: The application does not have access to delete + * the requested value. + *

- IDS_NULL_OR_UNKNOWN_PARAMETERS: Null or invalid parameter. + *

- IDS_DOES_NOT_EXIST: Name specified does not exist. + *

- IDS_ERROR_WHILE_CONTACTING_SERVICE: The provider was unable to + * communicate with it's service to perform operation. + *

- USER_RESOURCE_NAME_TOO_LONG: The name is longer than the maximum length + * allowed by the provider + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function deleteDataSuccess() { + alert("Delete data was successful"); + } + + function deleteDataFailure(result) { + alert("Failed to delete data: " + result.result + " details: " + result.failureInfo); + } + + blackberry.user.identity.registerProvider("ids:rim:profile"); + blackberry.user.identity.deleteData("ids:rim:profile", 1, 0, "usershandle", deleteDataSuccess, deleteDataFailure); + * </script> +*/ +deleteData : function(idsProvider, 0, 0, dataName, successCallback, failureCallback) { }; + + +/** + * Issue a request to challenge for identity + * + * @param {String} provider The identity provider to send this request to. + * @param type The type of challenge requested. Each identity provider may + * have a unique set of types that it supports. See the identity provider's + * documentation for details on valid types and their behavior. + * @param flags Special flags for the operation. Each provider may have a unique + * set of flags that it supports. See the documentation for the provider for + * details on valid values and their behaviour for this operation. + * @callback {Function} successCallback Function which is invoked upon successful operation of this + * method. + * @callback {Function} failureCallback Function which is invoked when this method fails. This + * callback contains an errorCode parameter to specify the failure condition. + * @callback {JSON} failureCallback.result A JSON object containing details of the failure in the form below: + *

{
+	* "result":"50004",
+	* "errorDescription":"The user could not be authenticated."
+	* }
+ *

Error Handling:
+ * Requests that do not complete successfully will result in the failure + * callback being called with one of the following result codes: + * - @c IDS_DEFAULT_ERROR: An internal error has occurred attempting to process + * the request. + * - @c IDS_NOT_ENOUGH_RESOURCES: There are not enough resources available to + * process the request. + * - @c IDS_ACCOUNT_LOCALLY_LOCKED_OUT: The account is currently locked, + * access is unavailable while locked. + * - @c IDS_USER_COULD_NOT_BE_AUTHENTICATED: The user could not be + * authenticated. + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function challengeSuccess(level) { + alert("Challenge was successful: " + level); + } + + function challengeFailure(result) { + alert("Challenge failed: " + result.result + " details: " + result.failureInfo); + } + + blackberry.user.identity.registerProvider("ids:rim:bbid"); + blackberry.user.identity.challenge("ids:rim:bbid", 0, 0, challengeSuccess, challengeFailure); + * </script> +*/ +challenge : function(idsProvider, 0, 0, successCallback, failureCallback) { }; + + +/** + * Register a callback function to be called when the named entry + * changes + * @param {String} provider The identity provider to send this request to. + * @param type The type of data referred to by name. + * @param flags Special flags for the operation. Each provider may have a unique + * set of flags that it supports. See the documentation for the provider for + * details on valid values and their behaviour for this operation. + * @param name The name of the entry to receive notifications for. + * @callback {Function} onChangeCallback The function that is invoked when a change is detected. + * @returns {void} + * @BB10X + * @example + * <script type="text/javascript"> + function onChangeCb(type, name, notification) { + alert("Notification received: " + name + " with notification: " + notification); + } + + blackberry.user.identity.registerProvider("ids:rim:bbid"); + blackberry.user.identity.registerNotifier("ids:rim:bbid", 0, propertyName, onChangeCb); + * </script> +*/ +registerNotifier : function(idsProvider, 0, name, onChangeCallback) { }; + + }; \ No newline at end of file From 64a8746cc72d8f2069dd57d25a8c6c13023144b4 Mon Sep 17 00:00:00 2001 From: efeener Date: Wed, 10 Jul 2013 13:26:42 -0400 Subject: [PATCH 09/11] Updating missing param types --- api/blackberry_user_identity.js | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/api/blackberry_user_identity.js b/api/blackberry_user_identity.js index 9a6107bd04..f6ee9e97e9 100644 --- a/api/blackberry_user_identity.js +++ b/api/blackberry_user_identity.js @@ -302,7 +302,7 @@ clearToken : function(idsProvider, tokenType, appliesTo, successCallback, failur * Issue a request for a property. * * @param {String} provider The identity provider to send this request to. - * @param type The type of properties contained in the @c propertyList + * @param {int} type The type of properties contained in the @c propertyList * parameter. Each provider may have a unique set of types that it is able to * handle. See the documentation for the provider for details on valid values. * @param {String} propertyList A comma separated string listing each of the properties @@ -373,7 +373,7 @@ getProperties : function(idsProvider, 0, userProperties, successCallback, failur * @param {String} provider The identity provider to send this request to. * @param {int} type The type of data. Each provider may have a unique set of types that it is able to * handle. See the documentation for the provider for details on valid values. - * @param flags Special flags for the operation. Each provider may have a unique + * @param {int} flags Special flags for the operation. Each provider may have a unique * set of flags that it supports. See the documentation for the provider for * details on valid values and their behaviour for this operation. * @param {String} dataName The data identifier @@ -429,7 +429,7 @@ setData : function(idsProvider, 0, 0, dataName, dataValue, successCallback, fail * @param {String} provider The identity provider to send this request to. * @param {int} type The type of data. Each provider may have a unique set of types that it is able to * handle. See the documentation for the provider for details on valid values. - * @param flags Special flags for the operation. Each provider may have a unique + * @param {int} flags Special flags for the operation. Each provider may have a unique * set of flags that it supports. See the documentation for the provider for * details on valid values and their behaviour for this operation. * @@ -487,7 +487,7 @@ createData : function(idsProvider, 0, 0, dataName, dataValue, successCallback, f * @param {String} provider The identity provider to send this request to. * @param {int} type The type of data.Each provider may have a unique set of types that it is able to * handle. See the documentation for the provider for details on valid values. - * @param flags Special flags for the operation. Each provider may have a unique + * @param {int} flags Special flags for the operation. Each provider may have a unique * set of flags that it supports. See the documentation for the provider for * details on valid values and their behaviour for this operation. * @param {String} dataName The property identifier @@ -542,10 +542,10 @@ deleteData : function(idsProvider, 0, 0, dataName, successCallback, failureCallb * Issue a request to challenge for identity * * @param {String} provider The identity provider to send this request to. - * @param type The type of challenge requested. Each identity provider may + * @param {int} type The type of challenge requested. Each identity provider may * have a unique set of types that it supports. See the identity provider's * documentation for details on valid types and their behavior. - * @param flags Special flags for the operation. Each provider may have a unique + * @param {int}flags Special flags for the operation. Each provider may have a unique * set of flags that it supports. See the documentation for the provider for * details on valid values and their behaviour for this operation. * @callback {Function} successCallback Function which is invoked upon successful operation of this @@ -591,11 +591,11 @@ challenge : function(idsProvider, 0, 0, successCallback, failureCallback) { }; * Register a callback function to be called when the named entry * changes * @param {String} provider The identity provider to send this request to. - * @param type The type of data referred to by name. - * @param flags Special flags for the operation. Each provider may have a unique + * @param {int} type The type of data referred to by name. + * @param {int} flags Special flags for the operation. Each provider may have a unique * set of flags that it supports. See the documentation for the provider for * details on valid values and their behaviour for this operation. - * @param name The name of the entry to receive notifications for. + * @param {String} name The name of the entry to receive notifications for. * @callback {Function} onChangeCallback The function that is invoked when a change is detected. * @returns {void} * @BB10X From 01250ba5368b7a149b5d329e9f478c7e583ffbc7 Mon Sep 17 00:00:00 2001 From: efeener Date: Mon, 2 Dec 2013 12:55:42 -0500 Subject: [PATCH 10/11] Updating API docs based on BRWSR-14847 --- api/blackberry_user_identity.js | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/api/blackberry_user_identity.js b/api/blackberry_user_identity.js index f6ee9e97e9..471f329909 100644 --- a/api/blackberry_user_identity.js +++ b/api/blackberry_user_identity.js @@ -138,7 +138,7 @@ getVersion : function(){}, * <script type="text/javascript"> var registerResult = blackberry.user.identity.registerProvider("ids:rim:bbid"); if( registerResult.errorDescription ) { - alert("IDS register provider error: " + registerResult.result + " with description: " + registerResult.errorDescription); + alert("IDS register provider error: " + registerResult.result); } * </script> */ @@ -175,7 +175,7 @@ registerProvider : function(name) { }, * <script type="text/javascript"> var setOptionResult = blackberry.user.identity.setOption(0, true); if( setOptionResult.errorDescription ) { - alert("IDS set option error: " + setOptionResult.result + " with description: " + setOptionResult.errorDescription); + alert("IDS set option error: " + setOptionResult.result); } * </script> */ @@ -285,7 +285,7 @@ getToken : function(idsProvider, tokenType, appliesTo, successCallback, failureC * @example * <script type="text/javascript"> function clearTokenSuccess(clearTokenResult) { - alert("Token cleared: " + clearTokenResult.cleared); + alert("Token cleared: " + clearTokenResult.clear); } function clearTokenFailure(result) { @@ -476,7 +476,7 @@ setData : function(idsProvider, 0, 0, dataName, dataValue, successCallback, fail } blackberry.user.identity.registerProvider("ids:rim:profile"); - blackberry.user.identity.createData("ids:rim:profile", 1, "usershandle", "johndoe123", createDataSuccess, createDataFailure); + blackberry.user.identity.createData("ids:rim:profile", 1, 0, "usershandle", "johndoe123", createDataSuccess, createDataFailure); * </script> */ createData : function(idsProvider, 0, 0, dataName, dataValue, successCallback, failureCallback) { }; @@ -601,12 +601,12 @@ challenge : function(idsProvider, 0, 0, successCallback, failureCallback) { }; * @BB10X * @example * <script type="text/javascript"> - function onChangeCb(type, name, notification) { + function onChangeCb(tyfpe, name, notification) { alert("Notification received: " + name + " with notification: " + notification); } blackberry.user.identity.registerProvider("ids:rim:bbid"); - blackberry.user.identity.registerNotifier("ids:rim:bbid", 0, propertyName, onChangeCb); + blackberry.user.identity.registerNotifier("ids:rim:bbid", 0, "propertyName", onChangeCb); * </script> */ registerNotifier : function(idsProvider, 0, name, onChangeCallback) { }; From 5509d5d4af79bcad014530b143264699a9517d92 Mon Sep 17 00:00:00 2001 From: efeener Date: Tue, 7 Jan 2014 09:17:27 -0500 Subject: [PATCH 11/11] Updating docs - BRWSR-14847 --- api/blackberry_user_identity.js | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/api/blackberry_user_identity.js b/api/blackberry_user_identity.js index 471f329909..af201fe974 100644 --- a/api/blackberry_user_identity.js +++ b/api/blackberry_user_identity.js @@ -137,8 +137,8 @@ getVersion : function(){}, * @example * <script type="text/javascript"> var registerResult = blackberry.user.identity.registerProvider("ids:rim:bbid"); - if( registerResult.errorDescription ) { - alert("IDS register provider error: " + registerResult.result); + if( registerResult.result ) { + alert("IDS register provider error: " + registerResult.result + " errno: " + registerResult.errno); } * </script> */ @@ -174,8 +174,8 @@ registerProvider : function(name) { }, * @example * <script type="text/javascript"> var setOptionResult = blackberry.user.identity.setOption(0, true); - if( setOptionResult.errorDescription ) { - alert("IDS set option error: " + setOptionResult.result); + if( setOptionResult.result ) { + alert("IDS set option error: " + setOptionResult.result + " errno: " + setOptionResult.errno); } * </script> */ @@ -351,10 +351,7 @@ clearToken : function(idsProvider, tokenType, appliesTo, successCallback, failur * @example * <script type="text/javascript"> function getPropertiesSuccess(properties) { - alert("Get properties returned the following user properties:"); - for( prop in properties ) { - alert("Property: " + properties[prop].uri + " value: " + properties[prop].value); - } + alert("Get properties returned the following user properties:" + JSON.stringify(properties)); } function getPropertiesFailure(result) {