CWFolder

A CWFolder object holds CWMessage instances.

Discussion

This abstract class is used to represent a folder which holds messages. A folder is a synonym for mailbox. Normally, you should never create an instance of CWFolder directly but rather use the subclasses which are CWIMAPFolder, CWLocalFolder and CWPOP3Folder. Futhermore, the corresponding CWStore classes will instanciate the CWFolder subclasses for you.

Superclass

NSObject

Declared In

CWFolder.h

Methods

-allContainers

-allMessages

-appendMessage:

-appendMessageFromRawSource:flags:

-cacheManager

-close

-count

-expunge

-initWithName:

-messageAtIndex:

-mode

-name

-numberOfDeletedMessages

-numberOfUnreadMessages

-propertyForKey:

-removeMessage:

-search: mask: options:

-search:mask:options:

-setCacheManager:

-setFlags: messages:

-setFlags:messages:

-setMessages:

-setMode:

-setName:

-setProperty: forKey:

-setProperty:forKey:

-setShowDeleted:

-setShowRead:

-setStore:

-showDeleted

-showRead

-size

-store

-thread

-unthread

-updateCache

- (NSArray *) allContainers; 

Return Value

Root containers if using message threading, nil otherwise.

Discussion

This method returns the list of root containers when using message threading.

- (NSArray *) allMessages; 

Return Value

An array of all visible messages.

Discussion

This method is used to obtain all visible messages in the CWFolder instance. It hides messages marked as Deleted if -setShowDeleted: was invoked with NO as the parameter and the the same for messages marked as read (see -setShowRead:). Note that the messages MIGHT NOT been all completely initialized.

- (void) appendMessage: (CWMessage *) theMessage; 

Parameters

Discussion

This method is used to add a message to a CWFolder instance. This method will NOT add the message to the underlying store. You MUST use -appendMessageFromRawSource: flags: if you want the message to be saved to the underlying store. Generally, you should not use this method directly. If the folder was threaded, this method will NOT thread the appended message.

- (void) appendMessageFromRawSource: (NSData *) theData flags: (CWFlags *) theFlags; 

Parameters

Discussion

This method is used to append a message from its raw source representation (RFC2822 compliant) to the underlying store. This method will raise an exception if it's invoked on an instance of CWFolder or CWPOP3Folder instead of an instance of CWIMAPFolder and CWLocalFolder. If the folder was threaded, this method will NOT thread the appended message. Methods will be invoked on the delegate and notifications will be posted. See the PantomimeFolderDelegate informal protocol for more details.

- (id) cacheManager; 

Return Value

The associated cache manager instance, nil otherwise.

Discussion

This method returns the associated cache manager for this folder. For a CWIMAPFolder, a CWIMAPCacheManager instance will be returned. For a CWLocalFolder, a CWLocalFolderCacheManager instance will be returned. For a CWPOP3Folder, a CWPOP3CacheManager instance will be returned.

- (void) close; 

Discussion

This method is used to close the folder. The subclasses of CWFolder MUST this method.

- (unsigned int) count; 

Return Value

The number of messages in the folder.

Discussion

This method is used to obtain the number of messages present in the folder. Hidden messages will NOT be part of the value returned. So, for example, if a folder has 10 messages, 2 of them have the PantomimeDeleted flag set and -setShowDeleted: NO was invoked on the folder, this method will return 8 as the messages count.

- (void) expunge; 

Discussion

This method is used to permanently remove messages marked as deleted in the folder.

- (id) initWithName: (NSString *) theName; 

Parameters

Return Value

The folder, nil in case of an error.

Discussion

This method initialize a folder with the specified name. The name can contain folder separators in order to create subfolders. The separator can be obtained from a class that implements the CWStore protocol.

- (CWMessage *) messageAtIndex: (unsigned int) theIndex; 

Parameters

Return Value

The message at the specified index, nil otherwise.

Discussion

This method is used to obtain the message at the specified index (which is zero-based). If the index is out of bounds, nil is returned.

- (PantomimeFolderMode) mode; 

Return Value

The mode of the folder.

Discussion

This method is used to get the mode of the folders. The returned values can be either PantomimeUnknownMode, PantomimeReadOnlyMode or PantomimeReadWriteMode. Calling this method on an instance of Folder (ie., not a subclass) will raise an exception.

- (NSString *) name; 

Return Value

The full name of the folder.

Discussion

This method returns the name of the folder.

- (unsigned int) numberOfDeletedMessages; 

Return Value

The number of message marked has deleted, 0 if none.

Discussion

This method returns the number of messages in this folder that have the PantomimeDeleted flag set.

- (unsigned int) numberOfUnreadMessages; 

Return Value

The number of unread messages, 0 if none.

Discussion

This method returns the number of messages in this folder that do not have the PantomimeSeen flag set.

- (id) propertyForKey: (id) theKey; 

Return Value

The property for the specified key, nil if key isn't found.

Discussion

This method is used to get an extra property for the specified key.

- (void) removeMessage: (CWMessage *) theMessage; 

Parameters

Discussion

This method removes permenantly a message from the folder. It is used when transferring message between folders in order to update the view or when expunge deletes messages from a view. If the folder is threaded, this method will rethread the folder before returning.

- (void) search: (NSString *) theString mask: (PantomimeSearchMask) theMask 
        options: (PantomimeSearchOption) theOptions; 

Parameters

Discussion

This method is used to search this folder using a criteria, mask and options. This method will post a PantomimeFolderSearchCompleted (or invoked -folderSearchCompleted: on the delegate) once it has completed its execution (or post PantomimeFolderSearchFailed or invoke -folderSearchFailed on the delegate if it failed). This method will do absolutely nothing on CWPOP3Folder instances as search operations are not supported in POP3.

See Also

- (void) search: (NSString *) theString mask: (PantomimeSearchMask) theMask 
        options: (PantomimeSearchOption) theOptions; 

Parameters

Discussion

This method is used to search this folder using a criteria, mask and options. This method will post a PantomimeFolderSearchCompleted (or invoked -folderSearchCompleted: on the delegate) once it has completed its execution (or post PantomimeFolderSearchFailed or invoke -folderSearchFailed on the delegate if it failed). This method will do absolutely nothing on CWPOP3Folder instances as search operations are not supported in POP3.

See Also

- (void) setCacheManager: (id) theCacheManager; 

Parameters

Discussion

This method is used to set the respective cache manager instance for this folder. Instance of CWIMAPCacheManager, CWLocalFolderCacheManager or CWPOP3CacheManager will generally be used.

- (void) setFlags: (CWFlags *) theFlags messages: (NSArray *) theMessages; 

Parameters

Discussion

This method is used to set the same flags to a set of messages. This can be useful, especially when dealing with CWIMAPFolder instances in order to NOT send many IMAP commands to the server but rather send just one.

See Also

- (void) setFlags: (CWFlags *) theFlags messages: (NSArray *) theMessages; 

Parameters

Discussion

This method is used to set the same flags to a set of messages. This can be useful, especially when dealing with CWIMAPFolder instances in order to NOT send many IMAP commands to the server but rather send just one.

See Also

- (void) setMessages: (NSArray *) theMessages; 

Parameters

Discussion

This method is used to replace all messages in the CWFolder instance by the ones specified in the array. Normally, you shouldn't use this method directly.

- (void) setMode: (PantomimeFolderMode) theMode; 

Parameters

Discussion

This method is used to adjust the mode on the specified folder. If has no impact on how the mailbox was open. For example, if a mailbox was open as read-only, the mailbox will not be re-opened as read-write after this method call.

- (void) setName: (NSString *) theName; 

Parameters

Discussion

Sets the name of a folder.

- (void) setProperty: (id) theProperty forKey: (id) theKey; 

Parameters

Discussion

This method is used to set an extra property for the specified key on this folder. If nil is passed for theProperty parameter, the value will actually be REMOVED for theKey.

See Also

- (void) setProperty: (id) theProperty forKey: (id) theKey; 

Parameters

Discussion

This method is used to set an extra property for the specified key on this folder. If nil is passed for theProperty parameter, the value will actually be REMOVED for theKey.

See Also

- (void) setShowDeleted: (BOOL) theBOOL; 

Parameters

Discussion

This method is used to specify if we want to show or hide messages marked as deleted in this folder.

- (void) setShowRead: (BOOL) theBOOL; 

Parameters

Discussion

This method is used to specify if we want to show or hide messages marked as read in this folder.

- (void) setStore: (id) theStore; 

Parameters

Discussion

This method is used to set the associated store to this folder. The store will NOT be retained since it is the store which holds and retains the CWFolder instances.

- (BOOL) showDeleted; 

Return Value

A BOOL corresponding to the value.

Discussion

This method returns YES if messages marked as deleted are shown in this folder, NO otherwise.

- (BOOL) showRead; 

Return Value

A BOOL corresponding to the value.

Discussion

This method returns YES if messages marked as read are shown in this folder, NO otherwise.

- (unsigned long) size; 

Return Value

The size of the folder.

Discussion

This method returns the size of the folder. That is, it returns the sum of the size of all visible messages in the folder.

- (id) store; 

Return Value

The associated store.

Discussion

This method returns the associated store to this folder. This will generally be an instance of CWIMAPStore, CWLocalStore or CWPOP3Store.

- (void) thread; 

Discussion

This method implements Jamie Zawinski's message threading algorithm. The full algorithm is available here: http://www.jwz.org/doc/threading.html After calling this method, -allContainers can be called to obtain the root set of CWContainer instances.

- (void) unthread; 

Discussion

This method is used to release all resources taken by the message threading code. After calling this method, -allContainers will return nil.

- (void) updateCache; 

Discussion

This method is used to update our cache (_allVisibleMessages). Applications can call this method if they set the PantomimeDeleted flags to messages inside this folder. If not called, the cache won't be updated the messages having the flag PantomimeDeleted will still be visible.

Member Data

_allContainers

_allVisibleMessages

_cacheManager

_mode

_name

_properties

_show_deleted

_show_read

_store

allMessages

protected

NSMutableArray *_allContainers; 

protected

NSMutableArray *_allVisibleMessages; 

protected

id _cacheManager; 

protected

PantomimeFolderMode _mode; 

protected

NSString *_name; 

protected

NSMutableDictionary *_properties; 

protected

BOOL _show_deleted; 

protected

BOOL _show_read; 

protected

id _store; 

public

NSMutableArray *allMessages;