# GWSService class documentation

### Authors

Richard Frith-Macdonald (`rfm@gnu.org`)

Version: 25485

Date: 2007-09-14 13:54:55 +0100 (Fri, 14 Sep 2007)

Copyright: (C) 2008 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the GWSService class
2. Software documentation for the GWSService(Delegate) category

# Software documentation for the GWSService class

## GWSService : NSObject

> Declared in:
>   GWSService.h

The GWSService class provides methods for makeing a Remote Procedure Call (RPC) as a web services client.
Instances of this class are (in an ideal world) created and owned by instances the GWSDocument class as it parses a WSDL document, and contain information parsed from that document allowing them to set up the coding mechanism and URL to talk to.
However, standalone instances may be created to allow you to perform RPCs to a web services server when you dont have a fully specified WSDL document (or if the GWSDocument mechanism isn't working).

The class provides a method for making a synchronous RPC (with timeout), or an asynchronous RPC in which the call completion is handled by a delegate.

In order to simply make a synchronous call to a server, all you need to do is write code like:

       GWSService	*server;
       NSDictionary       *result;
       server = [GWSService new];
       [server setURL: @"http://server/path"];
       [server setCoder: [GWSSOAPCoder coder]];
       result = [server invokeMethod: name
                          parameters: p
                               order: o
                             timeout: 30];

Saying that you want to call the specified method ('name') on the server, passing the parameters ('p') in the order they are listed in 'o' and with a 30 second timeout.
If there is a network or http-level error or a timeout, the result will contain GWSErrorKey , otherwise it will contain GWSParametersKey , and GWSOrderKey on success, or GWSFaultKey if the remote end returns a fault.

Method summary

- -completedRPC:
- -webService:buildRequest:parameters:order:
- -webService:didEncode:
- -webService:handleResponse:
- -webService:willDecode:
- -webService:willEncode:
- -webService:willHandleResponse:
- -webService:willSendRequest:
- +description
- +setPerHostPool:
- +setPerHostQMax:
- +setPool:
- +setQMax:
- +setReserve:forHost:
- +setUseIOThreads:
- +setWorkThreads:
- -buildRequest:parameters:order:
- -coder
- -debug
- -delegate
- -documentation
- -headers
- -invokeMethod:parameters:order:timeout:
- -name
- -objectForKey:
- -result
- -sendRequest:parameters:order:timeout:
- -sendRequest:parameters:order:timeout:prioritised:
- -setCoder:
- -setContentType:
- -setDebug:
- -setDelegate:
- -setDocumentation:
- -setHeaders:
- -setObject:forKey:
- -setSOAPAction:
- -setTimeZone:
- -setURL:
- -setURL:certificate:privateKey:password:
- -timeZone
- -timeout:
- -tree
- -webServiceOperation
- -webServiceParameters
- -webServicePort

### description

+ (NSString*) description;
Returns a description of the current asynchronous service queues.

### setPerHostPool:

+ (void) setPerHostPool: (unsigned)max;
Sets maximum active requests to a single host. This is silently limited to be no more than the value set by the +setPool: method.

### setPerHostQMax:

+ (void) setPerHostQMax: (unsigned)max;
Sets maximum queued requests to any single host.
This may be overridden for an individual host by using the +setReserve:forHost: method.

### setPool:

+ (void) setPool: (unsigned)max;
Sets the maximum number of simultaneous active async requests.
This is silently limited to the number of reserved hosts plus one on any attempt to set a lower value.

### setQMax:

+ (void) setQMax: (unsigned)max;
Sets the maximum number of queued async requests.
This may be overridden for an individual host by using the +setReserve:forHost: method.

### setReserve: forHost:

+ (void) setReserve: (unsigned)reserve forHost: (NSString*)host;
Sets a minimum queue size for a specific host... if the queue for this host is not full, an RPC can be queued even if the normal queue limits have been reached.
Setting a non-zero value for a host also reserves a single space in the connection pool for this host, so it is always possible for at least one request to be in progress to the host.
This setting overrides the values defined by the +setPerHostQMax: and +setQMax: methods.

### setUseIOThreads:

+ (void) setUseIOThreads: (BOOL)aFlag;
Sets whether the I/O for requests is to be performed in separate threads rather than the thread which queued the RPC.
Setting this option causes a small group of threads to be created and used to handle the I/O to the remote host.
If no work threads (see +setWorkThreads:) are enabled, the parsing of the response to the request is performed in the same thread that performed the I/O.
In any case, the -completedRPC: callback is sent to the thread which originally queued the RPC.

### setWorkThreads:

+ (void) setWorkThreads: (NSUInteger)count;
Sets the number of threads to be used for the building of request data to be POSTed to the remote system, the parsing of data received in response to that POST, and the callbacks to the delegate involved up to but excluding the execution of the -completedRPC: callback.
By default this is zero... so request data is built, and response data is parsed, in the thread which queues the request.

### buildRequest: parameters: order:

- (NSData*) buildRequest: (NSString*)method parameters: (NSDictionary*)parameters order: (NSArray*)order;
Builds an RPC method call.
The method argument is the name of the operation to be performed, however, if the receiver is owned by a GWSDocument instance which defines multiple ports for the service, the operation name may not be unique, in which case it must be specified as the port type and operation names separated by a full stop (port.operation).
Parameters must be supplied as for the [GWSCoder -buildRequest:parameters:order:] method.

### coder

- (GWSCoder*) coder;
Returns the coder instance used to serialize/deserialize for this instance.

### debug

- (BOOL) debug;
Returns `YES` if debug is enabled, `NO` otherwise. The default value of this is obtained from the GWSDebug user default (or `NO` if no default is set), but may also be adjusted by a call to the -setDebug: method.

### delegate

- (id) delegate;
Returns the delegate previously set by the -setDelegate: method.
The delegate handles completion of asynchronous method calls to the URL specified when the receiver was initialised (if any).

### documentation

- (GWSElement*) documentation;
Return the documentation for the receiver.

### headers

- (NSDictionary*) headers;
Returns the value set by a previous call to the -setHeaders: method.

### invokeMethod: parameters: order: timeout:

- (NSMutableDictionary*) invokeMethod: (NSString*)method parameters: (NSDictionary*)parameters order: (NSArray*)order timeout: (int)seconds;
Calls -sendRequest:parameters:order:timeout:prioritised: and waits for the response.
Parameters must be supplied as for the [GWSCoder -buildRequest:parameters:order:] method.
Returns the response dictionary containing values for the success or failure of the call (as returned by -result).
Returns `nil` if it was impossible to build a valid request from the supplied parameters.

### name

- (NSString*) name;
Returns the name of this WSDL service.

### objectForKey:

- (id) objectForKey: (NSString*)aKey;
Returns the extra information (if any) associated with aKey by an earlier call to the -setObject:forKey: method.

### result

- (NSMutableDictionary*) result;
Returns the result of the last method call, or `nil` if there has been no method call or one is in progress.
The result is as produced by the [GWSCoder -parseMessage:] method.
NB. Any containers (arrays or dictionaries) in the parsed parameters of a success response will be mutable, so you can modify this data structure as you like.

### sendRequest: parameters: order: timeout:

- (BOOL) sendRequest: (NSString*)method parameters: (NSDictionary*)parameters order: (NSArray*)order timeout: (int)seconds;
Calls -sendRequest:parameters:order:timeout:prioritised: for a normal (non urgent) request.

### sendRequest: parameters: order: timeout: prioritised:

- (BOOL) sendRequest: (NSString*)method parameters: (NSDictionary*)parameters order: (NSArray*)order timeout: (int)seconds prioritised: (BOOL)urgent;
Send an asynchronous RPC method call with the specified timeout.
The method argument is the name of the operation to be performed, however, if the receiver is owned by a GWSDocument instance which defines multiple ports for the service, the operation name may not be unique, in which case it must be specified as the port type and operation names separated by a full stop (port.operation).
A delegate should have been set to handle the result of this call, but if one was not set the state of the asynchronous call may be polled by calling the -result method, which will return `nil` as long as the call has not completed.
The call may be cancelled by calling the -timeout: method.
This method returns `YES` if the call was started, `NO` if it could not be started (eg because there is already a call in progress for the receiver, or too many other calls are in progress in total, or because of bad arguments).
NB. For the asynchronous operation to proceed, the current NSRunLoop must be run.
Parameters must be supplied as for the [GWSCoder -buildRequest:parameters:order:] method.

### setCoder:

- (void) setCoder: (GWSCoder*)aCoder;
Sets the coder to be used by the receiver for encoding to XML and decoding from XML. If this is not called, the receiver creates a coder as needed.
Calling this method sets the receiver as the delegate of the coder, or raises an NSInvalidArgumentException if the coder already had a different delegate.

### setContentType:

- (void) setContentType: (NSString*)cType;
Sets the value of the Content-Type header to be sent with a request.
Setting a `nil` or empty string value reverts to the default of text/xml.

### setDebug:

- (void) setDebug: (BOOL)flag;
Specifies whether debug information is enabled. See -debug for more information.

### setDelegate:

- (void) setDelegate: (id)aDelegate;
Sets the delegate object which will receive callbacks when an RPC call completes.
NB. this delegate is not retained, and should be removed before it is deallocated (call -setDelegate: again with a `nil` argument to remove the delegate).

### setDocumentation:

- (void) setDocumentation: (GWSElement*)documentation;
Set the documentation for the receiver.

### setHeaders:

- (void) setHeaders: (NSDictionary*)headers;
Sets extra headers to be sent as part of any HTTP or HTTPS request initiated by this service.
NB. These headers are set *after* the default headers set for content type and user agent etc, so you can override the values normally set by the service.

### setObject: forKey:

- (void) setObject: (id)anObject forKey: (NSString*)aKey;
Tags the service with entra information in the form of anObject references by aKey. if anObject is `nil`, this removes any previous association for aKey.
This facility is not used by the WebServices library, and is present purely so that delegates can associate extra information with the services they are handling.

### setSOAPAction:

- (void) setSOAPAction: (NSString*)action;
Sets the value of the SOAPAction header to be sent with a request.
Setting an `nil` string value suppresses the sending of this header.
Most servers expect two double quotes characters for this, so you should probably set @"\"\"" as the action.

### setTimeZone:

- (void) setTimeZone: (NSTimeZone*)timeZone;
Sets the time zone for use when sending/receiving date/time values.
The XMLRPC specification says that timezone is server dependent so you will need to set it according to the server you are connecting to.
If this is not set, UCT is assumed.

### setURL:

- (void) setURL: (id)url;
Sets up the receiver to make XMLRPC calls to the specified URL.
This method just calls -initWithURL:certificate:privateKey:password: with `nil` arguments for the SSL credentials.

### setURL: certificate: privateKey: password:

- (void) setURL: (id)url certificate: (NSString*)cert privateKey: (NSString*)pKey password: (NSString*)pwd;
Sets up the receiver to make XMLRPC calls to the specified url and (optionally) with the specified SSL parameters.
The url argument may be `nil`, in which case the receiver will be unable to make XMLRPC calls, but can be used to parse incoming requests and build responses.
The url can actually be either a string or an instance of NSURL.
If the SSL credentials are non-nil, connections to the remote server will be authenticated using the supplied certificate so that the remote system knows who is contacting it.
Certificate based authentication currently NOT implemented * for MacOS-X (though it is for GNUstep).
Please could someone let me know how certificate based authentication is done for HTTPS on MacOS-X?

### timeZone

- (NSTimeZone*) timeZone;
Return the time zone currently set.

### timeout:

- (void) timeout: (NSTimer*)t;
Handles timeouts, passing information to delegate ... you don't need to call this method, but you may call it (with `nil` as its argument) in order to cancel an asynchronous request as if it had timed out.

### tree

- (GWSElement*) tree;
Return a tree representation of the receiver for output as part of a WSDL document.

### webServiceOperation

- (NSString*) webServiceOperation;
Returns the name of the current operation being performed, or `nil` if there is no operation in progress.
In conjunction with -webServicePort this method can be used to look up all the details of the WSDL definition of the operation being performed.

### webServiceParameters

- (NSMutableDictionary*) webServiceParameters;
Returns the parameter dictionary of the current operation being performed, or `nil` if there is no operation in progress.
This method can be used to determine exactly what data is being passed in the current operation.

### webServicePort

- (GWSPort*) webServicePort;
Returns the port of the current operation being performed, or `nil` if there is no operation in progress.
In conjunction with -webServiceOperation this method can be used to look up all the details of the WSDL definition of the operation being performed.

# Software documentation for the GWSService(Delegate) category

## GWSService(Delegate)

> Declared in:
>   GWSService.h

Delegates should implement this method in order to be informed of the success or failure of an XMLRPC method call which was initiated by the -sendRequest:parameters:order:timeout: method.
Method summary

- -completedRPC:
- -webService:buildRequest:parameters:order:
- -webService:didEncode:
- -webService:handleResponse:
- -webService:willDecode:
- -webService:willEncode:
- -webService:willHandleResponse:
- -webService:willSendRequest:

### completedRPC:

- (void) completedRPC: (GWSService*)sender;
An empty method provided for subclasses to override.
Called by the sender when an RPC method call completes (either success or failure). The delegate may then call the -result method to retrieve the result of the method call from the sender.

### webService: buildRequest: parameters: order:

- (NSData*) webService: (GWSService*)service buildRequest: (NSString*)method parameters: (NSDictionary*)parameters order: (NSArray*)order;
This method informs the delegate that the service is about to configure itsself to build the request data for a request (by calling the -buildRequest:parameters:order: method). If the delegate method returns an NSData object, the request will not be built and the returned object will be used instead. If the delegate method returns `nil`, the normal request build will go ahead.

### webService: didEncode:

- (GWSElement*) webService: (GWSService*)service didEncode: (GWSElement*)element;
This method is used to inform the delegate of the encoded XML request (a GWSElement instance) which will be sent to the remote system.
The delegate may modify or replace this and must return the replacement value or the modified element tree.

### webService: handleResponse:

- (NSMutableDictionary*) webService: (GWSService*)service handleResponse: (NSData*)response;
This method informs the delegate that the service is about to parse response data from the remote system and place the results in a mutable dictionary.
If the delegate method returns `nil`, the response data will be processed as normal, otherwise the delegate is reponsible for the parsing of the data and production of the results dictionary.

### webService: willDecode:

- (GWSElement*) webService: (GWSService*)service willDecode: (GWSElement*)element;
This method is used to inform the delegate of the GWSElement instance being decoded as the SOAP Envelope, Header, Body, Fault or Method.
The instance to be decoded will contain the children from the document being decoded.
The delegate implementation should return the proposed instance (possibly modified) or a different object that it wishes the coder to use.

### webService: willEncode:

- (GWSElement*) webService: (GWSService*)service willEncode: (GWSElement*)element;
This method is used to inform the delegate of the proposed GWSElement instance used to encode SOAP Envelope, Header, Body, Fault or Method elements.
The proposed instance will not have any children at the point where this method is called (they are added later in the encoding process.
This method may be called with a `nil` value for the element parameter in the case where no Header element would be encoded... in this situation the delegate may return a Header element to be used, or may return some other element, which will be automatically inserted into a standard header.
The delegate implementation should return the proposed instance (possibly modified) or a different object that it wishes the coder to encode instead.
The default implementation returns element.
NB. A Fault or Method will obviously only be provided where the message contain such an element, and the Header will only be provided where the message has been told to contain headers by use of the GWSSOAPMessageHeadersKey in the parameters dictionary.

### webService: willHandleResponse:

- (NSData*) webService: (GWSService*)sender willHandleResponse: (NSData*)data;
An empty method provided for subclasses to override.
Called by the sender when it is about to handle response data from a remote server. The delegate may return a different data item to be decoded and/or take this opportunity to change the service settings before the response is handled.

### webService: willSendRequest:

- (NSData*) webService: (GWSService*)sender willSendRequest: (NSData*)data;
An empty method provided for subclasses to override.
Called by the sender when it is about to send an encoded request to a remote server. The delegate may return a different data item to be sent and/or take this opportunity to change the service settings (such as the URL to send to) before the data is actualy sent.