EmailBundle C Library Reference

EmailBundle

Represents a collection of Email objects.

Create/Dispose

HCkEmailBundle CkEmailBundle_Create(void);

Creates an instance of the CkEmailBundle object and returns a handle (i.e. a "void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.

void CkEmailBundle_Dispose(HCkEmailBundle handle);

Objects created by calling CkEmailBundle_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.

C "Properties"

void CkEmailBundle_getLastErrorHtml(HCkEmailBundle cHandle, HCkString retval);

Error information in HTML format for the last method called.

void CkEmailBundle_getLastErrorText(HCkEmailBundle cHandle, HCkString retval);

Error information in plain-text format for the last method called.

void CkEmailBundle_getLastErrorXml(HCkEmailBundle cHandle, HCkString retval);

Error information in XML format for the last method called.

long CkEmailBundle_getMessageCount(HCkEmailBundle cHandle);

The number of emails in this bundle.

BOOL CkEmailBundle_getUtf8(HCkEmailBundle cHandle);
void CkEmailBundle_putUtf8(HCkEmailBundle cHandle, BOOL newVal);

When set to true, all "const char *" arguments are expected to be utf-8 strings. If set to false, the "const char *" arguments are expected to be ANSI strings.

C "Methods"

BOOL CkEmailBundle_AddEmail(HCkEmailBundle cHandle, HCkEmail email);

Adds an email object to the bundle.

HCkEmail CkEmailBundle_FindByHeader(HCkEmailBundle cHandle, const char *name, const char *value);

Returns the first email having a header field matching the headerFieldName and headerFieldValue exactly (case sensitive). If no matching email is found, returns NULL.

Returns a null reference on failure

HCkEmail CkEmailBundle_GetEmail(HCkEmailBundle cHandle, long index);

Returns the Nth Email in the bundle. The email returned is a copy of the email in the bundle. Updating the email object returned by GetEmail has no effect on the email within the bundle. To update/replace the email in the bundle, your program should call GetEmail to get a copy, make modifications, call RemoveEmailByIndex to remove the email (passing the same index used in the call to GetEmail), and then call AddEmail to insert the new/modified email into the bundle.

IMPORTANT: This method does NOT communicate with any mail server to download the email. It simply returns the Nth email object that exists within it's in-memory collection of email objects.

Returns a null reference on failure

HCkStringArray CkEmailBundle_GetUidls(HCkEmailBundle cHandle);

Returns a StringArray object containing UIDLs for all Email objects in the bundle. UIDLs are only valid for emails retrieved from POP3 servers. An email on a POP3 server has a "UIDL", an email on IMAP servers has a "UID". If the email was retrieved from an IMAP server, the UID will be accessible via the "ckx-imap-uid" header field.

Returns a null reference on failure

void CkEmailBundle_GetXml(HCkEmailBundle cHandle, HCkString outXml);

Converts the email bundle to an XML document in memory. Returns the XML document as a string.

BOOL CkEmailBundle_LoadXml(HCkEmailBundle cHandle, const char *filename);

Loads an email bundle from an XML file.

Returns TRUE for success, FALSE for failure.

BOOL CkEmailBundle_LoadXmlString(HCkEmailBundle cHandle, const char *xmlStr);

Loads an email bundle from an XML string.

Returns TRUE for success, FALSE for failure.

BOOL CkEmailBundle_RemoveEmail(HCkEmailBundle cHandle, HCkEmail email);

Removes an email from the bundle. This does not remove the email from the mail server.

Returns TRUE for success, FALSE for failure.

BOOL CkEmailBundle_RemoveEmailByIndex(HCkEmailBundle cHandle, int index);

Removes the Nth email in a bundle. (Indexing begins at 0.)

Returns TRUE for success, FALSE for failure.

BOOL CkEmailBundle_SaveLastError(HCkEmailBundle cHandle, const char *filename);

Saves the last error information to an XML formatted file.

Returns TRUE for success, FALSE for failure.

BOOL CkEmailBundle_SaveXml(HCkEmailBundle cHandle, const char *filename);

Converts each email to XML and persists the bundle to an XML file. The email bundle can later be re-instantiated by calling MailMan.LoadXmlFile

Returns TRUE for success, FALSE for failure.

void CkEmailBundle_SortByDate(HCkEmailBundle cHandle, BOOL ascending);

Sorts emails in the bundle by date.

void CkEmailBundle_SortByRecipient(HCkEmailBundle cHandle, BOOL ascending);

Sorts emails in the bundle by recipient.

void CkEmailBundle_SortBySender(HCkEmailBundle cHandle, BOOL ascending);

Sorts emails in the bundle by sender.

void CkEmailBundle_SortBySubject(HCkEmailBundle cHandle, BOOL ascending);

Sorts emails in the bundle by subject.

const char *CkEmailBundle_getXml(HCkEmailBundle cHandle);

Converts the email bundle to an XML document in memory. Returns the XML document as a string.

Returns a null on failure

const char *CkEmailBundle_lastErrorHtml(HCkEmailBundle cHandle);

Error information in HTML format for the last method called.

Returns a null on failure

const char *CkEmailBundle_lastErrorText(HCkEmailBundle cHandle);

Error information in plain-text format for the last method called.

Returns a null on failure

const char *CkEmailBundle_lastErrorXml(HCkEmailBundle cHandle);

Error information in XML format for the last method called.

Returns a null on failure