source: trunk/gsdl/src/recpt/receptionist.h@ 533

/**********************************************************************
 *
 * receptionist.h -- 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.
 *
 * $Id: receptionist.h 533 1999-09-07 04:57:01Z sjboddie $
 *
 *********************************************************************/


#ifndef RECEPTIONIST_H
#define RECEPTIONIST_H

#include "gsdlconf.h"
#include "text_t.h"
#include "cgiargs.h"
#include "display.h"
#include "action.h"
#include "recptproto.h"
#include "converter.h"

// the MACROPRECEDENCE macro is used as a default. override
// it using something like:
//
// macroprecedence c,l
//
// in your configuration file
#ifndef MACROPRECEDENCE
#define MACROPRECEDENCE "c,l"
#endif


struct recptconf {
  text_t gsdlhome;
  text_t collection; // will equal "" in 'general' mode
  text_t collectdir; // will equal gsdlhome in 'general' mode
  text_t httpprefix;
  text_t httpimg;
  text_t gwcgi;
  text_tarray macrofiles;
  text_t saveconf;
  bool usecookies;  // true if we want cookies set
  bool logcgiargs;  // true if we want to log cgi arguments

  text_tmap pageparams;
  text_t macroprecedence;
  
  void clear ();
  recptconf () {clear();}
};


class receptionist {
protected:
  recptconf configinfo;

  cgiargsinfoclass argsinfo;
  actionmapclass actions;
  recptprotolistclass protocols;
  displayclass disp;
  convertinfoclass converters;
  ColInfoResponse_t collectinfo;
  
  // prepare_page sets up page parameters, sets display macros
  // and opens the page ready for output 
  virtual void prepare_page (action *a, cgiargsclass &args, recptproto *collectproto,
                 outconvertclass &outconvert, ostream &logout);
  
  virtual void translate_OIDs (cgiargsclass &args, recptproto *collectproto, ostream &logout);

  bool get_cookie (text_t &cookie);
  bool get_cookie ();

  virtual void define_general_macros (cgiargsclass &args, recptproto *collectproto,
                      outconvertclass &outconvert, ostream &logout);

public:
  receptionist ();
  virtual ~receptionist() {}

  // add_action makes another action available to the receptionist
  // the action remains the property of the calling code and that
  // code should destroy the action after the recptionist has been
  // destroyed.
  void add_action (action *theaction);
  actionmapclass *get_actionmap_ptr () {return &actions;}

  // add_protocol makes another protocol available to the receptionist
  // without any protocols, no collections will be available. The
  // protocols remain the property of the calling code.
  void add_protocol (recptproto *theprotocol) {protocols.addrecptproto(theprotocol);}
  recptprotolistclass *get_recptprotolist_ptr () {return &protocols;}
  
  // add_converter makes another converter available to the receptionist.
  // Converters are needed to display pages using different encodings.
  // The converters remain the property of the calling code.
  void add_converter (const text_t &name, inconvertclass *inconverter,
              rzwsoutconvertclass *outconverter) {
    converters.add_converter(name, inconverter, outconverter);}
  convertinfoclass *get_convertinfo_ptr () {return &converters;}
  
  
  // 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.
  virtual void configure (const text_t &key, const text_tarray &cfgline);
  virtual void configure (const text_t &key, const text_t &value);
  const recptconf &get_configinfo () {return configinfo;}
  cgiargsinfoclass *get_cgiargsinfo_ptr () {return &argsinfo;}
  

  // init should be called after all the actions, protocols, and
  // converters 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.
  virtual bool init (ostream &logout);
  
  // There are two ways to produce a page. You can either call parse_cgi_args,
  // get_cgihead_info, and produce_content or you can just call parse_cgi_args and
  // produce_cgi_page (which will be satisfactory in most cases). You might want to call
  // parse_cgi_args, get_cgihead_info, and produce_content when you want to
  // interface directly with a web server for which the standard header is inappropriate.

  // 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.
  virtual bool parse_cgi_args (const text_t &argstr, cgiargsclass &args, ostream &logout);

  virtual bool log_cgi_args (cgiargsclass &args, ostream &logout);

  // 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
  virtual bool produce_cgi_page (cgiargsclass &args, ostream &contentout, 
                 ostream &logout);
  
  // 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.
  virtual void get_cgihead_info (cgiargsclass &args, response_t &response,
                 text_t &response_data, ostream &logout);
  
  // produce the page content
  virtual bool produce_content (cgiargsclass &args, ostream &contentout,
                ostream &logout);
  
  // returns the compressed argument ("e") corresponding to the argument
  // list. This can be used to save preferences between sessions.
  text_t get_compressed_arg (cgiargsclass &args, ostream &logout);
  
protected:
  // 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.
  virtual bool read_macrofiles (ostream &logout);
  
  // 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.
  virtual bool check_mainargs (cgiargsclass &args, ostream &logout);
};


#endif