From 487afb796c9547de4353c503939b6666f8e0877d Mon Sep 17 00:00:00 2001 From: Gerd v. Egidy Date: Wed, 17 Sep 2008 14:29:26 +0000 Subject: [PATCH] libt2n: (gerd) some documentation improvement as preparation for release --- src/command_client.cpp | 27 +++++++++++++++++++++++++-- src/command_server.cpp | 1 + src/connection.cpp | 1 + src/server.cpp | 18 +++++++++++++++--- src/socket_client.cpp | 3 +++ src/socket_wrapper.cpp | 5 +++++ 6 files changed, 50 insertions(+), 5 deletions(-) diff --git a/src/command_client.cpp b/src/command_client.cpp index 63ff539..52ca0f1 100644 --- a/src/command_client.cpp +++ b/src/command_client.cpp @@ -71,7 +71,6 @@ command_client::command_client(client_connection* _c, long long _command_timeout } /** @brief replace the connection currently in use with a new one - @param _c pointer to the new connection @note the old connection must still be valid when this method is called, @@ -99,6 +98,12 @@ void command_client::replace_connection(client_connection* _c) read_hello(); } +/** @brief return a complete packet + @param usec_timeout maximum microseconds to wait until the packet is complete + @retval packet data as std::string + + @note throws a t2n_transfer_error if the timeout is exceeded +*/ std::string command_client::read_packet(const long long &usec_timeout) { string resultpacket; @@ -113,6 +118,10 @@ std::string command_client::read_packet(const long long &usec_timeout) return resultpacket; } +/** @brief read and check the hello message at the beginning of a connection + + @note throws exceptions if something went wrong +*/ void command_client::read_hello() { string resultpacket; @@ -133,7 +142,14 @@ void command_client::read_hello() throw t2n_version_mismatch("illegal hello received (incomplete): "+resultpacket); } -bool command_client::check_hello(const string& hellostr) +/** @brief check if a hello message is valid + @param hellostr std::string with the message to check + @retval true if the hello is good and complete + + @note you can check incomplete hellos. you will get a false return value + but no exception. throws exceptions as soon as something is wrong. +*/ +bool command_client::check_hello(const std::string& hellostr) { istringstream hello(hellostr); @@ -208,6 +224,13 @@ bool command_client::check_hello(const string& hellostr) return true; } +/** @brief send a command to the server and store the result + @param cmd pointer to a command-object + @param[out] res result container to store the result in + + @note you can check incomplete hellos. you will get a false return value + but no exception. throws exceptions as soon as something is wrong. +*/ void command_client::send_command(command* cmd, result_container &res) { ostringstream ofs; diff --git a/src/command_server.cpp b/src/command_server.cpp index 6146981..035c334 100644 --- a/src/command_server.cpp +++ b/src/command_server.cpp @@ -50,6 +50,7 @@ command_server::command_server(server& _s) s.add_callback(new_connection,bind(&command_server::send_hello, boost::ref(*this), _1)); } +/// send a hello message to a new connection void command_server::send_hello(unsigned int conn_id) { server_connection* sc=s.get_connection(conn_id); diff --git a/src/connection.cpp b/src/connection.cpp index 30a0b19..c9283fe 100644 --- a/src/connection.cpp +++ b/src/connection.cpp @@ -46,6 +46,7 @@ void connection::close() } } +/// get the number of bytes being available as next complete packet connection::packet_size_indicator connection::bytes_available() { // no size information -> no packet diff --git a/src/server.cpp b/src/server.cpp index 65ce62f..30bf7d3 100644 --- a/src/server.cpp +++ b/src/server.cpp @@ -68,6 +68,11 @@ void server_connection::reset_timeout() last_action_time=time(NULL); } +/** @brief add a callback to one connection + + @param event event the function will be called at + @param func functor (see boost::function) that will be called +*/ void server_connection::add_callback(callback_event_type event, const boost::function& func) { if (event == new_connection) @@ -94,10 +99,10 @@ server::~server() /** @brief add a callback @param event event the function will be called at - @param func functor (see boost function) that will be called + @param func functor (see boost::function) that will be called @note use boost::bind to bind to member functions like this: - s.add_callback(new_connection,bind(&my_class::func_to_call_back, boost::ref(*this), _1)); + s.add_callback(new_connection,boost::bind(&my_class::func_to_call_back, boost::ref(*this), _1)); */ void server::add_callback(callback_event_type event, const boost::function& func) { @@ -108,10 +113,16 @@ void server::add_callback(callback_event_type event, const boost::function::iterator ie=connections.end(); for(std::map::iterator i=connections.begin(); i != ie; i++) - i->second->add_callback(event,bind(func, i->first)); + i->second->add_callback(event,boost::bind(func, i->first)); } } + +/** @brief an event occured, call all server-side callbacks + + @param event event that occured + @param conn_id connection-id parameter that will be given to the callback-function +*/ void server::do_callbacks(callback_event_type event, unsigned int conn_id) { std::list >::iterator i,ie=callbacks[event].end(); @@ -119,6 +130,7 @@ void server::do_callbacks(callback_event_type event, unsigned int conn_id) (*i)(conn_id); } +/// add a new connection to the server int server::add_connection(server_connection* newconn) { unsigned int cid=next_id++; diff --git a/src/socket_client.cpp b/src/socket_client.cpp index 6b5b481..a26b004 100644 --- a/src/socket_client.cpp +++ b/src/socket_client.cpp @@ -101,6 +101,7 @@ socket_client_connection::socket_client_connection(const std::string& _path, do_callbacks(new_connection); } +/// establish a connection via tcp void socket_client_connection::tcp_connect(int max_retries) { struct sockaddr_in sock_addr; @@ -140,6 +141,7 @@ void socket_client_connection::tcp_connect(int max_retries) } } +/// establish a connection via unix-socket void socket_client_connection::unix_connect(int max_retries) { struct sockaddr_un unix_addr; @@ -168,6 +170,7 @@ void socket_client_connection::unix_connect(int max_retries) } } +/// execute a connect on a prepared socket (tcp or unix) respecting timeouts void socket_client_connection::connect_with_timeout(struct sockaddr *sock_addr,unsigned int sockaddr_size) { set_socket_options(sock); diff --git a/src/socket_wrapper.cpp b/src/socket_wrapper.cpp index ac88144..313f6ca 100644 --- a/src/socket_wrapper.cpp +++ b/src/socket_wrapper.cpp @@ -25,6 +25,7 @@ namespace libt2n { +/// return active connection, create new tcp or unix connection if not existing client_connection* BasicSocketWrapper::get_connection(void) { if (c.get() == NULL) @@ -40,6 +41,8 @@ client_connection* BasicSocketWrapper::get_connection(void) return c.get(); } +/// try to reconnect max_retries time if we encounter a t2n_communication_error +/// during execution of the command bool ReconnectSocketWrapper::handle(command_client* stubBase, boost::function< void() > f) { int tries=0; @@ -82,6 +85,7 @@ bool ReconnectSocketWrapper::handle(command_client* stubBase, boost::function< v return false; } +/// return active connection, return a dummy-connection if we can't establish one client_connection* ReconnectIgnoreFailureSocketWrapper::get_connection(void) { client_connection* tmp=BasicSocketWrapper::get_connection(); @@ -97,6 +101,7 @@ client_connection* ReconnectIgnoreFailureSocketWrapper::get_connection(void) return tmp; } +/// try to execute the command, may bool ReconnectIgnoreFailureSocketWrapper::handle(command_client* stubBase, boost::function< void() > f) { if (!connection_established()) -- 1.7.1