VMime
folder Class Referenceabstract
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< messagegetMessage (const size_t num)=0
 
virtual std::vector< shared_ptr< message > > getMessages (const messageSet &msgs)=0
 
virtual size_t getMessageCount ()=0
 
virtual shared_ptr< foldergetFolder (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< folderStatusgetStatus ()=0
 
virtual void expunge ()=0
 
virtual shared_ptr< foldergetParent ()=0
 
virtual shared_ptr< const storegetStore () const =0
 
virtual shared_ptr< storegetStore ()=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_tgetMessageNumbersStartingOnUID (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 &)
 
objectoperator= (const object &)
 
virtual ~object ()
 

Detailed Description

Abstract representation of a folder in a message store.

Member Typedef Documentation

◆ 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)

◆ 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
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

◆ 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
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

◆ addMessageChangedListener()

void addMessageChangedListener ( events::messageChangedListener l)

◆ addMessageCountListener()

void addMessageCountListener ( events::messageCountListener l)

◆ close()

virtual void close ( const bool  expunge)
pure virtual

Close this folder.

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

◆ copyMessages()

virtual messageSet copyMessages ( const folder::path dest,
const messageSet msgs 
)
pure 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

◆ create()

virtual void create ( const folderAttributes attribs)
pure virtual

Create this folder.

Parameters
attribsattributes of the new folder
Exceptions
exceptions::net_exceptionif an error occurs

◆ deleteMessages()

virtual void deleteMessages ( const messageSet msgs)
pure virtual

Remove one or more messages from this folder.

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

◆ destroy()

virtual void destroy ( )
pure virtual

Delete this folder.

The folder should be closed before attempting to delete it.

Exceptions
exceptions::net_exceptionif an error occurs

◆ exists()

virtual bool exists ( )
pure virtual

Test whether this folder exists.

Returns
true if the folder exists, false otherwise

◆ expunge()

virtual void expunge ( )
pure virtual

Expunge deleted messages.

Exceptions
exceptions::net_exceptionif an error occurs

◆ fetchMessage()

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

Fetch objects for the specified message.

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

◆ 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
msglist of message sequence numbers
attribsset of attributes to fetch
progressprogress listener, or NULL if not used
Exceptions
exceptions::net_exceptionif an error occurs

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

◆ getAttributes()

virtual const folderAttributes getAttributes ( )
pure virtual

Return the attributes of the folder.

Returns
folder attributes (see folder::Flags)

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

◆ 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
namesub-folder name
Returns
a new object referencing the specified folder
Exceptions
exceptions::net_exceptionif an error occurs

◆ 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
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

◆ getFullPath()

virtual const folder::path getFullPath ( ) const
pure virtual

Return the fully qualified path name of this folder.

Returns
absolute path of the folder

◆ 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
nummessage sequence number
Returns
a new object referencing the specified message
Exceptions
exceptions::net_exceptionif an error occurs

◆ getMessageCount()

virtual size_t getMessageCount ( )
pure virtual

Return the number of messages in this folder.

Returns
number of messages in the folder

◆ 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
uidthe uid of the first message
Exceptions
exceptions::net_exceptionif an error occurs

◆ 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)
// 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

◆ getMode()

virtual int getMode ( ) const
pure virtual

Return the mode in which the folder has been open.

Returns
folder opening mode (see folder::Modes)

◆ getName()

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

Return the name of this folder.

Returns
folder name

◆ getParent()

virtual shared_ptr<folder> getParent ( )
pure virtual

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

Returns
parent folder object

◆ getStatus()

virtual shared_ptr<folderStatus> getStatus ( )
pure virtual

Request folder status without opening it.

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

◆ 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

◆ 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

◆ 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

◆ notifyEvent()

◆ notifyFolder()

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

Referenced by folder::notifyEvent().

◆ notifyMessageChanged()

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

Referenced by folder::notifyEvent().

◆ notifyMessageCount()

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

Referenced by folder::notifyEvent().

◆ open()

virtual void open ( const int  mode,
bool  failIfModeIsNotAvailable = false 
)
pure 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

◆ removeFolderListener()

void removeFolderListener ( events::folderListener l)

◆ removeMessageChangedListener()

void removeMessageChangedListener ( events::messageChangedListener l)

◆ removeMessageCountListener()

void removeMessageCountListener ( events::messageCountListener l)

◆ rename()

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

Rename (move) this folder to another location.

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

◆ 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
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

◆ 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
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

The documentation for this class was generated from the following files:
vmime::net::messageSet::byUID
static messageSet byUID(const message::uid &uid)
Constructs a new message set and initializes it with a single message represented by its UID.
Definition: messageSet.cpp:253
vmime::net::folder::folder
folder()
Definition: folder.hpp:67
vmime::net::messageSet::byNumber
static messageSet byNumber(const size_t number)
Constructs a new message set and initializes it with a single message represented by its sequence num...
Definition: messageSet.cpp:180