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

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

<erlref>
  <header>
    <copyright>
      <year>1997</year><year>2011</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>mod_esi</title>
    <prepared>Joakim Greben&ouml;</prepared>
    <docno></docno>
    <date>1997-10-14</date>
    <rev>2.2</rev>
    <file>mod_esi.sgml</file>
  </header>
  <module>mod_esi</module>
  <modulesummary>Erlang Server Interface </modulesummary>
  <description>
    <p>This module defines the API - Erlang Server Interface (ESI).
    Which is a more efficient way of writing erlang scripts
    for your Inets web server than writing them as common CGI scripts.</p>

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

  <funcs>
    <func>
      <name>deliver(SessionID, Data) -> ok | {error, Reason}</name>
      <fsummary>Sends Data back to client.</fsummary>
      <type>
        <v>SessionID = term()</v>
        <v>Data = string() | io_list() | binary()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <marker id="deliver"></marker>
	<p>This function is <em>only</em> intended to be used from
	functions called by the Erl Scheme interface to deliver
	parts of the content to the user.</p>
	<p>Sends data from a Erl Scheme script back to the client.</p>
	
	<note>
	  <p>Note that if any HTTP-header fields should be added by the
	  script they must be in the first call to deliver/2  and the
	  data in the call must be a string. Calls after the headers
	  are complete may contain binary data to reduce copying
	  overhead.  Do not assume anything about the data type of 
	  SessionID, the SessionID must be the value given as input to 
	  the esi call back function that you implemented.</p>
	</note>
      </desc>
    </func>
  </funcs>

  <section>
    <title>ESI Callback Functions</title>
  </section>
  <funcs>
    <func>
      <name>Module:Function(SessionID, Env, Input)-> _ </name>
      <fsummary>Creates a dynamic web page and returns it chunk by chunk to the server process by calling mod_esi:deliver/2.</fsummary>
      <type>
        <v>SessionID = term()</v>
        <v>Env  = [EnvironmentDirectives] ++ ParsedHeader</v>
        <v>EnvironmentDirectives = {Key,Value}</v>
        <v>Key = query_string | content_length | server_software | gateway_interface | server_protocol | server_port | request_method | remote_addr | script_name</v>
        <v>Input = string()</v>
      </type>
      <desc>
        <p>The <c>Module</c> must be found in the code path and export
          <c>Function</c> with an arity of two. An erlScriptAlias must
          also be set up in the configuration file for the Web server.</p>
        <p>If the HTTP request is a post request and a body is sent
          then content_length will be the length of the posted
          data. If get is used query_string will be the data after
          <em>?</em> in the url.</p>
        <p>ParsedHeader is the HTTP request as a key value tuple
          list. The keys in parsed header will be the in lower case.</p>
        <p>SessionID is a identifier
          the server use when <c>deliver/2</c> is called, do not
          assume any-thing about the datatype.</p>
        <p>Use this callback function to dynamically generate dynamic web
          content. when a part of the page is generated send the
          data back to the client through <c>deliver/2</c>. Note
          that the first chunk of data sent to the client must at
          least contain all HTTP header fields that the response
          will generate. If the first chunk not contains 
          <em>End of HTTP header</em> that is <c>"\r\n\r\n"</c> 
          the server will
          assume that no HTTP header fields will be generated.</p>
      </desc>
    </func>
    <func>
      <name>Module:Function(Env, Input)-> Response </name>
      <fsummary>Creates a dynamic web page and return it as a list. This functions is deprecated and only kept for backwards compatibility.</fsummary>
      <type>
        <v>Env  = [EnvironmentDirectives] ++ ParsedHeader</v>
        <v>EnvironmentDirectives = {Key,Value}</v>
        <v>Key = query_string | content_length | server_software | gateway_interface | server_protocol | server_port | request_method | remote_addr | script_name. &lt;v>Input = string()</v>
        <v>Response = string()</v>
      </type>
      <desc>
        <p>This callback format consumes quite much memory since the
          whole response must be generated before it is sent to the
          user. This functions is deprecated and only keept for backwards
          compatibility. 
          For new development Module:Function/3 should be used.</p>
      </desc>
    </func>
  </funcs>
  
</erlref>