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

#include <mail.h>

Inheritance diagram for PMail:

Collaboration diagram for PMail:

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

Public Member Functions
Construction
	PMail ()
	Create a mail session. More...

	PMail (const PString &username, const PString &password)
	Create a mail session. More...

	PMail (const PString &username, const PString &password, const PString &service)
	Create a mail session. More...

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. More...

PBoolean	LogOn (const PString &username, const PString &password, const PString &service)
	Attempt to log on to the mail system using the parameters provided. More...

virtual PBoolean	LogOff ()
	Log off from the mail system. More...

PBoolean	IsLoggedOn () const
	Determine if the mail session is active and logged into the mail system. More...

Send message functions
PBoolean	SendNote (const PString &recipient, const PString &subject, const char *body)
	Send a new simple mail message. More...

PBoolean	SendNote (const PString &recipient, const PString &subject, const char *body, const PStringList &attachments)
	Send a new simple mail message. More...

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. More...

Read message functions
PStringArray	GetMessageIDs (PBoolean unreadOnly=true)
	Get a list of ID strings for all messages in the mail box. More...

PBoolean	GetMessageHeader (const PString &id, Header &hdrInfo)
	Get the header information for a message. More...

PBoolean	GetMessageBody (const PString &id, PString &body, PBoolean markAsRead=false)
	Get the body text for a message into the `body` string parameter. More...

PBoolean	GetMessageAttachments (const PString &id, PStringArray &filenames, PBoolean includeBody=false, PBoolean markAsRead=false)
	Get all of the attachments for a message as disk files. More...

PBoolean	MarkMessageRead (const PString &id)
	Mark the message as read. More...

PBoolean	DeleteMessage (const PString &id)
	Delete the message from the system. More...

Error functions
int	GetErrorCode () const
	Get the internal error code for the last error by a function in this mail session. More...

PString	GetErrorText () const
	Get the internal error description for the last error by a function in this mail session. More...

Public Member Functions inherited from PObject
unsigned	GetTraceContextIdentifier () const
	Get PTRACE context identifier. More...

void	SetTraceContextIdentifier (unsigned id)

void	GetTraceContextIdentifier (PObject &obj)

void	GetTraceContextIdentifier (PObject *obj)

void	SetTraceContextIdentifier (const PObject &obj)

void	SetTraceContextIdentifier (const PObject *obj)

virtual	~PObject ()

virtual PObject *	Clone () const
	Create a copy of the class on the heap. More...

template<class CLS >
CLS *	CloneAs () const
	As for Clone() but converts to specified type. More...

virtual PINDEX	HashFunction () const
	This function yields a hash value required by the `PDictionary` class. More...

virtual Comparison	Compare (const PObject &obj) const
	Compare the two objects and return their relative rank. More...

virtual Comparison	CompareObjectMemoryDirect (const PObject &obj) const
	Determine the byte wise comparison of two objects. More...

bool	operator== (const PObject &obj) const
	Compare the two objects. More...

bool	operator!= (const PObject &obj) const
	Compare the two objects. More...

bool	operator< (const PObject &obj) const
	Compare the two objects. More...

bool	operator> (const PObject &obj) const
	Compare the two objects. More...

bool	operator<= (const PObject &obj) const
	Compare the two objects. More...

bool	operator>= (const PObject &obj) const
	Compare the two objects. More...

virtual const char *	GetClass (unsigned ancestor=0) const
	Get the current dynamic type of the object instance. More...

PBoolean	IsClass (const char *cls) const

virtual PBoolean	InternalIsDescendant (const char *clsName) const
	Determine if the dynamic type of the current instance is a descendent of the specified class. More...

__inline const PObject *	PTraceObjectInstance () const

virtual void	PrintOn (ostream &strm) const
	Output the contents of the object to the stream. More...

virtual void	ReadFrom (istream &strm)
	Input the contents of the object from the stream. More...

Protected Member Functions
void	Construct ()

Protected Member Functions inherited from PObject
	PObject ()
	Constructor for PObject, made protected so cannot ever create one on its own. More...

Protected Attributes
PBoolean	loggedOn
	Flag indicating the session is active. More...

PString	m_mailProgram

Protected Attributes inherited from PObject
unsigned	m_traceContextIdentifier

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. More...

Additional Inherited Members
Public Types inherited from PObject
enum	Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
	Result of the comparison operation performed by the `Compare()` function. More...

Static Public Member Functions inherited from PObject
static Comparison	InternalCompareObjectMemoryDirect (const PObject obj1, const PObject obj2, PINDEX size)
	Internal function caled from CompareObjectMemoryDirect() More...

static const char *	Class ()
	Get the name of the class as a C string. More...

static __inline const PObject *	PTraceObjectInstance (const char *)

static __inline const PObject *	PTraceObjectInstance (const PObject *obj)

Friends inherited from PObject

Detailed Description

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

Member Enumeration Documentation

enum PMail::LookUpResult

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

PMail::PMail ( )

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

username	User withing mail system to use.
password	Password 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

username	User withing mail system to use.
password	Password for user in mail system.
service	A 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

PBoolean PMail::DeleteMessage ( const PString & id )

Delete the message from the system.

Returns: true if message was successfully deleted.

Parameters

id	Identifier 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.

PString PMail::GetErrorText ( ) const

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

id	Identifier of message to get attachments.
filenames	File names for each attachment.
includeBody	Include the message body as first attachment
markAsRead	Mark 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

id	Identifier of message to get body.
body	Body text of mail message.
markAsRead	Mark 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

id	Identifier of message to get header.
hdrInfo	Header 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

unreadOnly Only get the IDs for unread messages.

PBoolean PMail::IsLoggedOn ( ) const

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

username	User withing mail system to use.
password	Password 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

username	User withing mail system to use.
password	Password for user in mail system.
service	A 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

name	Name to look up.
fullName	String to receive full name of user passed in `name`. If NULL then the full name is not returned.

PBoolean PMail::MarkMessageRead ( const PString & id )

Mark the message as read.

Returns: true if message was successfully marked as read.

Parameters

id	Identifier 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

recipient	Name of recipient of the mail message.
subject	Subject name for the mail message.
body	Text 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

recipient	Name of recipient of the mail message.
subject	Subject name for the mail message.
body	Text body of the mail message.
attachments	List 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

recipient	Name of recipient of the mail message.
carbonCopies	Name of CC recipients.
blindCarbons	Name of BCC recipients.
subject	Subject name for the mail message.
body	Text body of the mail message.
attachments	List of files to attach to the mail message.

Member Data Documentation

PBoolean PMail::loggedOn

protected

Flag indicating the session is active.

PString PMail::m_mailProgram

protected

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

mail.h

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

User look up functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation