path: root/lib/inets/doc/src/httpd_util.xml

<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1997</year><year>2012</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at http://www.erlang.org/.

      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights and limitations
      under the License.

    </legalnotice>

    <title>httpd_util</title>
    <prepared>Joakim Greben&ouml;</prepared>
    <docno></docno>
    <date>1997-10-14</date>
    <rev>2.2</rev>
    <file>httpd_util.sgml</file>
  </header>
  <module>httpd_util</module>
  <modulesummary>Miscellaneous utility functions to be used when implementing Erlang Web server API modules.</modulesummary>
  <description>
    <p>This module provides the Erlang Web Server API module
      programmer with miscellaneous utility functions.</p>

    <marker id="convert_request_date"></marker>
  </description>

  <funcs>
    <func>
      <name>convert_request_date(DateString) -> ErlDate|bad_date</name>
      <fsummary>Convert The the date to the Erlang date format.</fsummary>
      <type>
        <v>DateString = string()</v>
        <v>ErlDate = {{Year,Month,Date},{Hour,Min,Sec}}</v>
        <v>Year = Month = Date = Hour = Min = Sec = integer()</v>
      </type>
      <desc>
        <p><c>convert_request_date/1</c> converts <c>DateString</c> to 
          the Erlang date format. DateString must be in one of the three 
          date formats that is defined in the RFC 2616.</p>

	<marker id="create_etag"></marker>
      </desc>
    </func>

    <func>
      <name>create_etag(FileInfo) -> Etag</name>
      <fsummary>Calculates the Etag for a file.</fsummary>
      <type>
        <v>FileInfo = file_info()</v>
        <v>Etag = string()</v>
      </type>
      <desc>
        <p><c>create_etag/1</c> calculates the Etag for a file, from its
          size and time for last modification. fileinfo is a record defined 
          in <c>kernel/include/file.hrl</c></p>

	<marker id="decode_hex"></marker>
      </desc>
    </func>

    <func>
      <name>decode_hex(HexValue) -> DecValue</name>
      <fsummary>Convert a hex value into its decimal equivalent.</fsummary>
      <type>
        <v>HexValue = DecValue = string()</v>
      </type>
      <desc>
        <p>Converts the hexadecimal value <c>HexValue</c> into its
          decimal equivalent (<c>DecValue</c>).</p>

	<marker id="day"></marker>
      </desc>
    </func>

    <func>
      <name>day(NthDayOfWeek) -> DayOfWeek</name>
      <fsummary>Convert the day of the week (integer [1-7]) to an abbreviated string.</fsummary>
      <type>
        <v>NthDayOfWeek = 1-7</v>
        <v>DayOfWeek = string()</v>
      </type>
      <desc>
        <marker id="day"></marker>
        <p><c>day/1</c> converts the day of the week
          (<c>NthDayOfWeek</c>) as an integer (1-7) to an abbreviated
          string, that is: </p>
        <p>1 = "Mon", 2 = "Tue", ..., 7 = "Sat".</p>

	<marker id="flatlength"></marker>
      </desc>
    </func>

    <func>
      <name>flatlength(NestedList) -> Size</name>
      <fsummary>Compute the size of a possibly nested list.</fsummary>
      <type>
        <v>NestedList = list()</v>
        <v>Size = integer()</v>
      </type>
      <desc>
        <marker id="flatlength"></marker>
        <p><c>flatlength/1</c> computes the size of the possibly nested
          list <c>NestedList</c>. Which may contain binaries.</p>

        <marker id="hexlist_to_integer"></marker>
      </desc>
    </func>

<!--
    <func>
      <name>header(StatusCode,PersistentConn)</name>
      <name>header(StatusCode,Date)</name>
      <name>header(StatusCode,MimeType,Date)</name>
      <name>header(StatusCode,MimeType,PersistentConn,Date) -> HTTPHeader</name>
      <fsummary>Generate a HTTP 1.1 header.</fsummary>
      <type>
        <v>StatusCode = integer()</v>
        <v>Date = rfc1123_date()</v>
        <v>MimeType = string()</v>
        <v>PersistentConn = true | false</v>
      </type>
      <desc>
        <marker id="header"></marker>
        <p><c>header</c> returns a HTTP 1.1 header string. The
          <c>StatusCode</c> is one of the status codes defined in RFC
          2616 and the <c>Date</c> string is RFC 1123 
          compliant. (See <seealso marker="#rfc1123_date">rfc1123_date/0</seealso>).
          </p>
        <p>Note that the two version of <c>header/n</c> that does not
          has a <c>PersistentConn</c> argument is there only for
          backward compatibility, and must not be used in new Erlang
          Webserver API modules.  that will support persistent
          connections.</p>

	<marker id="hexlist_to_integer"></marker>
      </desc>
    </func>
-->

    <func>
      <name>hexlist_to_integer(HexString) -> Number</name>
      <fsummary>Convert a hexadecimal string to an integer.</fsummary>
      <type>
        <v>Number = integer()</v>
        <v>HexString = string()</v>
      </type>
      <desc>
        <p><c>hexlist_to_integer</c> Convert the Hexadecimal value of 
          HexString to an integer.</p>

	<marker id="integer_to_hexlist"></marker>
      </desc>
    </func>

    <func>
      <name>integer_to_hexlist(Number) -> HexString</name>
      <fsummary>Convert an integer to a hexadecimal string.</fsummary>
      <type>
        <v>Number = integer()</v>
        <v>HexString = string()</v>
      </type>
      <desc>
        <marker id="integer_to_hexlist"></marker>
        <p><c>integer_to_hexlist/1</c> Returns a string that represents 
          the Number in a Hexadecimal form.</p>

	<marker id="lookup"></marker>
      </desc>
    </func>

    <func>
      <name>lookup(ETSTable,Key) -> Result</name>
      <name>lookup(ETSTable,Key,Undefined) -> Result</name>
      <fsummary>Extract the first value associated with a key in an ETS table.</fsummary>
      <type>
        <v>ETSTable = ets_table()</v>
        <v>Key = term()</v>
        <v>Result = term() | undefined | Undefined</v>
        <v>Undefined = term()</v>
      </type>
      <desc>
        <p><c>lookup</c> extracts <c>{Key,Value}</c> tuples from
          <c>ETSTable</c> and returns the <c>Value</c> associated  
          with <c>Key</c>. If <c>ETSTable</c> is of type <c>bag</c>
          only the first <c>Value</c> associated with <c>Key</c> is
          returned. <c>lookup/2</c> returns <c>undefined</c> and
          <c>lookup/3</c> returns <c>Undefined</c> if no <c>Value</c>
          is found.</p>

	<marker id="lookup_mime"></marker>
      </desc>
    </func>

    <func>
      <name>lookup_mime(ConfigDB,Suffix)</name>
      <name>lookup_mime(ConfigDB,Suffix,Undefined) -> MimeType</name>
      <fsummary>Return the mime type associated with a specific file suffix. </fsummary>
      <type>
        <v>ConfigDB = ets_table()</v>
        <v>Suffix = string()</v>
        <v>MimeType = string() | undefined | Undefined</v>
        <v>Undefined = term()</v>
      </type>
      <desc>
        <marker id="lookup_mime"></marker>
        <p><c>lookup_mime</c> returns the mime type associated with a
          specific file suffix as specified in the <c>mime.types</c>
          file (located in the 
          <path unix="$SERVER_ROOT/conf/mime.types" windows="%SERVER_ROOT%\conf\mime.types">config directory</path>).</p>

	<marker id="lookup_mime_default"></marker>
      </desc>
    </func>

    <func>
      <name>lookup_mime_default(ConfigDB,Suffix)</name>
      <name>lookup_mime_default(ConfigDB,Suffix,Undefined) -> MimeType</name>
      <fsummary>Return the mime type associated with a specific file suffix or the value of the DefaultType.</fsummary>
      <type>
        <v>ConfigDB = ets_table()</v>
        <v>Suffix = string()</v>
        <v>MimeType = string() | undefined | Undefined</v>
        <v>Undefined = term()</v>
      </type>
      <desc>
        <marker id="lookup_mime_default"></marker>
        <p><c>lookup_mime_default</c> returns the mime type associated
          with a specific file suffix as specified in the
          <c>mime.types</c> file (located in the
          <path unix="$SERVER_ROOT/conf/mime.types" windows="%SERVER_ROOT%\conf\mime.types">config  directory</path>). 
          If no appropriate association can be found 
          the value of DefaultType is
          returned.</p>

	<marker id="message"></marker>
      </desc>
    </func>

    <func>
      <name>message(StatusCode,PhraseArgs,ConfigDB) -> Message</name>
      <fsummary>Return an informative HTTP 1.1 status string in HTML.</fsummary>
      <type>
        <v>StatusCode = 301 | 400 | 403 | 404 | 500 | 501 | 504</v>
        <v>PhraseArgs = term()</v>
        <v>ConfigDB = ets_table</v>
        <v>Message = string()</v>
      </type>
      <desc>
        <marker id="message"></marker>
        <p><c>message/3</c> returns an informative HTTP 1.1 status
          string in HTML. Each <c>StatusCode</c> requires a specific
          <c>PhraseArgs</c>:
          </p>
        <taglist>
          <tag><c>301</c></tag>
          <item><c>string()</c>: A URL pointing at the new document
           position.</item>
          <tag><c>400 | 401 | 500</c></tag>
          <item><c>none</c> (No <c>PhraseArgs</c>)</item>
          <tag><c>403 | 404</c></tag>
          <item><c>string()</c>: A <c>Request-URI</c> as described in
           RFC 2616.</item>
          <tag><c>501</c></tag>
          <item><c>{Method,RequestURI,HTTPVersion}</c>: The HTTP
          <c>Method</c>, <c>Request-URI</c> and <c>HTTP-Version</c>
           as defined in RFC 2616.</item>
          <tag><c>504</c></tag>
          <item><c>string()</c>: A string describing why the service
           was unavailable.</item>
        </taglist>

	<marker id="month"></marker>
      </desc>
    </func>

    <func>
      <name>month(NthMonth) -> Month</name>
      <fsummary>Convert the month as an integer (1-12) to an abbreviated string.</fsummary>
      <type>
        <v>NthMonth = 1-12</v>
        <v>Month = string()</v>
      </type>
      <desc>
        <marker id="month"></marker>
        <p><c>month/1</c> converts the month <c>NthMonth</c> as an
          integer (1-12) to an abbreviated string, that is: </p>
        <p>1 = "Jan", 2 = "Feb", ..., 12 = "Dec".</p>

	<marker id="multi_lookup"></marker>
      </desc>
    </func>

    <func>
      <name>multi_lookup(ETSTable,Key) -> Result</name>
      <fsummary>Extract the values associated with a key in a ETS table.</fsummary>
      <type>
        <v>ETSTable = ets_table()</v>
        <v>Key = term()</v>
        <v>Result = [term()]</v>
      </type>
      <desc>
        <p><c>multi_lookup</c> extracts all <c>{Key,Value}</c> tuples
          from an <c>ETSTable</c> and returns <em>all</em><c>Values</c> associated with the <c>Key</c> in a list.</p>

	<marker id="reason phrase"></marker>
      </desc>
    </func>

    <func>
      <name>reason_phrase(StatusCode) -> Description</name>
      <fsummary>Return the description of an HTTP 1.1 status code.</fsummary>
      <type>
        <v>StatusCode = 100|  200 | 201 | 202 | 204 | 205 | 206 |  300 | 301 | 302 | 303 | 304 |  400 | 401 | 402 | 403 | 404 | 405 | 406 | 410 411 | 412 | 413 | 414 415 | 416 | 417 |  500 | 501 | 502 | 503 | 504 | 505</v>
        <v>Description = string()</v>
      </type>
      <desc>
        <p><c>reason_phrase</c> returns the <c>Description</c> of an
          HTTP 1.1 <c>StatusCode</c>, for example 200 is "OK" and 201
          is "Created". Read RFC 2616 for further information.</p>

	<marker id="rfc1123_date"></marker>
      </desc>
    </func>

    <func>
      <name>rfc1123_date() -> RFC1123Date</name>
      <name>rfc1123_date({{YYYY,MM,DD},{Hour,Min,Sec}}}) -> RFC1123Date</name>
      <fsummary>Return the current date in RFC 1123 format.</fsummary>
      <type>
        <v>YYYY = MM = DD = Hour = Min =Sec = integer()</v>
        <v>RFC1123Date = string()</v>
      </type>
      <desc>
        <marker id="rfc1123_date"></marker>
        <p><c>rfc1123_date/0</c> returns the current date in RFC 1123
          format. <c>rfc_date/1</c> converts the date in the Erlang format
          to the RFC 1123 date format.</p>

	<marker id="split"></marker>
      </desc>
    </func>

    <func>
      <name>split(String,RegExp,N) -> SplitRes</name>
      <fsummary>Split a string in N chunks using a regular expression.</fsummary>
      <type>
        <v>String = RegExp = string()</v>
        <v>SplitRes = {ok, FieldList} | {error, errordesc()}</v>
        <v>Fieldlist = [string()]</v>
        <v>N = integer</v>
      </type>
      <desc>
        <marker id="split"></marker>
        <p><c>split/3</c> splits the <c>String</c> in <c>N</c> chunks
          using the <c>RegExp</c>. <c>split/3</c> is is equivalent to
          <c>regexp:split/2</c> with one exception, that is <c>N</c>
          defines the number of maximum number of fields in the
          <c>FieldList</c>.</p>

	<marker id="split_script_path"></marker>
      </desc>
    </func>

    <func>
      <name>split_script_path(RequestLine) -> Splitted</name>
      <fsummary>Split a <c>RequestLine</c>in a file reference to an executable and a<c>QueryString</c>or a <c>PathInfo</c>string.</fsummary>
      <type>
        <v>RequestLine = string()</v>
        <v>Splitted = not_a_script | {Path, PathInfo, QueryString}</v>
        <v>Path = QueryString = PathInfo = string()</v>
      </type>
      <desc>
        <marker id="split_script_path"></marker>
        <p><c>split_script_path/1</c> is equivalent to
          <c>split_path/1</c> with one exception. If the longest
          possible path is not a regular, accessible and executable
          file <c>not_a_script</c> is returned.</p>

	<marker id="split_path"></marker>
      </desc>
    </func>

    <func>
      <name>split_path(RequestLine) -> {Path,QueryStringOrPathInfo}</name>
      <fsummary>Split a <c>RequestLine</c>in a file reference and a <c>QueryString</c>or a<c>PathInfo</c>string.</fsummary>
      <type>
        <v>RequestLine = Path = QueryStringOrPathInfo = string()</v>
      </type>
      <desc>
        <marker id="split_path"></marker>
        <p><c>split_path/1</c> splits the <c>RequestLine</c> in a file
          reference (<c>Path</c>) and a <c>QueryString</c> or a
          <c>PathInfo</c> string as specified in RFC 2616. A
          <c>QueryString</c> is isolated from the <c>Path</c> with a
          question mark (<c>?</c>) and <c>PathInfo</c> with a slash
          (/). In the case of a <c>QueryString</c>, everything before
          the <c>?</c> is a <c>Path</c> and everything after a
          <c>QueryString</c>. In the case of a <c>PathInfo</c> the
          <c>RequestLine</c> is scanned from left-to-right on the hunt
          for longest possible <c>Path</c> being a file or a
          directory. Everything after the longest possible
          <c>Path</c>, isolated with a <c>/</c>, is regarded as
          <c>PathInfo</c>. The resulting <c>Path</c> is decoded using
          <c>decode_hex/1</c> before delivery.</p>

	<marker id="strip"></marker>
      </desc>
    </func>

    <func>
      <name>strip(String) -> Stripped</name>
      <fsummary>Returns String where the leading and trailing space and tabs has been removed.</fsummary>
      <type>
        <v>String = Stripped = string()</v>
      </type>
      <desc>
        <marker id="strip"></marker>
        <p><c>strip/1</c> removes any leading or trailing linear white
          space from the string.  Linear white space should be read as
          horizontal tab or space.</p>

	<marker id="suffix"></marker>
      </desc>
    </func>

    <func>
      <name>suffix(FileName) -> Suffix</name>
      <fsummary>Extract the file suffix from a given filename.</fsummary>
      <type>
        <v>FileName = Suffix = string()</v>
      </type>
      <desc>
        <marker id="suffix"></marker>
        <p><c>suffix/1</c> is equivalent to
          <c>filename:extension/1</c> with one exception, that is
          <c>Suffix</c> is returned without a leading dot (<c>.</c>). </p>
      </desc>
    </func>
  </funcs>

  <section>
    <marker id="see_also"></marker>
    <title>SEE ALSO</title>
    <p><seealso marker="httpd">httpd(3)</seealso></p>
  </section>
  
</erlref>