<HIDDevice> Protocol Reference

Parent device object used to query device information and discover any active containers. More...

#import <HIDDevice.h>

Instance Methods
(id< HIDContainer >)	- createContainer:withSessionPassword:withListener:error:
	Triggers the container activation process to create a new container. More...
(BOOL)	- deleteContainer:withSessionPassword:withParams:error:
	Deletes a container identified by its ID. The method notifies the server the container is deleted, thus requires the device to be online. More...
(NSArray *)	- findContainers:error:
	Retrieves a container based on input parameter filter. More...
(NSString *)	- getDeviceInfo:error:
	Retrieves device information. More...
(NSString *)	- getVersion:
	Returns the version of the transaction processor client API. More...
(id< HIDServerActionInfo >)	- retrieveActionInfo:error:
	Retrieves and decrypts an encrypted "server action" message received from the server. More...
(id< HIDServerActionInfo >)	- retrieveActionInfo:withUserID:error:
	Retrieves and decrypts an encrypted "server action" message received from the server. More...
(BOOL)	- setConnectionConfiguration:error:
	Sets connection configuration. More...

Detailed Description

Parent device object used to query device information and discover any active containers.

Method Documentation

- (id<HIDContainer>) createContainer:		(HIDContainerInitialization *)	config
withSessionPassword:		(NSString *)	sessionPassword
withListener:		(NSObject< HIDProgressListener > *)	listener
error:		(NSError **)	error

Triggers the container activation process to create a new container.

Parameters

config	initialization configuration see HIDContainerInitialization for details
sessionPassword	transaction protection key password (can be nil if not required by the policy)
listener	A HIDProgressListener implementation to which to report status information or receive password request events.
error	error details. It may be nil.

Possible error codes are:

• HIDUnsupportedDevice if device is not supported by policy.
• HIDInternal if an unexpected error occurred.
• HIDServerAuthentication if the server rejected the authentication.
• HIDInvalidPassword if password validation fails.
• HIDRemote if server responds with any other error.
• HIDServerProtocol if the server response provoked an unexpected error.
• HIDPasswordCancelled if the password prompt dialog has been cancelled by the user.
• HIDUnsupportedOperationMode if the device does not support FIPS 140-2 requirements.
• HIDServerOperationFailed if the server encounters a failure for the operation requested.
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.

Returns

the container or nil if an error occurs.

- (BOOL) deleteContainer:		(NSInteger)	containerId
withSessionPassword:		(NSString *)	sessionPassword
withParams:		(NSArray *)	parameters
error:		(NSError **)	error

Deletes a container identified by its ID. The method notifies the server the container is deleted, thus requires the device to be online.

Parameters

containerId	id of the container.
sessionPassword	transaction protection key password (can be nil if not required by the policy).
parameters	can be empty (reserved for future use).
error	error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.
• #HIDPasswordExpiredException if expired password is given (changePassword required).
• #HIDAuthenticationException if password is incorrect.

Returns

YES if the delete was successfully performed.

- (NSArray*) findContainers:		(NSArray *)	filter
error:		(NSError **)	error

Retrieves a container based on input parameter filter.

Parameters

filter

array of HIDParameter objects required to specify container

Filter can indicate:

• HID_CONTAINER_NAME: Friendly Name of the container.
• HID_CONTAINER_URL: URL of server associated with the container.
• HID_CONTAINER_USERID: User identifier of the container.

Parameters

error

error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.

Returns

list of containers or nil if not found.

- (NSString*) getDeviceInfo:		(NSString *)	propertyId
error:		(NSError **)	error

Retrieves device information.

Parameters

propertyId

deviceInfo property to retrieve.

Supported property names:

• HID_DEVICE_INFO_BRAND
• HID_DEVICE_INFO_KEYSTORE
• HID_DEVICE_INFO_LOCALE
• HID_DEVICE_INFO_MANUFACTURER
• HID_DEVICE_INFO_MODEL
• HID_DEVICE_INFO_NAME
• HID_DEVICE_INFO_OS
• HID_DEVICE_INFO_OS_NAME
• HID_DEVICE_INFO_OS_VERSION
• HID_DEVICE_INFO_PRODUCT
• HID_DEVICE_INFO_ISROOTED

Parameters

error

error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.

Returns

the device property value, nil if an error occurs.

- (NSString*) getVersion:

(NSError **)

error

Returns the version of the transaction processor client API.

Returns

version of the SDK version number.

- (id<HIDServerActionInfo>) retrieveActionInfo:		(NSString *)	actionId
error:		(NSError **)	error

Retrieves and decrypts an encrypted "server action" message received from the server.

Parameters

actionId	action ID message received in push notification, scan to approve or via HIDContainer.retrieveTransactionsIds()
error	error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.
• HIDInvalidContainer if the action id refers to a container that does not exist.
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.
• HIDInexplicitContainer if the action id cannot determine which container to apply. Invoke retrieveActionInfo with 'UserId' parameter. HID_ERROR_PARAMETERS includes list with ('UserId':user1,'UserId':user2..).

Returns

a HIDServerActionInfo instance containing action details, nil if an error occurs.

- (id<HIDServerActionInfo>) retrieveActionInfo:		(NSString *)	actionId
withUserID:		(NSString *)	userId
error:		(NSError **)	error

Retrieves and decrypts an encrypted "server action" message received from the server.

Parameters

actionId	action ID message received in push notification, scan to approve or via HIDContainer.retrieveTransactionsIds()
userId	user identifier of the container to be used to retrieve action info from (Optional).
error	error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.
• HIDInvalidContainer if the action id refers to a container that does not exist.
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.
• HIDInexplicitContainer if the action id cannot determine which container to apply. Invoke retrieveActionInfo with 'UserId' parameter. HID_ERROR_PARAMETERS includes list with ('UserId':user1,'UserId':user2..).

Returns

a HIDServerActionInfo instance containing action details, nil if an error occurs.

- (BOOL) setConnectionConfiguration:		(HIDConnectionConfiguration *)	config
error:		(NSError **)	error

Sets connection configuration.

Parameters

config	configuration, see HIDConnectionConfiguration for details.
error	error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.

Returns

false if error occurs