source: trunk/greenorg/src/recpt/receptionist.cpp@ 9483

/**********************************************************************
 *
 * receptionist.cpp -- a web interface for the gsdl
 * Copyright (C) 1999  The New Zealand Digital Library Project
 *
 * A component of the Greenstone digital library software
 * from the New Zealand Digital Library Project at the
 * University of Waikato, New Zealand.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 *
 *********************************************************************/

// following line required to get fstream.filedesc() on darwin (Mac OS X)
// gcc 2.91 automatically defines this in stream.h
#define _STREAM_COMPAT  1

#include "receptionist.h"
#include "fileutil.h"
#include "cgiutils.h"
#include "gsdltools.h"
#include "gsdltimes.h"
#include <assert.h>
#include <time.h>
#include <stdio.h> // for open()
#include <fcntl.h> // for open() flags
// following 2 are for printing Last-Modified http header.
#include <sys/stat.h>
#include <time.h>

#if defined (GSDL_USE_IOS_H)
#include <fstream.h>
#else 
#include <fstream>
#endif

void recptconf::clear () {
  gsdlhome.clear();
  gdbmhome.clear();
  httpprefix.clear();
  httpimg = "/images";
  gwcgi.clear();
  macrofiles.erase(macrofiles.begin(), macrofiles.end());
  saveconf.clear();
  usecookies = false;
  logcgiargs = false;
  LogDateFormat = LocalTime;

  languages.erase(languages.begin(), languages.end());
  encodings.erase(encodings.begin(), encodings.end());
  
  // these default page parameters can always be overriden
  // in the configuration file
  pageparams.erase(pageparams.begin(), pageparams.end());
  pageparams["l"] = "en"; 

#ifdef MACROPRECEDENCE
  macroprecedence = MACROPRECEDENCE;
#else
  macroprecedence.clear();
#endif
}

void languageinfo_t::clear () {
  longname.clear();
  defaultencoding.clear();
}

receptionist::receptionist () {
  // create a list of cgi arguments
  // this must be done before the configuration

  cgiarginfo ainfo;

  ainfo.shortname = "e";
  ainfo.longname = "compressed arguments";
  ainfo.multiplechar = true;
  ainfo.defaultstatus = cgiarginfo::good;
  ainfo.argdefault = "";
  ainfo.savedarginfo = cgiarginfo::mustnot;
  argsinfo.addarginfo (NULL, ainfo);

  ainfo.shortname = "a";
  ainfo.longname = "action";
  ainfo.multiplechar = true;
  ainfo.defaultstatus = cgiarginfo::none;
  ainfo.argdefault = "";
  ainfo.savedarginfo = cgiarginfo::must;
  argsinfo.addarginfo (NULL, ainfo);

  // w=western
  ainfo.shortname = "w";
  ainfo.longname = "encoding";
  ainfo.multiplechar = true;
  ainfo.defaultstatus = cgiarginfo::none;
  ainfo.argdefault = "";
  ainfo.savedarginfo = cgiarginfo::must;
  argsinfo.addarginfo (NULL, ainfo);
  
  ainfo.shortname = "nw";
  ainfo.longname = "new encoding";
  ainfo.multiplechar = true;
  ainfo.defaultstatus = cgiarginfo::none;
  ainfo.argdefault = "";
  ainfo.savedarginfo = cgiarginfo::mustnot;
  argsinfo.addarginfo (NULL, ainfo);
  
  // the interface language name should use the ISO 639
  // standard
  ainfo.shortname = "l";
  ainfo.longname = "interface language";
  ainfo.multiplechar = true;
  ainfo.defaultstatus = cgiarginfo::weak;
  ainfo.argdefault = "en";
  ainfo.savedarginfo = cgiarginfo::must;
  argsinfo.addarginfo (NULL, ainfo);
  
  ainfo.shortname = "nl";
  ainfo.longname = "new language";
  ainfo.multiplechar = false;
  ainfo.defaultstatus = cgiarginfo::none;
  ainfo.argdefault = "0";
  ainfo.savedarginfo = cgiarginfo::mustnot;
  argsinfo.addarginfo (NULL, ainfo);
  
  // the GSDL_UID (cookie)
  ainfo.shortname = "z";
  ainfo.longname = "gsdl uid";
  ainfo.multiplechar = true;
  ainfo.defaultstatus = cgiarginfo::none;
  ainfo.argdefault = "";
  ainfo.savedarginfo = cgiarginfo::mustnot;
  argsinfo.addarginfo (NULL, ainfo);
}


void receptionist::add_action (action *theaction) {
  // make sure we have an action to add
  if (theaction == NULL) return;

  // add this action to the list of actions
  actions.addaction(theaction);
  
  // add the cgi arguments from this action
  argsinfo.addarginfo (NULL, theaction->getargsinfo());
}


// configure should be called for each line in the
// configuration files to configure the receptionist and everything
// it contains. The configuration should take place after everything
// has been added but before the initialisation.

void receptionist::configure (const text_t &key, const text_tarray &cfgline) {
  // configure the receptionist

   
   
  if (cfgline.size() >= 1) {
    cgiarginfo *info = NULL;
    if (key == "gsdlhome") {
      configinfo.gsdlhome = cfgline[0];
      if (configinfo.gdbmhome.empty()) configinfo.gdbmhome = cfgline[0];
    }
    else if (key == "gdbmhome") configinfo.gdbmhome = cfgline[0];
    else if (key == "httpprefix") configinfo.httpprefix = cfgline[0];
    else if (key == "httpimg") configinfo.httpimg = cfgline[0];
    else if (key == "gwcgi") configinfo.gwcgi = cfgline[0];
    else if (key == "macrofiles") {
      // want to append to macrofiles (i.e. may be several config files
      // contributing, maybe from several collections).
      text_tarray::const_iterator here = cfgline.begin();
      text_tarray::const_iterator end = cfgline.end();
      while (here != end) {
    configinfo.macrofiles.insert (*here);
    here ++;
      }
    }
    else if (key == "saveconf") configinfo.saveconf = cfgline[0];
    else if (key == "usecookies") configinfo.usecookies = (cfgline[0] == "true");
    else if (key == "logcgiargs") configinfo.logcgiargs = (cfgline[0] == "true");
    else if (key == "LogDateFormat") {
      if (cfgline[0] == "UTCTime") configinfo.LogDateFormat = UTCTime;
      else if (cfgline[0] == "Absolute") configinfo.LogDateFormat = Absolute;
    } 
    else if (key == "pageparam") {
      if (cfgline.size() >= 2) configinfo.pageparams[cfgline[0]] = cfgline[1];
      else configinfo.pageparams[cfgline[0]] = "";
    }
    else if (key == "macroprecedence") configinfo.macroprecedence = cfgline[0];
    else if (key == "cgiarg") {
      // get shortname
      bool seen_defaultstatus = false;
      text_t subkey, subvalue;
      text_t shortname;
      text_t::const_iterator cfglinesub_here;
      text_tarray::const_iterator cfgline_here = cfgline.begin();
      text_tarray::const_iterator cfgline_end = cfgline.end();
      while (cfgline_here != cfgline_end) {
    cfglinesub_here = getdelimitstr((*cfgline_here).begin(),
                    (*cfgline_here).end(), '=', subkey);
    if (subkey == "shortname") {
      shortname = substr (cfglinesub_here, (*cfgline_here).end());
    }
    cfgline_here++;
      }

      // if we found the shortname process the line again filling in values
      if (!shortname.empty()) {
    cgiarginfo &chinfo = argsinfo[shortname];
    chinfo.shortname = shortname; // in case this is a new argument
    
    cfgline_here = cfgline.begin();
    while (cfgline_here != cfgline_end) {
      cfglinesub_here = getdelimitstr((*cfgline_here).begin(),
                      (*cfgline_here).end(), '=', subkey);
      subvalue = substr (cfglinesub_here, (*cfgline_here).end());

      if (subkey == "longname") chinfo.longname = subvalue;
      else if (subkey == "multiplechar") chinfo.multiplechar = (subvalue == "true");
      else if (subkey == "defaultstatus") {
        seen_defaultstatus = true;
        if (subvalue == "none") chinfo.defaultstatus = cgiarginfo::none;
        else if (subvalue == "weak") chinfo.defaultstatus = cgiarginfo::weak;
        else if (subvalue == "good") chinfo.defaultstatus = cgiarginfo::good;
        else if (subvalue == "config") chinfo.defaultstatus = cgiarginfo::config;
        else if (subvalue == "imperative") chinfo.defaultstatus = cgiarginfo::imperative;
      }
      else if (subkey == "argdefault") {
        chinfo.argdefault = subvalue;
        if (!seen_defaultstatus) chinfo.defaultstatus = cgiarginfo::config;
      }
      else if (subkey == "savedarginfo") {
        if (subvalue == "mustnot") chinfo.savedarginfo = cgiarginfo::mustnot;
        else if (subvalue == "can") chinfo.savedarginfo = cgiarginfo::can;
        else if (subvalue == "must") chinfo.savedarginfo = cgiarginfo::must;
      }
      
      cfgline_here++;
    }
      }

    } else if (key == "Encoding") {

      configure_encoding (cfgline);

    } else if (key == "Language") {
      text_t subkey, subvalue, shortname;
      languageinfo_t lang;
      text_t::const_iterator cfglinesub_here;
      text_tarray::const_iterator cfgline_here = cfgline.begin();
      text_tarray::const_iterator cfgline_end = cfgline.end();
      while (cfgline_here != cfgline_end) {
    cfglinesub_here = getdelimitstr((*cfgline_here).begin(),
                    (*cfgline_here).end(), '=', subkey);
    if (subkey == "shortname") {
      shortname = substr (cfglinesub_here, (*cfgline_here).end());
    } else if (subkey == "longname") {
      lang.longname = substr (cfglinesub_here, (*cfgline_here).end());
    } else if (subkey == "default_encoding") {
      lang.defaultencoding = substr (cfglinesub_here, (*cfgline_here).end());
    }
    cfgline_here++;
      }
      if (!shortname.empty()) {
    if (lang.longname.empty()) lang.longname = shortname;
    configinfo.languages[shortname] = lang;
      }
    }
  }
  
  // configure the actions
  actionptrmap::iterator actionhere = actions.begin ();
  actionptrmap::iterator actionend = actions.end ();

  while (actionhere != actionend) {
    assert ((*actionhere).second.a != NULL);
    if ((*actionhere).second.a != NULL) 
      (*actionhere).second.a->configure(key, cfgline);

    actionhere++;
  }
}


void receptionist::configure (const text_t &key, const text_t &value) {
  text_tarray cfgline;
  cfgline.push_back (value);
  configure(key, cfgline);
}

bool receptionist::init (ostream &logout) {

  // read in the macro files
  if (!read_macrofiles (logout)) return false;

  // there must be at least one action defined
  if (actions.empty()) {
    logout << "Error: no actions have been added to the receptionist\n";
    return false;
  }

  // create a saveconf string if there isn't one already
  if (configinfo.saveconf.empty())
    configinfo.saveconf = create_save_conf_str (argsinfo, logout);

  // check the saveconf string
  if (!check_save_conf_str (configinfo.saveconf, argsinfo, logout))
    return false;

  // set a random seed
  srand (time(NULL));

  // init the actions
  actionptrmap::iterator actionhere = actions.begin ();
  actionptrmap::iterator actionend = actions.end ();
  while (actionhere != actionend) {
    if (((*actionhere).second.a == NULL) || 
    !(*actionhere).second.a->init(logout)) return false;
    actionhere++;
  }

  return true;
}

// get the default encoding for the given language - if it fails for any
// reason return ""
text_t receptionist::get_default_encoding (const text_t &language) {
  
  // make sure language is valid
  if (configinfo.languages.find(language) == configinfo.languages.end()) return "";

  text_t default_encoding = configinfo.languages[language].defaultencoding;

  // make sure the encoding is valid
  if (converters.find(default_encoding) == converters.end()) return "";

  return default_encoding;
}

// parse_cgi_args parses cgi arguments into an argument class.
// This function should be called for each page request. It returns false
// if there was a major problem with the cgi arguments.
bool receptionist::parse_cgi_args (const text_t &argstr, cgiargsclass &args, 
                   ostream &logout) {

  // get an initial list of cgi arguments
  args.clear();
  split_cgi_args (argsinfo, argstr, args);

  // expand the compressed argument (if there was one)
  if (!expand_save_args (argsinfo, configinfo.saveconf, args, logout)) return false;

  // add the defaults
  add_default_args (argsinfo, args, logout);

  // get the cookie
  if (configinfo.usecookies) get_cookie(args["z"]);
  
  // if we're changing languages, set the encoding to the default for the new language
  if (args["nl"] == "1") {
    args["nw"] = get_default_encoding(args["l"]);
  }

  // get the input encoding
  // if encoding isn't set, set it to the default for the current language
  if ((args.getarg("w") == NULL) || args["w"].empty()) {
    args["w"] = get_default_encoding(args["l"]);
  }

  text_t &arg_w = args["w"];

  inconvertclass defaultinconvert;
  inconvertclass *inconvert = converters.get_inconverter (arg_w);
  if (inconvert == NULL) inconvert = &defaultinconvert;

  // see if the next page will have a different encoding
  if (args.getarg("nw") != NULL) arg_w = args["nw"];

  // convert arguments which aren't in unicode to unicode
  args_tounicode (args, *inconvert);


  // decide on the output conversion class (needed for checking the external
  // cgi arguments)
  rzwsoutconvertclass defaultoutconverter;
  rzwsoutconvertclass *outconverter = converters.get_outconverter (arg_w);
  if (outconverter == NULL) outconverter = &defaultoutconverter;
  outconverter->reset();

  // check the arguments for the action
  action *a = actions.getaction (args["a"]);
  if (a != NULL) {
    if (!a->check_cgiargs (argsinfo, args, logout)) return false;
  } else {
    // the action was not found!!
    outconvertclass text_t2ascii;
    logout << text_t2ascii << "Error: the action \"" << args["a"] 
       << "\" could not be found.\n";
    return false;
  }

  // check external cgi arguments for each action
  actionptrmap::iterator actionhere = actions.begin ();
  actionptrmap::iterator actionend = actions.end ();
  while (actionhere != actionend) {
    assert ((*actionhere).second.a != NULL);
    if ((*actionhere).second.a != NULL) {
      if (!(*actionhere).second.a->check_external_cgiargs (argsinfo, args, *outconverter,
                               configinfo.saveconf, logout))
    return false;
    }
    actionhere++;
  }

  // the action might have changed but we will assume that
  // the cgiargs were checked properly when the change was made

  return true;
}

// returns true if cookie already existed, false
// if it was generated
bool receptionist::get_cookie (text_t &cookie) {

  text_t cookiestring = gsdl_getenv ("HTTP_COOKIE");
    
  text_t::const_iterator end = cookiestring.end();  
  text_t::const_iterator here = findchar ((text_t::const_iterator)cookiestring.begin(), end, 'G');

  while (here+9 < end) { 
    
    if (substr(here, here+8) == "GSDL_UID") {
      cookie = substr (here+9, findchar (here+9, end, ';')); 
      return true;
    }
    here = findchar ((text_t::const_iterator)cookiestring.begin(), end, 'G');
  }

  cookie.clear();
  text_t host = gsdl_getenv("REMOTE_ADDR");
  time_t ttime = time(NULL);
  if (!host.empty()) {
    cookie += host;
    cookie.push_back ('-');
  }
  cookie += text_t(ttime);
  
  return false;
}

// as above but just tests if cookie exists
bool receptionist::get_cookie () {

  text_t c = gsdl_getenv("HTTP_COOKIE");
  if (!c.empty()) {
    text_t cookiestring = c;
    
    text_t::const_iterator end = cookiestring.end();  
    text_t::const_iterator here = findchar ((text_t::const_iterator)cookiestring.begin(), end, 'G');

    while (here+9 < end) { 
      if (substr(here, here+8) == "GSDL_UID") return true;
      here = findchar ((text_t::const_iterator)cookiestring.begin(), end, 'G');
    }
  }
  return false;
}

bool receptionist::log_cgi_args (cgiargsclass &args, ostream &logout) {

  // see if we want to log the cgi arguments
  if (!configinfo.logcgiargs) return true;
  
  text_t host = gsdl_getenv ("REMOTE_HOST");
  text_t script_name = gsdl_getenv ("SCRIPT_NAME");
  if (host.empty()) host = gsdl_getenv ("REMOTE_ADDR");
  text_t browser = gsdl_getenv ("HTTP_USER_AGENT");

  cgiargsclass::const_iterator args_here = args.begin();
  cgiargsclass::const_iterator args_end = args.end();

  text_t argstr;
  bool first = true;
  while (args_here != args_end) {
    if (!first) argstr += ", ";
    argstr += (*args_here).first + "=" + (*args_here).second.value;
    first = false;
    args_here ++;
  }

  text_t logfile = filename_cat (configinfo.gdbmhome, "etc", "usage.txt");

  text_t logstr = script_name;
  logstr += " " + host;
  logstr += " [";
  if (configinfo.LogDateFormat == UTCTime) {
    logstr += get_date (false);
  } else if (configinfo.LogDateFormat == Absolute) {
    time_t ttime = time(NULL);
    logstr += ttime;
  } else {
    // LocalTime
    logstr += get_date (true);
  }
  logstr += "] (" + argstr + ") \"";
  logstr += browser;
  logstr += "\"\n";

  return append_logstr (logfile, logstr, logout);
}

bool receptionist::append_logstr (const text_t &filename, const text_t &logstr,
                  ostream &logout) {

  utf8outconvertclass text_t2utf8;
  char *lfile = filename.getcstr();

  int fd = open(lfile, O_WRONLY | O_APPEND);
  
  if (fd == -1) {
    logout << "Error: Couldn't open file " << lfile << "\n";
    delete lfile;
    return false;
  }

  // lock_val is set to 0 if file is locked successfully
  int lock_val = 1;
  GSDL_LOCK_FILE (fd);
  if (lock_val == 0) {
    text_t tmp_log_str(logstr); // so we don't pass a const to setinput...
    text_t2utf8.setinput(&tmp_log_str);
    char *buffer=new char[logstr.size()];
    size_t num_chars;
    convertclass::status_t status;
    text_t2utf8.convert(buffer, logstr.size(), num_chars, status);
    // ignore status - assume it is "finished" as buffer is big enough
    write(fd, buffer, num_chars);
    GSDL_UNLOCK_FILE (fd);
    delete buffer;
  } else {
    logout << "Error: Couldn't lock file " << lfile << "\n";
    close(fd);
    delete lfile;
    return false;
  }

  close(fd);
        
  delete lfile;
  return true;
}

text_t receptionist::expandmacros (const text_t &astring, cgiargsclass &args, 
                   ostream &logout) {
  text_t outstring;
  outconvertclass text_t2ascii;

  action *a = actions.getaction (args["a"]);
  prepare_page (a, args, text_t2ascii, logout);
  disp.expandstring ("Global", astring, outstring);
  return outstring;
}

// produce_cgi_page will call get_cgihead_info and 
// produce_content in the appropriate way to output a cgi header and
// the page content (if needed). If a page could not be created it
// will return false
bool receptionist::produce_cgi_page (cgiargsclass &args, ostream &contentout, 
                     ostream &logout) {
  outconvertclass text_t2ascii;

  response_t response;
  text_t response_data;

  // produce cgi header
  get_cgihead_info (args, response, response_data, logout);
  if (response == location) {
    // location response (url may contain macros!!)
    response_data = expandmacros (response_data, args, logout);
    contentout << text_t2ascii << "Location: " << response_data << "\n\n";
    contentout << flush;
    return true;
  } else if (response == content) {
    // content response

#ifdef GSDL_NOCACHE
    contentout << "Expires: Mon, 26 Jul 1997 05:00:00 GMT\n"; // date in the past
    tm *tm_ptr = NULL;
    time_t t = time(NULL);
    tm_ptr = gmtime (&t);
    if (tm_ptr != NULL) {
      char *timestr = new char[128];
      strftime (timestr, 128, "%a, %d %b %Y %H:%M:%S", tm_ptr);
      contentout << "Last-Modified: " << timestr << " GMT\n"; // always modified
      delete timestr;
    }
    contentout << "Cache-Control: no-cache, must-revalidate\n"; // HTTP/1.1
    contentout << "Pragma: no-cache\n"; // HTTP/1.0

#endif
    
    contentout << text_t2ascii << "Content-type: " << response_data << "\n\n";
  } else {
    // unknown response
    logout << "Error: get_cgihead_info returned an unknown response type.\n";
    return false;
  }

  // produce cgi page
  if (!produce_content (args, contentout, logout)) return false;

  // flush contentout
  contentout << flush;
  return true;
}


// get_cgihead_info determines the cgi header information for
// a set of cgi arguments. If response contains location then
// response_data contains the redirect address. If reponse
// contains content then reponse_data contains the content-type.
// Note that images can now be produced by the receptionist.
void receptionist::get_cgihead_info (cgiargsclass &args, response_t &response,
                     text_t &response_data, ostream &logout) {
  outconvertclass text_t2ascii;

  // get the action
  action *a = actions.getaction (args["a"]);
  if (a != NULL) {
    a->get_cgihead_info (args, response, response_data, logout);

  } else {
    // the action was not found!!
    logout << text_t2ascii << "Error receptionist::get_cgihead_info: the action \"" 
       << args["a"] << "\" could not be found.\n";
    response = content;
    response_data = "text/html";
  }

  // add the encoding information
  if (response == content) {
    if (converters.find(args["w"]) != converters.end()) {
      response_data += "; charset=" + args["w"];
    } else {
      // default to latin 1
      response_data += "; charset=ISO-8859-1";
    }

    // add cookie if required
    if (configinfo.usecookies && !get_cookie())
      response_data += "\nSet-Cookie: GSDL_UID=" + args["z"]
    + "; expires=25-Dec-37 00:00:00 GMT";
  }
}


// produce the page content
bool receptionist::produce_content (cgiargsclass &args, ostream &contentout,
                    ostream &logout) {

  // decide on the output conversion class
  text_t &arg_w = args["w"];
  rzwsoutconvertclass defaultoutconverter;
  rzwsoutconvertclass *outconverter = converters.get_outconverter (arg_w);
  if (outconverter == NULL) outconverter = &defaultoutconverter;
  outconverter->reset();

  // needed for 16-bit unicode only - big endian marker 0xfeff (RFC 2781)
  if (arg_w=="utf-16") {
    contentout << '\xfe' << '\xff' ;
  }
  
  // produce the page using the desired action
  action *a = actions.getaction (args["a"]);
  if (a != NULL) {
    if (a->uses_display(args)) prepare_page (a, args, (*outconverter), logout);
    if (!a->do_action (args, disp, (*outconverter), contentout, logout))
      return false;
  } else {
    // the action was not found!!
    outconvertclass text_t2ascii;

    logout << text_t2ascii << "Error receptionist::produce_content: the action \"" 
       << args["a"] << "\" could not be found.\n";
    
    contentout << (*outconverter) 
           << "<html>\n"
           << "<head>\n"
           << "<title>Error</title>\n"
           << "</head>\n"
           << "<body>\n"
           << "<h2>Oops!</h2>\n"
           << "Undefined Page. The action \"" 
           << args["a"] << "\" could not be found.\n"
           << "</body>\n"
           << "</html>\n";
  }
  return true;
}


// returns the compressed argument ("e") corresponding to the argument
// list. This can be used to save preferences between sessions.
text_t receptionist::get_compressed_arg (cgiargsclass &args, ostream &logout) {
  // decide on the output conversion class
  text_t &arg_w = args["w"];
  rzwsoutconvertclass defaultoutconverter;
  rzwsoutconvertclass *outconverter = converters.get_outconverter (arg_w);
  if (outconverter == NULL) outconverter = &defaultoutconverter;
  outconverter->reset();

  text_t compressed_args;
  if (compress_save_args (argsinfo, configinfo.saveconf, args, 
              compressed_args, *outconverter, logout))
    return compressed_args;

  return "";
}


// will read in all the macro files. If one is not found an
// error message will be written to logout and the method will
// return false.
bool receptionist::read_macrofiles (ostream &logout) {
  outconvertclass text_t2ascii;

  // redirect the error output to logout
  ostream *savedlogout = disp.setlogout (&logout);

  text_t gsdlmacrodir = filename_cat (configinfo.gsdlhome, "macros");

  text_tset::iterator arrhere = configinfo.macrofiles.begin();
  text_tset::iterator arrend = configinfo.macrofiles.end();
  text_t filename;
  while (arrhere != arrend) {
    filename = filename_cat (gsdlmacrodir, *arrhere);
    if (file_exists (filename)) {
      disp.loaddefaultmacros(filename);
    } else {
      logout << text_t2ascii 
         << "Error: the macro file \"" << *arrhere << "\" could not be found.\n";
      disp.setlogout (savedlogout);
      return false;
    }
    arrhere ++;
  }

  // success

  // reset logout to what it was
  disp.setlogout (savedlogout);
  return true;
}

// prepare_page sets up page parameters, sets display macros
// and opens the page ready for output 
void receptionist::prepare_page (action *a, cgiargsclass &args, 
                 outconvertclass &outconvert, 
                 ostream &logout) {
  // set up page parameters
  text_t pageparams;
  bool first = true;

  text_tmap::iterator params_here = configinfo.pageparams.begin();
  text_tmap::iterator params_end = configinfo.pageparams.end();
  while (params_here != params_end) {
    if (args[(*params_here).first] != (*params_here).second) {
      if (!first) pageparams += ",";
      first = false;
      pageparams += (*params_here).first;
      pageparams += "=";
      pageparams += args[(*params_here).first];
    }
    
    params_here++;
  }
  

  // open the page
  disp.openpage(pageparams, configinfo.macroprecedence);

  // define external macros for each action
  actionptrmap::iterator actionhere = actions.begin ();
  actionptrmap::iterator actionend = actions.end ();

  while (actionhere != actionend) {
    assert ((*actionhere).second.a != NULL);
    if ((*actionhere).second.a != NULL) {
      (*actionhere).second.a->define_external_macros (disp, args, logout);
    }
    actionhere++;
  }

  // define internal macros for the current action
  a->define_internal_macros (disp, args, logout);
  
  // define general macros. the defining of general macros is done here so that
  // the last possible version of the cgi arguments are used
  define_general_macros (args, outconvert, logout);
}

void receptionist::define_general_macros (cgiargsclass &args, outconvertclass &/*outconvert*/, 
                      ostream &logout) {

  disp.setmacro ("gsdlhome", "Global", dm_safe(configinfo.gsdlhome));
  disp.setmacro ("gwcgi", "Global", configinfo.gwcgi);
  disp.setmacro ("httpimg", "Global", configinfo.httpimg);
  disp.setmacro ("httpprefix", "Global", configinfo.httpprefix);

  text_t compressedoptions = get_compressed_arg(args, logout);
  disp.setmacro ("compressedoptions", "Global", dm_safe(compressedoptions));
  // need a decoded version of compressedoptions for use within forms
  // as browsers encode values from forms before sending to server
  // (e.g. %25 becomes %2525)
  decode_cgi_arg (compressedoptions);
  disp.setmacro ("decodedcompressedoptions", "Global", dm_safe(compressedoptions));

  // set _cgiargX_ macros for each cgi argument
  cgiargsclass::const_iterator argshere = args.begin();
  cgiargsclass::const_iterator argsend = args.end();
  while (argshere != argsend) {
    disp.setmacro ("cgiarg" + (*argshere).first, "Global", dm_safe((*argshere).second.value));
    argshere ++;
  }
}

// Handles an "Encoding" line from a configuration file - note that the
// configinfo.encodings map is a bit of a hack (to be fixed when the
// configuration files are tidied up).
void receptionist::configure_encoding (const text_tarray &cfgline) {

  text_t subkey, subvalue, shortname, longname, mapfile;
  int multibyte = 0;
  text_t::const_iterator cfglinesub_here;
  text_tarray::const_iterator cfgline_here = cfgline.begin();
  text_tarray::const_iterator cfgline_end = cfgline.end();
  while (cfgline_here != cfgline_end) {
    if (*cfgline_here == "multibyte") {
      multibyte = 1;
    } else {
      cfglinesub_here = getdelimitstr((*cfgline_here).begin(),
                      (*cfgline_here).end(), '=', subkey);
      if (subkey == "shortname") {
    shortname = substr (cfglinesub_here, (*cfgline_here).end());
      } else if (subkey == "longname") {
    longname = substr (cfglinesub_here, (*cfgline_here).end());
      } else if (subkey == "map") {
    mapfile = substr (cfglinesub_here, (*cfgline_here).end());
      }
    }
    cfgline_here++;
  }
  if (!shortname.empty()) {
    if (longname.empty()) longname = shortname;

    // add the converter
    if (shortname == "utf-8") {
      utf8inconvertclass *utf8inconvert = new utf8inconvertclass();
      utf8outconvertclass *utf8outconvert = new utf8outconvertclass();
      utf8outconvert->set_rzws(1);
      add_converter (shortname, utf8inconvert, utf8outconvert);
      configinfo.encodings[longname] = shortname;

    } else if (shortname == "utf-16") {
      // we use the default input converter as this shouldn't ever be used
      // for converting from unicode...
      inconvertclass *inconverter = new inconvertclass();
      utf16outconvertclass *outconverter = new utf16outconvertclass();
      add_converter (shortname, inconverter, outconverter);
      configinfo.encodings[longname] = shortname;
    
    } else if (!mapfile.empty()) {

      if (mapfile == "8859_1.ump") {
    // iso-8859-1 is a special case as it'll always be supported by the
    // standard converter class and therefore doesn't need to use its
    // mapping file
    inconvertclass *inconvert = new inconvertclass();
    rzwsoutconvertclass *outconvert = new rzwsoutconvertclass();
    outconvert->set_rzws(1);
    add_converter (shortname, inconvert, outconvert);  
    configinfo.encodings[longname] = shortname;

      } else {
    text_t to_uc_map = filename_cat(configinfo.gsdlhome, "mappings", "to_uc", mapfile);
    text_t from_uc_map = filename_cat(configinfo.gsdlhome, "mappings", "from_uc", mapfile);
    if (file_exists(to_uc_map) && file_exists(from_uc_map)) {

      mapinconvertclass *mapinconvert = new mapinconvertclass();
      mapinconvert->setmapfile (to_uc_map, 0x003F);
      mapinconvert->set_multibyte (multibyte);
      mapoutconvertclass *mapoutconvert = new mapoutconvertclass();
      mapoutconvert->setmapfile (from_uc_map, 0x3F);
      mapoutconvert->set_multibyte (multibyte);
      mapoutconvert->set_rzws(1);
      add_converter (shortname, mapinconvert, mapoutconvert);
      configinfo.encodings[longname] = shortname;
    }
      }
    }
  }
}