return retval;
}
-session::session(const std::string& profiledb, bool debug)throw(std::runtime_error, mapi_exception)
+session::session(const std::string& profiledb, bool debug) throw(std::runtime_error, mapi_exception)
: m_session(NULL), m_memory_ctx(talloc_init("libmapi++")), m_message_store(new message_store(*this))
{
mapi_exception::fill_status_map();
std::string profile_path;
// If profile is not provided, attempt to get it from default location
- // ~/.openchange/profiles.ldb
+ // (~/.openchange/profiles.ldb)
if (profiledb == "") {
profile_path = get_default_profile_path();
if (profile_path == "") {
// #define INVALID_HANDLE_VALUE 0xffffffff
class property_container;
-/** \brief Base Object class. \n
- * Most classes such as folder, message and message_store derive from this class.
- * It is important that objects be passed around as references and that no unnecessary
- * copies are made as this will call the class destructor which will call mapi_object_release()
- * and release the handle associated with this object.
+/**
+ * Base Object class
+ *
+ * Most classes such as folder, message and message_store derive from this class.
+ * It is important that objects be passed around as references and that no unnecessary
+ * copies are made as this will call the class destructor which will call
+ * mapi_object_release() and release the handle associated with this object.
*/
class object {
public:
- /** \brief Object Constructor
- * \param mapi_session Session this object is to be associated with.
- * \param object_type The name of the type of object (to be set in a subclass)
+ /**
+ * \brief Object Constructor
+ *
+ * \param mapi_session Session this object is to be associated with.
+ * \param object_type The name of the type of object (to be set in a subclass)
*/
object(session& mapi_session, const std::string& object_type = "") throw() : m_session(mapi_session), m_object_type(object_type)
{
mapi_object_init(&m_object);
}
- /** \brief Returns a reference to the mapi_object_t associated with this object
- * \return A reference to the C struct mapi_object_t associated with this object
+ /**
+ * \brief Obtain a reference to the mapi_object_t associated with this object
+ *
+ * \return A reference to the C struct mapi_object_t associated with this object
*/
virtual mapi_object_t& data() throw() { return m_object; }
- /** \brief Returns a property_container to be used with this object.
- * \return A property_container to be used with this object.
+ /**
+ * \brief Obtain a property_container to be used with this object.
+ *
+ * \return A property_container to be used with this object.
*/
virtual property_container get_property_container();
- /// \brief Returns session associated with this object.
+ /**
+ * \brief Obtain the session associated with this object.
+ *
+ * \return The session associated with this object
+ */
virtual session& get_session() { return m_session; }
- /** \brief Destructor\n
- * calls mapi_object_release() which releases the handle associated with this object.
+ /**
+ * \brief Destructor
+ *
+ * Calls mapi_object_release() which releases the handle associated with this object.
*/
virtual ~object() throw()
{
namespace libmapipp {
+/**
+ * This class represents a user %profile database
+ *
+ * \todo possibly rename profile class to profile_database?
+ * \todo we should be able to create a profile using libmapi++ classes
+ * \todo we should be able to delete a profile using libmapi++ classes
+ * \todo maybe move some of the session.h documentation on profiles to profile.h?
+ */
class profile
{
public:
+ /**
+ * Make the specified profile the default profile
+ *
+ * \param profname the name of the profile to make default
+ */
bool static set_default(const char* profname)
{
return (SetDefaultProfile(profname) == MAPI_E_SUCCESS);
}
+ /**
+ * Make the specified profile the default profile
+ *
+ * \param profname the name of the profile to make default
+ */
bool static set_default(const std::string& profname)
{
return set_default(profname.c_str());
}
+ /**
+ * Get the default profile name
+ *
+ * \return the name of the default profile
+ */
std::string static get_default_profile() throw (mapi_exception)
{
const char* profname = NULL;
}
}
- /** \brief Get Property Tag of the Property Value this operator points to.
- * \return Property Tag of Property this iterator points to or MAPI_PROP_RESERVED if this is an invalid iterator.
+ /**
+ * \brief Get Property Tag of the Property Value this operator points to.
+ *
+ * \return Property Tag of Property this iterator points to or MAPI_PROP_RESERVED if this is an invalid iterator.
*/
int get_tag()
{
return !(*this == rhs);
}
- /** \brief operator*
- * \return The property value as a void pointer.\n
+ /**
+ * \brief operator*
+ *
+ * \return The property value as a void pointer.
*/
const void* operator*()
{
{
}
- /** \brief Fetches properties with the tags supplied using operator<<
- * \return The number of objects that were fetched.
+ /**
+ * \brief Fetches properties with the tags supplied using operator<<
+ *
+ * \return The number of objects that were fetched.
*/
uint32_t fetch()
{
return *this;
}
- /** \brief Finds the property value associated with a property tag
- * \param property_tag The Property Tag to be searched for
- * \return Property Value as a const void pointer
+ /**
+ * \brief Finds the property value associated with a property tag
+ *
+ * \param property_tag The Property Tag to be searched for
+ *
+ * \return Property Value as a const void pointer
*/
const void* operator[](uint32_t property_tag)
{
namespace libmapipp
{
class message_store;
-/// This class represents a MAPI session with the Exchange Server
+/**
+ * This class represents a MAPI %session with the Exchange Server
+ *
+ * The %session is best thought of as the connection by a single user to a
+ * single server. It is possible to have multiple sessions open at the same
+ * time.
+ *
+ * A key concept in the %session is that of a \em profile, and the %profile
+ * database. The %profile is a pre-established data set that specifies the
+ * server information (e.g. server name / IP address, and Exchange domain)
+ * and client information (e.g. the user name, preferred language, and
+ * optionally the users password). The profiles are stored in a local store
+ * (Samba LDB database) known as the %profile store or %profile database. One
+ * of the profiles in the %profile database can be designated as the default
+ * %profile (which is particularly useful given that most users may only have
+ * one). See the profile class documentation for more information.
+ *
+ * The general concept is that you create a %session %object, log in to the
+ * %session using a selected %profile name, and then work with the message_store
+ * associated with that %session. The message_store is only valid so long
+ * as the session is valid.
+ */
class session {
public:
/**
* \brief Constructor
- * \param profiledb An absolute path specifying where the profile database is.\n
- * If none or "" is specified the default location will be used (~/.openchange.profiles.ldb).
+ *
+ * \param profiledb An absolute path specifying the location of the
+ * %profile database. If not specified (or "" is specified) the default
+ * location will be used (~/.openchange.profiles.ldb).
*
* \param debug Whether to output debug information to stdout
*/
/**
* \brief Log-in to the Exchange Server
- * \param profile_name The name of the profile, if left blank the default profile will be used.
- * \param password The password to use to login with.\n
- * It is possible to omit this if the password is stored in the profile database.
+ *
+ * \param profile_name The name of the profile to use to login with.
+ * If not specified (or "" is specified), then the default %profile will
+ * be used.
+ *
+ * \param password The password to use to login with. It is possible to
+ * omit this if the password is stored in the %profile database.
*/
void login(const std::string& profile_name = "", const std::string& password = "") throw(mapi_exception);
+ /**
+ * \brief The path to the default %profile database
+ *
+ * This method is not normally required to be called by user applications
+ * but might be useful under some circumstances.
+ */
static std::string get_default_profile_path();
+ /**
+ * \brief The name of the profile that is in use
+ *
+ * Calling this method only makes sense if login() has been called with
+ * this %session object.
+ */
std::string get_profile_name() const { return m_profile_name; }
- /** \brief Returns a reference to the message_store associated with this session
- * \return The message_store associated with this session.
+ /**
+ * \brief Obtain a reference to the message_store associated with this %session
+ *
+ * \return The message_store associated with this %session.
*/
message_store& get_message_store() throw() { return *m_message_store; }
- /// \brief Get Session TALLOC Memory Context pointer.
+ /**
+ * \brief Obtain a talloc memory context for this %session
+ *
+ * This pointer can be used for subsequent memory allocations, and
+ * these will be cleaned up when the %session is terminated.
+ */
TALLOC_CTX* get_memory_ctx() throw() { return m_memory_ctx; }
- /// Uninitializes the MAPI session.
+ /**
+ * \brief Uninitialize and clean up the MAPI %session.
+ */
~session()
{
uninitialize();
git.samba.org / jelmer / openchange-proposed.git / .git / commitdiff