Sony DADC User Rights Management Solution

URMS SDK for Android

Purpose

This document contains a description of URMS-SDK’s API. Refer to URMS SDK Overview for general information as well as installation information.

SDK Overview

URMS-SDK provides an API in the form of so-called URMS Tasks, which can be either executed synchronously or executed asynchronously with callbacks. The result, as well as error information, is also provided through these tasks.

Callbacks will be dispatched on main-thread. Therefore, application developers may handle UI operations directly in the callback.

URMS SDK provides two task queues for asynchronous calls, default queue and background queue. Normally, asynchronous API calls should be executed on the default queue using executeAsync().

Time consuming tasks, that could be executed in parallel to other URMS tasks (as of now only Download Tasks), can be added to a so-called background queue using executeBackground().

Upgrade Instructions

  1. Copy the files from the libs folder in the new SDK into the libs folder of your application. Overwrite the existing files.
  2. Replace the header files with new versions of those files provided in the include folder.

Troubleshooting

  1. Do not run your application with an attached debugger while using the SDK release, because this will cause it to crash when triggering the first URMS method.  The call stack will be corrupted.
  2. Make sure your application is designed to call the EvaluateLicense method before a user reads an eBook, even if the book is in offline mode.

Class Overview

com.sonydadc.urms.android.Urms

Description: This class is the facade of URMS-SDK.
Application developers interface with this class to create URMS Tasks, which in turn, provide the desired functionality.

com.sonydadc.urms.android.UrmsError

Description: URMS-SDK will report and error with the UrmsError class.

The application may know the error type via UrmsError.getErrorType()method.
This class contains error information, an error-type, as well as an error-code.

com.sonydadc.urms.android.task.ApiTaskBase<TR>

Note that “<TR>” here refers to a Java construct, showing that this class uses generics.

Description: Base class of all API-Task classes.
Features:
  • synchronous API call
  • asynchronous API call with callback
  • result with additional objects or error

com.sonydadc.urms.android.api

Description: API-Task classes and additional result classes.

com.sonydadc.urms.android.model

Description: Model classes, such as book.

com.sonydadc.urms.android.type

Description: Enum definitions

API-Task Base Class

The base class is defined in com.sonydadc.urms.android.task

public void executeAsync()

TR is a type parameter for additional result objects.
Some APIs are inherited from ApiTaskBase<EmptyResponse>

API-Task Parameters

API-Task classes provide setters for parameters.
Parameters are validated before execution.
Please refer to the API details.

Setters will return self instance. (AKA this)

It allows method-chaining.

Synchronous API-calls

The following methods in ApiTaskBase<TR> can be used to execute a call synchronously

public UrmsError execute ()
public UrmsError execute (boolean shouldCallback)

These methods will issue an synchronous API call, and return the status Object giving information about success or failure of the task.

As default, API-Task does not issue callbacks, even if callbacks are set.

In case shouldCallback is true, the callbacks are triggered.

Asynchronous API-call

The following method in ApiTaskBase<TR> can be used to execute a call asynchronously

public void executeAsync()

Or use the static method in URMS

public static void executeAsync(IUrmsTask task)
public static void executeBackground(IUrmsTask task)

These methods do not return any results directly.

Callbacks need to registered before executing this call. In case of success of the task the result can be obtained in the ISucceededCallback.

Callback interfaces

API-Tasks provide the following callbacks

Event Callback Interface Timing Condition
PreExecute IPreExecuteCallback Before execution Always
PostExecute IPostExecuteCallback After execution Always
Failed IFailedCallback After post-execute callback Failed
Cancelled ICancelledCallback After post-execute callback Cancelled
Succeeded ISucceededCallback<TR> After post-execute callback Succeeded

Each interface has one method. These method receives API-Task instances as IUrmsTask.

Result and error

Results returned by an API-Task have the following methods.

public boolean isError()
public UrmsError getError()
public TR result()

Method getError() may return null on success.
Method result() may return null on fail.
Before calling these, either isError() or the return value of execute() should be check.

Extra field

API-Task provides an extra field.

public void setExtra(Object extra)
public Object getExtra()

URMS-SDK does not manipulate this field.
Application developers may use it for any purpose.

API-Task will retain this with strong reference.
Please take care of circular references.

Method description

com.sonydadc.urms.android.Urms

initialize

Signature public static UrmsError initialize( Context context, int cgpApiTimeout)
Arguments context Android Activity Context
cgpApiTimeout Timeout parameter for calling cgp-api.
Description Initializes URMS-SDK. This must be called before any other URMS functionality is used. URMS-SDK will use the calling thread as callback dispatch target. We recommend to call this from the main thread. There are no network operations included.

shutdown

Signature public static UrmsError shutdown()
Arguments None
Description Shutdown SDK and free memory. This call is optional and is not required.

reset

Signature public static UrmsError reset()
Arguments None
Description Reset the current state and delete all persistent data for the currently active profile (other profiles are not affected).This function should be called after a failed de-registration.

setTaskModifier

Signature public static void setTaskModifier(IUrmsTaskModifier modifier)
Arguments modifier Task modifier. Or null to unset.
Description URMS will call IUrmsTaskModifier.onTaskCreated(IUrmsTask task) after creating task instance by URMS class.
Application developer may use this to apply common settings, such as error handling.

executeAsync

Signature public static void executeAsync(IUrmsTask task)
Arguments Task Target task
Description Adds a task to the default queue for asynchronous execution. The default task executer processes tasks in the order they were added to the queue.

executeBackground

Signature public static void executeBackground(IUrmsTask task)
Arguments Task Target task
Description Adds a task to the background queue for asynchronous execution. The background task executer processes tasks in order. It runs in parallel to the default task executor.

task factory

create~Task methods will create task instance. And apply task modifier, if given.

API-task class description

CreateProfileTask

Description Registers the device to a given user account (profile).
At least one active profile is required in order to use other URMS SDK functionality.
A profile can be actived either by creating one, or switching to one.
Subsequent API calls will fail or produce undefined behavior if no registration has happened.
Parameters authToken(required) The Auth-Token is provided from the CGP to a Store via the generateAuthToken call of Store – API.
Applications should receive this from the Store.
profileName(required) Name of the profile. The profile name is not case sensitive. The following characters are allowed:
alphanumeric characters, @, -, _, .
deviceName;(optional) Store can register devices with this name.
If none is provided, URMS – SDK generates a name from the device model information.
config (required) Class UrmsProfileConfiguration contains profile-specific settings.
cgpApiUrl (required), URL of CGP Service
marlinApiUrl (required), URL of Marlin Server
marlinServiceID (required), ServiceID of Marlin Server
marlinUseSSL (required), Using SSL connection for Marlin communication. 1 to yes, 0 to no.
Result type None
Note During profile creation the Marlin DRM system will be initialized and personalized.
As the personalization is a rather time consuming task, it is recommended to execute it asynchronously. This API will not create new user account on CGP.

DeleteProfileTask

Description Disassociates the device from the user account and deletes all data (configs, licenses).
In case the currently active profile is deleted, the app needs to switch to another one.
URMS – SDK will not remove content files (books).
Parameters profileName (required)
Result type None
Note

SwitchProfileTask

Description URMS can only handle one “active” profile at a time. This task allows switching to another profile.
In case profiles already exist at app startup, one of the available profiles can be activated by switching to it. If no profile is active, subsequent API calls will fail or produce undefined behavior.
Parameters profileName (required)
Result type None
Note This task does not use any network operation. Therefore it is eligible to be executed synchronously.

GetActiveProfileTask

Result typeUrmsGetActiveProfileResult, profile

Description Retrieve the name of the currently active profile. If no active profile is found, the task returns an empty string.
Parameters None
Note This task does not use any network operation. Therefore it is eligible to be executed synchronously.

If your application is designed to look for an error if no active profile is found, and the situation is handled in the failed callback, the application needs to be updated.  URMS returns an empty string if no active profile is found, so in that case the process needs to move to the success callback.

GetProfilesTask

Description Get a list of profiles available on the device.
Parameters None
Result type UrmsGetProfilesResult
List<String> profiles
Note This task does not use any network operation. Therefore it is eligible to be executed synchronously.

GetApplicationGroupTask

Description Get application group information. Application may know other applications in same group for common-bookshelf.
Parameters None
Result type List<String> applications Registered strings for the application group. Maybe application identifier.
Note Application may call this API without user-registration.

GetOnlineBooksTask

Description Inquire available books of the user to CGP.
Parameters containsOwn, defaults to True Result contains the books that are owned by the user.
containsLending, defaults to True Result contains the books currently lent (to friends)
containsSelling, defaults to True Result contains the books with status sell.
containsBorrowing, defaults to True Result contains the books with status borrow.
containsGroup, defaults to True Result contains the books on group that the user would seek to join.
containsCommonBookshelf, defaults to True Result contains the readable books on common-bookshelf.
bookFormat, defaults to ALL The books will be filtered with this condition
groupId, defaults to 0 Only specific group will be looked-up, if containsGroup was true.
If given 0, all available groups will be looked up.
pageSize, defaults to 64 The upper limit of result count.
To get more books, call with page parameter.
page, defaults to 1 Page number of result (first page is 1)
Result type GetOnlineBooksResult books List of books that are available on CGP server.
totalCount Total count of result.
It will be the same number of books count.

GetDownloadedBooksTask

Description Get information related to downloaded books.
Parameters None
Result type GetDownloadedBooksResult books List of downloaded books
totalCount Total count of result.
It will be same number to books count.
Note Download book means the book that downloaded by RegisterBookTask, and still having valid license.
This API is also available for airplane mode.

GetDownloadedBookTask

Description Get information of the downloaded book.
Parameters ccid (required) The CCID of the target book content
Result type DownloadedBook
Note This API is also available on offline.

IsMarlinBookTask

Description Checks if a book is protected by Marlin or not.
Parameters filepath The path to the ebook file in question
Result type True if the book is protected by Marlin, false otherwise
Note This API does not need network communication.

EvaluateLicenseTask

Description Evaluate the license of the book, and prepare DRM system.
Parameters ccid (required) The CCID of the target book content
Result type None
Note Before opening book, application should call this API.
Unless calling this, decryption will fail. This API is also available in airplane mode.

RegisterBookTask

Description Download book content file and register DRM licence to the device.

If the file identified by the destination parameter already exists, it is assumed that the file has been side-loaded, and downloads are skipped. If downloadSource is set, this overrides the download URL provided to URMS. The file is going to be downloaded by URMS directly from the provided downloadSource. If neither the destination file exists nor a downloadSource is provided, the SDK fetches the content from the download URL that was provided to URMS when the book was packaged.

During packaging, a hash value of the protected book is stored on the server, used to verify the integrity of the book. It is checked when executing the RegisterBookTask.

Parameters ccid (required) The CCID of the target book content
destination (required) Downloading destination file path.
Application should manage filepath for each book content file.
downloadSource (optional) Alternative content source URL.
If given, urms-sdk will ignore the URL provided by CGP.
timeoutMillis default 10000 Read timeout as milli second.
On Android, it will be set to java.net.URLConnection.setReadTime().
Additional callback progressCallback  To tell the progress, URMS-SDK will call this while downloading.
Result type None
Note This API contains downloading. Because of this, it takes longer time than other APIs. Application developer may execute it via executeBackground.

The URMS-SDK will process other API-tasks in default queue while downloading.

As an alternative, application developers may also implement their own downloading process, and use the side-loading capabilities of RegisterBookTask.

SynchronizeBookshelfTask

Description Remove information and DRM licences for nonreadable book contents(from the device).
Parameters None
Result type None
Note URMS-SDK will not check actual book status until licence evaluation. It cause difference from book status on CGP. This API will force check and sweep non readable book from downloaded book list.

DeregisterBookmarkTask

Description Remove information and DRM licence for specific book content (from the device).
Parameters ccid (required) The CCID of the target book content
Result type None

CreateBookmarkTask

Description Create bookmark on CGP. CGP will assign a bookmark ID for the bookmark which can later be used to reference the bookmark for update or delete.
Parameters ccid (required) The CCID of the book you want to create the bookmark for.
type This is a number to differentiate between different types of bookmarks, such as between automatically and manually created bookmarks. The interpretation of the number is up to you. There is no special handling from URMS side according to this type.
content Default: empty The format is not specified.
It can be any string which defines a specific location in the book.
tag Default: empty Additional information for the bookmark.
Result type The id of the Bookmark

DeleteBookmarkTask

Description Deletes a bookmark from CGP.
Parameters bookmarkID (required) ID of the bookmark to delete. This ID is returned by the CreateBookmarkTask or by the GetBookmarksTask.
Result None

GetBookmarksTask

Description Gets a list of bookmarks for one book from CGP.
Parameters ccid (required) CCID of target book content.
Result type GetBookmarksResult Bookmarks List<Bookmark>. See Model class description.

UpdateBookmarkTask

Description Updates tag, content, type and lastUpdated of a bookmark.
The task uses the bookmarkId in the bookmark parameter to identify the bookmark to update and the overwrites all fields of this bookmark. Also, the lastUpdated date will be overwritten by whatever value is in the parameter, even if the date is older than the one stored on the server.
Parameters bookmark (required) The bookmark object containing all updated fields
Result type None

LendBookTask

Description Lend the book to other user (assign temporary read permission)
Parameters ccid (required) CCID of target book content.
borrowerId (required) UserID of lending target user.
termSec (required) Lending duration in seconds.
It must be positive number.
Result type None
Note This API will fail if the target user already owns the book.

GiftBookTask

Description Give the book to other user (transfer the ownership)
Parameters ccid (required) CCID of target book content.
recieverId (required) UserID of target user.
Result type None
Note This API will fail if the target user already owns the book.

ReturnBookTask

Description Return the borrowed book to owner or store (revoke the lending state).
Parameters ccid (required) CCID of target book content.
Result type None

GetbackBookTask

Description Get back the lending book (revoke the lending state).
Parameters ccid (required) CCID of target book content.
Result type None

SellBookTask

Description Set book status to selling.
Parameters ccid (required) CCID of target book content.
Result type None
Note Urms will manage book selling only.

CancelSellingTask

Description Set book status to own, if status was selling.
Parameters ccid (required) CCID of target book content.
Result type None
Note Urms will manage book status only.

GetSettingsTask

Description Inquire settings about bookshelf.
Parameters None
Result type UrmsGetSettingsResult storeName Name of the store having the user account.
deviceName Device name on CGP.
commonBookshelfStatus Common-bookshelf setting.

GetContentDetailTask

Description Inquire detailed book status (ownership).
Parameters ccid (required) CCID of target book content.
Result type UrmsGetContentDetailResult own Book status on the bookshelf (of the user).
commonBookshelf List of book status on available common-bookshelves.
group List of book status on available groups.

CreateGroupTask

Description Create a group on CGP.
Parameters groupName (required) Group name
Result Type CreateGroupResult. groupID, ID of the created group
Note This API will create group with no member.
Created group have only the user as administrator.

DeleteGroupTask

Description Delete target group
Parameters groupID (required) ID of the target group
Result Type None
Note Only the administrator can delete the group.

RenameGroupTask

Description Change target group name
Parameters groupID (required) ID of the target group
groupName (required) New group name
Result Type None
Note Only the administrator can rename the group.

GetGroupsTask

Description Inquire available groups.
Parameters status default ALL The Result will be filtered with this condition (user role)
groupID default 0 If given, CGP will return the target group information only.
Result Type GetGroupsResult List of groups

AddGroupUserTask

Description Add user to the group as a member.
Parameters groupID (required) ID of the target group
userids (required) List of userID codes.
Result Type None
Note Only the administrator can add a user.

RemoveGroupUserTask

Description Remove other user from the group.
Parameters groupID (required) ID of the target group
userids (required) List of userID codes.
Result Type None
Note Only the administrator can remove a user.

AddGroupBookTask

Description Add a book to the group. The user has ownership.
Parameters groupID (required) ID of the target group
ccid (required) ID of the target book
Result Type None
Note Only the administrator can add a book.
After that, the user cannot lend or sell the book, while the book belongs to a group.

RemoveGroupBookTask

Description Remove a book from the group.
Parameters groupID (required) ID of the target group
ccid (required) ID of the target book
Result Type None
Note Only the administrator can remove a book. After that, the user gains ownership again.

GetLinkTokenTask

Description Receive a token which can be used for inviting another user to join the common bookshelf.
Parameters None
Result Type GetLinkTokenResult linkToken, the token string which needs to be passed to another user

LinkAccountsTask

Description Join a common bookshelf with the current account.
Parameters token (optional) The link token obtained form a GetLinkTokenTask.
Result Type None

UnlinkAccountTask

Description Leave the common bookshelf with the current account.
Parameters None
Result Type None

GetLendExpiryTask

Description Fetch information about lend expiration.
If there is no active lend for a book then the book will not be included in the result, even if the book’s CCID was provided in the CCIDs parameter.
Parameters containsCommonBookshelf (optional) Whether or not to contain the books of the common bookshelf. Defaults to False
ccids (optional) A list of CCID codes. If this list is provided, then the results are restricted to these CCIDs.
If the parameter is omitted, then all books which are on lend are returned.
Result Type List Lend<ExpiryInformation> ccid The CCID of a book
transactionType The lending type:
LEND, The book is lent to a friend
STORE_LEND, the book is borrowed from a store
BORROW, the book is borrowed from a friend
expiry The date and time that the book lending period expires, expressed as a Unix timestamp (in seconds)
commonBookshelf True if the book is available through the common bookshelf.
False if the book is available directly (on an owner’s bookshelf)

Model class description

Book

Description The information of book content
Property ccid Unique string that identify the book content.
externalid Additional identification code given by store. CGP does not use this value.
title Book title
storeName Name of store that sell the book.
bookFormat Book format. PDF, ePub2 or ePub3
ageLimit Age limit given by the store.
CGP does not check this.
thumbnailUrl URL pointing the thumbnail image of the book.
version Book file version.
status Combination of book status flags,
such as CanRead | InMainBookshelf

DownloadedBook

Description The information of downloaded book content.
This class extends Book class.
Property durationCopy
countCopy
durationPrint
countPrint
resolutionPrint
periodCopy
periodPrint
Metadata for copy and print control feature.
Note Only CanRead flag was set for downloaded book

Bookmark

Description Bookmark information
Property bookmarkId ID of the bookmark.
ccid CCID of the book that the bookmark belongs to
type This is a number to differentiate between different types of bookmarks, such as between automatically and manually created bookmarks.
The interpretation of the number is up to you. There is no special handling from URMS side according to this type.
content Not specified. It can be any string that defines a specific location within the book.
tag Additional information for the bookmark.
lastUpdated The date when this bookmark was last updated. This information can be used to keep bookmark on different devices in sync.

Group

Description Group information
Property groupId ID of the group.
groupName Group name
adnubud Administrator user of the group
userIds Member users
books List of Books that belong to the group.
isAdmin The user role is an administrator (or not)

OwnBook

Description Book status on bookshelf of the user.
Property status Bookstatus

CommonBookshelfBook

Description Book status on common bookshelf of the user.
Property status Bookstatus
userid UserID of common-bookshelf owner.

GroupBook

Description Book status on group.
Property status Book status
groupName Group name
adminid User ID of group administrator

Error types

Success No error occurred
OutdatedVersion The version of URMS does not match with server version
NotInitialized URMS has not been initialized
Cancelled The task had cancelled
GeneralError General error, such as I/O
InvalidParameter Wrong parameters were given
NetworkError The error occurred while connecting to CGP
NetworkTimeout The connection timed out
ServerDown The CGP server is down
ServerMaintenance The CGP server is not available due to maintenance
SystemError Urms internal error occurred
NotReadable The user did not have read rights to the book
InvalidLicense The license (in the DRM system) was invalid
RegisterDeviceFailed Failed to register device to DRM system
RegisterUserFailed Failed to associate user account to the device
RegisterUserDeviceCapacityReached Failed to associate user account to the device, because the user account has been registered too many devices
NoBook Target book was not found, or book status is inappropriate
NoUser Target user was not found
NoGroup Target group was not found
NoBookmark Target bookmark was not found
AlreadyOwn Target user already has this book
AlreadyExist The given name was already used
InvalidVersion CGP rejected the request, due to invalid version of urms-sdk
NotRegistered DRM system was not registed on the device
NotAuthorized No user was registered on the device
LoseTime CGP rejected the request, due to time gap between device and CGP
NotPermitted Application signature does not match