PTLib  Version 2.10.4
PMail Class Reference

This class establishes a mail session with the platforms mail system. More...

#include <mail.h>

Inheritance diagram for PMail:
PObject

List of all members.

Classes

struct  Header
 Message header for each mail item. More...

Public Member Functions

Construction
 PMail ()
 Create a mail session.
 PMail (const PString &username, const PString &password)
 Create a mail session.
 PMail (const PString &username, const PString &password, const PString &service)
 Create a mail session.
virtual ~PMail ()
Log in/out functions
PBoolean LogOn (const PString &username, const PString &password)
 Attempt to log on to the mail system using the parameters provided.
PBoolean LogOn (const PString &username, const PString &password, const PString &service)
 Attempt to log on to the mail system using the parameters provided.
virtual PBoolean LogOff ()
 Log off from the mail system.
PBoolean IsLoggedOn () const
 Determine if the mail session is active and logged into the mail system.
Send message functions
PBoolean SendNote (const PString &recipient, const PString &subject, const char *body)
 Send a new simple mail message.
PBoolean SendNote (const PString &recipient, const PString &subject, const char *body, const PStringList &attachments)
 Send a new simple mail message.
PBoolean SendNote (const PString &recipient, const PStringList &carbonCopies, const PStringList &blindCarbons, const PString &subject, const char *body, const PStringList &attachments)
 Send a new simple mail message.
Read message functions
PStringArray GetMessageIDs (PBoolean unreadOnly=true)
 Get a list of ID strings for all messages in the mail box.
PBoolean GetMessageHeader (const PString &id, Header &hdrInfo)
 Get the header information for a message.
PBoolean GetMessageBody (const PString &id, PString &body, PBoolean markAsRead=false)
 Get the body text for a message into the body string parameter.
PBoolean GetMessageAttachments (const PString &id, PStringArray &filenames, PBoolean includeBody=false, PBoolean markAsRead=false)
 Get all of the attachments for a message as disk files.
PBoolean MarkMessageRead (const PString &id)
 Mark the message as read.
PBoolean DeleteMessage (const PString &id)
 Delete the message from the system.
Error functions
int GetErrorCode () const
 Get the internal error code for the last error by a function in this mail session.
PString GetErrorText () const
 Get the internal error description for the last error by a function in this mail session.

Protected Member Functions

void Construct ()

Protected Attributes

PBoolean loggedOn
 Flag indicating the session is active.
PString m_mailProgram

User look up functions

enum  LookUpResult { UnknownUser, AmbiguousUser, ValidUser, LookUpError }
 Result of a lookup operation with the LookUp() function. More...
LookUpResult LookUp (const PString &name, PString *fullName=NULL)
 Look up the specified name and verify that they are a valid address in the mail system.

Detailed Description

This class establishes a mail session with the platforms mail system.


Member Enumeration Documentation

Result of a lookup operation with the LookUp() function.

Enumerator:
UnknownUser 

User name is unknown in mail system.

AmbiguousUser 

User is ambiguous in mail system.

ValidUser 

User is a valid, unique name in mail system.

LookUpError 

An error occurred during the look up.


Constructor & Destructor Documentation

Create a mail session.

It is initially not logged in.

PMail::PMail ( const PString username,
const PString password 
)

Create a mail session.

Attempt to log in using the parameters provided.

Parameters:
usernameUser withing mail system to use.
passwordPassword for user in mail system.
PMail::PMail ( const PString username,
const PString password,
const PString service 
)

Create a mail session.

Attempt to log in using the parameters provided.

Parameters:
usernameUser withing mail system to use.
passwordPassword for user in mail system.
serviceA platform dependent string indicating the location of the underlying messaging service, eg the path to a message store or node name of the mail server.
virtual PMail::~PMail ( ) [virtual]

Member Function Documentation

void PMail::Construct ( ) [protected]

Delete the message from the system.

Returns:
true if message was successfully deleted.
Parameters:
idIdentifier of message to get header.
int PMail::GetErrorCode ( ) const

Get the internal error code for the last error by a function in this mail session.

Returns:
integer error code for last operation.

Get the internal error description for the last error by a function in this mail session.

Returns:
string error text for last operation.
PBoolean PMail::GetMessageAttachments ( const PString id,
PStringArray filenames,
PBoolean  includeBody = false,
PBoolean  markAsRead = false 
)

Get all of the attachments for a message as disk files.

Returns:
true if attachments were successfully obtained.
Parameters:
idIdentifier of message to get attachments.
filenamesFile names for each attachment.
includeBodyInclude the message body as first attachment
markAsReadMark the message as read
PBoolean PMail::GetMessageBody ( const PString id,
PString body,
PBoolean  markAsRead = false 
)

Get the body text for a message into the body string parameter.

Note that if the body text for the mail message is very large, the function will return false. To tell between an error getting the message body and having a large message body the GetErrorCode() function must be used.

To get a large message body, the GetMessageAttachments() should be used with the includeBody parameter set to true so that the message body is placed into a disk file.

Returns:
true if the body text was retrieved, false if the body was too large or some other error occurred.
Parameters:
idIdentifier of message to get body.
bodyBody text of mail message.
markAsReadMark the message as read.
PBoolean PMail::GetMessageHeader ( const PString id,
Header hdrInfo 
)

Get the header information for a message.

Returns:
true if header information was successfully obtained.
Parameters:
idIdentifier of message to get header.
hdrInfoHeader info for the message.
PStringArray PMail::GetMessageIDs ( PBoolean  unreadOnly = true)

Get a list of ID strings for all messages in the mail box.

Returns:
An array of ID strings.
Parameters:
unreadOnlyOnly get the IDs for unread messages.

Determine if the mail session is active and logged into the mail system.

Returns:
true if logged into the mail system.
virtual PBoolean PMail::LogOff ( ) [virtual]

Log off from the mail system.

Returns:
true if successfully logged off.
PBoolean PMail::LogOn ( const PString username,
const PString password 
)

Attempt to log on to the mail system using the parameters provided.

Returns:
true if successfully logged on.
Parameters:
usernameUser withing mail system to use.
passwordPassword for user in mail system.
PBoolean PMail::LogOn ( const PString username,
const PString password,
const PString service 
)

Attempt to log on to the mail system using the parameters provided.

Returns:
true if successfully logged on.
Parameters:
usernameUser withing mail system to use.
passwordPassword for user in mail system.
serviceA platform dependent string indicating the location of the underlying messaging service, eg the path to a message store or node name of the mail server.
LookUpResult PMail::LookUp ( const PString name,
PString fullName = NULL 
)

Look up the specified name and verify that they are a valid address in the mail system.

Returns:
result of the name lookup.
Parameters:
nameName to look up.
fullNameString to receive full name of user passed in name. If NULL then the full name is not returned.

Mark the message as read.

Returns:
true if message was successfully marked as read.
Parameters:
idIdentifier of message to get header.
PBoolean PMail::SendNote ( const PString recipient,
const PString subject,
const char *  body 
)

Send a new simple mail message.

Returns:
true if the mail message was successfully queued. Note that this does {not} mean that it has been delivered.
Parameters:
recipientName of recipient of the mail message.
subjectSubject name for the mail message.
bodyText body of the mail message.
PBoolean PMail::SendNote ( const PString recipient,
const PString subject,
const char *  body,
const PStringList attachments 
)

Send a new simple mail message.

Returns:
true if the mail message was successfully queued. Note that this does {not} mean that it has been delivered.
Parameters:
recipientName of recipient of the mail message.
subjectSubject name for the mail message.
bodyText body of the mail message.
attachmentsList of files to attach to the mail message.
PBoolean PMail::SendNote ( const PString recipient,
const PStringList carbonCopies,
const PStringList blindCarbons,
const PString subject,
const char *  body,
const PStringList attachments 
)

Send a new simple mail message.

Returns:
true if the mail message was successfully queued. Note that this does {not} mean that it has been delivered.
Parameters:
recipientName of recipient of the mail message.
carbonCopiesName of CC recipients.
blindCarbonsName of BCC recipients.
subjectSubject name for the mail message.
bodyText body of the mail message.
attachmentsList of files to attach to the mail message.

Member Data Documentation

Flag indicating the session is active.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines