<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//EN" "http://www.gnustep.org/gsdoc-1_0_3.dtd">
<gsdoc base="WebServerBundles">
  <head>
    <title>WebServerBundles class documentation</title>
    <author name="Richard Frith-Macdonald">
      <email address="rfm@gnu.org">
        rfm@gnu.org
      </email>
    </author>
    <version>28737</version>
    <date>2009-09-25 11:17:32 +0100 (Fri, 25 Sep 2009)</date>
    <copy>2009 Free Software Foundation, Inc.</copy>
  </head>
  <body>
    <front><contents /></front>
    <chapter>
      <heading>
        Software documentation for the WebServerBundles class
      </heading>
      <class name="WebServerBundles" super="NSObject">
        <declared>WebServerBundles.h</declared>
        <conform>WebServerDelegate</conform>
        <desc>
          WebServerBundles is an example delegate for
          the WebServer class. <br /> This is intended to act as a
          convenience for a scheme where the WebServer
          instance in a program is configured by values
          obtained from the user defaults system, and incoming
          requests may be handled by different delegate
          objects depending on the path information supplied in
          the request. The WebServerBundles instance is responsible
          for loading the bundles (based on information in the
          WebServerBundles dictionary in the user
          defaults system) and for forwarding requests to the
          appropriate bundles for processing. <br /> If a
          request comes in which is not an exact match for the
          path of any handler, the request path is repeatedly
          shortened by chopping off the last path component
          until a matching handler is found. <br /> The paths in
          the dictionary must <em>not</em> end with a slash... an
          empty string will match all requests which do not match
          a handler with a longer path.
<example>
 </example>
        </desc>
        <ivariable type="NSMutableDictionary*" name="_handlers" 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="WebServer*" name="_http" 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="BOOL">
          <sel>defaultsUpdate:</sel>
          <arg type="NSNotification*">aNotification</arg>
          <desc>
            Handle a notification that the defaults have been
            updated... change WebServer configuration if
            necessary. <br />
            <list>
              <item>
                WebServerPort must be used to specify the
                port that the server listens on. See
                <ref type="method" id="-setPort:secure:" class="WebServer">[WebServer -setPort:secure:]</ref> for details.
              </item>
              <item>
                WebServerSecure may be supplied to make
                the server operate as an HTTPS server rather than
                an HTTP server. See
                <ref type="method" id="-setPort:secure:" class="WebServer">[WebServer -setPort:secure:]</ref> for details.
              </item>
              <item>
                WebServerBundles is a dictionary keyed
                on path strings, whose values are dictionaries, each
                containing per-handler configuration
                information and the name of the bundle
                containing the code to handle requests sent
                to the path. NB. the bundle name listed should omit
                the <code>.bundle</code> extension.
              </item>
            </list>
            Returns <code>YES</code> on success,
            <code>NO</code> on failure (if the port of the
            WebServer cannot be set).
          </desc>
        </method>
        <method type="id">
          <sel>handlerForPath:</sel>
          <arg type="NSString*">path</arg>
          <sel>info:</sel>
          <arg type="NSString**">info</arg>
          <desc>
            Returns the handler to be used for the specified
            <var>path</var>, or <code>nil</code> if there is no
            handler available. <br /> If the <var>info</var>
            argument is non-null, it is used to return
            additional information, either the
            <var>path</var> actually matched, or an error string.
          </desc>
        </method>
        <method type="NSMutableDictionary*">
          <sel>handlers</sel>
          <desc>
            Return dictionary of all handlers by name (path in
            request which maps to that handler instance).
          </desc>
        </method>
        <method type="WebServer*">
          <sel>http</sel>
          <desc>
            Return the WebServer instance that the receiver is
            acting as a delegate for.
          </desc>
        </method>
        <method type="id" init="yes">
          <sel>initAsDelegateOf:</sel>
          <arg type="WebServer*">http</arg>
          <desc>
            Initialises the receiver as the delegate of
            HTTP and configures the WebServer based upon the
            settings found in the user defaults system by
            using the
            <ref type="method" id="-defaultsUpdate:">
              -defaultsUpdate:
            </ref>
            method.
          </desc>
        </method>
        <method type="BOOL">
          <sel>processRequest:</sel>
          <arg type="GSMimeDocument*">request</arg>
          <sel>response:</sel>
          <arg type="GSMimeDocument*">response</arg>
          <sel>for:</sel>
          <arg type="WebServer*">http</arg>
          <desc>
            <p>
              Handles an incoming <var>request</var> by
              forwarding it to another handler. <br /> If a
              direct mapping is available from the path in the
              <var>request</var> to an existing handler, that
              handler is used to process the <var>request</var>
              . Otherwise, the WebServerBundles dictionary (obtained
              from the defaults system) is used to map the
              <var>request</var> path to configuration
              information listing the bundle containing the
              handler to be used.
            </p>
            <p>
              The configuration information is a dictionary
              containing the name of the bundle (keyed on
              'Name'), and this is used to locate the bundle
              in the applications resources. <br /> Before a
              <var>request</var> is passed on to a handler, two
              extra headers are set in it...
              <code>x-http-path-base</code> and
              <code>x-http-path-info</code> being the actual
              path matched for the handler, and the remainder of
              the path after that base part.
            </p>
            We handle the incoming requests here.
          </desc>
        </method>
        <method type="void">
          <sel>registerHandler:</sel>
          <arg type="id">handler</arg>
          <sel>forPath:</sel>
          <arg type="NSString*">path</arg>
          <desc>
            Registers an object as the <var>handler</var> for
            a particular <var>path</var>. <br /> Registering a
            <code>nil</code> <var>handler</var> destroys any
            existing <var>handler</var> for the
            <var>path</var>.
          </desc>
        </method>
        <method type="void">
          <sel>webAlert:</sel>
          <arg type="NSString*">message</arg>
          <sel>for:</sel>
          <arg type="WebServer*">http</arg>
          <desc>
            Just write to stderr using NSLog.
          </desc>
        </method>
        <method type="void">
          <sel>webAudit:</sel>
          <arg type="NSString*">message</arg>
          <sel>for:</sel>
          <arg type="WebServer*">http</arg>
          <desc>
            Log an audit record as UTF8 data on stderr.
          </desc>
        </method>
        <method type="void">
          <sel>webLog:</sel>
          <arg type="NSString*">message</arg>
          <sel>for:</sel>
          <arg type="WebServer*">http</arg>
          <desc>
            Just discard the <var>message</var>... please subclass
            or use a category to override this method if you wish to
            used the logged messages.
          </desc>
        </method>
      </class>
    </chapter>
  </body>
</gsdoc>
