Objective-C API Library Reference  4.3.0-42-g45f162a
 All Classes Functions Typedefs Properties Pages
Public Functions | Properties | List of all members
PWWebClient Class Reference

The PWWebClient class manages communications between the client application and the service application via PureWeb's middle tier. The critical functionality provided by this class includes:

About Command Types
The queueCommand methods in this class expect a "type" parameter. This is the name of the command. It must match exactly the name as it was provided when the command's handler was first registered using the service-side AddUiHandler or AddIoHandler methods. For more information, refer to the service API documentation for the CommandManager class.

Constructors

(id) - initWithFramework:
 

Public Functions

(void) - addMultipartHandler:withObject:multipartHandlerSelector:
 
(void) - clearCommands
 
(void) - connect:
 
(void) - connect:dictionary:
 
(void) - connect:xml:
 
(void) - disconnect
 
(void) - disconnectSynchronous
 
(NSString *) - getParameter:withDefaultValue:
 
(void) - getSessionShareUrlAsyncWithPassword:shareDescriptor:shareTimeout:completion:
 
(void) - invalidateSessionShareUrlAsync:completion:
 
(void) - joinSession:sharePassword:
 
(void) - queueCommand:
 
(void) - queueCommand:isDeferredCommand:
 
(void) - queueCommand:onComplete:
 
(void) - queueCommand:withParameters:
 
(void) - queueCommand:withParameters:isDeferredCommand:
 
(void) - queueCommand:withParameters:isDeferredCommand:onComplete:
 
(void) - queueCommand:withParameters:onComplete:
 
(void) - removeMultipartHandler:
 
(void) - resumeServerUpdate
 
(void) - retrieveObject:onComplete:
 
(void) - suppressServerUpdate
 

Properties

NSException * acquireException
 
PWAuthorizationInfoauthorizationInfo
 
id< PWWebClientDelegatedelegate
 
BOOL disconnectionInProgress
 
BOOL filterCommands
 
NSString * href
 
BOOL isConnected
 
PWEventPublisher * isConnectedChanged
 
BOOL isSecureURL
 
BOOL isStalled
 
PWEventPublisher * isStalledChanged
 
PWTimedEventProfilerlatency
 
NSUInteger maximumRedirectDepth
 
PWRateProfilermbps
 
NSTimeInterval minimumRequestInterval
 
PWEventPublisher * minimumRequestIntervalChanged
 
NSDictionary * parameters
 
PWEventTimerProfilerrequestBuilding
 
NSException * requestException
 
NSTimeInterval requestTimeout
 
NSException * responseException
 
PWEventTimerProfilerresponseHandlers
 
PWEventTimerProfilerresponseParsing
 
PWGuidsessionId
 
PWSessionState sessionState
 
PWEventPublisher * sessionStateChanged
 
NSString * sessionUrl
 
NSString * url
 

Methods Descriptions

- (void) addMultipartHandler: (NSString *)  name
withObject: (id)  target
multipartHandlerSelector: (SEL)  multipartHandler 

Registers a multipart selector with no completion selector.

Parameters
nameThe selector name.
targetThe target object that will be notified.
multipartHandlerThe multipart selector.
- (void) clearCommands

Clears queued commands.

- (void) connect: (NSString *)  href

Connects your iOS client to the service application. More specifically, it connects to a process on the service. The href parameter can be expressed in different ways, depending on whether you want to request acquisition of a new session and startup of a new process, or to connect to an existing process.

To request acquisition of a new session, specify the URL path as /app; you may also include additional parameters in the query string.

To request connection to an existing process, specify the URL path as /app/display/session/process; you may also include additional parameters in the query string.

Parameters
hrefThe URL of the service application to which the client will connect.
- (void) connect: (NSString *)  href
dictionary: (NSDictionary *)  dictionary 

Connects your iOS client to the service application, providing additional custom connection parameters as a dictionary.

Parameters
hrefThe URL of the service application to which the client will connect.
dictionaryAn NSDictionary containing the connection parameters.
- (void) connect: (NSString *)  href
xml: (PWXmlElement *)  xml 

Connects your iOS client to the service application, providing additional custom connection parameters as a PWXmlElement object.

Parameters
hrefThe URL of the service application to which the client will connect.
xmlA PWXmlElement object containing the connection parameters.
- (void) disconnect

Disconnects the client from the service application. The disconnect is asynchronous.

- (void) disconnectSynchronous

Disconnects the client from the service application. The disconnect is synchronous.

- (NSString *) getParameter: (NSString *)  key
withDefaultValue: (NSString *)  defaultValue 

Returns the value of the specified query parameter if present; otherwise, returns the specified default value.

- (void) getSessionShareUrlAsyncWithPassword: (NSString *)  password
shareDescriptor: (NSString *)  descriptor
shareTimeout: (NSInteger)  timeout
completion: (PWCreateAppShareCompletion)  completion 

Requests a session share URL from the service, for collaboration purposes; this request is asynchronous.

Parameters
passwordThe password that the participants will need to enter when using the share URL to join a session.
descriptorThe descriptor; this parameter is not used at this time and can be safely ignored.
timeoutThe length of time (in milliseconds) that the share URL will remain valid for new collaborators to join (collaborators already in the session are not affected when this timeout lapses).
completionThe completion block to execute when the share URL is received, or the error void ^(NSURL shareURL, NSError *error)
- (id) initWithFramework: (PWFramework *)  framework

Initiates a new instance of the PWWebClient class.

- (void) invalidateSessionShareUrlAsync: (NSString *)  shareUrl
completion: (PWDeleteAppShareCompletion)  completion 

Invalidates the specified session share URL asynchronously. When a share URL is invalidated, new collaboration participants are not allowed to access the URL, but this has no impact on existing participants already in the session.

Parameters
shareUrlThe share URL to invalidate.
completionThe function that will be called once the share URL has been rendered invalid.
- (void) joinSession: (NSString *)  href
sharePassword: (NSString *)  sharePassword 

Connects to an existing collaboration session using a share URL.

Parameters
hrefThe URL of the service application to connect to.
sharePasswordThe password set for the collaboration session.
- (void) queueCommand: (NSString *)  type

Adds the specified command, including any of its arguments, to the outgoing command queue, which delivers the commands to the service application.

Parameters
typeThe name of the command; this must match exactly the name as it was provided when the command's handler was first registered on the service.
- (void) queueCommand: (NSString *)  type
isDeferredCommand: (BOOL)  isDeferredCommand 

Adds the specified command, including any of its arguments, to the outgoing command queue, which delivers the commands to the service application.

Parameters
typeThe name of the command; this must match exactly the name as it was provided when the command's handler was first registered on the service.
isDeferredCommandA Boolean value that indicates whether this command should trigger a new request. Use NO if this is a normal command that should be sent immediately, otherwise use YES.
- (void) queueCommand: (NSString *)  type
onComplete: (void(^)(PWCommandResponseEventArgs *))  onComplete 

Adds the specified command, including any of its arguments, to the outgoing command queue, which delivers the commands to the service application. Also invokes the specified handler when complete.

Parameters
typeThe name of the command; this must match exactly the name as it was provided when the command's handler was first registered on the service.
onCompleteThe handler block to invoke on completion.
- (void) queueCommand: (NSString *)  type
withParameters: (NSDictionary *)  parameters 

Adds the specified command, including any of its arguments, to the outgoing command queue, which delivers the commands to the service application. The key value pairs in the parameters dictionary are added as element children of the command, in the form <key>value</key>.

Parameters
typeThe name of the command; this must match exactly the name as it was provided when the command's handler was first registered on the service.
parametersThe command parameters, expressed as key-value pairs.
- (void) queueCommand: (NSString *)  type
withParameters: (NSDictionary *)  parameters
isDeferredCommand: (BOOL)  isDeferredCommand 

Adds the specified command, including any of its arguments, to the outgoing command queue, which delivers the commands to the service application. The key value pairs in the parameters dictionary are added as element children of the command, in the form <key>value</key>.

Parameters
typeThe name of the command; this must match exactly the name as it was provided when the command's handler was first registered on the service.
parametersThe command parameters, expressed as key-value pairs.
isDeferredCommandA Boolean value that indicates whether this command should trigger a new request. Use NO if this is a normal command that should be sent immediately, otherwise use YES.
- (void) queueCommand: (NSString *)  type
withParameters: (NSDictionary *)  parameters
isDeferredCommand: (BOOL)  isDeferredCommand
onComplete: (void(^)(PWCommandResponseEventArgs *))  onComplete 

Adds the specified command, including any of its arguments, to the outgoing command queue, which delivers the commands to the service application. Also invokes the specified handler when complete. The key value pairs in the parameters dictionary are added as element children of the command, in the form <key>value</key>.

Parameters
typeThe name of the command; this must match exactly the name as it was provided when the command's handler was first registered on the service.
parametersThe command parameters, expressed as key-value pairs.
isDeferredCommandA Boolean value to indicate whether this command should trigger a new request. Use NO if this is a normal command that should be sent immediately, otherwise use YES.
onCompleteThe handler block to invoke on completion.
- (void) queueCommand: (NSString *)  type
withParameters: (NSDictionary *)  parameters
onComplete: (void(^)(PWCommandResponseEventArgs *))  onComplete 

Adds the specified command, including any of its arguments, to the outgoing command queue, which delivers the commands to the service application. Also invokes the specified handler when complete. The key value pairs in the parameters dictionary are added as element children of the command, in the form <key>value</key>.

Parameters
typeThe name of the command; this must match exactly the name as it was provided when the command's handler was first registered on the service.
parametersThe command parameters, expressed as key-value pairs.
onCompleteThe handler block to invoke on completion.
- (void) removeMultipartHandler: (NSString *)  name

Removes the multipart handler with the specified name.

- (void) resumeServerUpdate

Resumes sending updates to the service application; needed to cancel a previously called suppressServerUpdate.

- (void) retrieveObject: (PWGuid *)  resourceId
onComplete: (PWRetrieveResourceCompletionHandler)  onComplete 

Retrieves a resource (binary object) created by the service application. For more information, refer to the ResourceManager class in the service API.

Parameters
resourceIdThe unique identifier assigned to the resource by the service.
onCompleteThe handler to invoke upon receiving the resource, if applicable.
- (void) suppressServerUpdate

Stops sending updates to the service application, until resumeServerUpdate is called.

Properties Descriptions

- (NSException*) acquireException
readnonatomicstrong

The last acquire (connection) exception.

- (PWAuthorizationInfo*) authorizationInfo
readwritenonatomicstrong

Authentication information about a user, such as username and password.

- (id<PWWebClientDelegate>) delegate
readwritenonatomicunsafe_unretained

The instance of PWClientDelegate.

- (BOOL) disconnectionInProgress
readnonatomicassign

A Boolean value that indicates whether disconnection is in progress.

- (BOOL) filterCommands
readwritenonatomicassign

A Boolean value that enables or disables client-side command filtering. For more information, see the PWCommandFilterProtocol.

- (NSString*) href
readnonatomicstrong

The URL address of the service application to which the client will connect.

- (BOOL) isConnected
readnonatomicassign

A Boolean value that indicates whether the client is connected.

- (PWEventPublisher*) isConnectedChanged
readnonatomicstrong

The event that gets dispatched when the client connects to or disconnects from the service application.

- (BOOL) isSecureURL
readnonatomicassign

A Boolean value that indicates whether a URL is secure.

- (BOOL) isStalled
readnonatomicassign

A Boolean value that indicates whether the client connection is stalled.

- (PWEventPublisher*) isStalledChanged
readnonatomicstrong

The event that gets dispatched when the connection to the service application stalls (possibly indicating the connection has been lost), or recovers from a stall.

- (PWTimedEventProfiler*) latency
readnonatomicstrong

A profiler that measures the latency between the client and the service application.

- (NSUInteger) maximumRedirectDepth
readwritenonatomicassign

The maximum redirect depth when connecting.

- (PWRateProfiler*) mbps
readnonatomicstrong

A profiler that measures the network throughput between the client and the service application.

- (NSTimeInterval) minimumRequestInterval
readwritenonatomicassign

The minimum amount of time that must elapse between requests.

- (PWEventPublisher*) minimumRequestIntervalChanged
readnonatomicstrong

The event that gets dispatched when the value for the minimum request interval is changed; this is the minimum amount of time that must elapse between subsequent requests.

- (NSDictionary*) parameters
readnonatomicstrong

A list of the URL parameters.

- (PWEventTimerProfiler*) requestBuilding
readnonatomicstrong

A profiler that measures the time required to build requests to be sent to the service (including filtering).

- (NSException*) requestException
readnonatomicstrong

The last request exception.

- (NSTimeInterval) requestTimeout
readwritenonatomicassign

A timeout for all HTTP requests.

- (NSException*) responseException
readnonatomicstrong

The last response exception.

- (PWEventTimerProfiler*) responseHandlers
readnonatomicstrong

A profiler that measures the time taken to process incoming data by all multipart response handlers.

- (PWEventTimerProfiler*) responseParsing
readnonatomicstrong

A profiler that measures the time taken to parse multipart messages from the data stream received from the service.

- (PWGuid*) sessionId
readnonatomicstrong

The unique identifier of a session.

- (PWSessionState) sessionState
readnonatomicassign

A value indicating the current state of the session, such as Active, Disconnected, or Failed.

- (PWEventPublisher*) sessionStateChanged
readnonatomicstrong

The event that gets dispatched when the session state changes.

- (NSString*) sessionUrl
readnonatomicstrong

The URL of the service application to which the client is connected.

- (NSString*) url
readnonatomicstrong

A URL without any query parameters (in other words, the part of the URL that precedes the question mark).