<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.4//EN" "http://www.gnustep.org/gsdoc-1_0_4.dtd">
<gsdoc base="GWSService">
  <head>
    <title>GWSService class documentation</title>
    <author name="Richard Frith-Macdonald">
      <email address="rfm@gnu.org">
        rfm@gnu.org
      </email>
    </author>
    <version>25485</version>
    <date>2007-09-14 13:54:55 +0100 (Fri, 14 Sep 2007)</date>
    <copy>2008 Free Software Foundation, Inc.</copy>
  </head>
  <body>
    <front><contents /></front>
    <chapter>
      <heading>
        Software documentation for the GWSService class
      </heading>
      <class name="GWSService" super="NSObject">
        <declared>GWSService.h</declared>
        <desc>
          <p>
            The GWSService class provides methods for makeing a
            Remote Procedure Call (RPC) as a web services
            client. <br /> 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. <br /> 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).
          </p>
          <p>
            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.
          </p>
          <p>
            In order to simply make a synchronous call to a server,
            all you need to do is write code like:
          </p>
<example>
   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];
 </example>
          <p>
            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. <br /> If there is a network or
            http-level error or a timeout, the result will
            contain
            <ref type="constant" id="GWSErrorKey">
              GWSErrorKey
            </ref>
            , otherwise it will contain
            <ref type="constant" id="GWSParametersKey">
              GWSParametersKey
            </ref>
            , and
            <ref type="constant" id="GWSOrderKey">
              GWSOrderKey
            </ref>
            on success, or
            <ref type="constant" id="GWSFaultKey">
              GWSFaultKey
            </ref>
            if the remote end returns a fault.
          </p>
        </desc>
        <method type="NSString*" factory="yes">
          <sel>description</sel>
          <desc>
            Returns a description of the current asynchronous
            service queues.
          </desc>
        </method>
        <method type="void" factory="yes">
          <sel>setPerHostPool:</sel>
          <arg type="unsigned">max</arg>
          <desc>
            Sets maximum active requests to a single host. This is
            silently limited to be no more than the value set
            by the <ref type="method" id="+setPool:">+setPool:</ref>
            method.
          </desc>
        </method>
        <method type="void" factory="yes">
          <sel>setPerHostQMax:</sel>
          <arg type="unsigned">max</arg>
          <desc>
            Sets maximum queued requests to any single host.
            <br /> This may be overridden for an individual host
            by using the
            <ref type="method" id="+setReserve:forHost:">
              +setReserve:forHost:
            </ref>
            method.
          </desc>
        </method>
        <method type="void" factory="yes">
          <sel>setPool:</sel>
          <arg type="unsigned">max</arg>
          <desc>
            Sets the maximum number of simultaneous active async
            requests. <br /> This is silently limited to the
            number of reserved hosts plus one on any attempt to
            set a lower value.
          </desc>
        </method>
        <method type="void" factory="yes">
          <sel>setQMax:</sel>
          <arg type="unsigned">max</arg>
          <desc>
            Sets the maximum number of queued async requests.
            <br /> This may be overridden for an individual host
            by using the
            <ref type="method" id="+setReserve:forHost:">
              +setReserve:forHost:
            </ref>
            method.
          </desc>
        </method>
        <method type="void" factory="yes">
          <sel>setReserve:</sel>
          <arg type="unsigned">reserve</arg>
          <sel>forHost:</sel>
          <arg type="NSString*">host</arg>
          <desc>
            Sets a minimum queue size for a specific
            <var>host</var>... if the queue for this
            <var>host</var> is not full, an RPC can be queued
            even if the normal queue limits have been reached.
            <br /> Setting a non-zero value for a
            <var>host</var> also reserves a single space in the
            connection pool for this <var>host</var>, so it
            is always possible for at least one request to be in
            progress to the <var>host</var>. <br /> This
            setting overrides the values defined by the
            <ref type="method" id="+setPerHostQMax:">
              +setPerHostQMax:
            </ref>
            and <ref type="method" id="+setQMax:">+setQMax:</ref>
            methods.
          </desc>
        </method>
        <method type="void" factory="yes">
          <sel>setUseIOThreads:</sel>
          <arg type="BOOL">aFlag</arg>
          <desc>
            Sets whether the I/O for requests is to be performed
            in separate threads rather than the thread which queued
            the RPC. <br /> Setting this option causes a small
            group of threads to be created and used to handle the
            I/O to the remote host. <br /> 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. <br /> In any
            case, the
            <ref type="method" id="-completedRPC:">
              -completedRPC:
            </ref>
            callback is sent to the thread which originally
            queued the RPC.
          </desc>
        </method>
        <method type="void" factory="yes">
          <sel>setWorkThreads:</sel>
          <arg type="NSUInteger">count</arg>
          <desc>
            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
            <ref type="method" id="-completedRPC:">
              -completedRPC:
            </ref>
            callback. <br /> By default this is zero... so
            request data is built, and response data is parsed,
            in the thread which queues the request.
          </desc>
        </method>
        <method type="NSData*">
          <sel>buildRequest:</sel>
          <arg type="NSString*">method</arg>
          <sel>parameters:</sel>
          <arg type="NSDictionary*">parameters</arg>
          <sel>order:</sel>
          <arg type="NSArray*">order</arg>
          <desc>
            Builds an RPC <var>method</var> call. <br /> The
            <var>method</var> 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).
            <br /> Parameters must be supplied as for the
            <ref type="method" id="-buildRequest:parameters:order:" class="GWSCoder">[GWSCoder -buildRequest:parameters:order:]</ref> <var>method</var>. <br />
          </desc>
        </method>
        <method type="GWSCoder*">
          <sel>coder</sel>
          <desc>
            Returns the coder instance used to
            serialize/deserialize for this
            instance. <br />
          </desc>
        </method>
        <method type="BOOL">
          <sel>debug</sel>
          <desc>
            Returns <code>YES</code> if debug is enabled,
            <code>NO</code> otherwise. The default value of this
            is obtained from the GWSDebug user default (or
            <code>NO</code> if no default is set), but may also
            be adjusted by a call to the
            <ref type="method" id="-setDebug:">
              -setDebug:
            </ref>
            method.
          </desc>
        </method>
        <method type="id">
          <sel>delegate</sel>
          <desc>
            Returns the delegate previously set by the
            <ref type="method" id="-setDelegate:">
              -setDelegate:
            </ref>
            method. <br /> The delegate handles completion of
            asynchronous method calls to the URL specified
            when the receiver was initialised (if any).
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>documentation</sel>
          <desc>
            Return the documentation for the receiver.
          </desc>
        </method>
        <method type="NSDictionary*">
          <sel>headers</sel>
          <desc>
            Returns the value set by a previous call to the
            <ref type="method" id="-setHeaders:">
              -setHeaders:
            </ref>
            method.
          </desc>
        </method>
        <method type="NSMutableDictionary*">
          <sel>invokeMethod:</sel>
          <arg type="NSString*">method</arg>
          <sel>parameters:</sel>
          <arg type="NSDictionary*">parameters</arg>
          <sel>order:</sel>
          <arg type="NSArray*">order</arg>
          <sel>timeout:</sel>
          <arg type="int">seconds</arg>
          <desc>
            Calls
            <ref type="method" id="-sendRequest:parameters:order:timeout:prioritised:">-sendRequest:parameters:order:timeout:prioritised:</ref> and waits for the response. <br /> Parameters must be supplied as for the <ref type="method" id="-buildRequest:parameters:order:" class="GWSCoder">[GWSCoder -buildRequest:parameters:order:]</ref> <var>method</var>. <br /> Returns the response dictionary containing values for the success or failure of the call (as returned by -result). <br /> Returns <code>nil</code> if it was impossible to build a valid request from the supplied <var>parameters</var>.
          </desc>
        </method>
        <method type="NSString*">
          <sel>name</sel>
          <desc>
            Returns the name of this WSDL service.
          </desc>
        </method>
        <method type="id">
          <sel>objectForKey:</sel>
          <arg type="NSString*">aKey</arg>
          <desc>
            Returns the extra information (if any) associated
            with <var>aKey</var> by an earlier call to the
            <ref type="method" id="-setObject:forKey:">
              -setObject:forKey:
            </ref>
            method.
          </desc>
        </method>
        <method type="NSMutableDictionary*">
          <sel>result</sel>
          <desc>
            Returns the result of the last method call, or
            <code>nil</code> if there has been no method call or
            one is in progress. <br /> The result is as produced by
            the
            <ref type="method" id="-parseMessage:" class="GWSCoder">
              [GWSCoder -parseMessage:]
            </ref>
            method. <br /> 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.
          </desc>
        </method>
        <method type="BOOL">
          <sel>sendRequest:</sel>
          <arg type="NSString*">method</arg>
          <sel>parameters:</sel>
          <arg type="NSDictionary*">parameters</arg>
          <sel>order:</sel>
          <arg type="NSArray*">order</arg>
          <sel>timeout:</sel>
          <arg type="int">seconds</arg>
          <desc>
            Calls
            <ref type="method" id="-sendRequest:parameters:order:timeout:prioritised:">-sendRequest:parameters:order:timeout:prioritised:</ref> for a normal (non urgent) request.
          </desc>
        </method>
        <method type="BOOL">
          <sel>sendRequest:</sel>
          <arg type="NSString*">method</arg>
          <sel>parameters:</sel>
          <arg type="NSDictionary*">parameters</arg>
          <sel>order:</sel>
          <arg type="NSArray*">order</arg>
          <sel>timeout:</sel>
          <arg type="int">seconds</arg>
          <sel>prioritised:</sel>
          <arg type="BOOL">urgent</arg>
          <desc>
            Send an asynchronous RPC <var>method</var> call with
            the specified timeout. <br /> The <var>method</var>
            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). <br /> 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
            <ref type="method" id="-result">
              -result
            </ref>
            <var>method</var>, which will return <code>nil</code>
            as <strong>long</strong> as the call has not completed.
            <br /> The call may be cancelled by calling the
            <ref type="method" id="-timeout:">
              -timeout:
            </ref>
            <var>method</var>. <br /> This <var>method</var>
            returns <code>YES</code> if the call was started,
            <code>NO</code> 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). <br /> NB. For
            the asynchronous operation to proceed, the current
            <ref type="class" id="NSRunLoop">NSRunLoop</ref>
              must be run. <br /> Parameters must be supplied as
              for the
              <ref type="method" id="-buildRequest:parameters:order:" class="GWSCoder">[GWSCoder -buildRequest:parameters:order:]</ref> <var>method</var>. <br />
          </desc>
        </method>
        <method type="void">
          <sel>setCoder:</sel>
          <arg type="GWSCoder*">aCoder</arg>
          <desc>
            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. <br /> Calling
            this method sets the receiver as the delegate of the
            coder, or raises an NSInvalidArgumentException if
            the coder already had a different delegate.
          </desc>
        </method>
        <method type="void">
          <sel>setContentType:</sel>
          <arg type="NSString*">cType</arg>
          <desc>
            Sets the value of the Content-Type header to be sent
            with a request. <br /> Setting a <code>nil</code> or
            empty string value reverts to the default of
            text/xml.
          </desc>
        </method>
        <method type="void">
          <sel>setDebug:</sel>
          <arg type="BOOL">flag</arg>
          <desc>
            Specifies whether debug information is enabled.
            See <ref type="method" id="-debug">-debug</ref> for
            more information.
          </desc>
        </method>
        <method type="void">
          <sel>setDelegate:</sel>
          <arg type="id">aDelegate</arg>
          <desc>
            Sets the delegate object which will receive callbacks
            when an RPC call completes. <br /> NB. this delegate
            is <em>not</em> retained, and should be removed before
            it is deallocated (call
            <ref type="method" id="-setDelegate:">
              -setDelegate:
            </ref>
            again with a <code>nil</code> argument to remove the
            delegate).
          </desc>
        </method>
        <method type="void">
          <sel>setDocumentation:</sel>
          <arg type="GWSElement*">documentation</arg>
          <desc>
            Set the <var>documentation</var> for the receiver.
          </desc>
        </method>
        <method type="void">
          <sel>setHeaders:</sel>
          <arg type="NSDictionary*">headers</arg>
          <desc>
            Sets extra <var>headers</var> to be sent as part of
            any HTTP or HTTPS request initiated by this service.
            <br /> NB. These <var>headers</var> are set *after*
            the default <var>headers</var> set for content type and
            user agent etc, so you can override the values
            normally set by the service.
          </desc>
        </method>
        <method type="void">
          <sel>setObject:</sel>
          <arg type="id">anObject</arg>
          <sel>forKey:</sel>
          <arg type="NSString*">aKey</arg>
          <desc>
            Tags the service with entra information in the form of
            <var>anObject</var> references by <var>aKey</var>. if
            <var>anObject</var> is <code>nil</code>, this removes
            any previous association for <var>aKey</var>. <br />
            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.
          </desc>
        </method>
        <method type="void">
          <sel>setSOAPAction:</sel>
          <arg type="NSString*">action</arg>
          <desc>
            Sets the value of the SOAPAction header to be sent
            with a request. <br /> Setting an <code>nil</code>
            string value suppresses the sending of this header.
            <br /> Most servers expect two
            <strong>double</strong> quotes characters for
            this, so you should probably set
            @&quot;\&quot;\&quot;&quot; as
            the <var>action</var>. <br />
          </desc>
        </method>
        <method type="void">
          <sel>setTimeZone:</sel>
          <arg type="NSTimeZone*">timeZone</arg>
          <desc>
            Sets the time zone for use when sending/receiving
            date/time values. <br /> The XMLRPC specification
            says that timezone is server dependent so you will
            need to set it according to the server you are
            connecting to. <br /> If this is not set, UCT is
            assumed.
          </desc>
        </method>
        <method type="void">
          <sel>setURL:</sel>
          <arg type="id">url</arg>
          <desc>
            Sets up the receiver to make XMLRPC calls to the
            specified URL. <br /> This method just calls
            <ref type="method" id="-initWithURL:certificate:privateKey:password:">-initWithURL:certificate:privateKey:password:</ref> with <code>nil</code> arguments for the SSL credentials.
          </desc>
        </method>
        <method type="void">
          <sel>setURL:</sel>
          <arg type="id">url</arg>
          <sel>certificate:</sel>
          <arg type="NSString*">cert</arg>
          <sel>privateKey:</sel>
          <arg type="NSString*">pKey</arg>
          <sel>password:</sel>
          <arg type="NSString*">pwd</arg>
          <desc>
            Sets up the receiver to make XMLRPC calls to the
            specified <var>url</var> and (optionally) with
            the specified SSL parameters. <br /> The <var>url</var>
            argument may be <code>nil</code>, in which case
            the receiver will be unable to make XMLRPC calls, but
            can be used to parse incoming requests and build
            responses. <br /> The <var>url</var> can
            actually be either a string or an instance of
            NSURL. <br /> 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.
            <br /> Certificate based authentication currently
            <em>NOT</em> implemented * for MacOS-X (though it is
            for GNUstep). <br /> Please could someone let me know
            how certificate based authentication is done for HTTPS
            on MacOS-X?
          </desc>
        </method>
        <method type="NSTimeZone*">
          <sel>timeZone</sel>
          <desc>
            Return the time zone currently set.
          </desc>
        </method>
        <method type="void">
          <sel>timeout:</sel>
          <arg type="NSTimer*">t</arg>
          <desc>
            Handles timeouts, passing information to delegate
            ... you don't need to call this method, but you
            <em>may</em> call it (with <code>nil</code> as its
            argument) in order to cancel an asynchronous
            request as if it had timed out.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>tree</sel>
          <desc>
            Return a tree representation of the receiver for
            output as part of a WSDL document.
          </desc>
        </method>
        <method type="NSString*">
          <sel>webServiceOperation</sel>
          <desc>
            Returns the name of the current operation being
            performed, or <code>nil</code> if there is no
            operation in progress. <br /> In conjunction with
            <ref type="method" id="-webServicePort">
              -webServicePort
            </ref>
            this method can be used to look up all the details of
            the WSDL definition of the operation being performed.
          </desc>
        </method>
        <method type="NSMutableDictionary*">
          <sel>webServiceParameters</sel>
          <desc>
            Returns the parameter dictionary of the current
            operation being performed, or <code>nil</code> if
            there is no operation in progress. <br /> This method
            can be used to determine exactly what data is being
            passed in the current operation.
          </desc>
        </method>
        <method type="GWSPort*">
          <sel>webServicePort</sel>
          <desc>
            Returns the port of the current operation being
            performed, or <code>nil</code> if there is no
            operation in progress. <br /> In conjunction with
            <ref type="method" id="-webServiceOperation">
              -webServiceOperation
            </ref>
            this method can be used to look up all the details of
            the WSDL definition of the operation being performed.
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the GWSService(Delegate)
        category
      </heading>
      <category name="Delegate" class="GWSService">
        <declared>GWSService.h</declared>
        <desc>
          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
          <ref type="method" id="-sendRequest:parameters:order:timeout:">-sendRequest:parameters:order:timeout:</ref> method. <br />
        </desc>
        <method type="void" override="dummy">
          <sel>completedRPC:</sel>
          <arg type="GWSService*">sender</arg>
          <desc>
            Called by the <var>sender</var> when an RPC method
            call completes (either success or failure). The
            delegate may then call the
            <ref type="method" id="-result">
              -result
            </ref>
            method to retrieve the result of the method call
            from the <var>sender</var>.
          </desc>
        </method>
        <method type="NSData*">
          <sel>webService:</sel>
          <arg type="GWSService*">service</arg>
          <sel>buildRequest:</sel>
          <arg type="NSString*">method</arg>
          <sel>parameters:</sel>
          <arg type="NSDictionary*">parameters</arg>
          <sel>order:</sel>
          <arg type="NSArray*">order</arg>
          <desc>
            This <var>method</var> informs the delegate that the
            <var>service</var> is about to configure itsself to
            build the request data for a request (by calling the
            <ref type="method" id="-buildRequest:parameters:order:">
              -buildRequest:parameters:order:
            </ref>
            <var>method</var>). If the delegate <var>method</var>
            returns an NSData object, the request will not be
            built and the returned object will be used instead.
            If the delegate <var>method</var> returns
            <code>nil</code>, the normal request build will go
            ahead.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>webService:</sel>
          <arg type="GWSService*">service</arg>
          <sel>didEncode:</sel>
          <arg type="GWSElement*">element</arg>
          <desc>
            This method is used to inform the delegate of the
            encoded XML request (a
            <ref type="class" id="GWSElement">GWSElement</ref>
              instance) which will be sent to the remote
              system. <br /> The delegate may modify or replace
              this and must return the replacement value or the
              modified <var>element</var> tree.
          </desc>
        </method>
        <method type="NSMutableDictionary*">
          <sel>webService:</sel>
          <arg type="GWSService*">service</arg>
          <sel>handleResponse:</sel>
          <arg type="NSData*">response</arg>
          <desc>
            This method informs the delegate that the
            <var>service</var> is about to parse
            <var>response</var> data from the remote system and
            place the results in a mutable dictionary. <br /> If
            the delegate method returns <code>nil</code>, the
            <var>response</var> data will be processed as normal,
            otherwise the delegate is reponsible for the
            parsing of the data and production of the results
            dictionary.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>webService:</sel>
          <arg type="GWSService*">service</arg>
          <sel>willDecode:</sel>
          <arg type="GWSElement*">element</arg>
          <desc>
            This method is used to inform the delegate of the
            GWSElement instance being decoded as the SOAP
            Envelope, Header, Body, Fault or Method. <br />
            The instance to be decoded will contain the children
            from the document being decoded. <br /> The delegate
            implementation should return the proposed
            instance (possibly modified) or a different object
            that it wishes the coder to use.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>webService:</sel>
          <arg type="GWSService*">service</arg>
          <sel>willEncode:</sel>
          <arg type="GWSElement*">element</arg>
          <desc>
            This method is used to inform the delegate of the
            proposed
            <ref type="class" id="GWSElement">GWSElement</ref>
              instance used to encode SOAP Envelope, Header,
              Body, Fault or Method elements. <br /> The proposed
              instance will not have any children at the point
              where this method is called (they are added later
              in the encoding process. <br /> This method may be
              called with a <code>nil</code> value for the
              <var>element</var> parameter in the case where no
              Header <var>element</var> would be encoded... in
              this situation the delegate may return a Header
              <var>element</var> to be used, or may return some
              other <var>element</var>, which will be
              automatically inserted into a standard
              header. <br /> The delegate implementation should
              return the proposed instance (possibly modified)
              or a different object that it wishes the coder to
              encode instead. <br /> The default implementation
              returns <var>element</var>. <br /> NB. A Fault or
              Method will obviously only be provided where the
              message contain such an <var>element</var>, and
              the Header will only be provided where the message
              has been told to contain headers by use of the
              <ref type="constant" id="GWSSOAPMessageHeadersKey">
                GWSSOAPMessageHeadersKey
              </ref>
              in the parameters dictionary.
          </desc>
        </method>
        <method type="NSData*" override="dummy">
          <sel>webService:</sel>
          <arg type="GWSService*">sender</arg>
          <sel>willHandleResponse:</sel>
          <arg type="NSData*">data</arg>
          <desc>
            Called by the <var>sender</var> when it is about to
            handle response <var>data</var> from a remote
            server. The delegate may return a different
            <var>data</var> item to be decoded and/or take this
            opportunity to change the service settings
            before the response is handled.
          </desc>
        </method>
        <method type="NSData*" override="dummy">
          <sel>webService:</sel>
          <arg type="GWSService*">sender</arg>
          <sel>willSendRequest:</sel>
          <arg type="NSData*">data</arg>
          <desc>
            Called by the <var>sender</var> when it is about to
            send an encoded request to a remote server. The
            delegate may return a different <var>data</var>
            item to be sent and/or take this opportunity to change
            the service settings (such as the URL to send to)
            before the <var>data</var> is actualy sent.
          </desc>
        </method>
      </category>
    </chapter>
  </body>
</gsdoc>
