<HIDDevice> Protocol Reference

Main device instance. More...

#import <HIDDevice.h>

Instance Methods
(id< HIDContainer >)	- createContainer:withListener:error:
	Deprecated. Creates the container. More...
(id< HIDContainer >)	- createContainer:withSessionPassword:withListener:error:
	Creates the 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...
(id< HIDProtectionPolicy >)	- getDefaultInitializationPolicy:
	Deprecated. Retrieves the initialization password policy for the device. More...
(NSString *)	- getDeviceInfo:error:
	Retrieves device information. More...
(NSString *)	- getVersion:
	Returns the version of the transaction processor client API. More...
(BOOL)	- reset:error:
	Deprecated. Deletes containers and keys contained in the device. More...
(id< HIDTransaction >)	- retrieveTransaction:withPassword:withParams:error:
	Deprecated. Retrieves a transaction associated with that transaction ID. More...
(id< HIDTransactionInfo >)	- retrieveTransactionInfo:error:
	Retrieves a transaction info associated to that transaction ID. More...
(NSArray *)	- searchTransactionHistory:withFilter:error:
	Searches for transactions in the transaction history. More...
(BOOL)	- setConnectionConfiguration:error:
	Sets connection configuration. More...
(BOOL)	- updateDeviceInfo:withValue:withPassword:withParams:error:
	Updates device information. More...

Detailed Description

Main device instance.

Method Documentation

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

Deprecated. Creates the container.

Parameters

config	initialization configuration see HIDContainerInitialization for details
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 invalid parameter is given

Returns

the container or nil if an error occurs.

Deprecated:

Deprecated in SDK 5.1. Integrations should replace calls with the createContainer:withSessionPassword:withListener:error: method.

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

Creates the 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 invalid parameter is given

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 occurs
• HIDInvalidArgument if invalid parameter is given

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

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 occurs
• HIDInvalidArgument if invalid parameter is given

Returns

list of containers or nil if not found.

- (id<HIDProtectionPolicy>) getDefaultInitializationPolicy:

(NSError **)

error

Deprecated. Retrieves the initialization password policy for the device.

Parameters

error

error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurs

Returns

HIDProtectionPolicy

Deprecated:

Deprecated in SDK 5.1. Integrations should use the HIDProgressListener functionality.

- (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

Parameters

error

error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurs
• HIDInvalidArgument if invalid parameter is given

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.

- (BOOL) reset:		(NSArray *)	parameters
error:		(NSError **)	error

Deprecated. Deletes containers and keys contained in the device.

Parameters

parameters	can be empty (reserved for future use).
error	error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurs

Returns

YES if the reset was successfully performed.

Deprecated:

Deprecated in SDK 5.1. Integrations should replace calls with the HIDDeviceFactory.reset: method.

- (id<HIDTransaction>) retrieveTransaction:		(NSString *)	transactionId
withPassword:		(NSString *)	sessionPassword
withParams:		(NSArray *)	parameters
error:		(NSError **)	error

Deprecated. Retrieves a transaction associated with that transaction ID.

Parameters

transactionId	transaction ID message received in push notification.
sessionPassword	transaction protection key password (can be nil if not required by the policy)
parameters	NSArray of HIDParameter objects required to retrieve the transaction (such as password if needed).

Supported parameters:

• HID_PARAM_SYNC_PWD_TXPROTECT

Parameters

error

error details. It may be nil.

Possible error codes are:

• HIDAuthentication if invalid password is given
• HIDTransactionExpired if transaction is no longer valid
• HIDCredentialsExpired if key is no longer valid
• HIDInternal if unexpected error occurs
• HIDPasswordExpired if password is expired and requires password change according to protection policy.
• HIDServerAuthentication if server rejects authentication
• HIDInvalidArgument if invalid parameter is given

Returns

a HIDTransaction instance containing transaction details, nil if an error occurs.

If a password protection policy is set on the Transaction protection key the password protecting the key must be passed as parameter to enable retrieving the transaction.

Deprecated:

Deprecated in SDK 5.1. Integrations should replace calls with the HIDTransactionInfo.getTransaction:withParams:error: method.

- (id<HIDTransactionInfo>) retrieveTransactionInfo:		(NSString *)	transactionId
error:		(NSError **)	error

Retrieves a transaction info associated to that transaction ID.

Parameters

transactionId	transaction ID message received in push notification.
error	error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurs
• HIDInvalidArgument if invalid parameter is given

Returns

a HIDTransactionInfo instance containing transaction details, nil if an error occurs.

- (NSArray*) searchTransactionHistory:		(NSString *)	sessionPassword
withFilter:		(NSArray *)	filter
error:		(NSError **)	error

Searches for transactions in the transaction history.

Parameters

sessionPassword	If a password protection policy is set on the transaction protection key the password protecting the key must be passed.
filter	TransactionFilter.
error	error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurs
• HIDInvalidArgument if invalid parameter is given
• HIDNotImplemented if not implemented

Returns

The list of transactions or nil if not found.

Exceptions

NSInternalInconsistencyException

if not implemented

- (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 occurs
• HIDInvalidArgument if invalid parameter is given

Returns

false if error occurs

- (BOOL) updateDeviceInfo:		(NSString *)	propertyId
withValue:		(NSString *)	propertyValue
withPassword:		(NSString *)	sessionPassword
withParams:		(NSArray *)	parameters
error:		(NSError **)	error

Updates device information.

This method is used by the application to notify of a change in one of the externally generated device attributes.

Parameters

propertyId

deviceInfo property to update.

Supported name attributes:

• HID_DEVICE_INFO_PUSHID: update of the 'pushId', set up at provisioning and used by the server to notify the correct phone. Value may be null or empty to disable push notification for device.
• HID_DEVICE_INFO_NAME: update of the device friendly name, set up at provisioning and used by the server to identify the correct phone.

Parameters

sessionPassword	transaction protection key password (can be nil if not required by the policy)
propertyValue	the new value to replace.
parameters	empty (reserved for future use)

Supported parameters:

• HID_PARAM_SYNC_PWD_TXPROTECT

Parameters

error

error details. It may be nil.

Possible error codes are:

• HIDAuthentication if invalid password is given
• HIDTransactionExpired if transaction is no longer valid
• HIDCredentialsExpired if key is no longer valid
• HIDInternal if unexpected error occurs
• HIDPasswordExpired if password is expired and requires password change according to protection policy.
• HIDServerAuthentication if server rejects authentication
• HIDInvalidArgument if invalid parameter is given

Returns

YES if property value was successfully updated.

---

The documentation for this protocol was generated from the following file:

• HIDDevice.h