source: trunk/gsdl/src/recpt/receptionist.cpp@ 2379

/**********************************************************************
 *
 * 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)
#define _STREAM_COMPAT  1

#include "receptionist.h"
#include "fileutil.h"
#include "cgiutils.h"
#include "htmlutils.h"
#include "gsdltools.h"
#include "gsdltimes.h"
#include "OIDtools.h"
#include <assert.h>
#include <time.h>
#include <stdio.h>
#if defined (GSDL_USE_IOS_H)
#include <fstream.h>
#else 
#include <fstream>
#endif

#if defined (__WIN32_)
#include "wincgiutils.h"
#endif

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

  maintainer.clear();
  MailServer.clear();
  LogEvents = Disabled;
  EmailEvents = Disabled;
  EmailUserEvents = false;

  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["c"] = ""; 
  pageparams["l"] = "en"; 

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

void collectioninfo_t::clear () {
  gsdl_gsdlhome.clear();
  gsdl_gdbmhome.clear();

  info_loaded = false;
  info.clear();
}

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);
  
  ainfo.shortname = "c";
  ainfo.longname = "collection";
  ainfo.multiplechar = true;
  ainfo.defaultstatus = cgiarginfo::none;
  ainfo.argdefault = "";
  ainfo.savedarginfo = cgiarginfo::must;
  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());
}


void receptionist::add_browser (browserclass *thebrowser) {
  // make sure we have a browser to add
  if (thebrowser == NULL) return;

  // add this browser to the list of browsers
  browsers.addbrowser(thebrowser);
}


void receptionist::setdefaultbrowser (const text_t &browsername) {
  browsers.setdefaultbrowser (browsername);
}


// 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];
    else if (key == "gdbmhome") configinfo.gdbmhome = cfgline[0];
    else if (key == "collection") {
      configinfo.collection = cfgline[0];
      // also need to set the default arg to this collection
      if ((info = argsinfo.getarginfo("c")) != NULL) {
    info->defaultstatus = cgiarginfo::good;
    info->argdefault = cfgline[0];
      }
      
    } else if (key == "collectdir") configinfo.collectdir = 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 == "maintainer") configinfo.maintainer = cfgline[0];
    else if (key == "MailServer") configinfo.MailServer = cfgline[0];
    else if (key == "LogDateFormat") {
      if (cfgline[0] == "UTCTime") configinfo.LogDateFormat = UTCTime;
      else if (cfgline[0] == "Absolute") configinfo.LogDateFormat = Absolute;
    } 
    else if (key == "LogEvents") {
      if (cfgline[0] == "CollectorEvents") configinfo.LogEvents = CollectorEvents;
      else if (cfgline[0] == "AllEvents") configinfo.LogEvents = AllEvents;
    } 
    else if (key == "EmailEvents") {
      if (cfgline[0] == "CollectorEvents") configinfo.EmailEvents = CollectorEvents;
      else if (cfgline[0] == "AllEvents") configinfo.EmailEvents = AllEvents;
    } 
    else if (key == "EmailUserEvents") configinfo.EmailUserEvents = (cfgline[0] == "true");
    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 == "collectinfo") {
      if (cfgline.size() >= 3) {
    collectioninfo_t cinfo;
    cinfo.gsdl_gsdlhome = cfgline[1];
    cinfo.gsdl_gdbmhome = cfgline[2];
    configinfo.collectinfo[cfgline[0]] = cinfo;
      }
    }
    
    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++;
  }

  // configure the protocols
  recptprotolistclass::iterator protohere = protocols.begin ();
  recptprotolistclass::iterator protoend = protocols.end ();

  while (protohere != protoend) {
    assert ((*protohere).p != NULL);
    comerror_t err;
    if ((*protohere).p != NULL) 
      (*protohere).p->configure(key, cfgline, err);
    
    protohere++;
  }

  // configure the browsers
  browserptrmap::iterator browserhere = browsers.begin ();
  browserptrmap::iterator browserend = browsers.end ();

  while (browserhere != browserend) {
    assert ((*browserhere).second.b != NULL);
    if ((*browserhere).second.b != NULL) 
      (*browserhere).second.b->configure(key, cfgline);
    
    browserhere++;
  }
}


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


// init should be called after all the actions and protocols have been
// added to the receptionist and after everything has been configured but
// before any pages are created.  It returns true on success and false on
// failure. If false is returned getpage should not be called (without
// producing meaningless output), instead an error page should be produced
// by the calling code.
bool receptionist::init (ostream &logout) {

  // first configure collectdir
  text_t thecollectdir = configinfo.gsdlhome;
  if (!configinfo.collection.empty()) {
    // collection specific mode
    if (!configinfo.collectdir.empty()) {
      // has already been configured
      thecollectdir = configinfo.collectdir;
    } else {
      // decide where collectdir is by searching for collect.cfg
      // look in $GSDLHOME/collect/collection-name/etc/collect.cfg and
      // then $GSDLHOME/etc/collect.cfg
      thecollectdir = filename_cat (configinfo.gsdlhome, "collect");
      thecollectdir = filename_cat (thecollectdir, configinfo.collection);
      text_t filename = filename_cat (thecollectdir, "etc");
      filename = filename_cat (filename, "collect.cfg");

      if (!file_exists(filename)) thecollectdir = configinfo.gsdlhome;
    }
  }
  configure("collectdir", thecollectdir);

  // 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;
  }

  // there must be at least one browser defined
  if (browsers.empty()) {
    logout << "Error: no browsers 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));

  // if maintainer email address is something dodgy (for now I'll define
  // dodgy as being anything that doesn't contain '@') disable EmailEvents
  // and EmailUserEvents (we don't strictly need to disable EmailUserEvents
  // in this case but we will as it seems likely that MailServer will also
  // be screwed up if maintainer is).
  text_t::const_iterator maintainer_end = configinfo.maintainer.end ();
  text_t::const_iterator maintainer_here = findchar (configinfo.maintainer.begin(),
                             maintainer_end, '@');
  if (maintainer_here == maintainer_end) {
    configinfo.EmailEvents = Disabled;
    configinfo.EmailUserEvents = Disabled;
  } else {
    // if MailServer isn't set it should default to mail.maintainer-domain
    if (configinfo.MailServer.empty()) {
      configinfo.MailServer = "mail." + substr (maintainer_here+1, maintainer_end);
    }
  }

  // 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++;
  }

  // init the protocols
  recptprotolistclass::iterator protohere = protocols.begin ();
  recptprotolistclass::iterator protoend = protocols.end ();
  while (protohere != protoend) {
    comerror_t err;    
    if (((*protohere).p == NULL) ||
    !(*protohere).p->init(err, logout)) return false;
    protohere++;
  }

  // init the browsers
  browserptrmap::iterator browserhere = browsers.begin ();
  browserptrmap::iterator browserend = browsers.end ();
  while (browserhere != browserend) {
    if (((*browserhere).second.b == NULL) || 
    !(*browserhere).second.b->init(logout)) return false;
    browserhere++;
  }

  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, text_tmap &fcgienv) {

  // 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"], fcgienv);
  
  // 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 main cgi arguments
  if (!check_mainargs (args, logout)) return false;

  // 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_tmap &fcgienv) {

  text_t cookiestring = gsdl_getenv ("HTTP_COOKIE", fcgienv);
    
  text_t::const_iterator end = cookiestring.end();  
  text_t::const_iterator here = findchar (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 (cookiestring.begin(), end, 'G');
  }

  cookie.clear();
  text_t host = gsdl_getenv("REMOTE_ADDR", fcgienv);
  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_tmap &fcgienv) {

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

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

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

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

  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();

  ofstream log (lfile, ios::app);
  
  if (!log) {
    logout << "Error: Couldn't open file " << lfile << "\n";
    delete lfile;
    return false;
  }

  int fd = GSDL_GET_FILEDESC(log);

  // lock_val is set to 0 if file is locked successfully
  int lock_val = 1;
  GSDL_LOCK_FILE (fd);
  if (lock_val == 0) {
    log << text_t2utf8 << logstr;
    GSDL_UNLOCK_FILE (fd);
  } else {
    logout << "Error: Couldn't lock file " << lfile << "\n";
    log.close();
    delete lfile;
    return false;
  }

  log.close();
        
  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, text_tmap &fcgienv) {
  outconvertclass text_t2ascii;

  response_t response;
  text_t response_data;

  // produce cgi header
  get_cgihead_info (args, response, response_data, logout, fcgienv);
  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
    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, 
                     text_tmap &fcgienv) {
  outconvertclass text_t2ascii;

  // get the action
  action *a = actions.getaction (args["a"]);
  if (a != NULL) {
    a->get_cgihead_info (args, &protocols, 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(fcgienv))
      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();


  recptproto *collectproto = protocols.getrecptproto (args["c"], logout);
  if (collectproto != NULL) {
    // get browsers to process OID
    text_t OID = args["d"];
    if (OID.empty()) OID = args["cl"];
    if (!OID.empty()) {
      text_tset metadata;
      text_tarray OIDs;
      OIDs.push_back (OID);
      if (!is_top(OID)) OIDs.push_back (OID + ".pr");
      FilterResponse_t response;
      metadata.insert ("childtype");
      if (get_info (OIDs, args["c"], metadata, false, collectproto, response, logout)) {
    text_t classifytype;
    if (!response.docInfo[0].metadata["childtype"].values[0].empty())
      classifytype = response.docInfo[0].metadata["childtype"].values[0];
    else if (!is_top (OID)) {
      if (!response.docInfo[1].metadata["childtype"].values[0].empty())
        classifytype = response.docInfo[1].metadata["childtype"].values[0];
    }
    browserclass *b = browsers.getbrowser (classifytype);
    b->processOID (args, collectproto, logout);
      }
    }
  
    // translate "d" and "cl" arguments if required
    translate_OIDs (args, collectproto, logout);
  }
  
  // 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, &protocols, &browsers, 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);

  // load up the default macro files, the collection directory
  // is searched first for the file (if this is being used in
  // collection specific mode) and then the main directory(s)
  text_t colmacrodir = filename_cat (configinfo.collectdir, "macros");

  text_tset maindirs;
  text_t gsdlmacrodir = filename_cat (configinfo.gsdlhome, "macros");
  maindirs.insert (gsdlmacrodir);
  colinfo_tmap::iterator colhere = configinfo.collectinfo.begin();
  colinfo_tmap::iterator colend = configinfo.collectinfo.end();
  while (colhere != colend) {
    if (!((*colhere).second.gsdl_gsdlhome).empty()) {
      gsdlmacrodir = filename_cat ((*colhere).second.gsdl_gsdlhome, "macros");
      maindirs.insert (gsdlmacrodir);
    }
    colhere ++;
  }

  text_tset::iterator arrhere = configinfo.macrofiles.begin();
  text_tset::iterator arrend = configinfo.macrofiles.end();
  text_t filename;
  while (arrhere != arrend) {
    bool foundfile = false;

    // try in the collection directory if this is being
    // run in collection specific mode
    if (!configinfo.collection.empty()) {
      filename = filename_cat (colmacrodir, *arrhere);
      if (file_exists (filename)) {
    disp.loaddefaultmacros(filename);
    foundfile = true;
      }
    }

    // if we haven't found the macro file yet try in
    // the main macro directory(s)
    // if file is found in more than one main directory
    // we'll load all copies
    if (!foundfile) {
      text_tset::const_iterator dirhere = maindirs.begin();
      text_tset::const_iterator dirend = maindirs.end();
      while (dirhere != dirend) {
    filename = filename_cat (*dirhere, *arrhere);
    if (file_exists (filename)) {
      disp.loaddefaultmacros(filename);
      foundfile = true;
    }
    dirhere ++;
      }
    }

    // see if we found the file or not
    if (!foundfile) {
      logout << text_t2ascii 
         << "Error: the macro file \"" << *arrhere << "\" could not be found.\n";
      if (configinfo.collection.empty()) {
    text_t dirs;
    joinchar (maindirs, ", ", dirs);
    logout << text_t2ascii 
           << "It should be in either of the following directories ("
           << dirs << ").\n\n";

      } else {
    logout << text_t2ascii
           << "It should be in either " << colmacrodir << " or in " 
           << gsdlmacrodir << ".\n\n";
      }
      // reset logout to what it was
      disp.setlogout (savedlogout);
      return false;
    }
    arrhere++;
  }

  // success

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


// check_mainargs will check all the main arguments. If a major
// error is found it will return false and no cgi page should
// be created using the arguments.
bool receptionist::check_mainargs (cgiargsclass &args, ostream &logout) {
  // if this receptionist is running in collection dependant mode
  // then it should always set the collection argument to the
  // collection
  if (!configinfo.collection.empty()) args["c"] = configinfo.collection;

  // if current collection uses ccscols make sure
  // "ccs" argument is set and make "cc" default to
  // all collections in "ccs"
  if (!args["c"].empty()) {

    text_t &arg_c = args["c"];
    recptproto *collectproto = protocols.getrecptproto (arg_c, logout);
    if (collectproto == NULL) {
      // oops, this collection isn't valid
      outconvertclass text_t2ascii;
      logout << text_t2ascii << "ERROR: Invalid collection: " << arg_c << "\n";
      args["c"].clear();

    } else {

      ColInfoResponse_t *cinfo = get_collectinfo_ptr (collectproto, arg_c, logout);

      if (cinfo != NULL) {
    if (!cinfo->ccsCols.empty()) {
      args["ccs"] = 1;
      if (args["cc"].empty()) {
        text_tarray::const_iterator col_here = cinfo->ccsCols.begin();
        text_tarray::const_iterator col_end = cinfo->ccsCols.end();
        bool first = true;
        while (col_here != col_end) {
          // make sure it's a valid collection
          if (protocols.getrecptproto (*col_here, logout) != NULL) {
        if (!first) args["cc"].push_back (',');
        args["cc"] += *col_here;
        first = false;
          }
          col_here ++;
        }
      }
    }
      } else {
    logout << "ERROR (receptionist::check_mainargs): get_collectinfo_ptr returned NULL\n";
      }
    }
  }

  // argument "v" can only be 0 or 1. Use the default value
  // if it is out of range
  int arg_v = args.getintarg ("v");
  if (arg_v != 0 && arg_v != 1) {
    cgiarginfo *vinfo = argsinfo.getarginfo ("v");
    if (vinfo != NULL) args["v"] = vinfo->argdefault;
  }

  // argument "f" can only be 0 or 1. Use the default value
  // if it is out of range
  int arg_f = args.getintarg ("f");
  if (arg_f != 0 && arg_f != 1) {
    cgiarginfo *finfo = argsinfo.getarginfo ("f");
    if (finfo != NULL) args["f"] = finfo->argdefault;
  }

  return true;
}

// translate_OIDs translates the "d" and "cl" arguments to their correct values
// if they use the tricky ".fc", ".lc" type syntax.
void receptionist::translate_OIDs (cgiargsclass &args, recptproto *collectproto, 
                   ostream &logout) {

  FilterResponse_t response;
  FilterRequest_t request;
  comerror_t err;
  text_t &arg_d = args["d"];
  text_t &arg_cl = args["cl"];
  text_t &collection = args["c"];
  
  // do a call to translate OIDs if required
  request.filterName = "NullFilter";
  request.filterResultOptions = FROID;
  if (!arg_d.empty() && needs_translating (arg_d)) {
    request.docSet.push_back (arg_d);
    collectproto->filter (collection, request, response, err, logout);
    arg_d = response.docInfo[0].OID;
    request.clear();
  }
  // we'll also check here that the "cl" argument has a "classify" doctype 
  // (in case ".fc" or ".lc" have screwed up)
  if (needs_translating (arg_cl)) {
    request.fields.insert ("doctype");
    request.docSet.push_back (arg_cl);
    request.filterResultOptions = FRmetadata;
    collectproto->filter (collection, request, response, err, logout);
    // set to original value (without .xx stuff) if doctype isn't "classify"
    if (response.docInfo[0].metadata["doctype"].values[0] != "classify")
      strip_suffix (arg_cl);
    else
      arg_cl = response.docInfo[0].OID;
  }
}

// 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, &protocols, logout);
    }
    actionhere++;
  }

  // define internal macros for the current action
  a->define_internal_macros (disp, args, &protocols, 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) {

  text_t &collection = args["c"];

  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);

  if (!collection.empty()) {
    // DB // ****
    ColInfoResponse_t cinfo;
    comerror_t err;
    recptproto *collectproto = protocols.getrecptproto (collection, logout);
    if (collectproto != NULL) {
      collectproto->get_collectinfo (collection, cinfo, err, logout);
      text_t httpcollection;
      if (!cinfo.httpdomain.empty()) httpcollection = "http://";
      httpcollection += cinfo.httpdomain + cinfo.httpprefix + "/collect/" + collection; 
      disp.setmacro ("httpcollection", "Global", httpcollection); 
    }
  }

  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));

#if defined (__WIN32__)
  disp.setmacro ("win32", "Global", "1");
#endif

  // set macron macros if encoding is utf8
  if (args["w"] == "u") {
    disp.setmacro ("Amn", "Global", "&#256;");
    disp.setmacro ("amn", "Global", "&#257;");
    disp.setmacro ("Emn", "Global", "&#274;");
    disp.setmacro ("emn", "Global", "&#275;");
    disp.setmacro ("Imn", "Global", "&#298;");
    disp.setmacro ("imn", "Global", "&#299;");
    disp.setmacro ("Omn", "Global", "&#332;");
    disp.setmacro ("omn", "Global", "&#333;");
    disp.setmacro ("Umn", "Global", "&#362;");
    disp.setmacro ("umn", "Global", "&#363;");
  }

  // set _cgiargX_ macros for each cgi argument
  cgiargsclass::const_iterator argshere = args.begin();
  cgiargsclass::const_iterator argsend = args.end();
  while (argshere != argsend) {
    if (((*argshere).first == "q") ||
    ((*argshere).first == "qa") ||
    ((*argshere).first == "qtt") ||
    ((*argshere).first == "qty") ||
    ((*argshere).first == "qp") ||
    ((*argshere).first == "qpl") ||
    ((*argshere).first == "qr") ||
    ((*argshere).first == "q2"))
      // need to escape special characters from query string
      disp.setmacro ("cgiarg" + (*argshere).first, 
             "Global", html_safe((*argshere).second.value));
    else 
      disp.setmacro ("cgiarg" + (*argshere).first, "Global", dm_safe((*argshere).second.value));
    argshere ++;
  }

  // display text right to left if language is arabic (and if browser can support it)
  if (args["l"] == "ar")
    disp.setmacro ("htmlextra", "Global", " dir=rtl");

  // set collection specific macros
  if (!collection.empty()) {
    recptproto *collectproto = protocols.getrecptproto (collection, logout);
    if (collectproto != NULL) {
      FilterResponse_t response;
      text_tset metadata;
      get_info ("collection", collection, metadata, false, 
        collectproto, response, logout);
      
      if (!response.docInfo[0].metadata.empty()) {
    MetadataInfo_tmap::const_iterator here = response.docInfo[0].metadata.begin();
    MetadataInfo_tmap::const_iterator end = response.docInfo[0].metadata.end();
    while (here != end) {
      if (((*here).first != "haschildren") && ((*here).first != "hasnext") &&
          ((*here).first != "hasprevious")) {
        disp.setmacro ((*here).first, "Global", (*here).second.values[0]);
      }
      here ++;
    }
      }

      text_t iconcollection;
      disp.expandstring ("Global", "_iconcollection_", iconcollection);
      if (!iconcollection.empty())
    {
      ColInfoResponse_t cinfo;
      comerror_t err;
      collectproto->get_collectinfo (collection, cinfo, err, logout);
      if (iconcollection[0]=='/' && !cinfo.httpdomain.empty())
        {
          // local but with full path
          iconcollection = "http://" + cinfo.httpdomain + iconcollection;
          disp.setmacro("iconcollection", "Global", iconcollection);
        }
    }
    }
  }
}

// gets collection info from cache if found or 
// calls collection server (and updates cache)
// returns NULL if there's an error
ColInfoResponse_t *receptionist::get_collectinfo_ptr (recptproto *collectproto, 
                              const text_t &collection, 
                              ostream &logout) {
  
  // check the cache
  colinfo_tmap::iterator it = configinfo.collectinfo.find (collection);
  if ((it != configinfo.collectinfo.end()) && ((*it).second.info_loaded)) {
    // found it
    return &((*it).second.info);
  }

  // not cached, get info from collection server
  if (collectproto == NULL) {
    logout << "ERROR: receptionist::get_collectinfo_ptr passed null collectproto\n";
    return NULL;
  }
   
  comerror_t err;
  if (it == configinfo.collectinfo.end()) {
    collectioninfo_t cinfo;
    collectproto->get_collectinfo (collection, cinfo.info, err, logout);
    if (err != noError) {
      outconvertclass text_t2ascii;
      logout << text_t2ascii << "ERROR (receptionist::getcollectinfo_ptr): \""
         << get_comerror_string (err) << "\"while getting collectinfo\n";
      return NULL;
    }
    cinfo.info_loaded = true;
    configinfo.collectinfo[collection] = cinfo;
    return &(configinfo.collectinfo[collection].info);
  } else {
    collectproto->get_collectinfo (collection, (*it).second.info, err, logout);
    if (err != noError) {
      outconvertclass text_t2ascii;
      logout << text_t2ascii << "ERROR (receptionist::getcollectinfo_ptr): \""
         << get_comerror_string (err) << "\"while getting collectinfo\n";
      return NULL;
    }
    (*it).second.info_loaded = true;
    return &((*it).second.info);
  }
}

// removes a collection from the cache so that the next
// call to get_collectinfo_ptr() for that collection will
// retrieve the collection info from the collection server
void receptionist::uncache_collection (const text_t &collection) {

  colinfo_tmap::iterator it = configinfo.collectinfo.find (collection);
  if ((it != configinfo.collectinfo.end()) && ((*it).second.info_loaded)) {

    (*it).second.info_loaded = false;

  }
}

// 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 (!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;
    }
      }
    }
  }
}