Class: DSILibrary

Create an instance of the DSILibrary class to interact with the Mobile Enterprise Platform server.

To interact with the Mobile Enterprise Platform server, create an instance of the DSILibrary class, call logonUser with a full-access user with an appropriate role (for example, Mobile Client User) and call the methods for the required interactions. Call logoffUser to end the user session.

The DSILibrary class contains the following initializers, properties, and methods.

Initializers

To return an initialized library instance, call one of the following methods.

Method: initWithDeviceId:deviceIdhost:andHostPort: with default response and reply timeouts
Method: initWithDeviceId:deviceIdhost:hostPort:responseTimeout:andReplyTimeout: with response and reply timeout parameters

Properties

deviceID

Gets the Device ID for the device.

@property (nonatomic, readonly, nonnull) NSString* deviceId;

Use this property when you have automatically generated a Device ID when initializing the library so that you can store this ID in the preferences and reuse it in the future.

userLoggedOn

Gets whether the user is currently logged on with the server.

@property (nonatomic, readonly, getter=isUserLoggedOn) BOOL userLoggedOn;

Methods

Method: initWithDeviceId:deviceIdhost:andHostPort:

Returns an initialized Advanced Inventory Library instance with default response and reply timeouts. The default response timeout is 5 seconds. The default reply timeout is 30 seconds.

Declaration

                  -(nullableinstancetype)initWithDeviceId:(nullableNSString*)deviceIdhost:(nonnullNSString*)hostNameOrAddress andHostPort:(int)hostPort;

Parameters

Parameter	Value
deviceId	The Device ID to use for the device. If nil is passed, a Device ID will be generated. This value should be retrieved and stored in preferences so that it can be reused.
hostNameOrAddress	The host name or address for contacting the Mobile Enterprise Platform communications agent.
hostPort	The port for the Mobile Enterprise Platform communications agent.

Returns

Returns an initialized Advanced Inventory Library instance.

Exceptions

None

Method: initWithDeviceId:deviceIdhost:hostPort:responseTimeout:andReplyTimeout:

Returns an initialized library instance if you do not want to use the default response and reply timeouts. The default response timeout is 5 seconds. The default reply timeout is 30 seconds.

Declaration

                  -(nullableinstancetype)initWithDeviceId:(nullableNSString*)deviceIdhost:(nonnullNSString*)hostNameOrAddress hostPort:(int)hostPort responseTimeout:(NSUInteger)responseTimeout andReplyTimeout:(NSUInteger)replyTimeout;

Parameters

Parameter	Value
deviceId	The Device ID to use for the device. If nil is passed, a Device ID will be generated. This value should be retrieved and stored in preferences so that it can be reused.
hostNameOrAddress	The host name or address for contacting the Mobile Enterprise Platform communications agent.
hostPort	The port for the Mobile Enterprise Platform communications agent.
responseTimeout	The response timeout for messages to the server. This is the amount of time the library waits for the server to acknowledge that a message has been received. This value must be less than the reply timeout.
replyTimeout	The reply timeout for messages to the server. This is the amount of time the library waits for the server to reply to messages. This value must be greater than the response timeout.

Returns

Returns an initialized Advanced Inventory Library instance.

Exceptions

None

Method: callFunction:withVersion:onConnector:inEnvironment: synchronously:queueable:withTimeout:storeInTransactionLog:trackingReference:inputData:requestingOutputFields:

Executes a function call on the server.

Declaration

-(FunctionCallStatus)callFunction:(nonnull NSString*)functionName                       withVersion:(nonnull NSString*)functionDefinitionVersion                       onConnector:(nonnull NSString*)connectorName                     inEnvironment:(nonnull NSString*)environment                     synchronously:(BOOL)isSynchronous                         queueable:(BOOL)isQueueable                       withTimeout:(NSUInteger)timeout             storeInTransactionLog:(BOOL)storeInTransactionLog                 trackingReference:(nullable NSString*)trackingReference                         inputData:(nullable NSArray<FunctionCallField*>*)inputData            requestingOutputFields:(nullable NSArray<FunctionCallField*>*)outputFields;

Parameters

Parameter	Value
connectorName	The name of the connector for the function. Note: The Web Services connector is defined as the constant DSILibrary_FunctionCall_Connector_WebServices for convenience.
environment	The environment for the function call.
functionDefinitionVersion	The version of the function to call.
functionName	The name of the function to call.
inputData	The list of input values for the function call. If the function has no required input, this can be nil.
isQueueable	YES if the function call is queueable. Note that a function call cannot be queueable if it is synchronous.
isSynchronous	YES if the function call should be executed synchronously.
outputStructure	The requested output fields from the function call. This is the list of output fields whose values will be populated with the function call return. Note: You do not need to include all the fields defined as output by the definition of a function. Only include the ones whose values you want. This will optimize the amount of data returned from the server to include only the data of interest.
storeInTransactionLog	YES if a record of this function call should be stored in the transaction log on the server.
timeout	The timeout for this function call, in seconds.
trackingReference	The tracking reference for this function call to be stored in the transaction log. This is not applicable if the call will not be stored in the transaction log. It can be nil, even if a transaction log record is being written (the tracking reference value will be blank).

Returns

None

Exceptions

Exception type	Reason
CommunicationException	Communication with the server cannot be made, or the server does not reply within the timeout duration specified.
DSIArgumentException	The sqlStatement, connectionId, or environment is empty.
FunctionCallException	The function call returns error messages, an unexpected status, or the returned structure does not match the requested data.
ServerReplyException	The server returns an error.
SessionException	The user has not successfully logged in or has already logged out.

Method: changePasswordForUser:from:to:

Changes the password for a user and logs the user on.

Declaration

 -(void)changePasswordForUser:(nonnull NSString*)userID from:(nonnull NSString*)oldPassword to:(nonnull NSString*)newPassword;

Parameters

Parameter	Value
userID	The ID of the user whose password is changed.
oldPassword	The user's old password.
newPassword	The user's new password.

Returns

None

Exceptions

Exception type	Reason
CommunicationException	Communication with the server cannot be made, or the server does not reply within the timeout duration specified.
LogonException	Verification with the server failed, or the userID, oldPassword, or newPassword was nil. The exception message contains the reason for the failure.
ServerReplyException	The server returns an error.

Method: downloadWithSqlStatement:andReplacementValues:onConnection:inEnvironment:

Downloads data from a table registered on the server.

Declaration

-(nonnull NSArray<NSArray<NSString*>*>*)downloadWithSqlStatement:(nonnull NSString*)sqlStatement                                             andReplacementValues:(nullable NSArray<NSString*>*)replacementValues                                                     onConnection:(nonnull NSString*)connectionId                                                    inEnvironment:(nonnull NSString*)environment;

Parameters

Parameter	Value
sqlStatement	The SQL statement to execute to download the data.
replacementValues	The replacement values for parameters in the SQL statement (can be nil or empty if there are no parameters in the SQL statement).
connectionId	The registered connection ID on which to execute the SQL statement.
environment	The environment in which to execute the SQL statement.

Returns

Returns the rows downloaded from the table.

Exceptions

Exception type	Reason
CommunicationException	Communication with the server cannot be made, or the server does not reply within the timeout duration specified.
DSIArgumentException	The sqlStatement, connectionId, or environment is empty.
ServerReplyException	The server returns an error.
SessionException	The user has not successfully logged in or has already logged out.

Method: executeSqlStatement:withReplacementValues:onConnection:inEnvironment: trackingReference:

Executes a SQL statement on the server.

Declaration

-(NSUInteger)executeSqlStatement:(nonnull NSString*)sqlStatement            withReplacementValues:(nullable NSArray<NSString*>*)replacementValues                     onConnection:(nonnull NSString*)connectionId                    inEnvironment:(nonnull NSString*)environment                trackingReference:(nullable NSString*)trackingReference;

Parameters

Parameter	Value
connectionId	The registered connection ID on which to execute the SQL statement.
environment	The environment in which to execute the SQL statement.
replacementValues	The replacementValues for parameters in the SQL statement (can be nil or empty if there are no parameters in the SQL statement).
sqlStatement	The SQL statement to execute to insert/update/delete records.
trackingReference	The tracking reference string for the transaction log entry for this transaction (nil if you are not using tracking reference).

Returns

Returns the number of rows affected by the transaction.

Exceptions

Exception type	Reason
CommunicationException	Communication with the server cannot be made, or the server does not reply within the timeout duration specified.
DSIArgumentException	The sqlStatement, connectionId, or environment is empty.
ServerReplyException	The server returns an error.
SessionException	The user has not successfully logged in or has already logged out.

Method: getFile:toPath:

Downloads a file from the server.

Declaration

-(void)getFile:(nonnull NSString*)sourceFileServerPath toPath:(nonnull NSString*)destinationFilePath;

Parameters

Parameter	Value
sourceFileServerPath	The server path to the file that is downloaded.
destinationFilePath	The local path to which the file should be downloaded.

Returns

None

Exceptions

Exception type	Reason
CommunicationException	Communication with the server cannot be made, or the server does not reply within the timeout duration specified.
DSIArgumentException	Either the sourceFileServerPath or destinationFilePath is empty.
ServerReplyException	The server returns an error.
SessionException	The user has not successfully logged in or has already logged out.

Method: logoffUser

This method terminates with the server the current user session of the user logged on to the device if the session exists. If no user is logged on, logoffUser has no effect.

Declaration

-(void)logoffUser; None

Parameters

None

Returns

None

Exceptions

None

Method: logonUser:withPassword:

Verifies the user credentials with the server and starts a new user session.

Declaration

-(void)logonUser:(nonnull NSString*)userID withPassword:(nonnull NSString *)password;

Parameters

Parameter	Value
userID	The ID of the user to be verified
password	The user's password

Returns

None

Exceptions

Exception type	Reason
CommunicationException	Communication with the server cannot be made, or the server does not reply within the timeout duration specified.
LogonException	Verification with the server failed. The exception message contains the reason for the failure.
PasswordExpiredException	Verification with the server succeeded, but the user's password has expired, and the user must change the password before logon can succeed.
ServerReplyException	The server returns an error for any other reason that is not related to user verification.

Method: ping:

Contacts the server to make sure connection is possible.

Declaration

-(BOOL)ping;

Parameters

None

Returns

Returns YES if a connection to the server can be made.

Exceptions

Exception type	Reason
ServerReplyException	A connection to the server is made, but the server returns an error.

Method: replicateDatabaseForEnvironment:andForceFullReplication:

Replicates data from the server to a local SQLite database based on server replication rules for the current user. Requires that logonUser be called first.

Declaration

-(nonnull NSString*)replicateDatabaseForEnvironment:(nonnull NSString*)environmentName andForceFullReplication:(BOOL)forceFullReplication;

Parameters

Parameter	Value
environmentName	Name of the environment to replicate
forceFullReplication	Forces a full replication to replace the current existing database instead of a partial replication

Returns

Returns the full path name to the database file that was created.

Exceptions

Exception type	Reason
sessionException	User has not successfully logged in, or user has logged out.
replicationException	Replication from the server failed. The exception message contains the reason for the failure.

Method: sendFile:toServerWithName:

Sends a file to the server .

Declaration

-(void)sendFile:(nonnull NSString*)localFilePath toServerWithName:(nonnull NSString*)destinationFileName;

Parameters

Parameter	Value
localFilePath	The path to the local file that is sent to the server.
destinationFileName	The server destination file to which the content should be saved. This location is relative to the drop directory that is configured in the Communication Agent settings.

Returns

None

Exceptions

Exception type	Reason
CommunicationException	Communication with the server cannot be made, or the server does not reply within the timeout duration specified.
DSIArgumentException	Either the localFilePath string or destinationFileName is empty, or localFilePath points to a file that does not exist.
ServerReplyException	The server returns an error.
SessionException	The user has not successfully logged in or has already logged out.

Method: serverVersion:

Gets the version of the server.

Declaration

-(nonnull NSString*)serverVersion;

Parameters

None

Returns

Returns the version string from the server (e.g. 8.5.3).

Exceptions

Exception type	Reason
CommunicationException	Communication with the server cannot be made, or the server does not reply within the timeout duration specified.
ServerReplyException	The server returns an error.