folder Class Reference

#include <folder.hpp>

Inheritance diagram for folder:

Collaboration diagram for folder:

Public Types
enum	Modes { MODE_READ_ONLY , MODE_READ_WRITE }
typedef vmime::utility::path	path

Public Member Functions
virtual	~folder ()
int	getType ()
int	getFlags ()
virtual const folderAttributes	getAttributes ()=0
virtual int	getMode () const =0
virtual const folder::path::component	getName () const =0
virtual const folder::path	getFullPath () const =0
virtual void	open (const int mode, bool failIfModeIsNotAvailable=false)=0
virtual void	close (const bool expunge)=0
virtual void	create (const folderAttributes &attribs)=0
virtual bool	exists ()=0
virtual void	destroy ()=0
virtual bool	isOpen () const =0
virtual shared_ptr< message >	getMessage (const size_t num)=0
virtual std::vector< shared_ptr< message > >	getMessages (const messageSet &msgs)=0
virtual size_t	getMessageCount ()=0
virtual shared_ptr< folder >	getFolder (const folder::path::component &name)=0
virtual std::vector< shared_ptr< folder > >	getFolders (const bool recursive=false)=0
virtual void	rename (const folder::path &newPath)=0
virtual void	deleteMessages (const messageSet &msgs)=0
virtual void	setMessageFlags (const messageSet &msgs, const int flags, const int mode=message::FLAG_MODE_SET)=0
virtual messageSet	addMessage (shared_ptr< vmime::message > msg, const int flags=-1, vmime::datetime *date=NULL, utility::progressListener *progress=NULL)=0
virtual messageSet	addMessage (utility::inputStream &is, const size_t size, const int flags=-1, vmime::datetime *date=NULL, utility::progressListener *progress=NULL)=0
virtual messageSet	copyMessages (const folder::path &dest, const messageSet &msgs)=0
virtual void	status (size_t &count, size_t &unseen)=0
virtual shared_ptr< folderStatus >	getStatus ()=0
virtual void	expunge ()=0
virtual shared_ptr< folder >	getParent ()=0
virtual shared_ptr< const store >	getStore () const =0
virtual shared_ptr< store >	getStore ()=0
virtual void	fetchMessages (std::vector< shared_ptr< message > > &msg, const fetchAttributes &attribs, utility::progressListener *progress=NULL)=0
virtual void	fetchMessage (shared_ptr< message > msg, const fetchAttributes &attribs)=0
virtual std::vector< shared_ptr< message > >	getAndFetchMessages (const messageSet &msgs, const fetchAttributes &attribs)=0
virtual int	getFetchCapabilities () const =0
virtual std::vector< size_t >	getMessageNumbersStartingOnUID (const message::uid &uid)=0
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)

Protected Types
enum	PrivateConstants { TYPE_UNDEFINED = 9999 , FLAG_UNDEFINED = 9999 }

Protected Member Functions
	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

Abstract representation of a folder in a message store.

Member Typedef Documentation

path

typedef vmime::utility::path path

Type used for fully qualified path name of a folder.

Member Enumeration Documentation

Modes

enum Modes

Open mode.

Enumerator
MODE_READ_ONLY	Read-only mode (no modification to folder or messages is possible).
MODE_READ_WRITE	Full access mode (read and write).

PrivateConstants

enum PrivateConstants

protected

Enumerator
TYPE_UNDEFINED	Used internally to indicate type has not been initialized yet.
FLAG_UNDEFINED	Used internally to indicate flags have not been initialized yet.

Constructor & Destructor Documentation

folder() [1/2]

folder ( const folder &  )

protected

folder() [2/2]

folder ( )

protected

~folder()

virtual ~folder ( )

virtual

Member Function Documentation

addFolderListener()

void addFolderListener

(

events::folderListener *

l

)

References vmime::dynamicCast().

addMessage() [1/2]

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

pure 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

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

addMessage() [2/2]

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

pure 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

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

addMessageChangedListener()

void addMessageChangedListener

(

events::messageChangedListener *

l

)

References vmime::dynamicCast().

addMessageCountListener()

void addMessageCountListener

(

events::messageCountListener *

l

)

References vmime::dynamicCast().

close()

virtual void close ( const bool  expunge )

pure virtual

Close this folder.

Parameters

expunge

if set to true, deleted messages are expunged

Exceptions

exceptions::net_exception

if an error occurs

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

copyMessages()

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

pure 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

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

create()

virtual void create ( const folderAttributes &  attribs )

pure virtual

Create this folder.

Parameters

attribs

attributes of the new folder

Exceptions

exceptions::net_exception

if an error occurs

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

Referenced by maildirMessage::fetchPartHeader().

deleteMessages()

virtual void deleteMessages ( const messageSet &  msgs )

pure 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

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

destroy()

virtual void destroy ( )

pure virtual

Delete this folder.

The folder should be closed before attempting to delete it.

Exceptions

exceptions::net_exception

if an error occurs

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

exists()

virtual bool exists ( )

pure virtual

Test whether this folder exists.

Returns

true if the folder exists, false otherwise

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

expunge()

virtual void expunge ( )

pure virtual

Expunge deleted messages.

Exceptions

exceptions::net_exception

if an error occurs

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

fetchMessage()

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

pure 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

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

fetchMessages()

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

pure 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

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

getAndFetchMessages()

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

pure 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()

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

getAttributes()

virtual const folderAttributes getAttributes ( )

pure virtual

Return the attributes of the folder.

Returns

folder attributes (see folder::Flags)

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

Referenced by folder::getFlags(), and folder::getType().

getFetchCapabilities()

virtual int getFetchCapabilities ( ) const

pure virtual

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

Returns

list of supported fetchable objects

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

getFlags()

int getFlags

(

)

Return the flags of this folder.

Deprecated:

Use the getAttributes().getFlags() method instead

Returns

folder flags (see folderAttributes::Flags enum)

References folder::getAttributes(), and folderAttributes::getFlags().

getFolder()

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

pure 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

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

getFolders()

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

pure 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

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

getFullPath()

virtual const folder::path getFullPath ( ) const

pure virtual

Return the fully qualified path name of this folder.

Returns

absolute path of the folder

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

getMessage()

virtual shared_ptr< message > getMessage ( const size_t  num )

pure 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

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

getMessageCount()

virtual size_t getMessageCount ( )

pure virtual

Return the number of messages in this folder.

Returns

number of messages in the folder

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

getMessageNumbersStartingOnUID()

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

pure 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

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

getMessages()

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

pure 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

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

getMode()

virtual int getMode ( ) const

pure virtual

Return the mode in which the folder has been open.

Returns

folder opening mode (see folder::Modes)

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

getName()

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

pure virtual

Return the name of this folder.

Returns

folder name

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

getParent()

virtual shared_ptr< folder > getParent ( )

pure virtual

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

Returns

parent folder object

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

getStatus()

virtual shared_ptr< folderStatus > getStatus ( )

pure virtual

Request folder status without opening it.

Returns

current folder status

Exceptions

exceptions::net_exception

if an error occurs

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

getStore() [1/2]

virtual shared_ptr< const store > getStore ( ) const

pure virtual

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

Returns

the store object to which this folder is attached

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

Referenced by POP3Message::extract().

getStore() [2/2]

virtual shared_ptr< store > getStore ( )

pure virtual

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

Returns

the store object to which this folder is attached

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

getType()

int getType

(

)

Return the type of this folder.

Deprecated:

Use the getAttributes().getType() method instead

Returns

folder type (see folderAttributes::Types enum)

References folder::getAttributes(), and folderAttributes::getType().

isOpen()

virtual bool isOpen ( ) const

pure virtual

Test whether this folder is open.

Returns

true if the folder is open, false otherwise

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

notifyEvent()

void notifyEvent ( shared_ptr< events::event >  event )

protected

References vmime::dynamicCast(), messageCountEvent::EVENT_CLASS, messageChangedEvent::EVENT_CLASS, folderEvent::EVENT_CLASS, folder::notifyFolder(), folder::notifyMessageChanged(), and folder::notifyMessageCount().

notifyFolder()

void notifyFolder ( shared_ptr< events::folderEvent >  event )

protected

References vmime::dynamicCast().

Referenced by folder::notifyEvent().

notifyMessageChanged()

void notifyMessageChanged ( shared_ptr< events::messageChangedEvent >  event )

protected

References vmime::dynamicCast().

Referenced by folder::notifyEvent().

notifyMessageCount()

void notifyMessageCount ( shared_ptr< events::messageCountEvent >  event )

protected

References vmime::dynamicCast().

Referenced by folder::notifyEvent().

open()

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

pure 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

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

removeFolderListener()

void removeFolderListener

(

events::folderListener *

l

)

References vmime::dynamicCast().

removeMessageChangedListener()

void removeMessageChangedListener

(

events::messageChangedListener *

l

)

References vmime::dynamicCast().

removeMessageCountListener()

void removeMessageCountListener

(

events::messageCountListener *

l

)

References vmime::dynamicCast().

rename()

virtual void rename ( const folder::path &  newPath )

pure virtual

Rename (move) this folder to another location.

Parameters

newPath

new path of the folder

Exceptions

exceptions::net_exception

if an error occurs

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

setMessageFlags()

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

pure 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

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

Referenced by IMAPMessage::setFlags(), and maildirMessage::setFlags().

status()

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

pure 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

Implemented in IMAPFolder, maildirFolder, and POP3Folder.

---

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

• folder.hpp
• folder.cpp