<HIDDevice> Protocol Reference

Main device instance. More...

#import <HIDDevice.h>

Instance Methods
(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...
(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< HIDTransactionInfo >)	- retrieveTransactionInfo:error:
	Deprecated. Retrieves a transaction info associated to that transaction ID. More...
(NSArray *)	- searchTransactionHistory:withFilter:error:
	Searches for transactions in the transaction history. (RFU) 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
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 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 Parameter 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 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.

Returns

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

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

Deprecated. 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 occurred.
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.

Returns

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

Deprecated:

Deprecated in SDK 5.7.1. This method is no longer acceptable to retrieve transaction information. Use HIDDevice#retrieveActionInfo:error:.

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

Searches for transactions in the transaction history. (RFU)

Parameters

sessionPassword	transaction protection key password (can be nil if not required by the policy).
filter	TransactionFilter.
error	error details. It may be nil.

Possible error codes are:

• HIDNotImplemented if the operation is not implemented and reserved for future use.

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 occurred.
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.

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 password is incorrect.
• HIDTransactionExpired if transaction is no longer valid
• HIDCredentialsExpired if key is no longer valid
• HIDInternal if unexpected error occurred.
• HIDPasswordExpired if expired password is given (changePassword required).
• HIDServerAuthentication if server rejects authentication
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.

Returns

YES if property value was successfully updated.

Deprecated:

Deprecated in SDK 5.1. Integrations should replace calls with the HIDContainer.updateDeviceInfo:withParams:error: method.