/**
\mainpage libmapi++

<h2>libmapi++ - C++ Bindings for OpenChange Clients</h2>

libmapi++ provides C++ bindings for OpenChange client libraries (<a href="../libmapi/index.html">libmapi</a>).
It is intended to provide a higher level abstraction of the OpenChange client libraries for C++ users who
would prefer to work with an object-oriented API.

<h2>Using libmapi++</h2>

\note libmapi++ classes live in the libmapipp namespace.

When using libmapi++, you start by creating a session, and logging in to the server.
\code
// Initialize MAPI Session
libmapipp::session mapi_session;

// login() can use an optional profile_name, and an optional password
mapi_session.login();
\endcode

The session can then access the message store, which is the tree of private folders associated
with a single user (containing various folders, such as the Inbox, Sent Mail, Calendar, Journal
and so on).

The message store is associated with the session, so you don't create it yourself. Instead,
you obtain it using the session object's get_message_store() method.
\code
// Take a reference to the message store
libmapipp::message_store &msg_store = mapi_session.get_message_store();
\endcode
\note It has to be a reference, not a copy / assignment.

Most objects in libmapi++ (and any kind of MAPI library) can be considered to have properties
that belong to them, and subordinate (child) objects. For example, the name of the message
store is a property of the message store, but the various folders in the message store (or equally,
the messages in a folder, or the attachments to a message) are part of a hierachy. 

To get access to the properties of an object, you obtain the property_container associated
with the object, set the properties you want to access, call fetch(), and then read off the
various properties.
\code
// Get a property of the top level message store
libmapipp::property_container msg_store_props = msg_store.get_property_container();
msg_store_props << PR_DISPLAY_NAME; // you could use other properties here
msg_store_props.fetch();
std::cout << "Message store display name: "
	  << (const char*)msg_store_props[PR_DISPLAY_NAME]
	  << std::endl;
\endcode

Note that the operator[] is essentially a lookup operator. If you'd prefer to use an
iterator, look at libmapipp::property_container_iterator.

As noted above, the objects in libmapi++ can be considered as a hierachy. To get the
child elements for an object, you use the hierachy table for that element. For example,
to get the various folders in the private information store, you could use code like this:
\code
// We start off by fetching the top level folder
mapi_id_t top_folder_id = msg_store.get_default_folder(olFolderTopInformationStore);
libmapipp::folder top_folder(msg_store, top_folder_id);
// Now get the child folders of the top level folder. These are returned as
// a std::vector of pointers to folders
libmapipp::folder::hierarchy_container_type child_folders = top_folder.fetch_hierarchy();

// Display the name, total item count and unread item count for each folder
for (unsigned int i = 0; i < child_folders.size(); ++i) {
    libmapipp::property_container child_props = child_folders[i]->get_property_container();
    child_props << PR_DISPLAY_NAME << PR_CONTENT_COUNT << PR_CONTENT_UNREAD;
    child_props.fetch();
    std::cout << "|-----> " << (const char*)child_props[PR_DISPLAY_NAME]
              << " (" << (*(int*)child_props[PR_CONTENT_COUNT]) << " items, "
              << (*(int*)child_props[PR_CONTENT_UNREAD]) << " unread)"
              << std::endl;
}
\endcode

As an alternative to working through the folder tree hierachy, you can also open 
folders directly. In the example below, we open the Inbox. The API documentation
for message_store::get_default_folder() provides a list of other folder IDs that
you may find useful.
\code
mapi_id_t inbox_id = msg_store.get_default_folder(olFolderInbox);
libmapipp::folder inbox_folder(msg_store, inbox_id);
\endcode

You can then get each message in the folder:
\code
// These are returned as a std::vector of pointers to messages
libmapipp::folder::message_container_type messages = inbox_folder.fetch_messages();
std::cout << "Inbox contains " << messages.size() << " messages" << std::endl;
\endcode

You can then get the various properties of each message in the same way as was
used for the folder properties - you get the associated property_container, set
the required properties, and call fetch() before reading off the required
properties:
\code
// Work through each message
for (unsigned int i = 0; i < messages.size(); ++i) {
	// Get the properties we are interested in
	libmapipp::property_container msg_props = messages[i]->get_property_container();
	// We get the "to" addressee, and the subject
	msg_props << PR_DISPLAY_TO << PR_CONVERSATION_TOPIC;
	msg_props.fetch();
	// Display those properties
	std::cout << "|-----> " << (const char*)msg_props[PR_DISPLAY_TO]
		  << "\t\t| " << (const char*)msg_props[PR_CONVERSATION_TOPIC]
		  << std::endl;
}
\endcode

\todo Explain attachments.

*/
