Identity services (ids.h)
The ids.h file includes functions and types for authenticating users to access off-device services.
Data storage and retrieval APIs
You can use the APIs in the IDS library to:
- store data initially (ids_create_data())
- retrieve data (ids_get_data())
- update data (ids_set_data())
- remove data (ids_delete_data())
- list stored data (ids_list_data())
User authentication without prompting for credentials
With the user authentication APIs in this library, you can avoid implementing username and password management in your app. After your user signs in with the identity provider on their device, that user is automatically signed in to your app as well. This eliminates the need for users to create and remember a username and password for your app, and it also reduces the number of times that users need to log in, providing a more fluid user experience.
User authorization for access to off-device services
If your app interacts with one of your identity provider's apps or off-device services, and that app or service requires user authentication, you can use the Identity Service APIs to perform that authentication. User authentication/authorization is done using tokens, and does not require user input. This allows your app and the off-device service to interact seamlessly.
Using personal information in your app
Users must first allow your app to access their information. If allowed access, you can integrate the personal information associated with your users' accounts in your app. The personal information that is available to your app depends on what information is available from your identity provider's account system.
For example, if your app uses BlackBerry ID as an identity provider, your app can access the following pieces of a user's personal information:
- first name
- last name
- screen name
Check with other identity providers to identify the personal information that they make available.
Many of the IDS APIs have the following three parameters:
- Success callback function
- Failure callback function
- Callback data (cb_data)
When your app sends API calls using the IDS APIs, the Identity Service responds asynchronously. When your app receives a response, the corresponding callback function that your app provided for the success or failure case is executed.
The Identity 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.
Your app sends callback data (cb_data) to the callback functions. The Identity Service does not process the cb_data in any way. The cb_data parameter is merely passed into the API from your app, and is passed along to the callback function. If your app doesn't need to pass information to the callback functions, you can set the cb_data parameter to NULL.
Registering your app to use the IDS APIs
To register your app so that it can use the IDS APIs, call ids_register_provider() from your app for at least one identity provider. Your app must then monitor the returned file descriptor for changes, using any of ionotify, poll, select, BPS, etc. When your app detects a change to the file descriptor, it must execute ids_process_msg(), which processes the data in the file descriptor.
After your app sends a request, the Identity Service processes the request asynchronously, and writes the response to a file descriptor (FD). The file descriptor contains the result of the ids_get_properties() call, and either the success or failure callback is executed accordingly, all in the same thread that the app is currently running in.
For example, your app can call ids_get_properties() and pass a success callback of my_app_success_callback and a failure callback of my_app_failure_callback. When your app detects a change to the file descriptor, it would call ids_process_msg(), which parses the information in the file descriptor. The file descriptor contains the result of the ids_get_properties() call, and either the success or failure callback would be invoked accordingly, all in the same thread that the app is currently running in.
Last modified: 2013-09-30