From 599469670eecc911e079c0f264885a23502a661e Mon Sep 17 00:00:00 2001 From: HanzZ Date: Tue, 15 Feb 2011 15:48:52 +0100 Subject: [PATCH] Docs --- include/transport/config.h | 22 +++++++++++++++- include/transport/sqlite3backend.h | 40 +++++++++++++++++++++++++++--- include/transport/storagebackend.h | 35 ++++++++++++++++++-------- include/transport/transport.h | 21 +++++++++++++--- src/sqlite3backend.cpp | 2 +- 5 files changed, 102 insertions(+), 18 deletions(-) diff --git a/include/transport/config.h b/include/transport/config.h index 4a0700e8..b79cb44b 100644 --- a/include/transport/config.h +++ b/include/transport/config.h @@ -38,18 +38,38 @@ namespace Transport { typedef boost::program_options::variables_map Variables; -/// Class used to load. +/// Represents config file. + +/// It's used to load config file and allows others parts of libtransport to be configured +/// properly. Config files are text files which use "ini" format. Variables are divided into multiple +/// sections. Every class is configurable with some variables which change its behavior. Check particular +/// class documentation to get a list of all relevant variables for that class. class Config { public: + /// Constructor. Config() {} + + /// Destructor virtual ~Config() {} + + /// Loads data from config file. You can pass your extra options which will be recognized by + /// the parser using opts parameter. + /// \param configfile path to config file + /// \param opts extra options which will be recognized by a parser bool load(const std::string &configfile, boost::program_options::options_description &opts); + + /// Loads data from config file. This function loads only config variables needed by libtransport. + /// \see load(const std::string &, boost::program_options::options_description &) + /// \param configfile path to config file bool load(const std::string &configfile); + /// Returns value of variable defined by key. For variables in sections you can use "section.variable" key format. + /// \param key config variable name const boost::program_options::variable_value &operator[] (const std::string &key) { return m_variables[key]; } + /// This signal is emitted when config is loaded/reloaded. boost::signal onConfigReloaded; private: diff --git a/include/transport/sqlite3backend.h b/include/transport/sqlite3backend.h index f1acb919..c6ee0acb 100644 --- a/include/transport/sqlite3backend.h +++ b/include/transport/sqlite3backend.h @@ -29,20 +29,54 @@ namespace Transport { +/// Used to store transport data into SQLite3 database. class SQLite3Backend : public StorageBackend { public: + /// Creates new SQLite3Backend instance. + /// \param config cofiguration, this class uses following Config values: + /// - database.database - path to SQLite3 database file, database file is created automatically + /// - service.prefix - prefix for tables created by createDatabase method SQLite3Backend(Config *config); + + /// Destructor. ~SQLite3Backend(); + /// Connects to the database and creates it if it's needed. This method call createDatabase() function + /// automatically. + /// \return true if database is opened successfully. bool connect(); + + /// Creates database structure. + /// \see connect() + /// \return true if database structure has been created successfully. Note that it returns True also if database structure + /// already exists. bool createDatabase(); + /// Stores user into database. + /// \param user user struct containing all information about user which have to be stored void setUser(const UserInfo &user); - bool getUser(const std::string &barejid, UserInfo &user); - void setUserOnline(long id, bool online); - void removeUser(long id); + /// Gets user data from database and stores them into user reference. + /// \param barejid barejid of user + /// \param user UserInfo object where user data will be stored + /// \return true if user has been found in database + bool getUser(const std::string &barejid, UserInfo &user); + + /// Changes users online state variable in database. + /// \param id id of user - UserInfo.id + /// \param online online state + void setUserOnline(long id, bool online); + + /// Removes user and all connected data from database. + /// \param id id of user - UserInfo.id + /// \return true if user has been found in database and removed + bool removeUser(long id); + + /// Returns JIDs of all buddies in user's roster. + /// \param id id of user - UserInfo.id + /// \param roster string list used to store user's roster + /// \return true if user has been found in database and roster has been fetched bool getBuddies(long id, std::list &roster); private: diff --git a/include/transport/storagebackend.h b/include/transport/storagebackend.h index a040c9d5..130a2a43 100644 --- a/include/transport/storagebackend.h +++ b/include/transport/storagebackend.h @@ -25,31 +25,46 @@ namespace Transport { +/// Represents all data needed to be stored in database. struct UserInfo { - long id; - std::string jid; - std::string uin; - std::string password; - std::string language; - std::string encoding; - bool vip; + long id; ///< id of user used as primary key in database + std::string jid; ///< barejid of XMPP user + std::string uin; ///< legacy network username + std::string password; ///< password for legacy network + std::string language; ///< user's preferred language + std::string encoding; ///< user's preferred encoding + bool vip; ///< true if user is VIP }; +/// Abstract class defining storage backends. class StorageBackend { public: + /// Virtual desctructor. virtual ~StorageBackend() {} + /// connect virtual bool connect() = 0; + + /// createDatabase virtual bool createDatabase() = 0; + /// setUser virtual void setUser(const UserInfo &user) = 0; - virtual bool getUser(const std::string &barejid, UserInfo &user) = 0; - virtual void setUserOnline(long id, bool online) = 0; - virtual void removeUser(long id) = 0; + /// getuser + virtual bool getUser(const std::string &barejid, UserInfo &user) = 0; + + /// setUserOnline + virtual void setUserOnline(long id, bool online) = 0; + + /// removeUser + virtual bool removeUser(long id) = 0; + + /// getBuddies virtual bool getBuddies(long id, std::list &roster) = 0; + /// onStorageError boost::signal onStorageError; }; diff --git a/include/transport/transport.h b/include/transport/transport.h index e7a783b6..b194281f 100644 --- a/include/transport/transport.h +++ b/include/transport/transport.h @@ -82,10 +82,25 @@ namespace Transport { /// \return Jabber ID of this transport Swift::JID &getJID() { return m_jid; } - boost::signal onConnectionError; + /// This signal is emitted when server disconnects the transport because of some error. + /// \param error disconnection error + boost::signal onConnectionError; + + /// This signal is emitted when transport successfully connects the server. boost::signal onConnected; - boost::signal onXMLOut; - boost::signal onXMLIn; + + /// This signal is emitted when XML stanza is sent to server. + /// \param xml xml stanza + boost::signal onXMLOut; + + /// This signal is emitted when XML stanza is received from server. + /// \param xml xml stanza + boost::signal onXMLIn; + + /// This signal is emitted when presence from XMPP user (for example "user@domain.tld") + /// is received. It's emitted only for presences addressed to transport itself + /// (for example to="j2j.domain.tld"). + /// \param presence presence data boost::signal onUserPresenceReceived; private: diff --git a/src/sqlite3backend.cpp b/src/sqlite3backend.cpp index 8682f21e..cb42cd19 100644 --- a/src/sqlite3backend.cpp +++ b/src/sqlite3backend.cpp @@ -131,7 +131,7 @@ bool SQLite3Backend::getBuddies(long id, std::list &roster) { return true; } -void SQLite3Backend::removeUser(long id) { +bool SQLite3Backend::removeUser(long id) { }