branches/plugfest/libmapi++/libmapi++-mainpage.doxy

   1 /**
   2 \mainpage libmapi++
   3
   4 <h2>libmapi++ - C++ Bindings for OpenChange Clients</h2>
   5
   6 libmapi++ provides C++ bindings for OpenChange client libraries (<a href="../libmapi/index.html">libmapi</a>).
   7 It is intended to provide a higher level abstraction of the OpenChange client libraries for C++ users who
   8 would prefer to work with an object-oriented API.
   9
  10 <h2>Using libmapi++</h2>
  11
  12 \note libmapi++ classes live in the libmapipp namespace.
  13
  14 When using libmapi++, you start by creating a session, and logging in to the server.
  15 \code
  16 // Initialize MAPI Session
  17 libmapipp::session mapi_session;
  18
  19 // login() can use an optional profile_name, and an optional password
  20 mapi_session.login();
  21 \endcode
  22
  23 The session can then access the message store, which is the tree of private folders associated
  24 with a single user (containing various folders, such as the Inbox, Sent Mail, Calendar, Journal
  25 and so on).
  26
  27 The message store is associated with the session, so you don't create it yourself. Instead,
  28 you obtain it using the session object's get_message_store() method.
  29 \code
  30 // Take a reference to the message store
  31 libmapipp::message_store &msg_store = mapi_session.get_message_store();
  32 \endcode
  33 \note It has to be a reference, not a copy / assignment.
  34
  35 Most objects in libmapi++ (and any kind of MAPI library) can be considered to have properties
  36 that belong to them, and subordinate (child) objects. For example, the name of the message
  37 store is a property of the message store, but the various folders in the message store (or equally,
  38 the messages in a folder, or the attachments to a message) are part of a hierachy.
  39
  40 To get access to the properties of an object, you obtain the property_container associated
  41 with the object, set the properties you want to access, call fetch(), and then read off the
  42 various properties.
  43 \code
  44 // Get a property of the top level message store
  45 libmapipp::property_container msg_store_props = msg_store.get_property_container();
  46 msg_store_props << PR_DISPLAY_NAME; // you could use other properties here
  47 msg_store_props.fetch();
  48 std::cout << "Message store display name: "
  49           << (const char*)msg_store_props[PR_DISPLAY_NAME]
  50           << std::endl;
  51 \endcode
  52
  53 Note that the operator[] is essentially a lookup operator. If you'd prefer to use an
  54 iterator, look at libmapipp::property_container_iterator.
  55
  56 As noted above, the objects in libmapi++ can be considered as a hierachy. To get the
  57 child elements for an object, you use the hierachy table for that element. For example,
  58 to get the various folders in the private information store, you could use code like this:
  59 \code
  60 // We start off by fetching the top level folder
  61 mapi_id_t top_folder_id = msg_store.get_default_folder(olFolderTopInformationStore);
  62 libmapipp::folder top_folder(msg_store, top_folder_id);
  63 // Now get the child folders of the top level folder. These are returned as
  64 // a std::vector of pointers to folders
  65 libmapipp::folder::hierarchy_container_type child_folders = top_folder.fetch_hierarchy();
  66
  67 // Display the name, total item count and unread item count for each folder
  68 for (unsigned int i = 0; i < child_folders.size(); ++i) {
  69     libmapipp::property_container child_props = child_folders[i]->get_property_container();
  70     child_props << PR_DISPLAY_NAME << PR_CONTENT_COUNT << PR_CONTENT_UNREAD;
  71     child_props.fetch();
  72     std::cout << "|-----> " << (const char*)child_props[PR_DISPLAY_NAME]
  73               << " (" << (*(int*)child_props[PR_CONTENT_COUNT]) << " items, "
  74               << (*(int*)child_props[PR_CONTENT_UNREAD]) << " unread)"
  75               << std::endl;
  76 }
  77 \endcode
  78
  79 As an alternative to working through the folder tree hierachy, you can also open
  80 folders directly. In the example below, we open the Inbox. The API documentation
  81 for message_store::get_default_folder() provides a list of other folder IDs that
  82 you may find useful.
  83 \code
  84 mapi_id_t inbox_id = msg_store.get_default_folder(olFolderInbox);
  85 libmapipp::folder inbox_folder(msg_store, inbox_id);
  86 \endcode
  87
  88 You can then get each message in the folder:
  89 \code
  90 // These are returned as a std::vector of pointers to messages
  91 libmapipp::folder::message_container_type messages = inbox_folder.fetch_messages();
  92 std::cout << "Inbox contains " << messages.size() << " messages" << std::endl;
  93 \endcode
  94
  95 You can then get the various properties of each message in the same way as was
  96 used for the folder properties - you get the associated property_container, set
  97 the required properties, and call fetch() before reading off the required
  98 properties:
  99 \code
 100 // Work through each message
 101 for (unsigned int i = 0; i < messages.size(); ++i) {
 102         // Get the properties we are interested in
 103         libmapipp::property_container msg_props = messages[i]->get_property_container();
 104         // We get the "to" addressee, and the subject
 105         msg_props << PR_DISPLAY_TO << PR_CONVERSATION_TOPIC;
 106         msg_props.fetch();
 107         // Display those properties
 108         std::cout << "|-----> " << (const char*)msg_props[PR_DISPLAY_TO]
 109                   << "\t\t| " << (const char*)msg_props[PR_CONVERSATION_TOPIC]
 110                   << std::endl;
 111 }
 112 \endcode
 113
 114 \todo Explain attachments.
 115
 116 */