sbuild::auth_conv_tty Class Reference

Authentication conversation handler for terminal devices. More...

#include <sbuild-auth-conv-tty.h>

Inheritance diagram for sbuild::auth_conv_tty:

Inheritance graph
[legend]
Collaboration diagram for sbuild::auth_conv_tty:

Collaboration graph
[legend]
List of all members.

Public Types

enum  error_code { TIMEOUT, TIMEOUT_PENDING, TERMIOS, CONV_TYPE }
 Error codes. More...
typedef custom_error< error_codeerror
 Exception type.

Public Member Functions

 auth_conv_tty ()
 The constructor.
virtual ~auth_conv_tty ()
 The destructor.
virtual time_t get_warning_timeout ()
 Get the time at which the user will be warned.
virtual void set_warning_timeout (time_t timeout)
 Set the time at which the user will be warned.
virtual time_t get_fatal_timeout ()
 Get the time at which the conversation will be terminated with an error.
virtual void set_fatal_timeout (time_t timeout)
 Set the time at which the conversation will be terminated with an error.
virtual void conversation (auth_conv::message_list &messages)
 Hold a conversation with the user.

Private Member Functions

int get_delay ()
 Get the time delay before the next SIGALRM signal.
std::string read_string (std::string message, bool echo)
 Read user input from standard input.

Private Attributes

time_t warning_timeout
 The time to warn at.
time_t fatal_timeout
 The time to end at.
time_t start_time
 The time the current delay was obtained at.

Detailed Description

Authentication conversation handler for terminal devices.

This class is an implementation of the auth_conv interface, and is used to interact with the user on a terminal (TTY) interface.

In order to implement timeouts, this class uses alarm(2). This has some important implications. Global state is modified by the object, so only one may be used at once in a single process. In addition, no other part of the process may set or unset the SIGALRM handlers and the alarm(2) timer during the time PAM authentication is proceeding.

Definition at line 44 of file sbuild-auth-conv-tty.h.


Member Typedef Documentation

typedef custom_error<error_code> sbuild::auth_conv_tty::error

Exception type.

Definition at line 57 of file sbuild-auth-conv-tty.h.


Member Enumeration Documentation

enum sbuild::auth_conv_tty::error_code

Error codes.

Enumerator:
TIMEOUT  Timed out.
TIMEOUT_PENDING  Time is running out...
TERMIOS  Failed to get terminal settings.
CONV_TYPE  Unsupported conversation type.

Definition at line 48 of file sbuild-auth-conv-tty.h.


Constructor & Destructor Documentation

auth_conv_tty::auth_conv_tty (  ) 

The constructor.

Definition at line 122 of file sbuild-auth-conv-tty.cc.

auth_conv_tty::~auth_conv_tty (  )  [virtual]

The destructor.

Definition at line 129 of file sbuild-auth-conv-tty.cc.


Member Function Documentation

time_t auth_conv_tty::get_warning_timeout (  )  [virtual]

Get the time at which the user will be warned.

Returns:
the time.

Implements sbuild::auth_conv.

Definition at line 134 of file sbuild-auth-conv-tty.cc.

References warning_timeout.

void auth_conv_tty::set_warning_timeout ( time_t  timeout  )  [virtual]

Set the time at which the user will be warned.

Parameters:
timeout the time to set.

Implements sbuild::auth_conv.

Definition at line 140 of file sbuild-auth-conv-tty.cc.

References warning_timeout.

time_t auth_conv_tty::get_fatal_timeout (  )  [virtual]

Get the time at which the conversation will be terminated with an error.

Returns:
the time.

Implements sbuild::auth_conv.

Definition at line 146 of file sbuild-auth-conv-tty.cc.

References fatal_timeout.

void auth_conv_tty::set_fatal_timeout ( time_t  timeout  )  [virtual]

Set the time at which the conversation will be terminated with an error.

Parameters:
timeout the time to set.

Implements sbuild::auth_conv.

Definition at line 152 of file sbuild-auth-conv-tty.cc.

References fatal_timeout.

void auth_conv_tty::conversation ( auth_conv::message_list messages  )  [virtual]

Hold a conversation with the user.

Each of the messages detailed in messages should be displayed to the user, asking for input where required. The type of message is indicated in the auth_message::type field of the auth_message. The auth_message::response field of the auth_message should be filled in if input is required.

On error, an exception will be thrown.

Parameters:
messages the messages to display to the user, and responses to return to the caller.

Implements sbuild::auth_conv.

Definition at line 278 of file sbuild-auth-conv-tty.cc.

References CONV_TYPE, sbuild::DEBUG_NOTICE, sbuild::log_debug(), sbuild::log_error(), sbuild::log_info(), sbuild::auth_message::MESSAGE_ERROR, sbuild::auth_message::MESSAGE_INFO, sbuild::auth_message::MESSAGE_PROMPT_ECHO, sbuild::auth_message::MESSAGE_PROMPT_NOECHO, and read_string().

Here is the call graph for this function:

int auth_conv_tty::get_delay (  )  [private]

Get the time delay before the next SIGALRM signal.

If either the warning timeout or the fatal timeout have expired, a message to notify the user is printed to stderr. If the fatal timeout is reached, an exception is thrown.

Returns:
the delay in seconds, or 0 if no delay is set.

Definition at line 158 of file sbuild-auth-conv-tty.cc.

References fatal_timeout, sbuild::log_exception_warning(), start_time, TIMEOUT, TIMEOUT_PENDING, timer_expired, and warning_timeout.

Referenced by read_string().

Here is the call graph for this function:

Here is the caller graph for this function:

std::string auth_conv_tty::read_string ( std::string  message,
bool  echo 
) [private]

Read user input from standard input.

The prompt message is printed to prompt the user for input. If echo is true, the user input it echoed back to the terminal, but if false, echoing is suppressed using termios(3).

If the SIGALRM timer expires while waiting for input, this is handled by re-checking the delay time which will warn the user or cause the input routine to terminate if the fatal timeout has expired.

Parameters:
message the message to prompt the user for input.
echo echo user input to screen.
Returns:
a string, which is empty on failure.

Definition at line 185 of file sbuild-auth-conv-tty.cc.

References get_delay(), reset_alarm(), set_alarm(), TERMIOS, and timer_expired.

Referenced by conversation().

Here is the call graph for this function:

Here is the caller graph for this function:


Member Data Documentation

time_t sbuild::auth_conv_tty::warning_timeout [private]

The time to warn at.

Definition at line 112 of file sbuild-auth-conv-tty.h.

Referenced by get_delay(), get_warning_timeout(), and set_warning_timeout().

time_t sbuild::auth_conv_tty::fatal_timeout [private]

The time to end at.

Definition at line 114 of file sbuild-auth-conv-tty.h.

Referenced by get_delay(), get_fatal_timeout(), and set_fatal_timeout().

time_t sbuild::auth_conv_tty::start_time [private]

The time the current delay was obtained at.

Definition at line 116 of file sbuild-auth-conv-tty.h.

Referenced by get_delay().


The documentation for this class was generated from the following files:
Generated on Sat Jan 27 16:12:49 2007 for schroot by  doxygen 1.5.1