dlib C++ Library - bridge_abstract.h

// Copyright (C) 2011 Davis E. King (davis@dlib.net)
// License: Boost Software License See LICENSE.txt for the full license.
#undef DLIB_BRIDGe_ABSTRACT_
#ifdef DLIB_BRIDGe_ABSTRACT_
#include <string>
#include "../pipe/pipe_kernel_abstract.h"
namespace dlib
{
// ---------------------------------------------------------------------------------------- 
 struct connect_to_ip_and_port
 {
 connect_to_ip_and_port (
 const std::string& ip,
 unsigned short port
 );
 /*!
 requires
 - is_ip_address(ip) == true
 - port != 0
 ensures
 - this object will represent a request to make a TCP connection
 to the given IP address and port number.
 !*/
 };
 connect_to_ip_and_port connect_to (
 const network_address& addr
 );
 /*!
 requires
 - addr.port != 0
 ensures
 - converts the given network_address object into a connect_to_ip_and_port
 object.
 !*/
 struct listen_on_port
 {
 listen_on_port(
 unsigned short port
 );
 /*!
 requires
 - port != 0
 ensures
 - this object will represent a request to listen on the given
 port number for incoming TCP connections.
 !*/
 };
 template <
 typename pipe_type
 >
 bridge_transmit_decoration<pipe_type> transmit ( 
 pipe_type& p
 ); 
 /*!
 requires
 - pipe_type is some kind of dlib::pipe object
 - the objects in the pipe must be serializable
 ensures
 - Adds a type decoration to the given pipe, marking it as a transmit pipe, and 
 then returns it. 
 !*/
 template <
 typename pipe_type
 >
 bridge_receive_decoration<pipe_type> receive ( 
 pipe_type& p
 );
 /*!
 requires
 - pipe_type is some kind of dlib::pipe object
 - the objects in the pipe must be serializable
 ensures
 - Adds a type decoration to the given pipe, marking it as a receive pipe, and 
 then returns it. 
 !*/
// ----------------------------------------------------------------------------------------
 struct bridge_status
 {
 /*!
 WHAT THIS OBJECT REPRESENTS
 This simple struct represents the state of a bridge object. A
 bridge is either connected or not. If it is connected then it
 is connected to a foreign host with an IP address and port number
 as indicated by this object.
 !*/
 
 bridge_status(
 ); 
 /*!
 ensures
 - #is_connected == false
 - #foreign_port == 0
 - #foreign_ip == ""
 !*/
 bool is_connected;
 unsigned short foreign_port;
 std::string foreign_ip;
 };
// ---------------------------------------------------------------------------------------- 
 class bridge : noncopyable
 {
 /*!
 WHAT THIS OBJECT REPRESENTS
 This object is a tool for bridging a dlib::pipe object between
 two network connected applications. 
 Note also that this object contains a dlib::logger object
 which will log various events taking place inside a bridge.
 If you want to see these log messages then enable the logger
 named "dlib.bridge".
 
 BRIDGE PROTOCOL DETAILS
 The bridge object creates a single TCP connection between
 two applications. Whenever it sends an object from a pipe
 over a TCP connection it sends a byte with the value 1 followed 
 immediately by the serialized copy of the object from the pipe. 
 The serialization is performed by calling the global serialize()
 function. 
 Additionally, a bridge object will periodically send bytes with
 a value of 0 to ensure the TCP connection remains alive. These
 are just read and ignored. 
 !*/
 public:
 bridge (
 );
 /*!
 ensures
 - this object is properly initialized
 - #get_bridge_status().is_connected == false
 !*/
 template <typename T, typename U, typename V>
 bridge (
 T network_parameters,
 U pipe1,
 V pipe2 
 ); 
 /*!
 requires
 - T is of type connect_to_ip_and_port or listen_on_port
 - U and V are of type bridge_transmit_decoration or bridge_receive_decoration,
 however, U and V must be of different types (i.e. one is a receive type and 
 another a transmit type).
 ensures
 - this object is properly initialized
 - performs: reconfigure(network_parameters, pipe1, pipe2)
 (i.e. using this constructor is identical to using the default constructor 
 and then calling reconfigure())
 !*/
 template <typename T, typename U>
 bridge (
 T network_parameters,
 U pipe 
 ); 
 /*!
 requires
 - T is of type connect_to_ip_and_port or listen_on_port
 - U is of type bridge_transmit_decoration or bridge_receive_decoration.
 ensures
 - this object is properly initialized
 - performs: reconfigure(network_parameters, pipe)
 (i.e. using this constructor is identical to using the default constructor 
 and then calling reconfigure())
 !*/
 ~bridge (
 );
 /*!
 ensures
 - blocks until all resources associated with this object have been destroyed.
 !*/
 void clear (
 );
 /*!
 ensures
 - returns this object to its default constructed state. That is, it will
 be inactive, neither maintaining a connection nor attempting to acquire one.
 - Any active connections or listening sockets will be closed.
 !*/
 bridge_status get_bridge_status (
 ) const;
 /*!
 ensures
 - returns the current status of this bridge object. In particular, returns 
 an object BS such that:
 - BS.is_connected == true if and only if the bridge has an active TCP 
 connection to another computer.
 - if (BS.is_connected) then
 - BS.foreign_ip == the IP address of the remote host we are connected to.
 - BS.foreign_port == the port number on the remote host we are connected to.
 - else if (the bridge has previously been connected to a remote host but hasn't been 
 reconfigured or cleared since) then
 - BS.foreign_ip == the IP address of the remote host we were connected to.
 - BS.foreign_port == the port number on the remote host we were connected to.
 - else
 - BS.foreign_ip == ""
 - BS.foreign_port == 0
 !*/
 template < typename T, typename R >
 void reconfigure (
 listen_on_port network_parameters,
 bridge_transmit_decoration<T> transmit_pipe,
 bridge_receive_decoration<R> receive_pipe
 ); 
 /*!
 ensures
 - This object will begin listening on the port specified by network_parameters
 for incoming TCP connections. Any previous bridge state is cleared out.
 - Onces a connection is established we will:
 - Stop accepting new connections.
 - Begin dequeuing objects from the transmit pipe and serializing them over 
 the TCP connection.
 - Begin deserializing objects from the TCP connection and enqueueing them 
 onto the receive pipe.
 - if (the current TCP connection is lost) then 
 - This object goes back to listening for a new connection.
 - if (the receive pipe can contain bridge_status objects) then
 - Whenever the bridge's status changes the updated bridge_status will be
 enqueued onto the receive pipe unless the change was a TCP disconnect 
 resulting from a user calling reconfigure(), clear(), or destructing this 
 bridge. The status contents are defined by get_bridge_status().
 throws
 - socket_error
 This exception is thrown if we are unable to open the listening socket.
 !*/
 template < typename T, typename R >
 void reconfigure (
 listen_on_port network_parameters,
 bridge_receive_decoration<R> receive_pipe,
 bridge_transmit_decoration<T> transmit_pipe
 ); 
 /*!
 ensures
 - performs reconfigure(network_parameters, transmit_pipe, receive_pipe)
 !*/
 template < typename T >
 void reconfigure (
 listen_on_port network_parameters,
 bridge_transmit_decoration<T> transmit_pipe
 );
 /*!
 ensures
 - This function is identical to the above two reconfigure() functions 
 except that there is no receive pipe.
 !*/
 template < typename R >
 void reconfigure (
 listen_on_port network_parameters,
 bridge_receive_decoration<R> receive_pipe
 );
 /*!
 ensures
 - This function is identical to the above three reconfigure() functions 
 except that there is no transmit pipe.
 !*/
 template <typename T, typename R>
 void reconfigure (
 connect_to_ip_and_port network_parameters,
 bridge_transmit_decoration<T> transmit_pipe,
 bridge_receive_decoration<R> receive_pipe
 ); 
 /*!
 ensures
 - This object will begin making TCP connection attempts to the IP address and port 
 specified by network_parameters. Any previous bridge state is cleared out.
 - Onces a connection is established we will:
 - Stop attempting new connections.
 - Begin dequeuing objects from the transmit pipe and serializing them over 
 the TCP connection.
 - Begin deserializing objects from the TCP connection and enqueueing them 
 onto the receive pipe.
 - if (the current TCP connection is lost) then 
 - This object goes back to attempting to make a TCP connection with the
 IP address and port specified by network_parameters.
 - if (the receive pipe can contain bridge_status objects) then
 - Whenever the bridge's status changes the updated bridge_status will be
 enqueued onto the receive pipe unless the change was a TCP disconnect 
 resulting from a user calling reconfigure(), clear(), or destructing this 
 bridge. The status contents are defined by get_bridge_status().
 !*/
 template <typename T, typename R>
 void reconfigure (
 connect_to_ip_and_port network_parameters,
 bridge_receive_decoration<R> receive_pipe,
 bridge_transmit_decoration<T> transmit_pipe
 ); 
 /*!
 ensures
 - performs reconfigure(network_parameters, transmit_pipe, receive_pipe)
 !*/
 template <typename T>
 void reconfigure (
 connect_to_ip_and_port network_parameters,
 bridge_transmit_decoration<T> transmit_pipe
 );
 /*!
 ensures
 - This function is identical to the above two reconfigure() functions 
 except that there is no receive pipe.
 !*/
 template <typename R>
 void reconfigure (
 connect_to_ip_and_port network_parameters,
 bridge_receive_decoration<R> receive_pipe
 );
 /*!
 ensures
 - This function is identical to the above three reconfigure() functions 
 except that there is no transmit pipe.
 !*/
 };
// ---------------------------------------------------------------------------------------- 
}
#endif // DLIB_BRIDGe_ABSTRACT_