#include <IMAPFolder.hpp>

Inheritance diagram for IMAPFolder:

[legend]

Collaboration diagram for IMAPFolder:

[legend]

Public Member Functions
	~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< message >	getMessage (const size_t num)
std::vector< shared_ptr< message > >	getMessages (const messageSet &msgs)
std::vector< size_t >	getMessageNumbersStartingOnUID (const message::uid &uid)
size_t	getMessageCount ()
shared_ptr< folder >	getFolder (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 (size_t &count, size_t &unseen)
shared_ptr< folderStatus >	getStatus ()
void	noop ()
void	expunge ()
shared_ptr< folder >	getParent ()
shared_ptr< const store >	getStore () const
shared_ptr< store >	getStore ()
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 &)
object &	operator= (const object &)
virtual	~object ()

Detailed Description

IMAP folder implementation.

Constructor & Destructor Documentation

◆ ~IMAPFolder()

~IMAPFolder ( )

References close(), and ~IMAPFolder().

Referenced by ~IMAPFolder().

Member Function Documentation

◆ addMessage() [1/2]

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

msg	message to add (data: header + body)
flags	flags for the new message (if -1, default flags are used)
date	date/time for the new message (if NULL, the current time is used)
progress	progress 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_exception if an error occurs

Implements folder.

References addMessage().

Referenced by addMessage(), addMessage(), and IMAPMessage.

◆ addMessage() [2/2]

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

is	message to add (data: header + body)
size	size of the message to add (in bytes)
flags	flags for the new message (if -1, default flags are used)
date	date/time for the new message (if NULL, the current time is used)
progress	progress 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_exception if an error occurs

Implements folder.

References addMessage(), IMAPCommand::APPEND(), stringUtils::bytesFromString(), messageSet::empty(), inputStream::eof(), stream::getBlockSize(), getFullPath(), isOpen(), folder::MODE_READ_ONLY, progressListener::progress(), inputStream::read(), progressListener::start(), status(), and progressListener::stop().

◆ close()

void close ( const bool expunge )

virtual

Close this folder.

Parameters

expunge if set to true, deleted messages are expunged

Exceptions

exceptions::net_exception if an error occurs

Implements folder.

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

Referenced by close(), IMAPMessage, and ~IMAPFolder().

◆ copyMessages()

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

virtual

Copy messages from this folder to another folder.

Parameters

dest	destination folder path
msgs	index 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_exception if an error occurs

Implements folder.

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

Referenced by copyMessages(), and IMAPMessage.

◆ create()

void create ( const folderAttributes & attribs )

virtual

Create this folder.

Parameters

attribs attributes of the new folder

Exceptions

exceptions::net_exception if an error occurs

Implements folder.

Referenced by create(), and IMAPMessage.

◆ deleteMessages()

void deleteMessages ( const messageSet & msgs )

virtual

Remove one or more messages from this folder.

Parameters

msgs	index set of messages to delete

Exceptions

exceptions::net_exception if an error occurs

Implements folder.

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

Referenced by deleteMessages(), and IMAPMessage.

◆ destroy()

void destroy ( )

virtual

Delete this folder.

The folder should be closed before attempting to delete it.

Exceptions

exceptions::net_exception if an error occurs

Implements folder.

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

Referenced by destroy(), and IMAPMessage.

◆ exists()

bool exists ( )

virtual

Test whether this folder exists.

Returns: true if the folder exists, false otherwise

Implements folder.

References exists(), and isOpen().

Referenced by create(), exists(), and IMAPMessage.

◆ expunge()

void expunge ( )

virtual

Expunge deleted messages.

Exceptions

exceptions::net_exception if an error occurs

Implements folder.

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

Referenced by close(), expunge(), and IMAPMessage.

◆ fetchMessage()

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

virtual

Fetch objects for the specified message.

Parameters

msg	the message
attribs	set of attributes to fetch

Exceptions

exceptions::net_exception if an error occurs

Implements folder.

References fetchMessage(), and fetchMessages().

Referenced by fetchMessage(), and IMAPMessage.

◆ fetchMessages()

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

virtual

Fetch objects for the specified messages.

Parameters

msg	list of message sequence numbers
attribs	set of attributes to fetch
progress	progress listener, or NULL if not used

Exceptions

exceptions::net_exception if an error occurs

Implements folder.

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

Referenced by fetchMessage(), fetchMessages(), and IMAPMessage.

◆ getAndFetchMessages()

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

msgs	index set of messages to retrieve
attribs	set of attributes to fetch

Returns: new objects referencing the specified messages

Exceptions

exceptions::net_exception if an error occurs

See also: folder::getMessages(); folder::fetchMessages()

Implements folder.

References getAndFetchMessages(), messageSet::isEmpty(), isOpen(), status(), and fetchAttributes::UID.

Referenced by getAndFetchMessages(), and IMAPMessage.

◆ getAttributes()

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, getAttributes(), folderAttributes::setFlags(), folderAttributes::setType(), and folderAttributes::TYPE_CONTAINS_FOLDERS.

Referenced by getAttributes(), and IMAPMessage.

◆ getFetchCapabilities()

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, getFetchCapabilities(), fetchAttributes::IMPORTANCE, fetchAttributes::SIZE, fetchAttributes::STRUCTURE, and fetchAttributes::UID.

Referenced by getFetchCapabilities(), and IMAPMessage.

◆ getFolder()

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

virtual

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

Parameters

name	sub-folder name

Returns: a new object referencing the specified folder

Exceptions

exceptions::net_exception if an error occurs

Implements folder.

References getFolder().

Referenced by getFolder(), and IMAPMessage.

◆ getFolders()

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

virtual

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

Parameters

recursive if 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_exception if an error occurs

Implements folder.

References getFolders(), getFullPath(), isOpen(), IMAPCommand::LIST(), mailbox::mailbox(), and status().

Referenced by getFolders(), and IMAPMessage.

◆ getFullPath()

const folder::path getFullPath ( ) const

virtual

Return the fully qualified path name of this folder.

Returns: absolute path of the folder

Implements folder.

References getFullPath().

Referenced by addMessage(), create(), destroy(), getFolders(), getFullPath(), getStatus(), IMAPMessage, open(), and rename().

◆ getHighestModSequence()

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 getHighestModSequence(), and isOpen().

Referenced by getHighestModSequence(), and IMAPMessage.

◆ getMessage()

shared_ptr< message > getMessage ( const size_t num )

virtual

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

Parameters

num	message sequence number

Returns: a new object referencing the specified message

Exceptions

exceptions::net_exception if an error occurs

Implements folder.

References getMessage(), and isOpen().

Referenced by getMessage(), and IMAPMessage.

◆ getMessageCount()

size_t getMessageCount ( )

virtual

Return the number of messages in this folder.

Returns: number of messages in the folder

Implements folder.

References getMessageCount(), and isOpen().

Referenced by getMessageCount(), and IMAPMessage.

◆ getMessageNumbersStartingOnUID()

std::vector< size_t > getMessageNumbersStartingOnUID ( const message::uid & uid )

virtual

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

Parameters

uid	the uid of the first message

Exceptions

exceptions::net_exception if an error occurs

Implements folder.

References getMessageNumbersStartingOnUID(), and IMAPCommand::SEARCH().

Referenced by getMessageNumbersStartingOnUID(), and IMAPMessage.

◆ getMessages()

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)
folder->getMessage(vmime::net::messageSet::byNumber(5, 8));
 
// Get all messages in the folder, starting from number 42
folder->getMessage(vmime::net::messageSet::byNumber(42, -1));

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
folder->getMessage(vmime::net::messageSet::byUID(1042));
 
// Get all messages in the folder, starting from UID 1000
folder->getMessage(vmime::net::messageSet::byUID(1000, "*"));

Parameters

msgs	index set of messages to retrieve

Returns: new objects referencing the specified messages

Exceptions

exceptions::net_exception if an error occurs

Implements folder.

References message::uid::empty(), IMAPCommand::FETCH(), getMessages(), messageSet::isEmpty(), isOpen(), and status().

Referenced by getMessages(), and IMAPMessage.

◆ getMode()

int getMode ( ) const

virtual

Return the mode in which the folder has been open.

Returns: folder opening mode (see folder::Modes)

Implements folder.

References getMode(), and isOpen().

Referenced by getMode(), and IMAPMessage.

◆ getName()

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

virtual

Return the name of this folder.

Returns: folder name

Implements folder.

References getName().

Referenced by getName(), and IMAPMessage.

◆ getParent()

shared_ptr< folder > getParent ( )

virtual

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

Returns: parent folder object

Implements folder.

References getParent().

Referenced by getParent(), and IMAPMessage.

◆ getStatus()

shared_ptr< folderStatus > getStatus ( )

virtual

Request folder status without opening it.

Returns: current folder status

Exceptions

exceptions::net_exception if an error occurs

Implements folder.

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

Referenced by getStatus(), IMAPMessage, and status().

◆ getStore() [1/2]

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.

References getStore().

◆ getStore() [2/2]

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.

References getStore().

Referenced by getStore(), getStore(), and IMAPMessage.

◆ getUIDValidity()

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 getUIDValidity(), and isOpen().

Referenced by getUIDValidity(), and IMAPMessage.

◆ isOpen()

bool isOpen ( ) const

virtual

Test whether this folder is open.

Returns: true if the folder is open, false otherwise

Implements folder.

References isOpen().

Referenced by addMessage(), close(), copyMessages(), create(), deleteMessages(), destroy(), exists(), expunge(), fetchMessages(), getAndFetchMessages(), getFolders(), getHighestModSequence(), getMessage(), getMessageCount(), getMessages(), getMode(), getUIDValidity(), IMAPMessage, and isOpen().

◆ noop()

void noop ( )

References IMAPCommand::NOOP(), noop(), and status().

Referenced by IMAPMessage, and noop().

◆ open()

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

virtual

Open this folder.

Parameters

mode	open mode (see folder::Modes)
failIfModeIsNotAvailable	if 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_exception	if an error occurs
exceptions::folder_already_open	if the folder is already open in the same session

Implements folder.

References service::getAuthenticator(), getFullPath(), folder::MODE_READ_ONLY, folder::MODE_READ_WRITE, open(), IMAPCommand::SELECT(), and status().

Referenced by IMAPMessage, and open().

◆ rename()

void rename ( const folder::path & newPath )

virtual

Rename (move) this folder to another location.

Parameters

newPath new path of the folder

Exceptions

exceptions::net_exception if an error occurs

Implements folder.

References getFullPath(), path::getLastComponent(), path::isEmpty(), path::isParentOf(), store::isValidFolderName(), folder::notifyFolder(), IMAPCommand::RENAME(), rename(), status(), and folderEvent::TYPE_RENAMED.

Referenced by IMAPMessage, and rename().

◆ setMessageFlags()

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

msgs	index set of messages on which to set the flags
flags	set of flags (see message::Flags)
mode	indicate how to treat old and new flags (see message::FlagsModes)

Exceptions

exceptions::net_exception if an error occurs

Implements folder.

References setMessageFlags(), status(), and IMAPCommand::STORE().

Referenced by IMAPMessage, and setMessageFlags().

◆ status()

void status	(	size_t &	count,
		size_t &	unseen )

virtual

Request folder status without opening it.

Deprecated: Use the new getStatus() method

Parameters

count	will receive the number of messages in the folder
unseen	will receive the number of unseen messages in the folder

Exceptions

exceptions::net_exception if an error occurs

Implements folder.

References vmime::count(), getStatus(), and status().

Referenced by addMessage(), copyMessages(), create(), deleteMessages(), destroy(), expunge(), fetchMessages(), getAndFetchMessages(), getFolders(), getMessages(), getStatus(), IMAPMessage, noop(), open(), rename(), setMessageFlags(), and status().

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

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ~IMAPFolder()

Member Function Documentation

◆ addMessage() [1/2]

◆ addMessage() [2/2]

◆ close()

◆ copyMessages()

◆ create()

◆ deleteMessages()

◆ destroy()

◆ exists()

◆ expunge()

◆ fetchMessage()

◆ fetchMessages()

◆ getAndFetchMessages()

◆ getAttributes()

◆ getFetchCapabilities()

◆ getFolder()

◆ getFolders()

◆ getFullPath()

◆ getHighestModSequence()

◆ getMessage()

◆ getMessageCount()

◆ getMessageNumbersStartingOnUID()

◆ getMessages()

◆ getMode()

◆ getName()

◆ getParent()

◆ getStatus()

◆ getStore() [1/2]

◆ getStore() [2/2]

◆ getUIDValidity()

◆ isOpen()

◆ noop()

◆ open()

◆ rename()

◆ setMessageFlags()

◆ status()