MessageSet C Reference Documentation

MessageSet

Represents a collection of email message sequence numbers or UIDs on an IMAP server.

Create/Dispose

HCkMessageSet CkMessageSet_Create(void);

Creates an instance of the HCkMessageSet 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 CkMessageSet_Dispose(HCkMessageSet handle);

Objects created by calling CkMessageSet_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function. Also, any handle returned by a Chilkat "C" function must also be freed by the application by calling the appropriate Dispose method, such as CkMessageSet_Dispose.

Properties

int CkMessageSet_getCount(HCkMessageSet cHandle);

The number of message UIDs (or sequence numbers) in this message set.

BOOL CkMessageSet_getHasUids(HCkMessageSet cHandle);

void CkMessageSet_putHasUids(HCkMessageSet cHandle, BOOL newVal);

If TRUE then the message set contains UIDs, otherwise it contains sequence numbers.

BOOL CkMessageSet_getUtf8(HCkMessageSet cHandle);

void CkMessageSet_putUtf8(HCkMessageSet cHandle, BOOL newVal);

When set to TRUE, all "const char *" arguments are interpreted as utf-8 strings. If set to FALSE (the default), then "const char *" arguments are interpreted as ANSI strings. Also, when set to TRUE, and Chilkat method returning a "const char *" is returning the utf-8 representation. If set to FALSE, all "const char *" return values are ANSI strings.

Methods

BOOL CkMessageSet_ContainsId(HCkMessageSet cHandle, int msgId);

Returns TRUE if the msgId is contained in the message set.

BOOL CkMessageSet_FromCompactString(HCkMessageSet cHandle, const char *str);

Loads the message set from a compact-string representation. Here are some examples:

Non-Compact String

Compact String

1,2,3,4,5

1:5

1,2,3,4,5,8,9,10

1:5,8:10

1,3,4,5,8,9,10

1,3:5,8:10

int CkMessageSet_GetId(HCkMessageSet cHandle, int index);

Returns the message ID of the Nth message in the set. (indexing begins at 0). Returns -1 if the index is out of range.

void CkMessageSet_InsertId(HCkMessageSet cHandle, int id);

Inserts a message ID into the set. If the ID already exists, a duplicate is not inserted.

BOOL CkMessageSet_LoadTaskResult(HCkMessageSet cHandle, HCkTask task);

Introduced in version 9.5.0.52

Loads the message set from a completed asynchronous task.

Returns TRUE for success, FALSE for failure.

void CkMessageSet_RemoveId(HCkMessageSet cHandle, int id);

Removes a message ID from the set.

BOOL CkMessageSet_ToCommaSeparatedStr(HCkMessageSet cHandle, HCkString outStr);

const char *CkMessageSet_toCommaSeparatedStr(HCkMessageSet cHandle);

Returns a string of comma-separated message IDs. (This is the non-compact string format.)

Returns TRUE for success, FALSE for failure.

BOOL CkMessageSet_ToCompactString(HCkMessageSet cHandle, HCkString outStr);

const char *CkMessageSet_toCompactString(HCkMessageSet cHandle);

Returns the set of message IDs represented as a compact string. Here are some examples:

Non-Compact String

Compact String

1,2,3,4,5

1:5

1,2,3,4,5,8,9,10

1:5,8:10

1,3,4,5,8,9,10

1,3:5,8:10

Returns TRUE for success, FALSE for failure.