Sony DADC User Rights Management Solution

URMS SDK for iOS

Purpose

This document contains a description of URMS-SDK’s API.

SDK Overview

URMS-SDK provides an API in the form of URMS Tasks, which can be:

  • executed synchronously
  • 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 background queue using executeBackground().

Upgrade instructions

  1. Replace the “urms” static library with a new one. Avoid mixing debug and release versions.
  2. Replace all header files, including marlin_sdk.h.
  3. Replace the scp-update-binary tool and corresponding dependencies, like libLLVM.dylib.

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.
  3. Make sure that the final binary file for your application is updated with the scp-update-binary tool.

Class Overview

URMS

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.

UrmsError

URMS-SDK reports error condition in the form of this class.

This class contains error information, an error-type, as well as an error-code.

UrmsTask

Base class of all API-Task classes.

  • synchronus API call
  • asynchronus API call with callback
  • result with addtional objects or error

API-Task

Parameters

API-Task classes provides properties for parameters, and validates these before execution.
Please refer to the API details.

Synchronous API-call

Send message to following method to API-Task.

- (Boolean) execute;
- (Boolean) execute:(Boolean)shouldCallback;

These methods will issue synchronous API-call, and return result “true” for success or “false” for fail.
As default, API-Task does not issue callback, even if callbacks are set.
In case shouldCallback is true, the callbacks are triggered.

Asynchronous API-call

Send message to following method of API-Task

- (Boolean) executeAsync;

Or use static method in URMS

+ (Boolean) executeAsync:(UrmsTask*)task;
+ (Boolean) executeBackground:(UrmsTask*)task;

These methods do not return API results. Callbacks should be registered before issuing calls.

Callback interfaces

API-Task provides following callbacks.

Property Callback block type Timing Condition
onPreExecute UrmsTaskCallbackBlock Before execute Always
onPostExecute UrmsTaskCallbackBlock After execute Always
onFailed UrmsTaskErrorCallbackBlock After post-execute callback Failed
onCancelled UrmsTaskCallbackBlock After post-execute callback Cancelled
onSucceeded UrmsTaskCallbackBlock After post-execute callback Succeeded

These block receives API-Task instance as ID. We recommend to define block with actual task type instead of ID.
We strongly recommend using task parameter to access the task from callback blocks. A strong reference from block may cause a memory leak.

Result and error

API-Task will return result with following method and properties.

- (Boolean) isError;
@property (nonatomic, readonly) UrmsError *error;
@property (nonatomic, readonly) *result type* result;

Note: Some tasks do not have result property.

Extra field

API-Task provides extra field.

@property (nonatomic) id extra;

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

Method description

initialize (urms)

Signature

+ (UrmsError*) initialize : (NSInteger)cgpApiTimeout
        keyChainServiceID : (NSString*)KeyChainServiceID
    keyChainVendorIDGroup : (NSString*)KeyChainVendorIDGroup

Arguments
cgpApiTimeout (required)
Timeout parameter for calling cgp-api.
keyChainServiceID (required)
KeyChain ServiceID used for storing DeviceID hash field
keyChainVendorIDGroup (required)
KeyChain VendorID used for storing DeviceID hash field. Set this value to “nil” as it is no longer used.

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

+ (UrmsError*) shutdown

Arguments
None
Description
Shutdown SDK and free memory. This call is optional and is not required.

reset

Signature

+ (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 failed de-registration.

setTaskModifier

Signature

+ (void) setTaskModifier:(UrmsSdkTaskModifierBlock)modifier

Arguments
modifier (optional)
Task modifier. Or nil to unset.
Description
Urms will call modifier block after creating task instance by Urms class.Application developer may use this to apply common settings, such as error handling.

executeAsync

Signature

+ (Boolean) executeAsync:(UrmsTask*)task;

Arguments
task (required)
Target task.
Description
Enqueue default queue for asynchronous call.
And default task-executer will process tasks in order.

executeBackground

Signature

+ (Boolean) executeBackground:(UrmsTask*)task;

Arguments
task (required)
Target task.
Description
Enqueue background queue for asynchronous call.
The background task-executer will process tasks in order and will run in parallel with the default queue.

task factory

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

API-task class description

CreateProfileTask

Description Register 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 in case 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 case insensitive. The following characters are allowed:
alphanumeric characters, @, -, _, .
deviceName (optional) Device name. Store can register devices with this name.
If none is provided, URMS – SDK generates a name from the device model information.
config (required) Structure (UrmsProfileConfiguration*) containing profile-specific configurations. cgpApiUrl (required) URL of CGP Service
MarlinApiUrl (required) URL of Marlin Server
MarlinServiceID (required) ServerID of Marlin Server
MarlinUseSSL (required) Using SSL connection for Marlin communication
1 for yes, 0 for no.
Result type None
Note This call also initializes the Marlin DRM Core to the given profile.
The profile is persistent on the device. Creation of a new profile is quite time-consuming.
Therefore it is recommended to execute this asynchronously.
This API will not create new user account.

DeleteProfileTask

Description Disassociate 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

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 made active 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

Description Retrieve the name of the currently active profile. If no active profile is found, the task returns an empty string.
Parameters None
Result type UrmsGetActiveProfileResult profile NSString
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 profiles NSArray of UNSArray of NSString
Note This task does not use any network operation.
Therefore it is eligible to be executed synchronously.

GetOnlineBooksTask

Description Inquire available books of the user to CGP.
Parameters containsOwn, defaults to True Result contains the books with status own.
containsLending, defaults to True Result contains the books with status lend, to result.
containsSelling, defaults to True Result contains the books with status sell, to result.
containsBorrowing, defaults to True Result contains the books with status borrow, to result.
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 UrmsGetOnlineBooksResult books NSArray of UrmsBookmark, that are available on CGP server.
totalCount Total count of result.
If totalCount was greater than books count,
the results were omitted by pageSize.

GetDownloadedBooksTask

Description Get information related to downloaded books.
Parameters None
Result type UrmsGetDownloadedBooksResult books NSArray of UrmsDownloadedBook, effectively, the 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.

GetDownloadedBookTask

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

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 on offline.

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 iOS, it will be used as timeoutInterval on [NSURLRequest requestWithURL:cachePolicy:timeoutInterval].
Additional callback PreDownload To tell the progress, URMS SDK will call this before downloading.
onProgress To tell the progress, yrms-sdk will call this while downloading.
Result type None
Note This API contains downloading.
Because of this, it takes longer time than other API.
Application developer may execute it via executeBackground.
The URMS SDK will process other API-tasks in default queue while downloading.
As an alternative, application developer also may implement own downloading process, and use the side-loading capabilities of RegisterBookTask.

SynchronizeBookshelfTask

Description Remove information and DRM licences for non-readable 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. For example 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.
CGP does not use this field.
Result type None
Note CGP will issue bookmarkID at registration. Application can know it via GetBookmarksTask.
The content and tag parameter should not be nil. Application should set empty string if not use.

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 type 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 NSArray of UrmsBookmark

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 then
overwrites all the 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 NSInteger, 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 NSArray of UrmsGroup

AddGroupUserTask

Description Add user to the group as a member.
Parameters groupID (required) ID of the target group
userids (required) List of userID codes. (NSArray of NSString)
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. (NSArray of NSString)
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. Target book status should be “own.”

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 token, 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 UrmsGetLendExpiryResult books, NSArray of UrmsBookLicense

Model class description

UrmsBook

Description The information of book content
Property ccid Unique string that identify the book content.
externalid Additional ID given by store. GCP 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

UrmsDownloadedBook

Description The information of downloaded book content.
This class extends UrmsBook 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

UrmsBookmark

Description Bookmark information
Property bookmarkId ID of the bookmark.
ccid CCID of the book that the bookmark belong to
type This is a number to differentiate between different types of bookmarks. For example 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 Content of the bookmark.
In most cases, it will be serialized bookmark object, and it depends on reader system.
tag Additional information for the bookmark.
CGP does not use this field.
lastUpdated The date when this bookmark was last updated. This information can be used to keep bookmark on different devices in sync.

UrmsGroup

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

UrmsOwnBook

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

UrmsCommonBookshelfBook

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

UrmsGroupBook

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

UrmsBookLicense

Description License status of a book.
Property 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)

IsMarlinBookTask

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

UrmsError

Urms-sdk will report error with UrmsError class. The application may know error type via the errorType property.

Error types

UrmsSuccess No error occurred
UrmsOutdatedVersion The version of URMS does not match with server version
UrmsNotInitialized URMS has not been initialized
UrmsCancelled The task had cancelled
UrmsGeneralError General error, such as I/O
UrmsInvalidParameter Wrong parameters were given
UrmsNetworkError The error occurred while connecting to CGP
UrmsNetworkTimeout The connection timed out
UrmsServerDown The CGP server is down
UrmsServerMaintenance The CGP server is not available due to maintenance
UrmsSystemError Urms internal error occurred
UrmsNotReadable The user did not have read rights to the book
UrmsInvalidLicense The license (in the DRM system) was invalid
UrmsRegisterDeviceFailed Failed to register device to DRM system
UrmsRegisterUserFailed Failed to associate user account to the device
UrmsRegisterUserDeviceCapacityReached Failed to associate user account to the device, because the user account has been registered too many devices
UrmsNoBook Target book was not found, or book status is inappropriate
UrmsNoUser Target user was not found
UrmsNoGroup Target group was not found
UrmsNoBookmark Target bookmark was not found
UrmsAlreadyOwn Target user already has this book
UrmsAlreadyExist The given name was already used
UrmsInvalidVersion CGP rejected the request, due to invalid version of urms-sdk
UrmsNotRegistered DRM system was not registed on the device
UrmsNotAuthorized No user was registered on the device
UrmsLoseTime CGP rejected the request, due to time gap between device and CGP
UrmsNotPermitted Application signature does not match