PMail Class Reference

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

`#include <mail.h>`

Inheritance 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
virtual | ~PObject ()
virtual PObject * | Clone () const
| Create a copy of the class on the heap. 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...
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

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

## Detailed Description

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

## Member Enumeration Documentation

## LookUpResult

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() [1/3]

PMail::PMail | ( |  | ) |

Create a mail session.

It is initially not logged in.

## PMail() [2/3]

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() [3/3]

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.

## ~PMail()

virtual PMail::~PMail | ( |  | ) |

virtual

## Member Function Documentation

## Construct()

void PMail::Construct | ( |  | ) |

protected

## DeleteMessage()

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.

## GetErrorCode()

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.

## GetErrorText()

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.

## GetMessageAttachments()

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

## GetMessageBody()

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.

## GetMessageHeader()

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.

## GetMessageIDs()

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.

## IsLoggedOn()

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.

## LogOff()

virtual PBoolean PMail::LogOff | ( |  | ) |

virtual

Log off from the mail system.

Returns
  true if successfully logged off.

## LogOn() [1/2]

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.

## LogOn() [2/2]

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.

## LookUp()

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.

## MarkMessageRead()

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.

## SendNote() [1/3]

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.

## SendNote() [2/3]

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.

## SendNote() [3/3]

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

## loggedOn

PBoolean PMail::loggedOn

protected

Flag indicating the session is active.

## m_mailProgram

PString PMail::m_mailProgram

protected

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

- mail.h