You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
257 lines
8.3 KiB
257 lines
8.3 KiB
MClass - a C++ wrapper class of C-client |
|
======================================== |
|
This document describes the wrapper MClass. |
|
Any comment/questions/bug-report please send me an email or discuss it |
|
in the mailing list. |
|
|
|
Basics |
|
------ |
|
-To use the class just put mclass.* util.* callback.cpp in your source |
|
directory, |
|
|
|
include mclass.h in the file you would like to access MClass. |
|
|
|
-Must call initCC() before instantiating any Folder/Message objects!! |
|
|
|
-In c-client libray 2 macros T & NIL are defined. They are basically |
|
just 1 and 0/NULL respectively. |
|
|
|
-Messages in a folder are referenced by their order(an *unsigned long*) in the |
|
folder. The first message will always be 1. (So dont do a getMsg(0) :-) |
|
|
|
-Types of Message: These types are defined by C-client |
|
|
|
Macro Description |
|
----- ------------ |
|
TYPETEXT Normal text |
|
TYPEMULTIPART MIME |
|
TYPEMESSAGE Encapsulated message |
|
TYPEAPPLICATION Application data |
|
TYPEAUDIO Sound/music |
|
TYPEIMAGE Static image |
|
TYPEVIDEO Video |
|
TYPEOTHER Unknown |
|
|
|
Additional type up to TYPEMAX can be defined dynamically. |
|
(so we can define TYPEHTML or something like that) |
|
|
|
-Encodings |
|
Macro Description |
|
----- ----------- |
|
ENC7BIT 7-Bit semantic data |
|
ENC8BIT 8-Bit semantic data |
|
ENCBINARY 8-bit binary data |
|
ENCBASE64 Base-64 encoded data |
|
ENCQUOTEDPRINTABLE human-readable 8-as-7 bit data |
|
ENCOTHER Unknown |
|
|
|
Additional encodings up to ENCMAX can be defined dynamically. |
|
|
|
-Callbacks |
|
This is important. They are all prefixed by mm_ .Every application MUST have |
|
these defined properly by the programmers. Basically these are called by |
|
c-client when something interesting happens. For example during accessing |
|
network folder mm_login will be called to get user's login and password. |
|
|
|
|
|
-------------------------------------------------------------------------------- |
|
Functions |
|
-------------------------------------------------------------------------------- |
|
void initCC() |
|
This must be called once and only once prior to instantiation of any |
|
Folder/Message objects. |
|
|
|
long createFolder(char *mbox) |
|
This function creates a mailbox with name mbox. |
|
It returns T if successful, otherwise returns NIL. |
|
|
|
const char *getName() |
|
It gets the user name(not login) from /etc/passwd. |
|
|
|
const char *getHomeDir() |
|
It returns the user's home directory. |
|
|
|
const char *getDefaultInbox() |
|
It returns the default inbox(eg. /var/spool/mail/user1) |
|
|
|
const char *getHostName() |
|
It returns the local host name. |
|
-------------------------------------------------------------------------------- |
|
Message class |
|
-------------------------------------------------------------------------------- |
|
There are two occasions where you want to instantiate a message object; |
|
Getting a message from an existing mailbox or composing a new mail. Two sets of |
|
function have been designed for these two operations accordingly. If you created |
|
a message object for composing new mail, don't call functions like setText(), |
|
the result would be disastrous(i.e core dump)! |
|
(This will be fixed in the future) |
|
|
|
|
|
Message() |
|
Use it if you are composing a NEW message. |
|
See also Folder::getMsg() below. |
|
|
|
Getting message from a mailbox |
|
------------------------------ |
|
The *ONLY* way to get a message from a folder is to called the member |
|
function Message *Folder::getMsg(unsigned long). Memory is allocated from |
|
free storage so you have to free it after use. |
|
|
|
const char *getHeader() const |
|
It returns string of *unfiltered* RFC822 headers. Good for displaying |
|
headers in the View window. |
|
|
|
const char *getText(unsigned long *length) const |
|
It returns the text part of the message. For attachment please use |
|
getAttch(). 'length' must be a non-null pointer, the length of the |
|
message will be stored here. This is neccessary cos the string returned |
|
might include embedded NULs. (So you CANNOT assume the returned string |
|
is NULL-terminated). |
|
|
|
void getDate(char *buf) const |
|
It writes the date to the string buf. The format of the date is |
|
"DD/MM HH:MM". The buf must be large enough to hold the data. |
|
|
|
void getSubject(char *buf) const |
|
It writes the subject to the string buf. |
|
The buf must be large enough to hold the data. |
|
|
|
void getFrom(char *buf) const |
|
It writes the "From" field to the string buf. |
|
The buf must be large enough to hold the data. |
|
|
|
char getFlag() const |
|
It gets the flag of the message. The defined flags are: |
|
'D' - Deleted |
|
'A' - Answered(Replied) |
|
'U' - Unseen |
|
'N' - New mail |
|
|
|
void setFlag(char *flag) |
|
Though it's called "setFlag" it's not used for message composition. It's |
|
mainly used when you want to delete the message or have replied to the message, |
|
you do a setFlag(FLAG). FLAGs can be: |
|
FLAG Meaning |
|
---- ------- |
|
F_DEL deleted |
|
F_NEW new |
|
F_ANS answered |
|
F_SEEN seen |
|
P.S: It's very unusual to set F_NEW & F_SEEN but I'll let you do that anyway :-) |
|
|
|
void clearFlag(char *flag) |
|
It reverses the effect of setFlag. |
|
|
|
void del() |
|
Equivalent to setFlag(F_DEL), provided for convenience. |
|
|
|
P.S: It does not remove the current message from the mailbox. Deleted |
|
messages are not removed until you call Folder::expunge() or you close |
|
the folder with Folder::close(). |
|
|
|
void undel() |
|
An alias to clearFlag(F_DEL). |
|
|
|
void numAttch() |
|
This returns the number of attachments in the message. It DOES NOT |
|
include the text part. |
|
|
|
void export(FILE *f) |
|
This function writes the message to the file stream f. This can be used |
|
to export a message to a file. |
|
|
|
Composing Message |
|
----------------- |
|
Message() |
|
This constructor creates a new object of message. |
|
|
|
void setFrom(char *buf) |
|
Right now all it does is: |
|
1) Setting the email to <login>@<localhost> |
|
2) Setting the name to the entry in the /etc/passwd. |
|
The actual implementation largely depends on the way of configuration of |
|
kmail. |
|
|
|
void setTo(char *buf) |
|
Sets the recipient to buf where buf is a pointer to a string of email |
|
addresses delimited by comma ",". |
|
|
|
void setCc(char *cc) |
|
Similar to setTo() above. |
|
|
|
void setBcc(char *) |
|
Similar to setCc() above. |
|
|
|
void setSubject(char *buf) |
|
Sets the subject to buf. |
|
|
|
void setText(char *buf) |
|
Sets the message body to buf. Use this only if it's a RFC822 message |
|
(i.e. text only). |
|
|
|
long sendSMTP(const char *host) |
|
Obvious. |
|
Returns NIL if any errors are encoutered. Otherwise returns T. |
|
|
|
long sendMTA(const char *mta) |
|
It calls the MTA mta(usually sendmail) to send the message. |
|
Actually it popen()s a pipe to the mta and calls export(). |
|
|
|
-------------------------------------------------------------------------------- |
|
Folder class |
|
-------------------------------------------------------------------------------- |
|
Folder() |
|
Create a folder object |
|
|
|
long open(const char *mbox) |
|
The constructor opens the mailbox mbox. For local mailbox mbox is just |
|
the full path of the mailbox. If mbox happens to be a network mailbox |
|
(ie. pop3 or imap) mbox should be in the form of |
|
|
|
{<hostname>:[port]/user=<username>/service=<service>} |
|
|
|
hostname = mail server |
|
username = login name of the maili server |
|
port = TCP/IP port (optional) |
|
service = imap4 or pop3 |
|
|
|
It returns T if successful, otherwise returns NIL. |
|
|
|
close(long option = CL_EXPUNGE) |
|
Call close() to close the current folder. If no argument is given |
|
all messages marked as "deleted" are removed permanently. To keep the |
|
deleted messages call close with 0 as its argument. |
|
|
|
long remove() |
|
Removes the folder. |
|
It returns T if successful, otherwise NIL. |
|
(It's an error to delete INBOX or an non-existent mailbox) |
|
|
|
long create(char *mbox) |
|
Create a mailbox and set the mailbox current. |
|
If mbox couldnt be created/accessed NIL is returned. If everything's |
|
ok T is returned. |
|
|
|
void expunge() |
|
This function removes ALL deleted messages PERMANENTLY. |
|
|
|
long ping() |
|
This function checks for changes in the mailbox such as arrival of |
|
new mail or deletion of mail. Returns T if the mailbox is alive, otherwise |
|
NIL. Together with a Timer it can be used to implement 'Biff'. |
|
|
|
unsigned long numMsg() |
|
This function returns the number of messages in the folder. |
|
|
|
Message *getMsg(unsigned long msgno) |
|
It returns a message object if msgno is valid or returns NIL/NULL/0 |
|
pointer if msgno is out of range. You have to free the object after use. |
|
|
|
long status(long stat = SA_MESSAGES | SA_RECENT | SA_UNSEEN) |
|
stat - flags ORed together. The default is: |
|
SA_MESSAGE(no. of messages) | SA_RECENT(no. of new messages) |
|
| SA_UNSEEN(no. of unseen messages) |
|
|
|
long putMsg(Message *msg) |
|
It writes the message msg to the folder. |
|
|
|
|