mcs::UserThread Class Reference

#include <mcs.hh>

Inheritance diagram for mcs::UserThread:

Inheritance graph
[legend]

List of all members.


Detailed Description

The server side client thread.

This class provide the server functionality for a single client connected. Every time a new client is connected a new object based on this class (or a derived one) will be generated by the Server object.

The main methods are run() and exec(), the first is the body of the thread which reads command from the socket, the second is the execution unit of those commands.

This class can be derived to customize MCS behaviour. To do so simply overload one or more of the "hook" methods:

These methods are virtual, so you can overload them to customize the server, see the following code for an example. Suppose you want to implement a custom command, you should derive the UserThread class and overload the hk_exec() method:

  class MyClient : public UserThread
  {
    //Constructors MUST have the same parameters.
    MyClient(Thread* parent, int lID, int newsock) :
            UserThread(parent, lID, newsock);
    {}

    ~MyClient() {}

    RetValue hk_exec(CommandParser* cmd, bool& cmd_executed)
    {
      cmd_executed = false;
      if (cmd->cmpCmd("MyCustomCommand")) {
        cmd_executed = true;  //we are executing the command here
        //... do the job ...
      }
    }
  }

Once you define this class you should also derive the Server class with the MCS_CUSTOM_SERVER macro, so that it istantiate the correct class when a client connects (see the Server class description). Virtual methods aren't the only way to customize MCS, see also the callback functions in the Server class.

Definition at line 6382 of file mcs.hh.


Public Member Functions

ClientInfoinfo ()
 Return internal ClientInfo structure.
UserThreadoperator= (const UserThread &)
 Declared to avoid using of default assignment operator.
int userID ()
string userName ()
 Return the user name used to authenticate the client.
 UserThread (Thread *parent, int lID, int newsock)
 Constructor, called by a Server object when a new client is connected.
 UserThread (const UserThread &)
 Declared to avoid using of default copy constructor.
void wakeUpClient (Event *e=NULL)
 Send a message to the client.
 ~UserThread ()
 Destructor.

Public Attributes

Record recv
 Record of Data objects received from the client or other threads.
Record send
 Record of Data objects to be dispatched to be sent to client.

Protected Member Functions

RetValue exec (string cmd, string pars="")
 Execution method for user's command.
virtual RetValue hk_auth (int &grants, bool &loginok)
 Virtual method called when the user issue the MCS_CMD_DBCONNECT command.
virtual RetValue hk_connect ()
 Virtual method called when a new user connects to the server.
virtual void hk_disconnect ()
 Virtual method called when the user disconnect.
virtual RetValue hk_exec (CommandParser *cmd, bool &cmd_executed)
 Virtual method called before executing a command.
virtual void hk_postexec (CommandParser *cmd, RetValue ret)
 Virtual method called after a command has been executed.
Serverparent ()
 Return the address of the Server object which generates this Thread.
void prompt (RetValue ret)
 Send a prompt to client.
void run ()
 The body of the thread.
RetValue Send (vector< string > vec)
 Send a vector of strings to the client.
RetValue Send (string filename, string path)
 Send a file to the client.
RetValue Send (Record &vec)
 Send a Record object to client.
RetValue Send (Data &data)
 Send a Data object to client.
RetValue Send (Event e, bool log=true)
 Send a message to client.
void send2OtherThread (Data &d, int destid)
 Used to send data object to other threads.
RetValue sendQueryRes ()
 Send query results as it was a file created with the Query.Result2Ascii() method.
RetValue sendStrings (string str)
 Send strings to client.
void setActiveRS (RecordSet *rs, bool delWhenFinished=true)
string wpath (string fn="")
 Return the path of the work directory followed by the path given in parameter.

Protected Attributes

int batchlevel
 Nested batch level.
DBConn db
 Object to access DB.
string dbhost
 Host running database server.
string dbname
 Database name, usually the same as Env.appname.
string fnerr
 Default error file.
string fnout
 Default output file.
int grants
 User grants.
bool loginok
 Tells if client has logged in correctly.
int luserid
 The userid of current user.
string pass
 Password.
Queryquery
 Query object.
Socketsock
 Socket to client.
string user
 User name.

Private Attributes

int csocket
 C socket descriptor, used to initialize the Socket object.
bool deleters
ClientInfo linfo
 Structure containing client informations.
 MCS_DEBUG_ALLOC
RecordSetrs
Synchro syn

Constructor & Destructor Documentation

mcs::UserThread::UserThread ( const UserThread  ) 

Declared to avoid using of default copy constructor.

Warning:
This constructor is declared but not implemented. If you try to use it you will get a compilation error.

mcs::UserThread::UserThread ( Thread parent,
int  lID,
int  newsock 
)

Constructor, called by a Server object when a new client is connected.

Parameters:
parent Address of the parent Server object;
lID Thread identifier;
newsock The new C socket descriptor to be used by the new thread.

Definition at line 835 of file UserThread.cc.

mcs::UserThread::~UserThread (  ) 

Destructor.

Definition at line 892 of file UserThread.cc.


Member Function Documentation

RetValue mcs::UserThread::exec ( string  cmd,
string  pars = "" 
) [protected]

Execution method for user's command.

This method execute user's command. It also call the necessary virtual methods, and even itself in case of a batch execution.

The command can be given entirely in the first parameter, or even using the second. In any case the executed command will be "cmd pars".

This method can throw several exceptions which are catched by the run() method. If a FATAL exception is raised the run() method will exit killing the thread.

Parameters:
cmd String with the command;
pars Optional parameters.
Returns:
value telling if the command has been executed correctly.
Note:
This method will run in a critical section to be synchronized with the execution of the wakeUpClient() method.

Definition at line 295 of file UserThread.cc.

RetValue mcs::UserThread::hk_auth ( int &  grants,
bool &  loginok 
) [protected, virtual]

Virtual method called when the user issue the MCS_CMD_DBCONNECT command.

This method calls the cb_auth() and cbwa_auth() callback functions if defined.

If you overload this method the callback functions won't be called anymore. In this case if the return value is different from OK the authentication process will fail, and you should send an error message to the client using the Send() method.

Parameters:
grants Upon return should bear the grants for the user;
loginok Upon return is a flag saying if the user has logged in.
Returns:
The return value from cb_auth(), or OK if no callback defined.

Definition at line 968 of file UserThread.cc.

RetValue mcs::UserThread::hk_connect (  )  [protected, virtual]

Virtual method called when a new user connects to the server.

This method calls the cb_connect() and cbwa_connect() callback functions if defined.

If you overload this method the callback functions won't be called anymore. In this case if the return value is different from OK the thread would die immediately.

Returns:
The return value from cb_connect(), or OK if no callback defined.

Definition at line 948 of file UserThread.cc.

void mcs::UserThread::hk_disconnect (  )  [protected, virtual]

Virtual method called when the user disconnect.

This method calls the cb_disconnect callback function if defined.

If you overload this method the callback functions won't be called anymore.

Definition at line 961 of file UserThread.cc.

RetValue mcs::UserThread::hk_exec ( CommandParser cmd,
bool &  cmd_executed 
) [protected, virtual]

Virtual method called before executing a command.

This method calls the cb_exec() and cbwa_exec() callback functions if defined.

If you overload this method the callback functions won't be called anymore. In this case if the "cmd_executed" flag is true the exec() method will return immediately with the overloaded method's return value.

Parameters:
cmd Address of the actual CommandParser object;
cmd_executed Upon return tells if the command has been already executed or not.
Returns:
The return value from cb_exec(), or OK if no callback defined.

Definition at line 925 of file UserThread.cc.

void mcs::UserThread::hk_postexec ( CommandParser cmd,
RetValue  ret 
) [protected, virtual]

Virtual method called after a command has been executed.

This method calls the cb_postexec() and cbwa_postexec() callback functions if defined.

If you overload this method the callback functions won't be called anymore.

Parameters:
cmd Address of the actual CommandParser object;
ret Return value of the exec() method.

Definition at line 939 of file UserThread.cc.

ClientInfo & mcs::UserThread::info (  ) 

Return internal ClientInfo structure.

Definition at line 918 of file UserThread.cc.

UserThread& mcs::UserThread::operator= ( const UserThread  ) 

Declared to avoid using of default assignment operator.

Warning:
This operator is declared but not implemented. If you try to use it you will get a compilation error.

Server * mcs::UserThread::parent (  )  [protected]

Return the address of the Server object which generates this Thread.

Reimplemented from mcs::Thread.

Definition at line 984 of file UserThread.cc.

void mcs::UserThread::prompt ( RetValue  ret  )  [protected]

Send a prompt to client.

Actually we have three type of prompt:

so the user can see if the last command executed successfully or not.

Parameters:
ret A RetValue to determine the prompt to send.

Definition at line 169 of file UserThread.cc.

void mcs::UserThread::run (  )  [protected, virtual]

The body of the thread.

Will send a welcome message followed by a prompt when the object is started, then read line by line commands from the socket and execute them with the exec() method, until the socket is closed, a FATAL exception is raised, or someone kills this thread.

Reimplemented from mcs::Thread.

Definition at line 184 of file UserThread.cc.

RetValue mcs::UserThread::Send ( vector< string >  vec  )  [protected]

Send a vector of strings to the client.

Strings will be sent using the MSG_OUT code.

Parameters:
vec Reference to a vector of strings to be sent.

Definition at line 128 of file UserThread.cc.

RetValue mcs::UserThread::Send ( string  filename,
string  path 
) [protected]

Send a file to the client.

The file must be present in the work directory. See wpath().

Parameters:
filename Name of the file to be sent.
path Path to the file, including working dir.

Definition at line 118 of file UserThread.cc.

RetValue mcs::UserThread::Send ( Record vec  )  [protected]

Send a Record object to client.

Parameters:
vec Reference to a Record object data to be sent.

Definition at line 99 of file UserThread.cc.

RetValue mcs::UserThread::Send ( Data data  )  [protected]

Send a Data object to client.

Parameters:
data Reference to a Data object data to be sent.

Definition at line 80 of file UserThread.cc.

RetValue mcs::UserThread::Send ( Event  e,
bool  log = true 
) [protected]

Send a message to client.

Parameters:
e Event object containing information about an event;
log If true the message will also be logged.

Definition at line 70 of file UserThread.cc.

void mcs::UserThread::send2OtherThread ( Data d,
int  destid 
) [protected]

Used to send data object to other threads.

Definition at line 1005 of file UserThread.cc.

RetValue mcs::UserThread::sendQueryRes (  )  [protected]

Send query results as it was a file created with the Query.Result2Ascii() method.

If an exception is raised during the execution it will be catched, then the message will be sent to the user as ane error, and the Event type will be returned. If the raised exception is of type FATAL it will be rethrown.

Returns:
WARN if there was no result set, event type on a catched exception, OK otherwise.

Definition at line 139 of file UserThread.cc.

RetValue mcs::UserThread::sendStrings ( string  str  )  [protected]

Send strings to client.

The parameter is splitted in at newlines, then sent to client one by one using the MSG_OUT code.

Parameters:
str Strings to be sent.
Returns:
OK.

Definition at line 255 of file UserThread.cc.

string mcs::UserThread::userName (  ) 

Return the user name used to authenticate the client.

Definition at line 990 of file UserThread.cc.

void mcs::UserThread::wakeUpClient ( Event e = NULL  ) 

Send a message to the client.

Usually the this object is waiting to receive a request from the client on the other side of the socket. But sometime the LocalThread (or derived class) object needs to force the client to do something (see the LocalThread.run() method), in this case it can call this method to send a message to the client. The message sent will be the one contained in the Event object passd as parameter. If the parameter is null the message sent will be MSG_WAKE_UP.

Using this method makes sense only if on the other side of the socket there is a ClientThread object (see relative documentation), only in this case the client will react to this message.

Definition at line 261 of file UserThread.cc.

string mcs::UserThread::wpath ( string  fn = ""  )  [protected]

Return the path of the work directory followed by the path given in parameter.

No blanks, quotes or backslashes allowed.

Parameters:
fn Relative path.
Returns:
An absolute path in the "work" directory.

Definition at line 44 of file UserThread.cc.


Member Data Documentation

int mcs::UserThread::batchlevel [protected]

Nested batch level.

Definition at line 6406 of file mcs.hh.

int mcs::UserThread::csocket [private]

C socket descriptor, used to initialize the Socket object.

Definition at line 6387 of file mcs.hh.

DBConn mcs::UserThread::db [protected]

Object to access DB.

Definition at line 6434 of file mcs.hh.

string mcs::UserThread::dbhost [protected]

Host running database server.

Definition at line 6430 of file mcs.hh.

string mcs::UserThread::dbname [protected]

Database name, usually the same as Env.appname.

Definition at line 6427 of file mcs.hh.

string mcs::UserThread::fnerr [protected]

Default error file.

Definition at line 6418 of file mcs.hh.

string mcs::UserThread::fnout [protected]

Default output file.

Definition at line 6415 of file mcs.hh.

int mcs::UserThread::grants [protected]

User grants.

Definition at line 6412 of file mcs.hh.

ClientInfo mcs::UserThread::linfo [private]

Structure containing client informations.

Definition at line 6390 of file mcs.hh.

bool mcs::UserThread::loginok [protected]

Tells if client has logged in correctly.

Definition at line 6409 of file mcs.hh.

int mcs::UserThread::luserid [protected]

The userid of current user.

Definition at line 6403 of file mcs.hh.

string mcs::UserThread::pass [protected]

Password.

Definition at line 6424 of file mcs.hh.

Query* mcs::UserThread::query [protected]

Query object.

Definition at line 6437 of file mcs.hh.

Record mcs::UserThread::recv

Record of Data objects received from the client or other threads.

Definition at line 6730 of file mcs.hh.

Record mcs::UserThread::send

Record of Data objects to be dispatched to be sent to client.

Definition at line 6727 of file mcs.hh.

Socket* mcs::UserThread::sock [protected]

Socket to client.

Definition at line 6400 of file mcs.hh.

string mcs::UserThread::user [protected]

User name.

Definition at line 6421 of file mcs.hh.


The documentation for this class was generated from the following files:
mcslogo

MCS (My Customizable Server) ver. 0.3.3-alpha3
Documentation generated on Thu Mar 22 13:22:23 UTC 2012