// 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_