MessageSet C Library Reference

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

C "Properties"

long CkMessageSet_getCount(HCkMessageSet handle);

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

BOOL CkMessageSet_getHasUids(HCkMessageSet handle);
void CkMessageSet_putHasUids(HCkMessageSet handle, BOOL newVal);

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

C "Methods"

BOOL CkMessageSet_ContainsId(HCkMessageSet handle, long id);

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

BOOL CkMessageSet_FromCompactString(HCkMessageSet handle, 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

long CkMessageSet_GetId(HCkMessageSet handle, long 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 handle, long id);

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

void CkMessageSet_RemoveId(HCkMessageSet handle, long id);

Removes a message ID from the set.

void CkMessageSet_ToCompactString(HCkMessageSet handle, HCkString str);

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

void CkMessageSet_ToString(HCkMessageSet handle, HCkString str);

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

const char *CkMessageSet_toCompactString(HCkMessageSet handle);

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

const char *CkMessageSet_toString(HCkMessageSet handle);

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