WLClient Class Reference

Inherits from	NSObject
Declared in	WLClient.h

This singleton class exposes methods that we use to communicate with the IBM MobileFirst Platform Server.

Tasks

isInitialized property

+ sharedInstance

– HTTPCookieStorage

– wlConnectWithDelegate:

– wlConnectWithDelegate:options:

– sendUrlRequest:delegate:NS_SWIFT_NAME:

– sendUrlRequest:delegate:responseQueue:NS_SWIFT_NAME:

– invokeProcedure:withDelegate:options:

– registerChallengeHandler:NS_SWIFT_NAME:

– addGlobalHeader:headerValue:

– removeGlobalHeader:

– getGlobalHeaders

– getChallengeHandlerBySecurityCheck:

– setHeartBeatInterval:

– setServerUrl:

– serverUrl

– pinTrustedCertificatePublicKeyFromFile:

– pinTrustedCertificatePublicKeyFromFiles:

– setDeviceDisplayName:WithCompletionHandler:

– getDeviceDisplayNameWithCompletionHandler:

  defaultRequestTimeoutInterval
	
	property

Properties

defaultRequestTimeoutInterval

Specifies default request time out.

@property (readwrite) NSTimeInterval defaultRequestTimeoutInterval

Declared In

WLClient.h

isInitialized

Sets an authentication handler that WLClient can use for authentication-related tasks. This method must be called for WLClient to be able to access protected resources in the IBM MobileFirst Platform server.

@property (nonatomic) BOOL isInitialized

Declared In

WLClient.h

Class Methods

sharedInstance

This method returns the shared instance of

WLClient.

+ (WLClient *)sharedInstance

Return Value

WLClient

Declared In

WLClient.h

Instance Methods

HTTPCookieStorage

Retrieves the shared cookie storage that is used by the framework when communicating with the server.

- (NSHTTPCookieStorage *)HTTPCookieStorage

Return Value

The cookie storage object

Declared In

WLClient.h

addGlobalHeader:headerValue:

We use this method to add a global header, which is sent on each request. Each WlRequest instance will use this header as an HTTP header.

- (void)addGlobalHeader:(NSString *)headerName headerValue:(NSString *)value

Parameters

headerName: The header name/key.

value: The header value.

Declared In

WLClient.h

getChallengeHandlerBySecurityCheck:

Get challenge handler by realm key

- (BaseChallengeHandler *)getChallengeHandlerBySecurityCheck:(NSString *)securityCheck

Declared In

WLClient.h

getDeviceDisplayNameWithCompletionHandler:

Gets the display name of the device. The display name is retrieved from the MobileFirst Server registration data.

- (void)getDeviceDisplayNameWithCompletionHandler:(void ( ^ ) ( NSString *deviceDisplayName , NSError *error ))completionHandler

Parameters

completionHandler

A completion-handler callback function. In the case of a successful completion, the display name of the device is returned in the completion handler’s

deviceDisplayName parameter.

Declared In

WLClient.h

getGlobalHeaders

Get a global header.

- (NSDictionary *)getGlobalHeaders

Declared In

WLClient.h

invokeProcedure:withDelegate:options:

This method is similar to invokeProcedure:invocationData:withDelegate, with an additional options parameter to provide more data for this procedure call.

- (void)invokeProcedure:(WLProcedureInvocationData *)invocationData withDelegate:(id<WLDelegate>)delegate options:(NSDictionary *)options

Parameters

invocationData: The invocation data for the procedure call.

delegate: The delegate object that is used for the onSuccess and onFailure callback methods.

options

A map with the following keys and values:

timeout – NSNumber: The time, in milliseconds, for this invokeProcedure to wait before the request fails with WLErrorCodeRequestTimeout. The default timeout is 10 seconds. To disable the timeout, set this parameter to 0.
invocationContext: An object that is returned with WLResponse to the delegate methods. We can use this object to distinguish different invokeProcedure calls.

Declared In

WLClient.h

pinTrustedCertificatePublicKeyFromFile:

Pins the host X509 certificate public key to the client application. Secured calls to the pinned remote host will be checked for a public key match. Secured calls to other hosts containing other certificates will be rejected. Some mobile operating systems might cache the certificate validation check results. Your app must call the certificate pinning method before making a secured request. Calling this method a second time overrides any previous pinning operation.

- (void)pinTrustedCertificatePublicKeyFromFile:(NSString *)certificateFilename

Parameters

certificateFilename: the name of the certificate file

Declared In

WLClient.h

pinTrustedCertificatePublicKeyFromFiles:

Pins a list of host X509 certificates with public key to the client application. Secured calls to the all pinned remote host will be checked for a public key match. Secured calls to other hosts containing other certificates not pinned with app will be rejected. Some mobile operating systems might cache the certificate validation check results. Your app must call the certificate pinning method before making a secured request. Calling this method a second time overrides any previous pinning operation.

- (void)pinTrustedCertificatePublicKeyFromFiles:(NSArray *)certificateFilenames

Parameters

certificateFilenames: the list conatining names of the certificate files

Declared In

WLClient.h

registerChallengeHandler:NS_SWIFT_NAME:

We can use this method to register a challenge handler, which is a class that inherits either from GatewayChallengeHandler or SecurityCheckChallengeHandler.

- (void)registerChallengeHandler:(BaseChallengeHandler *)challengeHandler NS_SWIFT_NAME

Parameters

challengeHandler: The challenge handler to register.

Declared In

WLClient.h

removeGlobalHeader:

We use this method to remove a global header, which is no longer sent with each request.

- (void)removeGlobalHeader:(NSString *)headerName

Parameters

headerName: The header name to be removed.

Declared In

WLClient.h

sendUrlRequest:delegate:NS_SWIFT_NAME:

This method uses

NSURLConnection to execute the provided NSURLRequest.

- (void)sendUrlRequest:(NSURLRequest *)request delegate:(id)delegate NS_SWIFT_NAME

Parameters

request

NSURLRequest object

@param delegate An object that conforms to the

NSURLSessionDataDelegate or NSURLSessionTaskDelegate protocol.

Declared In

WLClient.h

sendUrlRequest:delegate:responseQueue:NS_SWIFT_NAME:

This method uses

NSURLConnection to execute the provided NSURLRequest.

- (void)sendUrlRequest:(NSURLRequest *)request delegate:(id)delegate responseQueue:(dispatch_queue_t)responseQueue NS_SWIFT_NAME

Parameters

request

NSURLRequest object

@param delegate An object that conforms to the

NSURLSessionDataDelegate or NSURLSessionTaskDelegate protocol.
@param responseQueue
An callback queue of type dispatch_queue_t

Declared In

WLClient.h

serverUrl

Returns the current IBM MobileFirst Platform server URL.

- (NSURL *)serverUrl

Return Value

IBM MobileFirst Platform server URL

Declared In

WLClient.h

setDeviceDisplayName:WithCompletionHandler:

Sets the display name of the device. The display name is stored in the MobileFirst Server registration data.

- (void)setDeviceDisplayName:(NSString *)deviceDisplayName WithCompletionHandler:(void ( ^ ) ( NSError *error ))completionHandler

Parameters

deviceDisplayName: The device display name to set.

completionHandler: A completion-handler callback function.

Declared In

WLClient.h

setHeartBeatInterval:

This method sets the interval, in seconds, at which the client (device) sends a heartbeat signal to the server.

- (void)setHeartBeatInterval:(NSInteger)val

Parameters

val: The interval, in seconds, at which the heartbeat signal is sent to the server.

Discussion

We use the heartbeat signal to prevent a session with the server from timing out because of inactivity. Typically, the heartbeat interval has a value that is less than the server session timeout.The server session timeout is defined in the worklight.properties file. By default, the value of the heartbeat interval is set to 420 seconds (7 minutes). To disable the heartbeat signal, set a value that is less than, or equal to zero.

Note: The client sends a heartbeat signal to the server only when the application is in the foreground. When the application is sent to the background, the client stops sending heartbeat signals. The client resumes sending heartbeat signals when the application is brought to the foreground again.

Declared In

WLClient.h

setServerUrl:

Sets the IBM MobileFirst Platform server URL to the specified URL.

- (void)setServerUrl:(NSURL *)url

Parameters

url: The URL of the new server, including protocol, IP, port, and context.

Discussion

Changes the IBM MobileFirst Platform server URL to the new URL and cleans the HTTP client context. After calling this method, the application is not logged in to any server.

Notes:

The responsibility for checking the validity of the URL is on the developer.

For hybrid applications: This call does not clean the HTTP client context saved in JavaScript. For hybrid applications, it is recommended to set the server URL by using the following JavaScript function:

WL.App.setServerUrl.

Example:

    [[WLClient sharedInstance] setServerUrl:[NSURL URLWithString:@"http://9.148.23.88:10080/context"]];

Declared In

WLClient.h

wlConnectWithDelegate:

- (void)wlConnectWithDelegate:(id<WLDelegate>)delegate

Parameters

delegate: A class that conforms to the WLDelegate protocol.

Discussion

If the server returns a successful response, the

onSuccess method is called. If an error occurs, the onFailure method is called.

Note: This method must be called before any other WLClient method that calls the server, such as

logActivity and invokeProcedure.

Declared In

WLClient.h

wlConnectWithDelegate:options:

This method uses the connection properties and the application ID from the worklight.plist file to initialize communication with the IBM MobileFirst Platform Server. The server checks the validity of the application version. This method accepts a “timeout” key in its options parameter - (NSNumber) Number of milliseconds to wait for the server response before the request times out.

- (void)wlConnectWithDelegate:(id<WLDelegate>)delegate options:(NSDictionary *)options

Parameters

delegate: A class that conforms to the WLDelegate protocol.

options: Optional, can be nil. Used to set the timeout while connecting to the server and/or to set the application userId which is used by Push service. In this dictionary the user puts key “timeout” (milliseconds) to set the timeout or the key “appUserId” (NSString) to set the application UserId.

Discussion

If the server returns a successful response, the

onSuccess method is called. If an error occurs, the onFailure method is called.

Note: This method must be called before any other WLClient method that calls the server, such as

logActivity and invokeProcedure.

Declared In

WLClient.h