#ifndef __HTTP_IDL
#define __HTTP_IDL

/*
 * Interface for CORBA http servlets.
 * (C) GradSoft 2000, 2001, 2002
 * http://www.gradsoft.com.ua
 * All rights reserved.
 * (C) Ruslan Shevchenko <Ruslan@Shevchenko.Kiev.UA>
 *  1999, 2000, 2001, 2002
 * All rights reserved.
 * $Id: HTTP.idl,v 1.2 2002/06/17 21:15:59 rssh Exp $
 */


#pragma prefix "gradsoft.kiev.ua"

/**
 * Module for CORBA http servlets.
 **/
module HTTP {

   ///

   ///
   typedef sequence<octet> HTTPOctSeq;
   ///
   typedef sequence<string> HTTPStrSeq;

   /**
    * used for passing binary parameters from
    * users forms
    **/
   struct BinaryParameter
   {
     /// 
     string  name;
     /// 
     HTTPOctSeq value;
   };
   ///
   

 
   /**
    * used for passing parameters from
    * users forms
    **/
   struct Parameter
   {
     ///
     string  name;
     ///
     string value;
   };


   ///
   typedef sequence<Parameter>  ParameterSequence;
   ///
   typedef sequence<BinaryParameter>  BinaryParameterSequence;

   /**
    * what we know about client:
    **/
   struct ClientInfo
   {
     /**
      * IP adress of client
      **/
     string ip;
     /**
      * hostname of client
      **/
     string hostname;
     /**
      * user name of client.
      * (or 'unknown', if handler does not require authorization)
      **/
     string user_name;
   };

   /**
    * what we know about web server
    **/
   struct ServerInfo
   {
     ///
     string hostname;
     ///
     short  port;
   };

   /**
    * this struct describe user request
    **/
   struct RequestInfo
   {
     ///
     ClientInfo        client_info;
     ///
     ServerInfo        server_info;
     ///
     ParameterSequence parameters;
     ///
     ParameterSequence cookies;
     ///
     BinaryParameterSequence binary_parameters;
     ///
     string            method;
   };


   /**
    * Information about reply header in one package.
    **/
   struct ReplyHeaderInfo
   {
     string            content_type;
     ParameterSequence fields;
     ParameterSequence cookies;
     unsigned long     cookie_expire_time;
   };

   /**
    * Can be raised by user servlets code.
    **/
   exception ExternalException
   {
     /// http code, which we want return to client
     short http_code;
     /// string description of error.
     string reason;
   };

   /**
    * raised by web server, when user output stream is cancelled
    **/
   exception StreamClosedException {};

   /**
    * raised by create_handler(), when user login and password required
    **/
   exception RequireAuthInfo {};

   /**
    * raised by create_handler(), when ClientInfo::ip or ClientInfo::hostname
    * or ServerInfo::hostname or ServerInfo::port have no access to this
    * servlet or handler
    **/
   exception AccessDenied {};

   /**
    * throwed from Servlet::create_handler or handler::run to redirect request
    * to other URL.
    **/
   exception Redirect {
     ///
     string url;
     ///
     ParameterSequence parameters;
   };


   /**
    * Servel comunicate with web server (and users web browser)
    * via this interface, during handling of request.
    **/
   interface HTTPStream
   {
     ///

     /**
      * set content type of servlet output.
      *@precondition
      *  it must be done before call of send_http_header
      **/
     void set_content_type(in string content_type);


     /**
      * set additional http header name-value pair
      *@precondition
      *  it must be done before call of send_http_header
      **/
     void set_http_header(in string name, in string value);


     /**
      * get http header value for requested name
      * return value of http header in request.
      **/
     string get_http_header(in string name);

     /**
      * set cookie in output client header.
      *@precondition
      *  it must be done before call of send_http_header
      **/
     void set_cookie(in string name, in string value, 
                     in unsigned long expire_time );
                                   
     ///
     void send_http_header(); 

     ///
     void send_http_header_ex(in ReplyHeaderInfo header_info);

     /**
      * send string to user browser
      **/
     void puts(in string str)  
                   raises(StreamClosedException);

     /**
      * send sequence of octet to user browser.
      **/
     unsigned long send_buffer(in HTTPOctSeq buffer)
                   raises(StreamClosedException);

     /**
      * flush output stream.
      **/
     void flush()
                   raises(StreamClosedException);

   };

   /**
    * Application programmer must provide implementation of this
    * interface.
    **/
   interface RequestHandler
   {

     ///

     /**
      * handle request and output results to HTTPStream
      **/
     void  handle(in RequestInfo request_info, in HTTPStream stream)
                  raises(ExternalException, StreamClosedException, Redirect);

     /**
      * destroy request handler. This method is
      * called by servlet engine after processing of request.
      * programmer must not call this method directly.
      **/
     void  destroy();
   };

   /**
    * throwed by servlet when we try to call unexistent handler
    **/
   exception NoSuchHandlerException {};


   /**
    * Application programmer must provide implementation
    * for this interface and bind it to "HTTPServ/Name" in
    * Naming Service
    **/
   interface Servlet
   {
      /**
       * create handler for request.
       *@exception NoSuchHandlerException when we try to call 
       *            unexistent handler
       *@exception RequireAuthInfo  when Servelt require filled client name
       *            and client password structure, but it is not passed with
       *            this call (and ModCbroker popup auth window on next step)
       *@exception AccessDenied when access for this user is denied
       *@exception ExternalException can be throwed by servlet.
       *@exception Redirect
       **/
      RequestHandler create_handler(in string handler_name, 
                                    in ClientInfo client_info, 
                                    in ServerInfo server_info,
                                    in string passwd)
                                       raises(NoSuchHandlerException,
                                              RequireAuthInfo,
                                              AccessDenied,
                                              ExternalException,
                                              Redirect
                                             );
   };


};

#endif