WLClient Class Reference
| Inherits from | NSObject |
|---|---|
| Declared in | WLClient.h |
Overview
This singleton class exposes methods that you use to communicate with the IBM MobileFirst Platform Server.
Tasks
-
registeredEventSourceIDsproperty -
+ sharedInstance -
– HTTPCookieStorage -
– sendUrlRequest:delegate: -
– wlConnectWithDelegate:cookieExtractor: -
– wlConnectWithDelegate: -
– wlConnectWithDelegate:options: -
– invokeProcedure:withDelegate: -
– invokeProcedure:withDelegate:options: -
– subscribeWithToken:adapter:eventSource:eventSourceID:notificationType:delegate: -
– subscribeWithToken:adapter:eventSource:eventSourceID:notificationType:delegate:options: -
– unsubscribeAdapter:eventSource:delegate: -
– isSubscribedToAdapter:eventSource: -
– updateDeviceToken:delegate: -
– getEventSourceIDFromUserInfo: -
– logActivity: -
– registerChallengeHandler: -
– addGlobalHeader:headerValue: -
– removeGlobalHeader: -
– getGlobalHeaders -
– getChallengeHandlerByRealm: -
– setHeartBeatInterval: -
– getWLDevice -
– transmitEvent: -
– transmitEvent:immediately: -
– setEventTransmissionPolicy: -
– setServerUrl: -
– serverUrl -
– purgeEventTransmissionBuffer -
– login:withDelegate: -
– login:withDelegate:options: -
– logout:withDelegate: -
– lastAccessToken -
– lastAccessTokenForScope: -
– obtainAccessTokenForScope:withDelegate: -
– obtainAccessTokenForScope:withDelegate:options: -
– getRequiredAccessTokenScopeFromStatus:authenticationHeader: -
– logout:withDelegate:options: -
– pinTrustedCertificatePublicKeyFromFile: -
– pinTrustedCertificatePublicKeyFromFiles: -
– setFriendlyName:withCompletionHandler: -
– getFriendlyNameWithCompletionHandler: -
defaultRequestTimeoutIntervalproperty
Properties
defaultRequestTimeoutInterval
Specifies default request time out.
@property (readwrite) NSTimeInterval defaultRequestTimeoutIntervalDeclared In
WLClient.hregisteredEventSourceIDs
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, strong) NSMutableDictionary *registeredEventSourceIDsDeclared In
WLClient.hInstance Methods
HTTPCookieStorage
Retrieves the shared cookie storage that is used by the framework when communicating with the server.
- (NSHTTPCookieStorage *)HTTPCookieStorageReturn Value
The cookie storage object
Declared In
WLClient.haddGlobalHeader:headerValue:
You 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 *)valueParameters
- headerName
The header name/key.
- value
The header value.
Declared In
WLClient.hgetChallengeHandlerByRealm:
Get challenge handler by realm key
- (BaseChallengeHandler *)getChallengeHandlerByRealm:(NSString *)realmDeclared In
WLClient.hgetEventSourceIDFromUserInfo:
This method returns the eventSourceID that the IBM MobileFirst Platform Server sends in the push notification.
- (int)getEventSourceIDFromUserInfo:(NSDictionary *)userInfoParameters
- userInfo
The NSDictionary received in the application:didReceiveRemoteNotification method.
Declared In
WLClient.hgetFriendlyNameWithCompletionHandler:
Gets the display name (“friendly name”) of the device from MobileFirst Server.
- (void)getFriendlyNameWithCompletionHandler:(void ( ^ ) ( WLResponse *response , NSError *error ))completionHandlerParameters
- 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
responseparameter.
Declared In
WLClient.hgetRequiredAccessTokenScopeFromStatus:authenticationHeader:
Determines whether an access token is requested by the server, and returns the required scope, or null if the response is not related to IBM MobileFirst Platform tokens. (Deprecated: in version 7.0)
- (NSString *)getRequiredAccessTokenScopeFromStatus:(int)status authenticationHeader:(NSString *)authHeaderParameters
- status
The status code of the response.
- authenticationHeader
The value of the
WWW-Authenticateheader of the response.
Declared In
WLClient.hinvokeProcedure:withDelegate:
Invokes an adapter procedure. This method is asynchronous.
The response is returned to the callback functions of the provided delegate.
If the call succeeds, onSuccess is called. If it fails, onFailure is called.
- (void)invokeProcedure:(WLProcedureInvocationData *)invocationData withDelegate:(id<WLDelegate>)delegateParameters
- invocationData
The invocation data for the procedure call.
- delegate
The delegate object that is used for the onSuccess and onFailure callback methods.
Discussion
Example: The following code invokes a procedure “getStoriesFiltered” in the adapter “RSSReader” using a parameter “Africa”:
WLProcedureInvocationData *myInvocationData = [[WLProcedureInvocationData alloc] initWithAdapterName:@"RSSReader" procedureName:@"getStoriesFiltered"];
myInvocationData.parameters = [NSArray arrayWithObjects:@"Africa", nil];
Declared In
WLClient.hinvokeProcedure: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 *)optionsParameters
- 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. You can use this object to distinguish different invokeProcedure calls.
Declared In
WLClient.hisSubscribedToAdapter:eventSource:
This method returns true if the current logged-in user on the current device is already subscribed to the adapter and event source. The method checks the information received from the server in the success response for the login request. If the information that is sent from the server is not received, or if there is no subscription, this method returns false.
- (BOOL)isSubscribedToAdapter:(NSString *)adapter eventSource:(NSString *)eventSourceParameters
- adapter
The name of the adapter.
- eventSource
TThe name of the event source.
Declared In
WLClient.hlastAccessToken
Returns the last obtained access token (regardless of scope), or null if no tokens were previosly obtained. (Deprecated: in version 7.0, use [WLAuthorizationManager cachedAuthorizationHeader] instead.)
- (NSString *)lastAccessTokenDeclared In
WLClient.hlastAccessTokenForScope:
Returns the last obtained access token for a specific scope, or null if no tokens were previously obtained
for the given scope. (Deprecated: in version 7.0, use [WLAuthorizationManager cachedAuthorizationHeader] instead.)
- (NSString *)lastAccessTokenForScope:(NSString *)scopeParameters
- scope
The scope of the requested token.
Declared In
WLClient.hlogActivity:
This method reports a user activity for auditing or reporting purposes. (Deprecated: since V7.0. Use OCLogger instead.)
- (void)logActivity:(NSString *)activityTypeParameters
- activityType
A string that identifies the activity.
Discussion
The activity is stored in the application statistics tables (the GADGET_STAT_N tables).
Declared In
WLClient.hlogin:withDelegate:
This method logs in to a specific realm. It is an asynchronous function. You must specify the realm name and a wlDelegate instance for accepting onSuccess and onFailure events. A default timeout of 60 seconds is used for waiting for the server to respond before the request times out.
- (void)login:(NSString *)realmName withDelegate:(id<WLDelegate>)delegateParameters
- realmName
the realm name to log in to
- delegate
implements wlDelegate protocol (which has onSuccess and onFailure methods)
Declared In
WLClient.hlogin:withDelegate:options:
This method logs in to a specific realm. It is an asynchronous function. You must specify the realm name and a wlDelegate instance for accepting onSuccess and onFailure events. 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)login:(NSString *)realmName withDelegate:(id<WLDelegate>)delegate options:(NSDictionary *)optionsParameters
- realmName
the realm name to log in to
- delegate
implements wlDelegate protocol (which has onSuccess and onFailure methods)
- options
in this dictionary - the user puts the key “timeout” (milliseconds)
Declared In
WLClient.hlogout:withDelegate:
This method logs out of a specific realm. It is an asynchronous function. You must specify the realm name and a wlDelegate instance for accepting onSuccess and onFailure events. A default timeout of 60 seconds is used for waiting for the server to respond before the request times out
- (void)logout:(NSString *)realmName withDelegate:(id<WLDelegate>)delegateParameters
- realmName
the realm name to logout from
- delegate
implements wlDelegate protocol (which has onSuccess and onFailure methods)
Declared In
WLClient.hlogout:withDelegate:options:
This method logs out of a specific realm. It is an asynchronous function. You must specify the realm name and a wlDelegate instance for accepting onSuccess and onFailure events. 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)logout:(NSString *)realmName withDelegate:(id<WLDelegate>)delegate options:(NSDictionary *)optionsParameters
- realmName
the realm name to logout from
- delegate
implements wlDelegate protocol (which has onSuccess and onFailure methods)
- options
in this dictionary the user puts the key “timeout” (milliseconds)
Declared In
WLClient.hobtainAccessTokenForScope:withDelegate:
Obtains an oauth 2.0 access token from the IBM MobileFirst Platform server. The token is required in order to send a request to an external server which uses this IBM MobileFirst Platform authentication method. This method is asynchronous; the response is returned to the supplied delegate callback functions. (Deprecated: in version 7.0, use [WLAuthorizationManager obtainAuthorizationHeaderForScope] instead.)
- (void)obtainAccessTokenForScope:(NSString *)scope withDelegate:(id<WLDelegate>)delegateParameters
- delegate
WLDelegate. Implements the callback methods onSuccess and onFailure.
Discussion
Note that there is no need to parse the response for the access token. Instead, use WL.Client.lastAccessToken
or WL.Client.lastAccessTokenForScope in order to get the last obtained token.
Exceptions
- NSException
raised if scope or delegate are nil.
Declared In
WLClient.hobtainAccessTokenForScope:withDelegate:options:
Obtains an oauth 2.0 access token from the IBM MobileFirst Platform server. The token is required in order to send a request to an external server which uses this IBM MobileFirst Platform authentication method. This method is asynchronous; the response is returned to the supplied delegate callback functions. (Deprecated: in version 7.0, use [WLAuthorizationManager obtainAuthorizationHeaderForScope] instead.)
- (void)obtainAccessTokenForScope:(NSString *)scope withDelegate:(id<WLDelegate>)delegate options:(NSDictionary *)optionsParameters
- delegate
WLDelegate. Implements the callback methods onSuccess and onFailure.
- options
A dictionary for which the following key can contain a value: “timeout” - NSNumber. time in miliseconds for this invokeProcedure to wait before failing with WLErrorCodeRequestTimeout
Discussion
Note that there is no need to parse the response for the access token. Instead, use WL.Client.lastAccessToken
or WL.Client.lastAccessTokenForScope in order to get the last obtained token.
Exceptions
- NSException
raised if scope or delegate are nil.
Declared In
WLClient.hpinTrustedCertificatePublicKeyFromFile:
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 *)certificateFilenameParameters
- certificateFilename
the name of the certificate file
Declared In
WLClient.hpinTrustedCertificatePublicKeyFromFiles:
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 *)certificateFilenamesParameters
- certificateFilenames
the list conatining names of the certificate files
Declared In
WLClient.hpurgeEventTransmissionBuffer
Purges the internal event transmission buffer.
The internal event transmission buffer is purged, and all events awaiting transmission are permanently lost.
- (void)purgeEventTransmissionBufferDeclared In
WLClient.hregisterChallengeHandler:
You can use this method to register a custom Challenge Handler, which is a class that inherits from ChallengeHandler. See example 1: Adding a custom Challenge Handler. You can also use this method to override the default Remote Disable / Notify Challenge Handler, by registering a class that inherits from WLChallengeHandler. See example link 2: Customizing the Remote Disable / Notify.
- (void)registerChallengeHandler:(BaseChallengeHandler *)challengeHandlerParameters
- challengeHandler
The Challenge Handler to register.
Declared In
WLClient.hremoveGlobalHeader:
You use this method to remove a global header, which is no longer sent with each request.
- (void)removeGlobalHeader:(NSString *)headerNameParameters
- headerName
The header name to be removed.
Declared In
WLClient.hsendUrlRequest:delegate:
This method uses NSURLConnection to execute the provided NSURLRequest.
- (void)sendUrlRequest:(NSURLRequest *)request delegate:(id)delegateParameters
- request
NSURLRequestobject@param delegate An object that conforms to the
NSURLConnectionDataDelegateorNSURLConnectionDelegateprotocol.
Declared In
WLClient.hserverUrl
Returns the current IBM MobileFirst Platform server URL
- (NSURL *)serverUrlReturn Value
IBM MobileFirst Platform server URL
Declared In
WLClient.hsetEventTransmissionPolicy:
Configures the transmission of events from the client to the server, according to the provided transmission policy.
- (void)setEventTransmissionPolicy:(WLEventTransmissionPolicy *)policyParameters
- policy
The policy instance which will be used.
Declared In
WLClient.hsetFriendlyName:withCompletionHandler:
Sets the display name (“friendly name”) of the device in MobileFirst Server.
- (void)setFriendlyName:(NSString *)friendlyName withCompletionHandler:(void ( ^ ) ( WLResponse *response , NSError *error ))completionHandlerParameters
- friendlyName
The device display name to set.
- completionHandler
A completion-handler callback function.
Declared In
WLClient.hsetHeartBeatInterval:
This method sets the interval, in seconds, at which the client (device) sends a heartbeat signal to the server.
- (void)setHeartBeatInterval:(NSInteger)valParameters
- val
The interval, in seconds, at which the heartbeat signal is sent to the server.
Discussion
You 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.hsetServerUrl:
Sets the IBM MobileFirst Platform server URL to the specified URL.
- (void)setServerUrl:(NSURL *)urlParameters
- 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. - If the app uses push notification, it is the developer's responsibility to unsubscribe from the previous server and subscribe to the new server.
For more information on push notification, see
WLPush.
Example:
[[WLClient sharedInstance] setServerUrl:[NSURL URLWithString:@"http://9.148.23.88:10080/context"]];
Declared In
WLClient.hsubscribeWithToken:adapter:eventSource:eventSourceID:notificationType:delegate:
This method subscribes the application to receive push notifications from the specified event source and adapter.
- (void)subscribeWithToken:(NSData *)deviceToken adapter:(NSString *)adapter eventSource:(NSString *)eventSource eventSourceID:(int)eventSourceID notificationType:(UIRemoteNotificationType)types delegate:(id<WLDelegate>)delegateParameters
- deviceToken
The token received from the method application:didRegisterForRemoteNotificationsWithDeviceToken. Save the device token in case unsubscribedWithToken:adapter:eventSource:delegate: is called.
- adapter
The name of the adapter.
- eventSource
The name of the event source.
- eventSourceID
An ID that you assign to the event source that is returned by the IBM MobileFirst Platform Server with each notification from this event source. You can use the ID in your notification callback function to identify the notification event source. The ID is passed on the notification payload. To save space in the notification payload, pass a short integer, otherwise it is used to pass the adapter and event source names.
- delegate
A standard IBM MobileFirst Platform delegate with onSuccess and onFailure methods to indicate success or failure of the subscription to the IBM MobileFirst Platform Server.
- notificationType
Constants that indicate the types of notifications that the application accepts. For more information, see the link Apple documentation.
Declared In
WLClient.hsubscribeWithToken:adapter:eventSource:eventSourceID:notificationType:delegate:options:
This method subscribes the application to receive push notifications from the specified event source and adapter.
- (void)subscribeWithToken:(NSData *)deviceToken adapter:(NSString *)adapter eventSource:(NSString *)eventSource eventSourceID:(int)eventSourceID notificationType:(UIRemoteNotificationType)types delegate:(id<WLDelegate>)delegate options:(NSDictionary *)optionsParameters
- deviceToken
The token received from the method application:didRegisterForRemoteNotificationsWithDeviceToken. Save the device token in case unsubscribedWithToken:adapter:eventSource:delegate: is called.
- adapter
The name of the adapter.
- eventSource
The name of the event source.
- eventSourceID
An ID that you assign to the event source that is returned by the IBM MobileFirst Platform Server with each notification from this event source. You can use the ID in your notification callback function to identify the notification event source. The ID is passed on the notification payload. To save space in the notification payload, pass a short integer, otherwise it is used to pass the adapter and event source names.
- delegate
A standard IBM MobileFirst Platform delegate with onSuccess and onFailure methods to indicate success or failure of the subscription to the IBM MobileFirst Platform Server.
- options
Optional. This parameter contains data that is passed to the IBM MobileFirst Platform Server, which is used by the adapter.
- notificationType
Constants that indicate the types of notifications that the application accepts. For more information, see the link Apple documentation.
Declared In
WLClient.htransmitEvent:
Equivalent to [transmitEvent: eventJson immediately: NO].
- (void)transmitEvent:(NSMutableDictionary *)eventJsonParameters
- event
the event to be transmitted.
Declared In
WLClient.htransmitEvent:immediately:
Transmits a provided event object to the server.
- (void)transmitEvent:(NSMutableDictionary *)eventJson immediately:(BOOL)immediatelyParameters
- eventJson
The event object that is being transmitted. The event object is either a literate object, or a reference to an object.
- immediately
A boolean flag that indicates whether the transmission should be immediate (
true), or should be based on the transmission policy’s interval (false). If immediate istrue, previously buffered events are transmitted, as well as the current event. The default value isfalse.
Discussion
An event object is added to the transmission buffer. The event object is either transmitted immediately,
if the immediate parameter is set to true, otherwise it is transmitted according to the transmission policy.
For more information, see WL.Client.setEventTransmissionPolicy. One of the properties for the event object might be the device context, which comprises geo-location and WiFi data.
If no device context is transmitted as part of the event, the current device context, as returned by WL.Device.getContext, is added automatically to the event during the transmission process.
Declared In
WLClient.hunsubscribeAdapter:eventSource:delegate:
This method unsubscribes to notifications from the specified event source in the specified adapter.
- (void)unsubscribeAdapter:(NSString *)adapter eventSource:(NSString *)eventSource delegate:(id<WLDelegate>)delegateParameters
- adapter
The name of the adapter.
- eventSource
TThe name of the event source.
- delegate
A standard IBM MobileFirst Platform delegate with the onSuccess and onFailure methods to indicate success or failure of the unsubscription to the IBM MobileFirst Platform Server.
Declared In
WLClient.hupdateDeviceToken:delegate:
This method compares the device token to the one registered in the IBM MobileFirst Platform Server with the current logged-in user and current device. If the device token is different, the method sends the updated token to the server.
- (void)updateDeviceToken:(NSData *)deviceToken delegate:(id<WLDelegate>)delegateParameters
- deviceToken
The token received from the method
application:didRegisterForRemoteNotificationsWithDeviceToken. Save the device token in caseunsubscribedWithToken:adapter:eventSource:delegateis called.
- delegate
A standard IBM MobileFirst Platform delegate with the onSuccess and onFailure methods to indicate success or failure of the unsubscription to the IBM MobileFirst Platform Server.
Discussion
The registered device token from the server is received in the success response for the login request. It is available without the need for an additional server call to retrieve. If a registered device token from the server is not available in the application, this method sends an update to the server with the device token.
Declared In
WLClient.hwlConnectWithDelegate:
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.
- (void)wlConnectWithDelegate:(id<WLDelegate>)delegateParameters
- 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.hwlConnectWithDelegate:cookieExtractor:
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.
- (void)wlConnectWithDelegate:(id<WLDelegate>)delegate cookieExtractor:(WLCookieExtractor *)cookieExtractorParameters
- delegate
A class that conforms to the WLDelegate protocol.
- cookieExtractor
Optional, can be nil. Used to share the cookies between the native code and the web code in the app.
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.hwlConnectWithDelegate: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 *)optionsParameters
- 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