VantiqUI Class Reference

Inherits from NSObject
Conforms to CLLocationManagerDelegate
Declared in VantiqUI.h
VantiqUI.m

Overview

The VantiqUI class declares the interface for authentication and subsequent interaction with a Vantiq server.

Session Information Dictionary Keys

The keys listed below are returned in the response dictionary returned by the following methods: serverType, verifyAuthToken, authWithOAuth, and authWithInternal.

• serverType (NSString): the type of authentication used by the given Vantiq server, either @“Internal” or @“OAuth”

• authValid (BOOL): is the previously establed authentication token valid

• username (NSString): the username of the authenticated user

• preferredUsername (NSString): the preferred username of the authenticated user, will be the same as the username for Internal authentication

• errorStr (NSString): a text description of any error that occurred, will be the empty string (@“”) if there is no error

• statusCode (NSNumber): the HTTP status code of any related REST operations

(Not all keys will be present depending on error conditions and the method.)

Other Methods

  v

Instance of the underlying Vantiq class for direct communication to the Vantiq SDK

@property (readonly, nonatomic) Vantiq *v

Discussion

Instance of the underlying Vantiq class for direct communication to the Vantiq SDK

Declared In

VantiqUI.h

  username

User name of the last authenticated user.

@property (readonly, nonatomic) NSString *username

Discussion

User name of the last authenticated user.

Declared In

VantiqUI.h

  preferredUsername

Preferred user name of the last authenticated user.

@property (readonly, nonatomic) NSString *preferredUsername

Discussion

Preferred user name of the last authenticated user.

Declared In

VantiqUI.h

  serverType

Type of the server, will be either ‘Internal’ or ‘OAuth’

@property (readonly, nonatomic) NSString *serverType

Discussion

Type of the server, will be either ‘Internal’ or ‘OAuth’

Declared In

VantiqUI.h

– init:namespace:completionHandler:

Constructor for use with all other Vantiq UI and server operations.

- (id _Nullable)init:(NSString *_Nonnull)serverURL namespace:(NSString *_Nonnull)targetNamespace completionHandler:(void ( ^ _Nonnull ) ( NSDictionary *_Nonnull response ))handler

Parameters

serverURL

Server URL, e.g. https://dev.vantiq.com
targetNamespace

Vantiq Namespace in which to operate, not currently used
handler

The handler block to execute.

Discussion

Constructor for use with all other Vantiq UI and server operations.

Declared In

VantiqUI.h

– serverType:

The serverType method determines if the given server uses Internal (username/password) or OAuth (via Keycloak) for authentication. If a subsequent call to verifyAuthToken indicates the current access token is invalid or doesn’t exist, use the isInternal return to determine if the user should authenticate using authWithInternal or authWithOAuth.

- (void)serverType:(void ( ^ _Nonnull ) ( NSDictionary *_Nullable response ))handler

Parameters

handler

The handler block to execute.

Return Value

response: dictionary containing session information, see Session Information Dictionary Keys above

Discussion

The serverType method determines if the given server uses Internal (username/password) or OAuth (via Keycloak) for authentication. If a subsequent call to verifyAuthToken indicates the current access token is invalid or doesn’t exist, use the isInternal return to determine if the user should authenticate using authWithInternal or authWithOAuth.

Warning: Please also note this method invokes a callback block associated with a network- related block. Because this block is called from asynchronous network operations, its code must be wrapped by a call to dispatch_async(dispatch_get_main_queue(), ^ {…}); to ensure any UI operations are completed on the main thread.

See Also

Declared In

VantiqUI.h

– verifyAuthToken:

The verifyAuthToken method determines if a previously opaquely-saved access token is still valid. If not, then one of authWithInternal or authWithOAuth must be called to generate a new access token.

- (void)verifyAuthToken:(void ( ^ _Nonnull ) ( NSDictionary *_Nullable response ))handler

Parameters

handler

The handler block to execute.

Return Value

response: dictionary containing session information, see Session Information Dictionary Keys above

Discussion

The verifyAuthToken method determines if a previously opaquely-saved access token is still valid. If not, then one of authWithInternal or authWithOAuth must be called to generate a new access token.

Warning: Please also note this method invokes a callback block associated with a network- related block. Because this block is called from asynchronous network operations, its code must be wrapped by a call to dispatch_async(dispatch_get_main_queue(), ^ {…}); to ensure any UI operations are completed on the main thread.

See Also

Declared In

VantiqUI.h

– authWithOAuth:clientId:completionHandler:

The authWithOAuth method retrieves an OAuth access token from a Keycloak server associated with the Vantiq server. This is an opaque access token maintained by the VantiqUI class. This method should be called if the verifyAuthToken returns false in its isInternal callback return.

- (void)authWithOAuth:(NSString *)urlScheme clientId:(NSString *)clientId completionHandler:(void ( ^ _Nonnull ) ( NSDictionary *response ))handler

Parameters

urlScheme

A URL scheme configured in the Keycloak server used to complete the OAuth authentication process
clientId

A Client ID configured in the Keycloak sever used to identify the mobile app
handler

The handler block to execute.

Return Value

response: dictionary containing session information, see Session Information Dictionary Keys above

Discussion

The authWithOAuth method retrieves an OAuth access token from a Keycloak server associated with the Vantiq server. This is an opaque access token maintained by the VantiqUI class. This method should be called if the verifyAuthToken returns false in its isInternal callback return.

Warning: Please also note this method invokes a callback block associated with a network- related block. Because this block is called from asynchronous network operations, its code must be wrapped by a call to dispatch_async(dispatch_get_main_queue(), ^ {…}); to ensure any UI operations are completed on the main thread.

See Also

Declared In

VantiqUI.h

– authWithInternal:password:completionHandler:

The authWithInternal method retrieves an access token from the Vantiq server based on the user-supplied username and password. This is an opaque access token maintained by the VantiqUI class. This method should be called if the verifyAuthToken returns true in its isInternal callback return.

- (void)authWithInternal:(NSString *)username password:(NSString *)password completionHandler:(void ( ^ _Nonnull ) ( NSDictionary *response ))handler

Parameters

username

The username entered by the user
password

The password entered by the user
handler

The handler block to execute.

Return Value

response: dictionary containing session information, see Session Information Dictionary Keys above

Discussion

The authWithInternal method retrieves an access token from the Vantiq server based on the user-supplied username and password. This is an opaque access token maintained by the VantiqUI class. This method should be called if the verifyAuthToken returns true in its isInternal callback return.

Warning: Please also note this method invokes a callback block associated with a network- related block. Because this block is called from asynchronous network operations, its code must be wrapped by a call to dispatch_async(dispatch_get_main_queue(), ^ {…}); to ensure any UI operations are completed on the main thread.

See Also

Declared In

VantiqUI.h

– logout:

The logout method invalidates the current access token and is used to log current user out

- (void)logout:(void ( ^ _Nullable ) ( NSDictionary *_Nullable response ))handler

Parameters

handler

The handler block to execute.

Return Value

response: dictionary containing session information, see Session Information Dictionary Keys above

Discussion

The logout method invalidates the current access token and is used to log current user out

Warning: Please also note this method invokes a callback block associated with a network- related block. Because this block is called from asynchronous network operations, its code must be wrapped by a call to dispatch_async(dispatch_get_main_queue(), ^ {…}); to ensure any UI operations are completed on the main thread.

Declared In

VantiqUI.h

– ensureValidToken:

The ensureValidToken method should be used before any REST operation to attempt to have a valid authorization token. If the current authorization token has expired, this method will attempt to obtain a new token. The caller should check the authValid key of the returned dictionary to determine if the current or new token is valid. If not, then it is up to the application to call either authWithOAuth or authWithInternal depending on what kind of server is in use. The server type is identified using the serverType key of the returned dictionary, which will contain the value @“Internal” or @“OAuth”.

- (void)ensureValidToken:(void ( ^ _Nonnull ) ( NSDictionary *_Nonnull response ))handler

Parameters

handler

The handler block to execute.

Return Value

response: dictionary containing session information, see Session Information Dictionary Keys above

Discussion

The ensureValidToken method should be used before any REST operation to attempt to have a valid authorization token. If the current authorization token has expired, this method will attempt to obtain a new token. The caller should check the authValid key of the returned dictionary to determine if the current or new token is valid. If not, then it is up to the application to call either authWithOAuth or authWithInternal depending on what kind of server is in use. The server type is identified using the serverType key of the returned dictionary, which will contain the value @“Internal” or @“OAuth”.

Warning: Please also note this method invokes a callback block associated with a network- related block. Because this block is called from asynchronous network operations, its code must be wrapped by a call to dispatch_async(dispatch_get_main_queue(), ^ {…}); to ensure any UI operations are completed on the main thread.

Declared In

VantiqUI.h

– formError:error:resultStr:

The formError method is a helper to produce an error string based on the NSHTTPURLResponse and NSError responses from calls made directly to the Vantiq SDK via the v class variable. If no error is returned by the Vantiq SDK, the resultStr will return the empty (@“”) string.

- (BOOL)formError:(NSHTTPURLResponse *_Nonnull)response error:(NSError *_Nullable)error resultStr:(NSString *_Nullable *_Nonnull)resultStr

Parameters

response

The NSHTTPURLResponse returned from the Vantiq SDK call
error

The NEError returned from the Vantiq SDK call
resultStr

Pointer to an NSString instance (note the double indirection)

Return Value

errorStr: localized version of error encountered, if any, or an empty (@“”) string otherwise. Check for zero-length string to indicate success.

Discussion

The formError method is a helper to produce an error string based on the NSHTTPURLResponse and NSError responses from calls made directly to the Vantiq SDK via the v class variable. If no error is returned by the Vantiq SDK, the resultStr will return the empty (@“”) string.

Declared In

VantiqUI.h

– dictionaryToJSONString:

The dictionaryToJSONString method is a helper to produce a string from an dictionary.

- (NSString *_Nonnull)dictionaryToJSONString:(NSDictionary *_Nonnull)dict

Parameters

dict

The dictionary

Return Value

NSString if the string is successfully created, nil otherwise

Discussion

The dictionaryToJSONString method is a helper to produce a string from an dictionary.

Declared In

VantiqUI.h

– JSONStringToDictionary:

The JSONStringToDictionary method is a helper to produce a dictionary from a string.

- (NSDictionary *_Nonnull)JSONStringToDictionary:(NSString *_Nonnull)jsonString

Parameters

dict

The dictionary

Return Value

NSDictionary if the dictionary is successfully created, nil otherwise

Discussion

The JSONStringToDictionary method is a helper to produce a dictionary from a string.

Declared In

VantiqUI.h

+ convertAPNSToken:

The convertAPNSToken method is a helper to convert an APNS device token into an NSString suitable for registering the APNS token for a Vantiq user

+ (NSString *_Nonnull)convertAPNSToken:(NSData *_Nonnull)deviceToken

Parameters

deviceToken

The NSData return from didRegisterForRemoteNotificationsWithDeviceToken

Return Value

NSString version of the APNS token

Discussion

The convertAPNSToken method is a helper to convert an APNS device token into an NSString suitable for registering the APNS token for a Vantiq user

Declared In

VantiqUI.h

– processPushNotification:completionHandler:

The processPushNotification method is used in the iOS app’s AppDelegate didReceiveRemoteNotification method to process APNS notifications.

- (void)processPushNotification:(nonnull NSDictionary *)userInfo completionHandler:(void ( ^ _Nonnull ) ( BOOL notificationHandled ))completionHandler

Parameters

completionHandler

a method to determine whether the Vantiq UI library has handled the notification (as in the case for location-related notifications) or whether the notification must be handled by the calling application. The completion handler’s notificationHandled BOOL indicates whether the Vantiq UI library has handled the notification.

Discussion

The processPushNotification method is used in the iOS app’s AppDelegate didReceiveRemoteNotification method to process APNS notifications.

Declared In

VantiqUI.h

– doBFTasksWithCompletionHandler:completionHandler:

The doBFTasksWithCompletionHandler method is used in the iOS app’s AppDelegate performFetchWithCompletionHandler method to process background fetch calls from iOS

- (void)doBFTasksWithCompletionHandler:(BOOL)alwaysPublish completionHandler:(void ( ^ _Nonnull ) ( BOOL notificationHandled ))completionHandler

Parameters

completionHandler

a method to determine whether the Vantiq UI library has handled the background fetch call or whether the call must be handled by the calling application. The completion handler’s notificationHandled BOOL indicates whether the Vantiq UI library has handled the notification.

Discussion

The doBFTasksWithCompletionHandler method is used in the iOS app’s AppDelegate performFetchWithCompletionHandler method to process background fetch calls from iOS

Declared In

VantiqUI.h

– createInternalUser:password:email:firstName:lastName:phone:completionHandler:

New User Creation

- (void)createInternalUser:(NSString *_Nonnull)username password:(NSString *_Nonnull)password email:(NSString *_Nullable)email firstName:(NSString *_Nullable)firstName lastName:(NSString *_Nullable)lastName phone:(NSString *_Nullable)phone completionHandler:(void ( ^ _Nonnull ) ( NSDictionary *_Nonnull response ))handler

Discussion

New User Creation

Declared In

VantiqUI.m

Other Methods

– publishCurrentLocation:

Location Tracking

- (void)publishCurrentLocation:(NSTimer *)timer

Discussion

Location Tracking

Declared In

VantiqUI.m

– locationManager:didUpdateLocations:

CLLocationManager Delegates

- (void)locationManager:(CLLocationManager *)manager didUpdateLocations:(NSArray *)locations

Discussion

CLLocationManager Delegates

Declared In

VantiqUI.m