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

Title: Mail Daemon
Auther: Parthenon @ LPUniversity
Date: 22-AUG-2006
Contributers: Parthenon

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

Contents:

i.   What is the mail daemon?
ii.  How the mail daemon works.
iii. How to create a client to interface with the mail daemon.
iv.  Variables used by the mail daemon.
v.   All of the functions the daemon entails.


i.   What is the mail daemon?

     The LPUniversity mail daemon takes care of the handling all of the mail
     related stuff on the mud... pretty obvious, huh? The mail daemon retrieves
     messages from a users mail box for viewing. It also is what handles the
     sending of messages to other players.
   

ii.  How the mail daemon works.

     The mail daemon really just sits there until a users uses a client to
     interface with the daemon. We will get to how to make a client for the mailer
     in a little bit. For now, you just need to know that the client will collect
     all the data, such as who the recipient of the message is, who the user
     wants it CC'd to, the subject, and the body of the message. After the
     client gets all of this info, it then sends that info to the mail daemon.
     The daemon then loads the recipients mail box, and saves the message in
     it. It then will also load the senders mail box and save a copy of the
     message to that persons outbox.
     

iii. How to create a client to interface with the mail daemon.

     Although there is already a mail client provided by LPUniversity, maybe
     you wish to create your own personalized one for your mud. If that is
     the case, you are going to need to know a few key functions to interface
     correctly with the mail daemon. Here I will list the way in which you will
     need to call the functions of the mail daemon. Please see section iv for
     details on each of the functions.
     
     This function is how the mail daemon sends messages to other players:
     
     MAIL_D->send_message(mapping mail, string owner, int in_msg, int out_msg)
     
     This function is how the mail daemon deletes a message:
     
     MAIL_D->delete_message(string owner, int num1, int num2, int flag, int curr_msg)
     
     This function will return a string of the path to the user's saved mail
     box file:
     
     MAIL_D->get_mail_box_file(string user)
     
     This function will restore a users mail box file, it is useful in
     resyncing the mail client if changes have been made to the mail file
     (such as new mail sent while already in the client):
     
     MAIL_D->restore(string user)
     
     This function allows a user to save mail messages to a file:
     
     MAIL_D->save(string user, mapping in_box, mapping out_box, int *indices)


iv.  Variables used by the mail daemon.

     mapping inbox:
       This mapping is of the form:
         ([ int <num1> : (["READ" : int is_read,
                           "BODY" : string num1_body,
                           "DATE" : string num1_date,
                           "FROM" : string sender,
                           "SUBJECT" : string num1_subject,
                           "TO" : string *num1_recipients,
                           "CC" : string *num1_cc_recipients ]),
            int <numN> : ([ blah blah ])
         ])
       
     mapping outbox:
       This mapping is of the same form as the inbox, only it is used for the
       outbox.
     
     int curr_in_msg:
       The current message index of the inbox.
     
     curr_out_msg:
       The current message index of the outbox.
     
     int in_start/end_index:
       This is the start and end point that tells the client which messages to
       display in the inbox
       
     int out_start/end_index:
       This is the start and end point that tells the client which messages to
       display in the outbox


v.   All of the functions the daemon entails.

     This section will tell you each of the functions contained in the mail
     daemon and the details of all it's arguments.
     
     string *get_all_members(string *parent_users);
     
     One of the features of the current LPUniversity mail client is that it
     allows a user to mail to groups instead of 'only' individual users. If
     someone wants to mail to a group then the need only put that group name
     surrounded by paranthesis as a recipient. This function is called by the
     mail daemon itself. The argument passed is the list of recipients. It
     checks if the names are surrounded by paranthesis and if so then it finds
     all users that exist inside that group. It is also powerful enough to
     work out groups inside of groups inside of groups and so on.
     
     string get_mail_box_file(string user);
     
     This function returns a users mail box file. The argument is a string of
     the users name.
     
     mixed send_message(mapping mail, string owner, int in_msg, int out_msg);
     
     This is the function that will 'send' the mail message. The first argument
     is a mapping containing all of the details of the mail message. The format
     of this mapping should be: ([ "TO" : string *recipients, "FROM" : string
     owner, "SUBJECT" : string subject, "CC" : string *cc_recipients, "DATE" :
     string date, "BODY" : string msg_body ]). The second argument is a string
     containing the 'owner'. The owner is the user that is using the mail
     client. Third argument is current inbox message, and the fourth is the
     current outbox message. The LPUniversity mail client keeps track of which
     message is currently 'activated' and marks it for the user. This way, if
     user wishes to choose options in the mail client, then the current message
     can be used instead of a specific message.
     
     varargs mixed delete_message(string owner, int num1, int num2, int flag, int curr_msg);
     
     This function deletes a message from a users mail box file. The first
     is a string containing the owner of the client's name. The second is
     an integer argument containing either the message number to delete
     or if it is a range of messages to delete, then it is where to start the
     deletion. The third argument is a the second number in a range to delete.
     If the user is only deleting a single message, then num2 should be passed
     as 0. The fourth argument is an integer variable that tells the daemon
     whether it needs to delete a message from the outbox or the inbox. If flag
     is 1, then it will delete the message/s from the outbox and if it is 0
     then it will delete from the inbox. The last argument is the current message.
     In your mail client you will need to figure out if it needs to be the current
     outbox message or inbox message, then send the apporpiate number. This will
     set the new current message to the message just after the deleted message/s.
     
     mapping restore(string user);
     
     This function returns a mapping of the users restored mail box file. 
     It is good for resyncing the mail client variables. All it takes is a string
     of the user's name. The return mapping is of the form ([ "inbox" :
     mapping inbox, "outbox" : mapping outbox, "curr_in_msg" : int curr_in_msg,
     "curr_out_msg" : int curr_out_msg, "in_start_index" : int in_start_index,
     "in_end_index" : int in_end_index, "out_start_index" : int out_start_index,
     "out_end_index" : int out_end_index ]).
     
     void save(string user, mapping in_box, mapping out_box, int *indices);
     
     This function allows the saving of messages to a file. A user can save one
     or more messages to the same file. The first argument is a string of the users
     name. The second is a mapping of the uesrs current inbox, and the third
     is a mapping of the users current outbox. The fourth argument is an array of
     integers of the form: ({ int curr_in_msg, int curr_out_msg, int in_start_index,
     int in_end_index, int out_start_index, int out_end_index }).
