VMime
IMAPFolder Class Reference
Inheritance diagram for IMAPFolder:
Collaboration diagram for IMAPFolder:

Public Member Functions

 IMAPFolder (const folder::path &path, shared_ptr< IMAPStore > store, shared_ptr< folderAttributes > attribs)
 
 ~IMAPFolder ()
 
int getMode () const
 
const folderAttributes getAttributes ()
 
const folder::path::component getName () const
 
const folder::path getFullPath () const
 
void open (const int mode, bool failIfModeIsNotAvailable=false)
 
void close (const bool expunge)
 
void create (const folderAttributes &attribs)
 
bool exists ()
 
void destroy ()
 
bool isOpen () const
 
shared_ptr< messagegetMessage (const int num)
 
std::vector< shared_ptr
< message > > 
getMessages (const messageSet &msgs)
 
std::vector< int > getMessageNumbersStartingOnUID (const message::uid &uid)
 
int getMessageCount ()
 
shared_ptr< foldergetFolder (const folder::path::component &name)
 
std::vector< shared_ptr< folder > > getFolders (const bool recursive=false)
 
void rename (const folder::path &newPath)
 
void deleteMessages (const messageSet &msgs)
 
void setMessageFlags (const messageSet &msgs, const int flags, const int mode=message::FLAG_MODE_SET)
 
messageSet addMessage (shared_ptr< vmime::message > msg, const int flags=-1, vmime::datetime *date=NULL, utility::progressListener *progress=NULL)
 
messageSet addMessage (utility::inputStream &is, const size_t size, const int flags=-1, vmime::datetime *date=NULL, utility::progressListener *progress=NULL)
 
messageSet copyMessages (const folder::path &dest, const messageSet &msgs)
 
void status (int &count, int &unseen)
 
shared_ptr< folderStatusgetStatus ()
 
void noop ()
 
void expunge ()
 
shared_ptr< foldergetParent ()
 
shared_ptr< const storegetStore () const
 
shared_ptr< storegetStore ()
 
void fetchMessages (std::vector< shared_ptr< message > > &msg, const fetchAttributes &options, utility::progressListener *progress=NULL)
 
void fetchMessage (shared_ptr< message > msg, const fetchAttributes &options)
 
std::vector< shared_ptr
< message > > 
getAndFetchMessages (const messageSet &msgs, const fetchAttributes &attribs)
 
int getFetchCapabilities () const
 
vmime_uint32 getUIDValidity () const
 
vmime_uint64 getHighestModSequence () const
 
- Public Member Functions inherited from folder
virtual ~folder ()
 
int getType ()
 
int getFlags ()
 
void addMessageChangedListener (events::messageChangedListener *l)
 
void removeMessageChangedListener (events::messageChangedListener *l)
 
void addMessageCountListener (events::messageCountListener *l)
 
void removeMessageCountListener (events::messageCountListener *l)
 
void addFolderListener (events::folderListener *l)
 
void removeFolderListener (events::folderListener *l)
 

Additional Inherited Members

- Public Types inherited from folder
enum  Modes { MODE_READ_ONLY, MODE_READ_WRITE }
 
typedef vmime::utility::path path
 
- Protected Types inherited from folder
enum  PrivateConstants { TYPE_UNDEFINED = 9999, FLAG_UNDEFINED = 9999 }
 
- Protected Member Functions inherited from folder
 folder (const folder &)
 
 folder ()
 
void notifyMessageChanged (shared_ptr< events::messageChangedEvent > event)
 
void notifyMessageCount (shared_ptr< events::messageCountEvent > event)
 
void notifyFolder (shared_ptr< events::folderEvent > event)
 
void notifyEvent (shared_ptr< events::event > event)
 
- Protected Member Functions inherited from object
 object ()
 
 object (const object &)
 
objectoperator= (const object &)
 
virtual ~object ()
 

Detailed Description

IMAP folder implementation.

Constructor & Destructor Documentation

IMAPFolder ( const folder::path path,
shared_ptr< IMAPStore store,
shared_ptr< folderAttributes attribs 
)
~IMAPFolder ( )

References IMAPFolder::close().

Member Function Documentation

messageSet addMessage ( shared_ptr< vmime::message msg,
const int  flags = -1,
vmime::datetime date = NULL,
utility::progressListener progress = NULL 
)
virtual

Add a message to this folder.

Parameters
msgmessage to add (data: header + body)
flagsflags for the new message (if -1, default flags are used)
datedate/time for the new message (if NULL, the current time is used)
progressprogress listener, or NULL if not used
Returns
a message set containing the number or UID of the new message, or an empty set if the information could not be obtained (ie. the server does not support returning the number or UID of an added message)
Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

messageSet addMessage ( utility::inputStream is,
const size_t  size,
const int  flags = -1,
vmime::datetime date = NULL,
utility::progressListener progress = NULL 
)
virtual

Add a message to this folder.

Parameters
ismessage to add (data: header + body)
sizesize of the message to add (in bytes)
flagsflags for the new message (if -1, default flags are used)
datedate/time for the new message (if NULL, the current time is used)
progressprogress listener, or NULL if not used
Returns
a message set containing the number or UID of the new message, or an empty set if the information could not be obtained (ie. the server does not support returning the number or UID of an added message)
Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

References IMAPCommand::APPEND(), stringUtils::bytesFromString(), messageSet::empty(), inputStream::eof(), stream::getBlockSize(), progressListener::progress(), inputStream::read(), progressListener::start(), and progressListener::stop().

void close ( const bool  expunge)
virtual

Close this folder.

Parameters
expungeif set to true, deleted messages are expunged
Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

References IMAPCommand::CLOSE(), IMAPFolder::isOpen(), and folder::MODE_READ_ONLY.

Referenced by IMAPFolder::~IMAPFolder().

messageSet copyMessages ( const folder::path dest,
const messageSet msgs 
)
virtual

Copy messages from this folder to another folder.

Parameters
destdestination folder path
msgsindex set of messages to copy
Returns
a message set containing the number(s) or UID(s) of the copied message(s), or an empty set if the information could not be obtained (ie. the server does not support returning the number or UID of a copied message)
Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

References IMAPCommand::COPY(), messageSet::empty(), and IMAPFolder::isOpen().

void deleteMessages ( const messageSet msgs)
virtual

Remove one or more messages from this folder.

Parameters
msgsindex set of messages to delete
Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

References message::FLAG_DELETED, message::FLAG_MODE_ADD, messageSet::isEmpty(), IMAPFolder::isOpen(), folder::MODE_READ_ONLY, and IMAPCommand::STORE().

void destroy ( )
virtual

Delete this folder.

The folder should be closed before attempting to delete it.

Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

References IMAPCommand::DELETE(), IMAPFolder::getFullPath(), IMAPFolder::isOpen(), folder::notifyFolder(), and folderEvent::TYPE_DELETED.

bool exists ( )
virtual

Test whether this folder exists.

Returns
true if the folder exists, false otherwise

Implements folder.

References IMAPFolder::isOpen().

Referenced by IMAPFolder::create().

void expunge ( )
virtual

Expunge deleted messages.

Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

References IMAPCommand::EXPUNGE(), IMAPFolder::isOpen(), and folder::MODE_READ_ONLY.

void fetchMessage ( shared_ptr< message msg,
const fetchAttributes attribs 
)
virtual

Fetch objects for the specified message.

Parameters
msgthe message
attribsset of attributes to fetch
Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

References IMAPFolder::fetchMessages().

void fetchMessages ( std::vector< shared_ptr< message > > &  msg,
const fetchAttributes attribs,
utility::progressListener progress = NULL 
)
virtual

Fetch objects for the specified messages.

Parameters
msglist of message sequence numbers
attribsset of attributes to fetch
progressprogress listener, or NULL if not used
Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

References messageSet::byNumber(), IMAPFolder::isOpen(), progressListener::progress(), progressListener::start(), and progressListener::stop().

Referenced by IMAPFolder::fetchMessage().

std::vector< shared_ptr< message > > getAndFetchMessages ( const messageSet msgs,
const fetchAttributes attribs 
)
virtual

Get new references to messages in this folder, given either their sequence numbers or UIDs, and fetch objects for them at the same time.

Parameters
msgsindex set of messages to retrieve
attribsset of attributes to fetch
Returns
new objects referencing the specified messages
Exceptions
exceptions::net_exceptionif an error occurs
See also
folder::getMessages()
folder::fetchMessages()

Implements folder.

References fetchAttributes::add(), messageSet::isEmpty(), and fetchAttributes::UID.

const folderAttributes getAttributes ( )
virtual

Return the attributes of the folder.

Returns
folder attributes (see folder::Flags)

Implements folder.

References folderAttributes::FLAG_HAS_CHILDREN, folderAttributes::FLAG_NO_OPEN, path::isEmpty(), folderAttributes::setFlags(), folderAttributes::setType(), and folderAttributes::TYPE_CONTAINS_FOLDERS.

int getFetchCapabilities ( ) const
virtual

Return the list of fetchable objects supported by the underlying protocol (see folder::fetchAttributes).

Returns
list of supported fetchable objects

Implements folder.

References fetchAttributes::CONTENT_INFO, fetchAttributes::ENVELOPE, fetchAttributes::FLAGS, fetchAttributes::FULL_HEADER, fetchAttributes::IMPORTANCE, fetchAttributes::SIZE, fetchAttributes::STRUCTURE, and fetchAttributes::UID.

shared_ptr< folder > getFolder ( const folder::path::component name)
virtual

Get a new reference to a sub-folder in this folder.

Parameters
namesub-folder name
Returns
a new object referencing the specified folder
Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

std::vector< shared_ptr< folder > > getFolders ( const bool  recursive = false)
virtual

Get the list of all sub-folders in this folder.

Parameters
recursiveif set to true, all the descendant are returned. If set to false, only the direct children are returned.
Returns
list of sub-folders
Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

References IMAPFolder::getFullPath(), path::isDirectParentOf(), IMAPFolder::isOpen(), IMAPCommand::LIST(), and mailbox::mailbox().

const folder::path getFullPath ( ) const
virtual

Return the fully qualified path name of this folder.

Returns
absolute path of the folder

Implements folder.

Referenced by IMAPFolder::create(), IMAPFolder::destroy(), IMAPFolder::getFolders(), IMAPFolder::getStatus(), IMAPFolder::open(), and IMAPFolder::rename().

vmime_uint64 getHighestModSequence ( ) const

Returns the highest modification sequence of this folder, ie the modification sequence of the last message that changed in this folder.

Returns
modification sequence, or zero if not supported by the underlying protocol

References IMAPFolder::isOpen().

shared_ptr< message > getMessage ( const int  num)
virtual

Get a new reference to a message in this folder, given its number.

Parameters
nummessage sequence number
Returns
a new object referencing the specified message
Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

References IMAPFolder::isOpen().

int getMessageCount ( )
virtual

Return the number of messages in this folder.

Returns
number of messages in the folder

Implements folder.

References IMAPFolder::isOpen().

std::vector< int > getMessageNumbersStartingOnUID ( const message::uid uid)
virtual

Return the sequence numbers of messages whose UID equal or greater than the specified UID.

Parameters
uidthe uid of the first message
Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

References IMAPCommand::SEARCH().

std::vector< shared_ptr< message > > getMessages ( const messageSet msgs)
virtual

Get new references to messages in this folder, given either their sequence numbers or UIDs.

To retrieve messages by their number, use:

// Get messages from sequence number 5 to sequence number 8 (including)
// Get all messages in the folder, starting from number 42

Or, to retrieve messages by their UID, use:

// Get messages from UID 1000 to UID 1042 (including)
folder->getMessage(vmime::net::messageSet::byUID(1000, 1042));
// Get message with UID 1042
// Get all messages in the folder, starting from UID 1000
folder->getMessage(vmime::net::messageSet::byUID(1000, "*"));
Parameters
msgsindex set of messages to retrieve
Returns
new objects referencing the specified messages
Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

References IMAPCommand::FETCH(), messageSet::isEmpty(), messageSet::isNumberSet(), IMAPFolder::isOpen(), and messageSet::isUIDSet().

int getMode ( ) const
virtual

Return the mode in which the folder has been open.

Returns
folder opening mode (see folder::Modes)

Implements folder.

References IMAPFolder::isOpen().

const folder::path::component getName ( ) const
virtual

Return the name of this folder.

Returns
folder name

Implements folder.

shared_ptr< folder > getParent ( )
virtual

Return a new folder object referencing the parent folder of this folder.

Returns
parent folder object

Implements folder.

References path::getParent(), and path::isEmpty().

shared_ptr< folderStatus > getStatus ( )
virtual

Request folder status without opening it.

Returns
current folder status
Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

References IMAPFolder::getFullPath(), IMAPCommand::STATUS(), and IMAPFolder::status().

Referenced by IMAPFolder::status().

shared_ptr< const store > getStore ( ) const
virtual

Return a reference to the store to which this folder belongs.

Returns
the store object to which this folder is attached

Implements folder.

shared_ptr< store > getStore ( )
virtual

Return a reference to the store to which this folder belongs.

Returns
the store object to which this folder is attached

Implements folder.

vmime_uint32 getUIDValidity ( ) const

Returns the UID validity of the folder for the current session.

If the server is capable of persisting UIDs accross sessions, this value should never change for a folder. If the UID validity differs across sessions, then the UIDs obtained during a previous session may not correspond to the UIDs of the same messages in this session.

Returns
UID validity of the folder

References IMAPFolder::isOpen().

void noop ( )

References IMAPCommand::NOOP().

void open ( const int  mode,
bool  failIfModeIsNotAvailable = false 
)
virtual

Open this folder.

Parameters
modeopen mode (see folder::Modes)
failIfModeIsNotAvailableif set to false and if the requested mode is not available, a more restricted mode will be selected automatically. If set to true and if the requested mode is not available, the opening will fail.
Exceptions
exceptions::net_exceptionif an error occurs
exceptions::folder_already_openif the folder is already open in the same session

Implements folder.

References IMAPFolder::getFullPath(), folder::MODE_READ_ONLY, folder::MODE_READ_WRITE, and IMAPCommand::SELECT().

void rename ( const folder::path newPath)
virtual

Rename (move) this folder to another location.

Parameters
newPathnew path of the folder
Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

References word::getBuffer(), IMAPFolder::getFullPath(), path::getLastComponent(), path::getSize(), path::isEmpty(), path::isParentOf(), folder::notifyFolder(), IMAPCommand::RENAME(), and folderEvent::TYPE_RENAMED.

void setMessageFlags ( const messageSet msgs,
const int  flags,
const int  mode = message::FLAG_MODE_SET 
)
virtual

Change the flags for one or more messages in this folder.

Parameters
msgsindex set of messages on which to set the flags
flagsset of flags (see message::Flags)
modeindicate how to treat old and new flags (see message::FlagsModes)
Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

References IMAPCommand::STORE().

void status ( int &  count,
int &  unseen 
)
virtual

Request folder status without opening it.

Deprecated:
Use the new getStatus() method
Parameters
countwill receive the number of messages in the folder
unseenwill receive the number of unseen messages in the folder
Exceptions
exceptions::net_exceptionif an error occurs

Implements folder.

References IMAPFolder::getStatus().

Referenced by IMAPFolder::getStatus().


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