			    NETMESSAGE - NETWORK OBJECT SERIALIZATION

Networking is accomplished in Olympus via a class called netmessage. Subclasses
of netmessage operate like any other object save one important distinction: they
can serialize/deserialize and send/receive themselves over the network given a 
network socket.

Each netmessage subclass is purpose specific and has a unique object ID as 
defined in:

    olympus/src/common/include/commid.h

They all take a Socket (not the system socket, but rather the non-blocking Socket
class fourn in olympus/src/common/transport/), a sessionID (or a moduleID as the
modules/plugins know it as) and a commandID.

There are currently seven different netmessage subclasses. Others are to come and
the existing ones will be filled out as additional functionality is required. We
are taking the "one step at a time" approach to reduce bloat due to featuritis.

Some of the netmessages still to come:

    nmUserData - return detailed information on the user    
    
Two special netmessages of import are nmSuccess and nmFailure. These are 
returned upon the success or failure of a netmessage command that otherwise has
nothing to return to the sender. They can be detected by looking at the ID given
along with the netmessage in the plugin->recv() method.

Each netmessage subclass is listed below with all their details, except the 
following, which are system utilities for user authentication, encryption 
negotiation, etc and are not relevant to writing plugins (if interested, look
at the source files):

    nmKexInit
    nmKexReply
    nmUserAuth
    nmVersion

--------------------------------------------------------------------------------
Name: nmExec                ID: COMMAND_EXEC

Purpose: To execute a command on the target host.

Constructor: nmExec(char* module, 
                    char* action, 
                    Socket * connection, 
                    unsigned long sessionID, 
                    unsigned long commandID)
                    
Parameters:  module and action are the identifiers for what you want to run on  
the target host. For example, to start the Apache webserver, module would be 
"Apache" and action would be "Start". Lists of modules and identifiers can be 
seen in the olympusd descriptor files or by polling the database at runtime.

This is perhaps one of the most flexible of all netmessages. It is nearly a 
virtual console allowing one to execute programs, get listings (module "system", 
action "ls"), etc...

Other Important Functions: 

char* results() - returns the results of the command
--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
Name: nmFetchConfig          ID: COMMAND_FETCHCONFIG

Purpose: Retrieves a configuration file from the target host.

Constructor: nmFetchConfig(char* _module,
                           char* _file,
                           Socket *connection,
                           unsigned long sessionID,
                           unsigned long commandID)
                           
Parameters:  module and file are the identifiers for which file you wish to get
from the target host. For example, to get the Apache configfile, module would be 
"Apache" and file would be "httpd.conf". Lists of modules and identifiers can be 
seen in the olympusd descriptor files or by polling the database at runtime.

Other Important Functions:

int configData() - returns a path to the temp file that has been received
--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
Name: nmPing                 ID: COMMAND_PING

Purpose: Sends a "ping" packet.

Constructor: nmFetchConfig(Socket *connection,
                           unsigned long sessionID,
                           unsigned long commandID)
                           
Parameters:  An extremely simple netmessage used to ping an Olympus target host.

Other Important Functions: 

void activate() - performs the ping calculations
--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
Name: nmSetExec              ID: COMMAND_SETEXEC

Purpose: Sets the command to be executed given a module and an action via 
nmExec.

Constructor: nmSetExecute(char* module, 
                          char* action, 
                          char* command, 
                          Socket * connection, 
                          unsigned long sessionID, 
                          unsigned long commandID);

                           
Parameters:  module and action are the identifiers for the command to alter and 
command is what to change it to. For example, to have Apache use apachectl to 
start the daemon, module would be "Apache", action would be "start" and command
would be "/path/to/apache/bin/apachectl start"

Other Important Functions: n/a 
--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
Name: nmStrStream            ID: COMMAND_STRSTREAM

Purpose: Allows a number of strings to be sent across the network 10 at a time.

Constructor: nmStrStream(transport * connection, 
                         unsigned long sessionID, 
                         unsigned long commandID,
                         int sequenceID = 0)
  
  
Parameters:  the only parameter of note here is sequenceID. It allows the 
receiver to know which nmStrStream messages belong together. Since each 
nmStrStream only transports a maximum of StrStreamCapacity (#def'd in 
nmStrStream.h) strings at a time, there is a need to know which "stream" the 
current message belongs to. On the server side there is a global object called 
serverSequence which will give a unique number that can be used for just this 
situation by calling serverSequence->next()

Other Important Functions:

int addStr(char* strToAdd) - adds a string to the list to send. it deep copies it
so strToAdd can be transient. If successful it returns the number of strings 
currently used out of the 10, or if already full returns TooFull (#def'd in 
nmStrStream.h)

int FillStrs(char* str1, char* str2 = "", char* str3 = "", char* str4 = "", 
             char* str5 = "", char* str6 = "", char* str7 = "", 
             char* str8 = "", char* str9 = "", char* str10 = "") - allows you
             to batch add strings (in case you know all of them at once)

void clear() - clears all the strings currently in use, resetting them to be
filled again

int amtFilled() - # of strings currently stored (server side)
int amtStrs() - # of strings currently stored (client side)
int amtEmpty() - capacity remaining in this netmessage

void setSequence(int sequenceID) - sets the sequence number to sequenceID
int  getSequence() - returns the sequence ID for this netmessage

bool lastPacket() - returns true if this is the last packet expected in this 
stream. (Determined by receiving a message in a stream that isn't completely
full. This may not be optimal in every conceivable situation, but works well
for everything we need to do and is easily worked around if it doesn't)


--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
Name: nmUpdateConfig        ID: COMMAND_UPDATECONFIG

Purpose: Updates a configuration file on the target host.

Constructor: nmUpdateConfig(char* newmodule, 
                            char* newfile, 
                            char* newinfo, 
                            Socket * connection, 
                            unsigned long sessionID,
                            unsigned long commandID);

Parameters:  module and file are the identifiers for which file you wish to get
from the target host. For example, to update the Apache configfile, module would 
be "Apache" and file would be "httpd.conf". newinfo is a pointer to the new data
to use. Lists of modules and identifiers can be seen in the olympusd descriptor 
files or by polling the database at runtime.

Other Important Functions: n/a
--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
Name: nmUsers               ID: COMMAND_USERS

Purpose: nmUsers allows one to add, remove or change the password for a user
account in the olympusd users database. Note that this is NOT used to make 
changes to user privileges on the target host; nmExec would be used for that.

Constructor: nmUsers(char* user, 
                     char* passwd, 
                     int action, 
                     Socket * connection, 
                     unsigned long sessionID, 
                     unsigned long commandID);
                           
Parameters:  user and passwd are the user's login name and password. action is 
one of: NMUSERS_ADD_USER, NMUSERS_REMOVE_USER or NMUSERS_CHANGE_PASSWORD. They
each do exactly what they say the do.

Other Important Functions: n/a
--------------------------------------------------------------------------------
