<?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="GWSCoder">
  <head>
    <title>GWSCoder 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 GWSCoder class
      </heading>
      <class name="GWSCoder" super="NSObject">
        <declared>GWSCoder.h</declared>
        <desc>
          <p>
            The GWSCoder class is a semi-abstract class for
            handling encoding to XML and decoding from XML for
            a group of services. <br /> With its standard instance
            variables and helper functions it really just
            provides a convenient mechanism to store data in a
            mutable string, but in conjunction with
            <ref type="class" id="GWSElement">GWSElement</ref>
              it can be used to serialize a tree of elements to a
              string and will parse an XML document ninto a tree
              of elements. <br /> Usually (for RPC and messaging),
              the actual encoding/decoding is handled by a concrete
              subclass. <br /> Instances of these classes are
              not expected to be re-entrant or thread-safe, so you
              need to create an instance for each thread in which
              you are working.
            </p>
            <p>
              With Web Services, the design of the XML
              specification is that services have an
              abstract definition and then also a concrete
              binding to a particular implementation (generally
              SOAP). <br /> Within the GWS classes a similar
              separation is implemented at the level of the
              coders, with the idea being that coders can be
              used separately and their operation can be driven
              entirely from the parameter dictionary passed to
              them (with various special keys in the dictionary
              controlling behavior). <br /> Thus to send a
              message for a particular service, the basic
              parameters are placed in a dictionary by the
              application, and that dictionary is then
              passed to the GWSService which invokes
              extensibility classes to modify the
              dictionary contents by adding additional
              keys/values to tell the coder how to handle
              them. <br /> A programmer wishing to use the coder
              without web services support to, simply send an
              RPC, merely needs to supply any required additional
              key/value pairs themselves rather than having a
              web service do it.
            </p>
        </desc>
        <ivariable type="NSMutableArray*" name="_stack" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <method type="GWSCoder*" factory="yes">
          <sel>coder</sel>
          <desc>
            Creates and returns an autoreleased instance.
            <br /> The default implementation creates an
            instance of the GWSXMLRPCCoder concrete subclass.
          </desc>
        </method>
        <method type="BOOL">
          <sel>compact</sel>
          <desc>
            Return the value set by a prior call to
            <ref type="method" id="-setCompact:">
              -setCompact:
            </ref>
            (or <code>NO</code>... the default).
          </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="NSData*">
          <sel>decodeBase64From:</sel>
          <arg type="NSString*">str</arg>
          <desc>
            Decode the supplied base64 encoded data and return
            the result.
          </desc>
        </method>
        <method type="NSData*">
          <sel>decodeBase64UrlFrom:</sel>
          <arg type="NSString*">str</arg>
          <desc>
            Decode the supplied base64url encoded data and
            return the result.
          </desc>
        </method>
        <method type="NSData*">
          <sel>decodeHexBinaryFrom:</sel>
          <arg type="NSString*">str</arg>
          <desc>
            Decode the supplied hexBinary encoded data and
            return the result. <br /> This is a tolerant parser,
            it accepts lower case hex digits and white space, but it
            does insist on an even number of hexadecimal digits.
            <br /> A decoding failure results in
            <code>nil</code> being returned.
          </desc>
        </method>
        <method type="NSString*">
          <sel>encodeBase64From:</sel>
          <arg type="NSData*">source</arg>
          <desc>
            Take the supplied data and convert it to base64
            encoded text.
          </desc>
        </method>
        <method type="NSString*">
          <sel>encodeBase64UrlFrom:</sel>
          <arg type="NSData*">source</arg>
          <desc>
            Take the supplied data and convert it to base64url
            encoded text.
          </desc>
        </method>
        <method type="NSString*">
          <sel>encodeHexBinaryFrom:</sel>
          <arg type="NSData*">source</arg>
          <desc>
            Encode the supplied data as hexBinary data in the
            canonical form (as per W3 schema recommendations)
            and return the result. <br /> The canonical form uses
            upper case hexadecimal digits.
          </desc>
        </method>
        <method type="NSString*">
          <sel>escapeXMLFrom:</sel>
          <arg type="NSString*">str</arg>
          <desc>
            Take the supplied string and add all necessary escapes
            for XML.
          </desc>
        </method>
        <method type="void">
          <sel>indent</sel>
          <desc>
            Increase the indentation level used while creating
            an XML document.
          </desc>
        </method>
        <method type="NSMutableString*">
          <sel>mutableString</sel>
          <desc>
            Returns the mutable string currently in use for
            encoding.
          </desc>
        </method>
        <method type="void">
          <sel>nl</sel>
          <desc>
            Add a new line to the temporary string currently in use
            for creating an XML document, and add padding on the
            new line so that the next item written is indented
            correctly.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>parseXML:</sel>
          <arg type="NSData*">xml</arg>
          <desc>
            Parses XML data to form a tree of GWSElement
            objects. <br /> This method uses the
            <ref type="class" id="NSXMLParser">NSXMLParser</ref>
              class to perform the actual parsing by acting as a
              delegate to build a tree of
              <ref type="class" id="GWSElement">GWSElement</ref>
                objects, so you may use your own subclass and
                override the NSXMLParser delegate methods to
                provide additional control over the parsing
                operation.
          </desc>
        </method>
        <method type="id">
          <sel>parseXSI:</sel>
          <arg type="NSString*">type</arg>
          <sel>string:</sel>
          <arg type="NSString*">value</arg>
          <desc>
            Parses simple XSI typed string data into Objective-C
            objects. <br /> The <var>type</var> is the name of
            the simple datatype (if <code>nil</code>,
            'xsd:string'). <br /> The <var>value</var>
            is the string to be decoded. <br /> The result returned
            may be an NSString, and NSNumber, an NSDate or an
            NSData object. <br /> A result of <code>nil</code>
            is returned if the <var>value</var> cannot be decoded as
            the specified <var>type</var>.
          </desc>
        </method>
        <method type="void">
          <sel>reset</sel>
          <desc>
            Resets parsing and/or building, releasing any
            temporary data stored during parse etc.
          </desc>
        </method>
        <method type="void">
          <sel>setCompact:</sel>
          <arg type="BOOL">flag</arg>
          <desc>
            Specify whether to generate compact XML (omit
            indentation and other white space and omit
            &lt;string&gt; element markup for XMLRPC).
            <br /> Compact representation saves some space (can
            be important when sent over slow/low bandwidth
            connections), but sacrifices readability.
          </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>unindent</sel>
          <desc>
            Decrease the indentation level used while creating
            an XML document. creating an XML document.
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the GWSJSONCoder class
      </heading>
      <class name="GWSJSONCoder" super="GWSCoder">
        <declared>GWSCoder.h</declared>
        <desc>
          <p>
            The GWSJSONCoder class is a concrete subclass of
            <ref type="class" id="GWSCoder">GWSCoder</ref>
              which implements coding/decoding for JSON texts.
            </p>
            <p>
              The correspondence between JSON values and
              Objective-C objects is as follows -
            </p>
            <list>
              <item>
                <strong>null</strong> is the
                <ref type="class" id="NSNull">NSNull</ref>
                  object.
                </item>
                <item>
                  <strong>true</strong> is an
                  <ref type="class" id="NSNumber">NSNumber</ref>
                    created as a BOOL.
                  </item>
                  <item>
                    <strong>false</strong> is an
                    <ref type="class" id="NSNumber">NSNumber</ref>
                      created as a BOOL.
                    </item>
                    <item>
                      <strong>numeric</strong> is an
                      <ref type="class" id="NSNumber">NSNumber</ref>
                        other than a boolean.
                      </item>
                      <item>
                        <strong>string</strong> is an
                        <ref type="class" id="NSString">NSString</ref>
                          object.
                        </item>
                        <item>
                          <strong>array</strong> is an
                          <ref type="class" id="NSArray">NSArray</ref>
                            object.
                          </item>
                          <item>
                            <strong>object</strong> is an
                            <ref type="class" id="NSDictionary">NSDictionary</ref>object.</item>
                          </list>
                          <p>
                            In addition, any
                            <ref type="class" id="NSDate">NSDate</ref>
                              object is encoded as a string
                              using the
                              <ref type="method" id="-encodeDateTimeFrom:">-encodeDateTimeFrom:</ref> method, and any <ref type="class" id="NSData">NSData</ref>object is encoded as a string by using base64 encoding.</p>
                              <p>
                                If you attempt to use any other type
                                of object in the construction of a
                                JSON text, the
                                <ref type="method" id="-description" class="NSObject">[NSObject -description]</ref> method of that object will be used to create a string, and the resulting object will be encoded as a JSON <em>string</em> element.
                              </p>
                              <p>
                                In particular, the names of members
                                in a JSON <em>object</em> must be
                                strings, so if you provide an
                                <ref type="class" id="NSDictionary">NSDictionary</ref>object to represent a JSON <em>object</em> the keys of the dictionary will be converted to strings where necessary.</p>
                                <p>
                                  The JSON coder supports JSON-RPC
                                  versions 1.0 and 2.0 as well
                                  as supporting simple
                                  encoding/decoding
                                  of JSON documents without JSON-RPC
                                  (where the RPC version is set
                                  to <code>nil</code>).
                                </p>
        </desc>
        <ivariable type="id" name="_jsonID" validity="protected">
          <desc>
            Default request/response ID <br /> <em>Warning</em>
            the underscore at the start of the name of this
            instance variable indicates that, even though it
            is not technically <em>private</em>, it is intended for
            internal use within the package, and you should
            not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSString*" name="_version" validity="protected">
          <desc>
            Not retained... default version <br /> <em>Warning</em>
            the underscore at the start of the name of this
            instance variable indicates that, even though it
            is not technically <em>private</em>, it is intended for
            internal use within the package, and you should
            not use the variable in other code.
          </desc>
        </ivariable>
        <method type="id">
          <sel>RPCID</sel>
          <desc>
            Returns the RPC ID set for this coder. See
            <ref type="method" id="-setRPCID:">
              -setRPCID:
            </ref>
            for details.
          </desc>
        </method>
        <method type="void">
          <sel>appendObject:</sel>
          <arg type="id">o</arg>
          <desc>
            This method appends an object to the mutable string in
            use by the coder.
          </desc>
        </method>
        <method type="NSData*">
          <sel>buildFaultWithCode:</sel>
          <arg type="GWSRPCFaultCode">code</arg>
          <sel>andText:</sel>
          <arg type="NSString*">text</arg>
          <desc>
            Builds a simple fault response.
          </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>
            <p>
              The JSON-RPC format encoding depends on the
              GWSRPCVersionKey or (if that key is
              missing from the <var>parameters</var>
              dictionary) the version set for the coder
              using the
              <ref type="method" id="-setVersion:">
                -setVersion:
              </ref>
              <var>method</var>. <br /> If the version is
              <code>nil</code> (ie not set using
              GWSRPCVersionKey or using
              <ref type="method" id="-setVersion:">
                -setVersion:
              </ref>
              then JSON-RPC is not used and data is encoded as a
              simple JSON document. <br /> Each RPC must have an
              ID, which is set using the GWSRPCIDKey or (if that is
              missing) using the
              <ref type="method" id="-setRPCID:">
                -setRPCID:
              </ref>
              <var>method</var> (if neither supply an
              <strong>id</strong>, and an RPC version is set,
              a null is used). <br /> The
              <ref type="method" id="-setVersion:">
                -setVersion:
              </ref>
              and
              <ref type="method" id="-setRPCID:">
                -setRPCID:
              </ref>
              methods are automatically called when a request
              is parsed, so that the default version and
              <strong>id</strong> of any response built after
              the request was parsed will match those of the
              incoming request. <br /> If JSON-RPC is not
              used, a single parameter is encoded directly as a
              JSON object, while multiple <var>parameters</var>
              are encoded as a struct. <br /> If an encoding
              <var>order</var> is specified (or if the RPC
              version is 1.0) then the encoded result is an
              array and <var>parameters</var> are passed by
              position as items in that array. <br />
              Otherwise, if there is a single parameter
              whose name is the constant GWSJSONResultKey (the
              string 'GWSJSONResult'), then that parameter
              parameter is encoded as the result. <br />
              Otherwise the encoded result is an object, and
              the <var>parameters</var> are passed by name (as
              fields in that object).
            </p>
          </desc>
        </method>
        <method type="NSData*">
          <sel>buildResponse:</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> simply calls the
            <ref type="method" id="-buildRequest:parameters:object:">
              -buildRequest:parameters:object:
            </ref>
            <var>method</var> encoding the supplied
            <var>parameters</var> as the result of the RPC.
          </desc>
        </method>
        <method type="NSString*">
          <sel>encodeDateTimeFrom:</sel>
          <arg type="NSDate*">source</arg>
          <desc>
            Take the supplied date and encode it as a string.
            <br /> This uses the timezone currently set in the
            receiver to determine the time of day encoded.
            <br /> There is no standard for JSON timestamps.
          </desc>
        </method>
        <method type="void">
          <sel>setRPCID:</sel>
          <arg type="id">o</arg>
          <desc>
            Sets the RPC ID... may be any string, number or
            NSNull, though you should not use NSNull or a
            non-integer number. <br /> This value will be
            used as the JSON 'id' when the coder builds a request
            or response, but only if the request/response does not
            contain an GWSRPCIDKey (ie the value supplied in
            the parameters to the method call overrides any value
            set in the coder). <br /> If no RPC version is set,
            this value is unused.
          </desc>
        </method>
        <method type="void">
          <sel>setVersion:</sel>
          <arg type="NSString*">v</arg>
          <desc>
            Sets the json-rpc version. <br /> May be "2.0" or
            "1.0" (any other non-nil value is currently
            considered to be version 1.0) or
            <code>nil</code> if JSON-RPC is not to be used.
            <br /> This value will be used as the JSON RPC
            version when the coder builds a request or
            response, but only if the request/response does
            not contain an GWSRPCVersionKey (ie the value supplied
            in the parameters to the method call overrides any value
            set in the coder).
          </desc>
        </method>
        <method type="NSString*">
          <sel>version</sel>
          <desc>
            Returns the json-rpc version (currently "2.0" or
            "1.0" or <code>nil</code>). <br /> See
            <ref type="method" id="-setVersion:">
              -setVersion:
            </ref>
            for details.
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the GWSSOAPCoder class
      </heading>
      <class name="GWSSOAPCoder" super="GWSCoder">
        <declared>GWSCoder.h</declared>
        <desc>
          <p>
            The GWSSOAPCCoder class is a concrete subclass of
            <ref type="class" id="GWSCoder">GWSCoder</ref>
              which implements coding/decoding for the SOAP
              protocol.
            </p>
            <p>
              Dictionaries passed to/from the SOAP coder
              may contain special keys with the
              <code>GWSSOAP</code> prefix which control the
              coding rather than specifying values to be coded
              (this is in addition to the special
              <ref type="constant" id="GWSOrderKey">
                GWSOrderKey
              </ref>
              used for ordering fields in a complex type). <br />
              See the section on constants for a description of
              what the keys below are used for:
            </p>
            <list>
              <item>
                <ref type="constant" id="GWSSOAPBodyEncodingStyleKey">
                  GWSSOAPBodyEncodingStyleKey
                </ref>
              </item>
              <item>
                <ref type="constant" id="GWSSOAPMessageHeadersKey">
                  GWSSOAPMessageHeadersKey
                </ref>
              </item>
              <item>
                <ref type="constant" id="GWSSOAPNamespaceNameKey">
                  GWSSOAPNamespaceNameKey
                </ref>
              </item>
              <item>
                <ref type="constant" id="GWSSOAPNamespaceURIKey">
                  GWSSOAPNamespaceURIKey
                </ref>
              </item>
              <item>
                <ref type="constant" id="GWSSOAPUseKey">
                  GWSSOAPUseKey
                </ref>
              </item>
            </list>
        </desc>
        <ivariable type="NSString*" name="_style" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="BOOL" name="_useLiteral" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <method type="NSString*">
          <sel>encodeDateTimeFrom:</sel>
          <arg type="NSDate*">source</arg>
          <desc>
            Take the supplied data and return it in the format
            used for an xsd:dateTime typed element. <br /> This
            uses the timezone currently set in the receiver to
            determine the time of day encoded and to provide
            the timezone offset in the encoded string.
          </desc>
        </method>
        <method type="NSString*">
          <sel>operationStyle</sel>
          <desc>
            Returns the style of message being used for
            encoding by the receiver. One of
            <ref type="constant" id="GWSSOAPBodyEncodingStyleDocument">GWSSOAPBodyEncodingStyleDocument</ref> or <ref type="constant" id="GWSSOAPBodyEncodingStyleRPC">GWSSOAPBodyEncodingStyleRPC</ref> or <ref type="constant" id="GWSSOAPBodyEncodingStyleWrapped">GWSSOAPBodyEncodingStyleWrapped</ref>
          </desc>
        </method>
        <method type="void">
          <sel>setOperationStyle:</sel>
          <arg type="NSString*">style</arg>
          <desc>
            Sets the <var>style</var> for this coder to be
            <ref type="constant" id="GWSSOAPBodyEncodingStyleDocument">GWSSOAPBodyEncodingStyleDocument</ref> or <ref type="constant" id="GWSSOAPBodyEncodingStyleRPC">GWSSOAPBodyEncodingStyleRPC</ref> or <ref type="constant" id="GWSSOAPBodyEncodingStyleWrapped">GWSSOAPBodyEncodingStyleWrapped</ref>
          </desc>
        </method>
        <method type="void">
          <sel>setUseLiteral:</sel>
          <arg type="BOOL">use</arg>
          <desc>
            Sets the encoding usage in operation to be 'literal' (
            <code>YES</code>) or encoded (<code>NO</code>).
          </desc>
        </method>
        <method type="BOOL">
          <sel>useLiteral</sel>
          <desc>
            Returns whether the encoding usage in operation is
            'literal' (<code>YES</code>) or 'encoded' (
            <code>NO</code>).
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the GWSXMLRPCCoder class
      </heading>
      <class name="GWSXMLRPCCoder" super="GWSCoder">
        <declared>GWSCoder.h</declared>
        <desc>
          <p>
            The GWSXMLRPCCoder class is a concrete subclass of
            <ref type="class" id="GWSCoder">GWSCoder</ref>
              which implements coding/decoding for the XMLRPC
              protocol.
            </p>
            <p>
              The correspondence between XMLRPC values and
              Objective-C objects is as follows -
            </p>
            <list>
              <item>
                <strong>i4</strong> (or
                <em><strong>int</strong></em>) is an
                <ref type="class" id="NSNumber">NSNumber</ref>
                  other than a real/float or boolean.
                </item>
                <item>
                  <strong>boolean</strong> is an
                  <ref type="class" id="NSNumber">NSNumber</ref>
                    created as a BOOL.
                  </item>
                  <item>
                    <strong>string</strong> is an
                    <ref type="class" id="NSString">NSString</ref>
                      object.
                    </item>
                    <item>
                      <strong>double</strong> is an
                      <ref type="class" id="NSNumber">NSNumber</ref>
                        created as a <strong>float</strong> or
                        <strong>double</strong>.
                      </item>
                      <item>
                        <strong>dateTime.iso8601</strong> is
                        an
                        <ref type="class" id="NSDate">NSDate</ref>
                          object.
                        </item>
                        <item>
                          <strong>base64</strong> is an
                          <ref type="class" id="NSData">NSData</ref>
                            object.
                          </item>
                          <item>
                            <strong>array</strong> is an
                            <ref type="class" id="NSArray">NSArray</ref>object.</item> <item><strong>struct</strong> is an <ref type="class" id="NSDictionary">NSDictionary</ref>object.</item></list>
                            <p>
                              If you attempt to use any other type
                              of object in the construction of an
                              XMLRPC document, the
                              <ref type="method" id="-description" class="NSObject">[NSObject -description]</ref> method of that object will be used to create a string, and the resulting object will be encoded as an XMLRPC <em>string</em> element.
                            </p>
                            <p>
                              In particular, the names of members in
                              a <em>struct</em> must be strings, so
                              if you provide an
                              <ref type="class" id="NSDictionary">NSDictionary</ref>object to represent a <em>struct</em> the keys of the dictionary will be converted to strings where necessary.</p>
        </desc>
        <ivariable type="BOOL" name="_strictParsing" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <method type="NSData*">
          <sel>buildFaultWithCode:</sel>
          <arg type="GWSRPCFaultCode">code</arg>
          <sel>andText:</sel>
          <arg type="NSString*">text</arg>
          <desc>
            Builds a simple fault response.
          </desc>
        </method>
        <method type="NSString*">
          <sel>encodeDateTimeFrom:</sel>
          <arg type="NSDate*">source</arg>
          <desc>
            Take the supplied date and encode it as an XMLRPC
            timestamp. <br /> This uses the timezone
            currently set in the receiver to determine the
            time of day encoded.
          </desc>
        </method>
        <method type="void">
          <sel>setStrictParsing:</sel>
          <arg type="BOOL">isStrict</arg>
          <desc>
            Sets whether parsing requires strict use of plain XML
            elements, or permits attributes and namespaces to
            be attached to them (and ignored).
          </desc>
        </method>
        <method type="BOOL">
          <sel>strictParsing</sel>
          <desc>
            Returns whether parsing requires strict use of
            plain XML elements, or permits attributes and
            namespaces to be attached to them (and ignored).
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the GWSCoder(RPC) category
      </heading>
      <category name="RPC" class="GWSCoder">
        <declared>GWSCoder.h</declared>
        <desc>
          The methods in this category are used to handle web
          services RPC and messaging tasks. Most of these
          methods are implemented by subclasses and cannmot be
          used in the base class.
        </desc>
        <method type="NSData*">
          <sel>buildFaultWithParameters:</sel>
          <arg type="NSDictionary*">parameters</arg>
          <sel>order:</sel>
          <arg type="NSArray*">order</arg>
          <desc>
            Constructs an XML document for an RPC fault
            response with the specified <var>parameters</var>.
            The resulting document is returned as an NSData object.
            <br /> For XMLRCP the <var>parameters</var> should
            be 'faultCode' (an integer), and 'faultString'. <br />
            For JSONRCP the <var>parameters</var> should be 'code'
            (an integer), 'message' (a string), and optionally,
            'data' (any type of item). <br /> As a convenience,
            the <var>parameters</var> 'faultCode' is mapped to
            'code' and 'faultMessage' is mapped to 'message' in
            a JSON fault. <br /> The <var>order</var> array is
            ignored, as is the GWSOrderKey value. <br /> This
            method simply calls
            <ref type="method" id="-setFault:">
              -setFault:
            </ref>
            to say that a fault is being built, then calls
            <ref type="method" id="-buildRequest:parameters:order:">
              -buildRequest:parameters:order:
            </ref>
            with a <code>nil</code> request name, and calls
            <ref type="method" id="-setFault:">
              -setFault:
            </ref>
            again before returning the result. If you override
            this method in a subclass, you should perform the same
            handling of the fault flag. <br /> This method is
            intended for use by applications acting as RPC
            servers.
          </desc>
        </method>
        <method type="NSData*" override="subclass">
          <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>
            Given a <var>method</var> name and a set of
            <var>parameters</var>, this <var>method</var>
            constructs the document for the corresponding
            message or RPC call and returns it as an NSData
            object. <br /> The <var>parameters</var> dictionary
            may be empty or <code>nil</code> if there are no
            <var>parameters</var> to be passed. <br /> The
            <var>order</var> array may be empty or
            <code>nil</code> if the <var>order</var> of the
            <var>parameters</var> is not important, otherwise it
            must contain the names of the <var>parameters</var> in
            the <var>order</var> in which they are to be encoded.
            <br /> If composite data types within the
            <var>parameters</var> dictionary contain fields which
            must be sent in a specific <var>order</var>, the
            dictionary containing those fields may contain a
            key 'GWSOrderKey' whose value is an array containing
            the names of those fields in the <var>order</var> of
            their encoding. <br /> An array keyed on
            'GWSOrderKey' in top level
            <var>parameters</var> dictionary overrides the
            <var>order</var> argument. <br /> A dictionary keyed
            on 'GWSParametersKey' in top level <var>parameters</var>
            dictionary overrides the <var>parameters</var>
            argument (ie the content of the lower level
            dictionary is treated as the container of the
            actual <var>parameters</var>). <br /> The
            <var>method</var> returns <code>nil</code> if passed
            an invalid <var>method</var> name. <br /> This
            <var>method</var> is used internally when sending an
            RPC <var>method</var> call to a remote system, but you
            can also call it yourself.
          </desc>
        </method>
        <method type="NSData*" override="subclass">
          <sel>buildResponse:</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 response with the specified set of
            <var>parameters</var> and returns the document as an
            NSData object. <br /> The <var>method</var> name may
            be <code>nil</code> (and is indeed ignored for XMLRPC)
            where any <var>parameters</var> are not wrapped
            inside a <var>method</var>. <br /> The
            <var>parameters</var> dictionary may be empty or
            <code>nil</code> if there are no
            <var>parameters</var> to be returned (an empty
            <var>parameters</var> element will be created).
            <br /> The <var>order</var> array may be empty or
            <code>nil</code> if the <var>order</var> of the
            <var>parameters</var> is not important, otherwise it
            must contain the names of the <var>parameters</var> in
            the <var>order</var> in which they are to be encoded.
            <br /> This <var>method</var> is intended for use by
            applications acting as RPC servers.
          </desc>
        </method>
        <method type="id">
          <sel>delegate</sel>
          <desc>
            Returns the RPC encoding delegate (if any) set by a
            previous call to the
            <ref type="method" id="-setDelegate:">
              -setDelegate:
            </ref>
            method. <br /> Normally the delegate of a coder is
            the GWSService instance which owns it... a service will
            automatically set itsself as the coder's
            delegate when the coder is set in the service, so
            if you need to have a different delegate, you should set
            it after adding the coder to the service.
          </desc>
        </method>
        <method type="BOOL">
          <sel>fault</sel>
          <desc>
            Returns a flag to say whether this coder is
            encoding/decoding a fault or not.
          </desc>
        </method>
        <method type="NSMutableDictionary*" override="subclass">
          <sel>parseMessage:</sel>
          <arg type="NSData*">data</arg>
          <desc>
            Parses <var>data</var> containing an method call or
            message etc. <br /> The result dictionary may
            contain
            <ref type="constant" id="GWSMethodKey">
              GWSMethodKey
            </ref>
            ,
            <ref type="constant" id="GWSParametersKey">
              GWSParametersKey
            </ref>
            , and
            <ref type="constant" id="GWSOrderKey">
              GWSOrderKey
            </ref>
            on success, or
            <ref type="constant" id="GWSErrorKey">
              GWSErrorKey
            </ref>
            on failure. <br /> NB. Any containers (arrays or
            dictionaries) in the parsed parameters will
            be mutable, so you can modify this <var>data</var>
            structure as you like. <br /> This method is
            intended for the use of server applications.
          </desc>
        </method>
        <method type="void">
          <sel>setDelegate:</sel>
          <arg type="id">delegate</arg>
          <desc>
            Sets a <var>delegate</var> to handle decoding and
            encoding of data items. <br /> The
            <var>delegate</var> should implement the informal
            GWSCoder protocol to either handle the
            encoding/decoding or to inform the coder
            that it won't do it for a particular case.
          </desc>
        </method>
        <method type="void">
          <sel>setFault:</sel>
          <arg type="BOOL">flag</arg>
          <desc>
            Sets the fault <var>flag</var> to indicate that a
            fault is being encoded or decoded.
          </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="NSTimeZone*">
          <sel>timeZone</sel>
          <desc>
            Return the time zone currently set.
          </desc>
        </method>
      </category>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the NSArray(JSON) category
      </heading>
      <category name="JSON" class="NSArray">
        <declared>GWSCoder.h</declared>
        <desc>
          <em>Description forthcoming.</em>
        </desc>
        <method type="NSData*">
          <sel>JSONText</sel>
          <desc>
            Return the receiver encoded as a JSON text in UTF-8
            encoding.
          </desc>
        </method>
      </category>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the NSData(JSON) category
      </heading>
      <category name="JSON" class="NSData">
        <declared>GWSCoder.h</declared>
        <desc>
          <em>Description forthcoming.</em>
        </desc>
        <method type="id">
          <sel>JSONPropertyList</sel>
          <desc>
            Parse the receiver as a JSON property list and return
            the result.
          </desc>
        </method>
      </category>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the NSDictionary(JSON)
        category
      </heading>
      <category name="JSON" class="NSDictionary">
        <declared>GWSCoder.h</declared>
        <desc>
          <em>Description forthcoming.</em>
        </desc>
        <method type="NSData*">
          <sel>JSONText</sel>
          <desc>
            Return the receiver encoded as a JSON text in UTF-8
            encoding.
          </desc>
        </method>
      </category>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the NSObject(GWSCoder)
        category
      </heading>
      <category name="GWSCoder" class="NSObject">
        <declared>GWSCoder.h</declared>
        <desc>
          This informal protocol specifies the methods that a
          coder delegate may implement in order to override
          general encoding/decoding of service arguments.
          <br /> Generally the delegate is a
          <ref type="class" id="GWSService">GWSService</ref>
            instance.
        </desc>
        <method type="id">
          <sel>decodeWithCoder:</sel>
          <arg type="GWSCoder*">coder</arg>
          <sel>item:</sel>
          <arg type="GWSElement*">item</arg>
          <sel>named:</sel>
          <arg type="NSString*">name</arg>
          <desc>
            This method is called to ask the delegate to decode
            the specified element and return the result. If the
            delegate does not wish to decode the element, it
            should simply return <code>nil</code>. <br /> The
            <var>name</var> and ctxt arguments provide context
            for decoding, allowing the delegate to better
            understand how the element should be decoded...
            the ctxt is the parent element of the <var>item</var>
            being decoded, and the <var>name</var> is the
            identifier that will be used for the
            <var>item</var>. <br /> The default implementation
            returns <code>nil</code>.
          </desc>
        </method>
        <method type="BOOL">
          <sel>encodeWithCoder:</sel>
          <arg type="GWSCoder*">coder</arg>
          <sel>item:</sel>
          <arg type="id">item</arg>
          <sel>named:</sel>
          <arg type="NSString*">name</arg>
          <sel>in:</sel>
          <arg type="GWSElement*">ctxt</arg>
          <desc>
            This method is called to ask the delegate to encode
            the specified <var>item</var> with the given
            <var>name</var> into the parent context. <br /> The
            delegate must return <code>NO</code> if it does
            not wish to encode the <var>item</var> itsself,
            otherwise it must return <code>YES</code> after
            adding the new element as a child of <var>ctxt</var>
            . <br /> The <var>name</var> is the key used to identify
            the <var>item</var> in in its current context (normally
            the <var>name</var> of the element it will be encoded
            to). <br /> The default implementation returns
            <code>NO</code>.
          </desc>
        </method>
        <method type="NSString*">
          <sel>webServiceOperation</sel>
          <desc>
            Returns the name of the operation that the receiver
            is being used to implement.
          </desc>
        </method>
        <method type="GWSPort*">
          <sel>webServicePort</sel>
          <desc>
            Returns the port object defining the binding and
            address of the operation being performed.
          </desc>
        </method>
      </category>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the NSObject(GWSSOAPCoder)
        informal protocol
      </heading>
      <category name="GWSSOAPCoder" class="NSObject">
        <declared>GWSCoder.h</declared>
        <desc>
          This informal protocol specifies the methods that a
          coder delegate may implement in order to modify or
          overriding encoding/decoding of SOAP specific
          message components.
        </desc>
        <method type="GWSElement*">
          <sel>coder:</sel>
          <arg type="GWSSOAPCoder*">coder</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 serialised to an
              NSData. <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="GWSElement*">
          <sel>coder:</sel>
          <arg type="GWSSOAPCoder*">coder</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 <var>coder</var> to use. <br /> The
            default implementation returns <var>element</var>.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>coder:</sel>
          <arg type="GWSSOAPCoder*">coder</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
              <var>coder</var> 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>
      </category>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the NSString(JSON) category
      </heading>
      <category name="JSON" class="NSString">
        <declared>GWSCoder.h</declared>
        <desc>
          <em>Description forthcoming.</em>
        </desc>
        <method type="id">
          <sel>JSONPropertyList</sel>
          <desc>
            Parse the receiver as a JSON property list and return
            the result.
          </desc>
        </method>
      </category>
    </chapter>
    <chapter>
      <heading>GWSCoder types</heading>
      <p></p>
      <type type="enum ..." name="GWSRPCFaultCode">
        <desc>
          This type defines standard JSONRPC and XMLRPC fault
          codes. <br /> Use it with the utility methods for
          creating fault respnses. <br /> If you wish to use
          your own error codes (because none of the standard ones
          is suitable), you can use almost any other integer value,
          but the range -32099 to -32000 inclusive is reserved for
          implementation defined server errors (so don't
          use this range).
          <deflist>
            <term><em>GWSRPCParseError</em></term> <desc></desc>
            <term><em>GWSRPCUnsupportedEncoding</em></term>
            <desc></desc>
            <term><em>GWSRPCInvalidCharacter</em></term>
            <desc></desc>
            <term><em>GWSRPCFormatError</em></term>
            <desc></desc>
            <term><em>GWSRPCUnknownMethod</em></term>
            <desc></desc>
            <term><em>GWSRPCInvalidParameter</em></term>
            <desc></desc>
            <term><em>GWSRPCServerError</em></term>
            <desc></desc>
            <term><em>GWSRPCApplicationError</em></term>
            <desc></desc>
            <term><em>GWSRPCSystemError</em></term>
            <desc></desc>
            <term><em>GWSRPCTransportError</em></term>
            <desc></desc>
          </deflist>
        </desc>
      </type>
    </chapter>
  </body>
</gsdoc>
