diff options
author | 2016-10-07 14:13:19 +0200 | |
---|---|---|
committer | 2016-10-07 14:13:19 +0200 | |
commit | ff01b716711b97c2fcaa709ea97f7650f106aa10 (patch) | |
tree | 50dd4d687f38f50c4e136af030c02c267c769f3a /3rdparty/asio/src/examples/cpp03/tutorial/daytime_dox.txt | |
parent | 2a138159c30457aecd9e9679be5159704db0f954 (diff) |
Added ASIO networking library (nw)
Diffstat (limited to '3rdparty/asio/src/examples/cpp03/tutorial/daytime_dox.txt')
-rw-r--r-- | 3rdparty/asio/src/examples/cpp03/tutorial/daytime_dox.txt | 502 |
1 files changed, 502 insertions, 0 deletions
diff --git a/3rdparty/asio/src/examples/cpp03/tutorial/daytime_dox.txt b/3rdparty/asio/src/examples/cpp03/tutorial/daytime_dox.txt new file mode 100644 index 00000000000..1bf591a43a8 --- /dev/null +++ b/3rdparty/asio/src/examples/cpp03/tutorial/daytime_dox.txt @@ -0,0 +1,502 @@ +// +// Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com) +// +// Distributed under the Boost Software License, Version 1.0. (See accompanying +// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +// + +/** +\page tutdaytime1 Daytime.1 - A synchronous TCP daytime client + +This tutorial program shows how to use asio to implement a client application +with TCP. + +\dontinclude daytime1/client.cpp +\skip #include + +We start by including the necessary header files. + +\until asio.hpp + +The purpose of this application is to access a daytime service, +so we need the user to specify the server. + +\until } + +All programs that use asio need to have at least one asio::io_service +object. + +\until asio::io_service + +We need to turn the server name that was specified as a parameter to the +application, into a TCP endpoint. To do this we use an +asio::ip::tcp::resolver object. + +\until tcp::resolver + +A resolver takes a query object and turns it into a list of endpoints. We +construct a query using the name of the server, specified in <tt>argv[1]</tt>, +and the name of the service, in this case <tt>"daytime"</tt>. + +\until tcp::resolver::query + +The list of endpoints is returned using an iterator of type +asio::ip::tcp::resolver::iterator. (Note that a default constructed +asio::ip::tcp::resolver::iterator object can be used as an end iterator.) + +\until tcp::resolver::iterator + +Now we create and connect the socket. The list of endpoints obtained above may +contain both IPv4 and IPv6 endpoints, so we need to try each of them until we +find one that works. This keeps the client program independent of a specific IP +version. The asio::connect() function does this for us automatically. + +\until asio::connect + +The connection is open. All we need to do now is read the response from the +daytime service. + +We use a <tt>boost::array</tt> to hold the received data. The asio::buffer() +function automatically determines the size of the array to help prevent buffer +overruns. Instead of a <tt>boost::array</tt>, we could have used a <tt>char +[]</tt> or <tt>std::vector</tt>. + +\until read_some + +When the server closes the connection, the asio::ip::tcp::socket::read_some() +function will exit with the asio::error::eof error, which is how we know to +exit the loop. + +\until } + +Finally, handle any exceptions that may have been thrown. + +\until } +\until } + +See the \ref tutdaytime1src "full source listing" \n +Return to the \ref index "tutorial index" \n +Next: \ref tutdaytime2 + +*/ + +/** +\page tutdaytime1src Source listing for Daytime.1 +\include daytime1/client.cpp +Return to \ref tutdaytime1 +*/ + +/** +\page tutdaytime2 Daytime.2 - A synchronous TCP daytime server + +This tutorial program shows how to use asio to implement a server application +with TCP. + +\dontinclude daytime2/server.cpp +\skip #include + +\until using + +We define the function <tt>make_daytime_string()</tt> to create the string to +be sent back to the client. This function will be reused in all of our daytime +server applications. + +\until asio::io_service + +A asio::ip::tcp::acceptor object needs to be created to listen +for new connections. It is initialised to listen on TCP port 13, for IP version 4. + +\until tcp::acceptor + +This is an iterative server, which means that it will handle one +connection at a time. Create a socket that will represent the connection to the +client, and then wait for a connection. + +\until acceptor.accept + +A client is accessing our service. Determine the current time +and transfer this information to the client. + +\until } +\until } + +Finally, handle any exceptions. + +\until } +\until } + +See the \ref tutdaytime2src "full source listing" \n +Return to the \ref index "tutorial index" \n +Previous: \ref tutdaytime1 \n +Next: \ref tutdaytime3 + +*/ + +/** +\page tutdaytime2src Source listing for Daytime.2 +\include daytime2/server.cpp +Return to \ref tutdaytime2 +*/ + +/** +\page tutdaytime3 Daytime.3 - An asynchronous TCP daytime server + +\section tutdaytime3funcmain The main() function + +\dontinclude daytime3/server.cpp +\skip int main() +\until try +\until { + +We need to create a server object to accept incoming client connections. The +asio::io_service object provides I/O services, such as sockets, that the +server object will use. + +\until tcp_server + +Run the asio::io_service object so that it will perform asynchronous operations +on your behalf. + +\until return 0; +\until } + +\section tutdaytime3classtcp_server The tcp_server class + +\dontinclude daytime3/server.cpp +\skip class tcp_server +\until public: + +The constructor initialises an acceptor to listen on TCP port 13. + +\until private: + +The function <tt>start_accept()</tt> creates a socket and initiates an +asynchronous accept operation to wait for a new connection. + +\until } + +The function <tt>handle_accept()</tt> is called when the asynchronous accept +operation initiated by <tt>start_accept()</tt> finishes. It services the client +request, and then calls <tt>start_accept()</tt> to initiate the next accept +operation. + +\until } +\until } + +\section tutdaytime3classtcp_connection The tcp_connection class + +We will use <tt>shared_ptr</tt> and <tt>enable_shared_from_this</tt> because we +want to keep the <tt>tcp_connection</tt> object alive as long as there is an +operation that refers to it. + +\dontinclude daytime3/server.cpp +\skip class tcp_connection +\until shared_ptr +\until } +\until } + +In the function <tt>start()</tt>, we call asio::async_write() to serve the data +to the client. Note that we are using asio::async_write(), rather than +asio::ip::tcp::socket::async_write_some(), to ensure that the entire block of +data is sent. + +\until { + +The data to be sent is stored in the class member <tt>message_</tt> as we need +to keep the data valid until the asynchronous operation is complete. + +\until message_ + +When initiating the asynchronous operation, and if using \ref boost_bind, you +must specify only the arguments that match the handler's parameter list. In +this program, both of the argument placeholders (asio::placeholders::error and +asio::placeholders::bytes_transferred) could potentially have been removed, +since they are not being used in <tt>handle_write()</tt>. + +\until placeholders::bytes_transferred + +Any further actions for this client connection are now the responsibility of +<tt>handle_write()</tt>. + +\until }; + +\section tutdaytime3remunused Removing unused handler parameters + +You may have noticed that the <tt>error</tt>, and <tt>bytes_transferred</tt> +parameters are not used in the body of the <tt>handle_write()</tt> function. If +parameters are not needed, it is possible to remove them from the function so +that it looks like: + +\code + void handle_write() + { + } +\endcode + +The asio::async_write() call used to initiate the call can then be changed to +just: + +\code + asio::async_write(socket_, asio::buffer(message_), + boost::bind(&tcp_connection::handle_write, shared_from_this())); +\endcode + +See the \ref tutdaytime3src "full source listing" \n +Return to the \ref index "tutorial index" \n +Previous: \ref tutdaytime2 \n +Next: \ref tutdaytime4 + +*/ + +/** +\page tutdaytime3src Source listing for Daytime.3 +\include daytime3/server.cpp +Return to \ref tutdaytime3 +*/ + +/** +\page tutdaytime4 Daytime.4 - A synchronous UDP daytime client + +This tutorial program shows how to use asio to implement a client application +with UDP. + +\dontinclude daytime4/client.cpp +\skip #include +\until using asio::ip::udp; + +The start of the application is essentially the same as for the TCP daytime +client. + +\until asio::io_service + +We use an asio::ip::udp::resolver object to find the correct remote endpoint to +use based on the host and service names. The query is restricted to return only +IPv4 endpoints by the asio::ip::udp::v4() argument. + +\until udp::v4 + +The asio::ip::udp::resolver::resolve() function is guaranteed to return at +least one endpoint in the list if it does not fail. This means it is safe to +dereference the return value directly. + +\until udp::endpoint + +Since UDP is datagram-oriented, we will not be using a stream socket. Create an +asio::ip::udp::socket and initiate contact with the remote endpoint. + +\until receiver_endpoint + +Now we need to be ready to accept whatever the server sends back to us. The +endpoint on our side that receives the server's response will be initialised by +asio::ip::udp::socket::receive_from(). + +\until } + +Finally, handle any exceptions that may have been thrown. + +\until } +\until } +See the \ref tutdaytime4src "full source listing" \n +Return to the \ref index "tutorial index" \n +Previous: \ref tutdaytime3 \n +Next: \ref tutdaytime5 + +*/ + +/** +\page tutdaytime4src Source listing for Daytime.4 +\include daytime4/client.cpp +Return to \ref tutdaytime4 +*/ + +/** +\page tutdaytime5 Daytime.5 - A synchronous UDP daytime server + +This tutorial program shows how to use asio to implement a server application +with UDP. + +\dontinclude daytime5/server.cpp +\skip int main() +\until asio::io_service + +Create an asio::ip::udp::socket object to receive requests on UDP port 13. + +\until udp::socket + +Wait for a client to initiate contact with us. The remote_endpoint object will +be populated by asio::ip::udp::socket::receive_from(). + +\until throw + +Determine what we are going to send back to the client. + +\until std::string message + +Send the response to the remote_endpoint. + +\until } +\until } + +Finally, handle any exceptions. + +\until } +\until } + +See the \ref tutdaytime5src "full source listing" \n +Return to the \ref index "tutorial index" \n +Previous: \ref tutdaytime4 \n +Next: \ref tutdaytime6 + +*/ + +/** +\page tutdaytime5src Source listing for Daytime.5 +\include daytime5/server.cpp +Return to \ref tutdaytime5 +*/ + +/** +\page tutdaytime6 Daytime.6 - An asynchronous UDP daytime server + +\section tutdaytime6funcmain The main() function + +\dontinclude daytime6/server.cpp +\skip int main() +\until try +\until { + +Create a server object to accept incoming client requests, and run +the asio::io_service object. + +\until return 0; +\until } + +\section tutdaytime6classudp_server The udp_server class + +\dontinclude daytime6/server.cpp +\skip class udp_server +\until public: + +The constructor initialises a socket to listen on UDP port 13. + +\until private: +\until { + +The function asio::ip::udp::socket::async_receive_from() will cause the +application to listen in the background for a new request. When such a request +is received, the asio::io_service object will invoke the +<tt>handle_receive()</tt> function with two arguments: a value of type +asio::error_code indicating whether the operation succeeded or failed, and a +<tt>size_t</tt> value <tt>bytes_transferred</tt> specifying the number of bytes +received. + +\until } + +The function <tt>handle_receive()</tt> will service the client request. + +\until { + +The <tt>error</tt> parameter contains the result of the asynchronous operation. +Since we only provide the 1-byte <tt>recv_buffer_</tt> to contain the client's +request, the asio::io_service object would return an error if the client sent +anything larger. We can ignore such an error if it comes up. + +\until { + +Determine what we are going to send. + +\until make_daytime_string() + +We now call asio::ip::udp::socket::async_send_to() to serve the data to the +client. + +\until asio::placeholders::bytes_transferred + +When initiating the asynchronous operation, and if using \ref boost_bind, you +must specify only the arguments that match the handler's parameter list. In +this program, both of the argument placeholders (asio::placeholders::error and +asio::placeholders::bytes_transferred) could potentially have been removed. + +Start listening for the next client request. + +\until start_receive + +Any further actions for this client request are now the responsibility of +<tt>handle_send()</tt>. + +\until } +\until } + +The function <tt>handle_send()</tt> is invoked after the service request has +been completed. + +\until } +\until } + +See the \ref tutdaytime6src "full source listing" \n +Return to the \ref index "tutorial index" \n +Previous: \ref tutdaytime5 \n +Next: \ref tutdaytime7 + +*/ + +/** +\page tutdaytime6src Source listing for Daytime.6 +\include daytime6/server.cpp +Return to \ref tutdaytime6 +*/ + +/** +\page tutdaytime7 Daytime.7 - A combined TCP/UDP asynchronous server + +This tutorial program shows how to combine the two asynchronous servers that we +have just written, into a single server application. + +\section tutdaytime7funcmain The main() function + +\dontinclude daytime7/server.cpp +\skip int main() +\until asio::io_service + +We will begin by creating a server object to accept a TCP client connection. + +\until tcp_server + +We also need a server object to accept a UDP client request. + +\until udp_server + +We have created two lots of work for the asio::io_service object to do. + +\until return 0; +\until } + +\section tutdaytime7classtcp The tcp_connection and tcp_server classes + +The following two classes are taken from \ref tutdaytime3 "Daytime.3". + +\dontinclude daytime7/server.cpp +\skip class tcp_connection +\until }; +\until }; + +\section tutdaytime7classudp The udp_server class + +Similarly, this next class is taken from the +\ref tutdaytime6 "previous tutorial step". + +\dontinclude daytime7/server.cpp +\skip class udp_server +\until }; + +See the \ref tutdaytime7src "full source listing" \n +Return to the \ref index "tutorial index" \n +Previous: \ref tutdaytime6 + +*/ + +/** +\page tutdaytime7src Source listing for Daytime.7 +\include daytime7/server.cpp +Return to \ref tutdaytime7 +*/ |