Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members  

client.h

Go to the documentation of this file.
00001 #ifndef DV_TICKET_CLIENT_H
00002 #define DV_TICKET_CLIENT_H
00003 
00004 // $Id: ticket.h,v 1.11 2003/07/19 12:38:55 dvermeir Exp $
00005 #include <string>
00006 #include <set>
00007 #include <iostream>
00008 #include <stdexcept>
00009 #include <dvticket/user.h>
00010 #include <dvutil/date.h>
00011 #include <dvutil/ref.h>
00012 
00013 namespace Dv {
00014 namespace Ticket {
00015 
00016 class LoginRequest;
00017 class AnonLoginRequest;
00018 class ValidateRequest;
00019 
00020 /** Class representing a ticket. */
00021 class Ticket {
00022 friend class LoginRequest;
00023 friend class AnonLoginRequest;
00024 friend class ValidateRequest;
00025 
00026 public:
00027 
00028   /** Ticket exception class. */
00029   class Exception: public std::runtime_error {
00030   public:
00031     /** Class name, i.e. "Dv::Ticket::Server::Exception".  */
00032     static const std::string NAME;
00033     /** Constructor.
00034      * @param msg message to append to NAME.
00035      */
00036     Exception(const std::string& msg): std::runtime_error(NAME + ": " + msg) {}
00037   };
00038 
00039   /** Type of serial number of ticket. */
00040   typedef unsigned long SERIAL;
00041   /** Type of reference-counted pointer to ticket. */
00042   typedef Dv::Util::ref<Dv::Ticket::Ticket> Ref;
00043 
00044   /** @return Owner of this ticket. */
00045   const User&  user() const { return user_; }
00046   /** @return Serial number of this ticket. */
00047   SERIAL serial() const { return serial_; }
00048   /** @return expiration date of this ticket */
00049   const Dv::Util::Date&  expiration_date() const { return expiration_date_; }
00050 
00051   /** Return an XML representation of a ticket.
00052    * @param name to be used as the root tag
00053    * @return root node of XML representation
00054    */
00055   Dv::Xml::Node xml(const std::string& name="ticket") const;
00056 
00057   /** Obtain a new ticket from a ticket server.
00058    * @param host name of ticket server
00059    * @param port on which ticket server is listening
00060    * @param name of user to obtain ticket for
00061    * @param password of user to obtain ticket for
00062    * @param info to be added to (user date member) in ticket
00063    * @param duration (in minutes) that ticket should remain valid.
00064    * @return a reference-counted pointer to a valid ticket,
00065    *   or a nil pointer.
00066    * @sa Dv::Ticket::Authenticator
00067    */
00068   static Ref buy(const std::string& host, int port, const std::string& name, 
00069     const std::string& password, const std::string& info="", size_t duration=30)
00070       throw ();
00071 
00072   /** Obtain a new ticket from a ticket server. This function
00073    * explicitly specifies the client host, which may be different
00074    * from the host on which this function is called.
00075    * It is useful e.g. for general "login" cgi programs. Such
00076    * programs avoid user programs to deal with passwords.
00077    * @param client_host name of ticket server
00078    * @param server_host name of ticket server
00079    * @param port on which ticket server is listening
00080    * @param name of user to obtain ticket for
00081    * @param password of user to obtain ticket for
00082    * @param info to be added to (user date member) in ticket
00083    * @param duration (in minutes) that ticket should remain valid.
00084    * @return a reference-counted pointer to a valid ticket,
00085    *   or a nil pointer.
00086    * @warning This function must be called from the same host
00087    *   as the one running the ticket server.
00088    * @sa Dv::Ticket::Authenticator
00089    */
00090   static Ref buy(const std::string& client_host, const std::string& server_host, int port,
00091     const std::string& name, const std::string& password, const std::string& info="", 
00092     size_t duration=30) throw ();
00093 
00094   /** Buy an anonymous ticket from a ticket server.
00095    * @param host name of ticket server
00096    * @param port on which ticket server is listening
00097    * @param name of user to obtain ticket for
00098    * @param info to be added to (user date member) in ticket
00099    * @param duration (in minutes) that ticket should remain valid.
00100    * @return a reference-counted pointer to a valid ticket,
00101    *   or a nil pointer. The ticket user will have "anonymous"
00102    *   as its category.
00103    * @sa Dv::Ticket::User
00104    * @sa Dv::Ticket::Authenticator
00105    */
00106   static Ref buy_anon(const std::string& host, int port, const std::string& name="anonymous", 
00107     const std::string& info="", size_t duration=30) throw ();
00108 
00109 
00110   /** Obtain a ticket by validating a serial number with a ticket
00111    * server.
00112    * @param server_host name of ticket server
00113    * @param server_port on which ticket server is listening
00114    * @param serial number of previously obtained ticket
00115    * @return a reference-counted pointer to a valid ticket,
00116    *   or a nil pointer.
00117    */
00118   static Ref validate(const std::string& server_host, int server_port, SERIAL serial)
00119     throw ();
00120 
00121   /** Obtain a ticket by validating a serial number with a ticket
00122    * server.
00123    * @param server_host name of ticket server
00124    * @param server_port on which ticket server is listening
00125    * @param host dot address of owner host of ticket
00126    * @param serial number of previously obtained ticket
00127    * @return a reference-counted pointer to a valid ticket,
00128    *   or a nil pointer.
00129    */
00130   static Ref validate(const std::string& server_host, int server_port,
00131     const std::string& host, SERIAL serial) throw ();
00132 
00133 private:
00134   /** Copy ctor is forbidden. */
00135   Ticket(const Ticket&); 
00136   /** Assignment is forbidden. */
00137   Ticket& operator=(const Ticket&); 
00138 
00139   /** Create and store a new ticket for a user.
00140    * @param db database connection.
00141    * @param user which is supposed to have been authenticated
00142    * @param host for which ticket will be valid, in dot notation (e.g.  134.184.65.2)
00143    * @param duration that ticket will be valid, in minutes.
00144    * @exception Dv::Ticket::Ticket::Exception if anything goes wrong
00145    */
00146   Ticket(Dv::Sql::Db& db, const User& user, const std::string& host, size_t duration)
00147     throw (Dv::Ticket::Ticket::Exception);
00148 
00149   /** Retrieve a ticket with a given serial number.
00150    * @param db database connection.
00151    * @param serial unique numeric ID of ticket
00152    * @param host that should be associated with the ticket
00153    * @exception Dv::Ticket::Ticket::Exception if anything goes wrong,
00154    *  e.g. the ticket is no longer valid, or the ticket with the
00155    *  given id was issued for a different host.
00156    */
00157   Ticket(Dv::Sql::Db& db, SERIAL serial, const std::string& host) 
00158     throw (Dv::Ticket::Ticket::Exception);
00159   /** Simple ctor. 
00160    * @param user which is supposed to have been authenticated
00161    * @param serial unique numeric ID of ticket
00162    * @param expiration_date when ticket expires
00163    */
00164   Ticket(const User& user, SERIAL serial, Dv::Util::Date expiration_date)
00165     throw (): user_(user), serial_(serial), expiration_date_(expiration_date) {}
00166 
00167   /** User to whom this ticket was issued. */
00168   User  user_;
00169   /** Host for which this ticket was issued. */
00170   // std::string  host_;
00171   /** Unique serial number of this ticket. */
00172   SERIAL  serial_;
00173   /** Expiration date for this ticket. */
00174   Dv::Util::Date  expiration_date_;
00175 };
00176 
00177 }}
00178 
00179 #endif

dvticket-0.5 [ 6 August, 2003]