All examples assume access to the namespace HTTPTunnel, eg; with:

   using namespace HTTPTunnel;


##############################################################################
##############################################################################
## HTTPTunneler class.
##############################################################################
##############################################################################


==============================================================================
==============================================================================
== HTTPTunneler instance handling.
==
== All the methods in this section provide top-level library functionality and
== HTTPTunneler instance handling.
==============================================================================
==============================================================================


******************************************************************************
* Method name: Get
* Description: Get HTTPTunneler singleton instance.
*
* Prototype:
* static HTTPTunneler* Get(void) throw(TunnelError)
******************************************************************************

This method returns a reference to a HTTPTunneler object which can then be
used to control the HTTP tunneling library. Calling this method for the first
time also has the effect of initialising the HTTP tunneling library.

The HTTPTunneler object pointer returned by this method remains owned by the
library and should not be deleted by the calling code. To free up the
HTTPTunneler reference and to shut the HTTP tunneling library down you should
instead use the HTTPTunneler::Release() method.

Example usage:

   try {
      HTTPTunneler* httptunneler = HTTPTunneler::Get();
   }
   catch(TunnelError& e) {}


******************************************************************************
* Method name: Release
* Description: Release HTTPTunneler singleton instance.
*
* Prototype:
* static void Release(void) throw(TunnelError)
******************************************************************************

This method releases the HTTPTunneler object reference obtained by an earlier
call to HTTPTunneler::Get(). Calling this method also has the effect of
shutting down the HTTP tunneling library.

Any remaining references to HTTPTunneler objects will become invalid after
calling this method and must nolonger be used.

Example usage:

   try {
      HTTPTunneler::Release();
   }
   catch(TunnelError& e) {}


******************************************************************************
* Method name: SetName
* Description: Set name to use when logging.
*
* Prototype:
* static void SetName(std::string name)
******************************************************************************

This method sets the name of the application to be used within log messages
generated by the HTTP tunneling library.

Example usage:

   HTTPTunneler::SetName("My_Application");


==============================================================================
==============================================================================
== HTTPTunneler initialisation & shutdown.
==
== The methods in this section control the initialisation and shutdown of the
== core tunneling engine, and by association therefore the starting and
== stopping of any configured HTTP tunnels.
==============================================================================
==============================================================================


******************************************************************************
* Method name: Start
* Description: Start the HTTP tunneling engine.
*
* Prototype:
* void Start(void) throw(TunnelError)
******************************************************************************

This method kicks off the core HTTP tunneling engine. Any tunnels configured
before calling this method will be started at this point. Any tunnels
configured after calling this method will be started immediately.

Example usage:

   try {
      httptunneler->Start();
   }
   catch(TunnelError& e) {}


******************************************************************************
* Method name: Stop
* Description: Stop the HTTP tunneling engine.
*
* Prototype:
* void Stop(void) throw(TunnelError)
******************************************************************************

This method stops the core HTTP tunneling engine. Any tunnels running before
calling this method will be immediately stopped at this point.

NOTE: Any active tunnels stopped by calling Stop() will not be cleanly shutdown
first. If you want to ensure a tunnel is cleanly shutdown before stopping the
core HTTP tunneling engine you must wait for the tunneler owning that tunnel
to become inactive, for example by using the HTTPTunneler::IsTunnelerActive()
method described below.

Example usage:

   try {
      httptunneler->Stop();
   }
   catch(TunnelError& e) {}


==============================================================================
==============================================================================
== Configure the HTTP tunneling.
==
== These methods allow you to configure the core behaviour of the HTTP
== tunneling engine.
==
== There are methods for configuring global options, creating client and
== server HTTP tunnelers, and destroying HTTP tunnelers.
==============================================================================
==============================================================================


******************************************************************************
* Method name: ConfigureFromFile
* Description: Parse and apply configuration from the named file.
*
* Prototype:
* void ConfigureFromFile(const char* fileName) throw(TunnelError)
******************************************************************************

This method allows you to specify the entire configuration for the HTTP
tunneling engine using a single file.

For a description of the format of the configuration file, please refer to the
CONFIGURATION text file in the same documentation directory as this API file.

Example usage:

   try {
      httptunneler->ConfigureFromFile("path_to/my_config_file.cfg");
   }
   catch(TunnelError& e) {}


******************************************************************************
* Method name: RegenerateCfgFile
* Description: Create the named file and fill it with the default
*              configuration settings.
*
* Prototype:
* void RegenerateCfgFile(const char* fileName) throw(TunnelError)
******************************************************************************

This method creates a default initial configuration file. This default file
will contain just enough configuration to allow the HTTP tunneling engine to
start, but will not define any actual tunnelers.

Example usage:

   try {
      httptunneler->RegenerateCfgFile("path_to/default_config_file.cfg");
   }
   catch(TunnelError& e) {}


******************************************************************************
* Method name: ConfigureGlobal
* Description: Parse and apply the global configuration settings specified.
*
* Prototype:
* void ConfigureGlobal(const GlobalConfigBlob& blob) throw(TunnelError)
******************************************************************************

This method applies the global configuration settings defined by the given
'GlobalConfigBlob blob' argument. Only global settings will be configured by
this method; i.e. those settings contained within the [GLOBAL] section of a
configuration file.

The GlobalConfigBlob that encapsulates the configuration settings is passed
the global options to use into its constructor, and these options are then
parsed and applied by the ConfigureGlobal method. Currntly the only global
configuration option supported by the GlobalConfigBlob is the debug level to
use.

Example usage:

   try {
      GlobalConfigBlob globalBlob(VERBOSE);
      httptunneler->ConfigureGlobal(globalBlob);
   }
   catch(TunnelError& e) {}


******************************************************************************
* Method name: ConfigureClientTunneler
* Description: Parse and apply the client tunneler configuration settings
*              specified.
*
* Prototype:
* TunnelerID ConfigureClientTunneler(const ClientConfigBlob& blob)
*    throw(TunnelError)
******************************************************************************

This method applies the client tunneler configuration settings defined by the
given 'ClientConfigBlob blob' argument. Only client tunneler settings will be
configured by this method; i.e. those settings contained within a [CLIENT]
section of a configuration file.

The ClientConfigBlob that encapsulates the configuration settings is passed
the basic client options to use into its constructor, and any further options
can be set/changed by using additional member functions. These options are
then parsed and applied by the ConfigureClientTunneler method.

If the client tunneler configuration is successfully parsed and a resulting
client tunneler is created and launched, this method will return a TunnelerID
object which may be used to identify that tunneler in any further calls to
the HTTP tunneling library.

Example usage:

   try {
      ClientConfigBlob clientBlob(Enums::TCP, false, "localhost", 1080,
         "192.168.1.10", 80);
      TunnelerID cliID = httptunneler->ConfigureClientTunneler(clientBlob);
   }
   catch(TunnelError& e) {}


******************************************************************************
* Method name: ConfigureServerTunneler
* Description: Parse and apply the server tunneler configuration settings
*              specified.
*
* Prototype:
* TunnelerID ConfigureServerTunneler(const ServerConfigBlob& blob)
*    throw(TunnelError)
******************************************************************************

This method applies the server tunneler configuration settings defined by the
given 'ServerConfigBlob blob' argument. Only server tunneler settings will be
configured by this method; i.e. those settings contained within a [SERVER]
section of a configuration file.

The ServerConfigBlob that encapsulates the configuration settings is passed
the basic server options to use into its constructor, and any further options
can be set/changed by using additional member functions. These options are
then parsed and applied by the ConfigureServerTunneler method.

If the server tunneler configuration is successfully parsed and a resulting
server tunneler is created and launched, this method will return a TunnelerID
object which may be used to identify that tunneler in any further calls to
the HTTP tunneling library.

Example usage:

   try {
      ServerConfigBlob serverBlob("", 80, false);
		TunnelerID svrID = httptunneler->ConfigureServerTunneler(serverBlob);
   }
   catch(TunnelError& e) {}


******************************************************************************
* Method name: ShutdownTunneler
* Description: Cleanly shutdown the specified tunneler.
*
* Prototype:
* void ShutdownTunneler(const TunnelerID& tid) throw(TunnelError)
******************************************************************************

This method initiates a controlled shutdown of the specified currently active
tunneler (can be either a client or server tunneler). This method does not
destroy the tunneler or free up any resources held by it, that must be done
separately by calling the 'RemoveTunneler' method described below.

The TunnelerID parameter passed to this method is the TunnelerID as returned
by a previous call to ConfigureClientTunneler or ConfigureServerTunneler.

Example usage:

   try {
      httptunneler->ShutdownTunneler(cliID);
   }
   catch(TunnelError& e) {}


******************************************************************************
* Method name: RemoveTunneler
* Description: Shutdown and remove the specified tunneler.
*
* Prototype:
* void RemoveTunneler(const TunnelerID& tid) throw(TunnelError)
******************************************************************************

This method shuts down the specified currently active tunneler (can be either a
client or server tunneler) and frees any resources held by that tunneler.

Unlike with the 'ShutdownTunneler' method described above, the tunneler is not
shutdown cleanly by this method, it is instead simply killed immediately and
destroyed. Any still active tunnels controlled by the tunneler will therefore
be aborted without first notifying the other end of the tunnel.

The TunnelerID parameter passed to this method is the TunnelerID as returned
by a previous call to ConfigureClientTunneler or ConfigureServerTunneler.

Example usage:

   try {
      httptunneler->RemoveTunneler(cliID);
   }
   catch(TunnelError& e) {}


==============================================================================
==============================================================================
== Query the HTTP tunneling state.
==
== These methods allow you to query the state of things within the HTTP
== tunneling engine.
==============================================================================
==============================================================================


******************************************************************************
* Method name: IsTunnelerActive
* Description: Check if a specified tunneler is carrying any active tunnels.
*
* Prototype:
* bool IsTunnelerActive(const TunnelerID& tid) throw(TunnelError)
******************************************************************************

This method returns true if the specified tunneler is currently carrying any
active tunnels and false otherwise. This can be used to poll a tunneler and
wait until all tunnels have cleanly shutdown before destroying the tunneler.

Example usage:

   try {
		while(httptunneler->IsTunnelerActive(cliID))
         sleep(1);
   }
   catch(TunnelError& e) {}


==============================================================================
==============================================================================
== Socket based HTTP tunneling.
==
== These methods provide a simple interface for carrying Berkely sockets over
== a HTTP tunnel. Using these methods you can include HTTP tunneling within
== any socket based application.
==
== There are methods for creating client HTTP tunnel sockets and for handling
== HTTP tunnel socket connections at a server.
==============================================================================
==============================================================================


******************************************************************************
* Method name: LaunchServerSocket
* Description: Parse and apply the server socket tunneler configuration
*              settings specified.
*
* Prototype:
* ServerSockTunHandle LaunchServerSocket(const SockTunServerConfigBlob& blob)
*    throw(TunnelError)
******************************************************************************

This method applies the server socket tunneler configuration settings defined
by the given 'SockTunServerConfigBlob blob' argument.

The SockTunServerConfigBlob that encapsulates the configuration settings is
passed the basic server socket options to use into its constructor, and any
further options can be set/changed by using additional member functions. These
options are then parsed and applied by the LaunchServerSocket method.

If the server socket configuration is successfully parsed and a resulting
server socket tunneler is created and launched, this method will return a
'ServerSockTunHandle' object which may be queried to obtain further details
about the created server socket tunneler. For example; the 'getTunID' method
returns a TunnelerID that can be used to identify that tunneler in any further
calls to the HTTP tunneling library.

When a new client connection arrives at the server, the HTTP tunneling library
will notify the creater of the server socket tunneler via the callback
specified as part of the configuration. The socket created to communicate with
the client is passed to that callback, and from that point on is considered to
be owned by the user of the library.

Example usage:

   try {
      SockTunServerConfigBlob svrBlob("192.168.1.10", 80, false,
         new GlobalSockTunCallback(&NewClientConnection));
      ServerSockTunHandle svrHandle = httptunneler->LaunchServerSocket(svrBlob);
      TunnelerID svrID = svrHandle.getTunID();
   }
   catch(TunnelError& e) {}


******************************************************************************
* Method name: LaunchClientSocket
* Description: Parse and apply the client socket tunneler configuration
*              settings specified.
*
* Prototype:
* ClientSockTunHandle LaunchClientSocket(const SockTunClientConfigBlob& blob)
*    throw(TunnelError)
******************************************************************************

This method applies the client socket tunneler configuration settings defined
by the given 'SockTunClientConfigBlob blob' argument.

The SockTunClientConfigBlob that encapsulates the configuration settings is
passed the basic client socket options to use into its constructor, and any
further options can be set/changed by using additional member functions. These
options are then parsed and applied by the LaunchClientSocket method.

If the client socket configuration is successfully parsed and a resulting
client socket tunneler is created and launched, this method will return a
'ClientSockTunHandle' object which may be queried to obtain further details
about the created client socket tunneler. For example; the 'getTunID' method
returns a TunnelerID that can be used to identify that tunneler in any further
calls to the HTTP tunneling library.

The ClientSockTunHandle 'getSock' method returns a reference for a connected
socket which may be used to read and write tunneled data. This client side
socket reference always remains owned by the client socket tunneler that
created it.

Example usage:

   try {
      SockTunClientConfigBlob cliBlob(Enums::TCP, false, "192.168.1.10", 80);
      ClientSockTunHandle cliHandle = httptunneler->LaunchClientSocket(cliBlob);
      TunnelerID cliID = cliHandle.getTunID();
      Sock* connectedSock = cliHandle.getSock();
   }
   catch(TunnelError& e) {}


==============================================================================
==============================================================================
== HTTP tunneling client and server examples.
==============================================================================
==============================================================================


A pair of simple example client and server HTTP tunneling test programs are
provided in the files testcli.cc and testsvr.cc

These example programs can be built by going into the source directory and
issuing the build command:

   make test

This should leave you with a pair of executable command line applications
called testcli and testsvr.

The test client attempts to establish a HTTP tunnel to a server listening at
localhost:8080 and then carries a TCP socket over that tunnel. Any text entered
on the console at the client is sent over the tunnel to the server, and any
text received from the server is echoed on the console at the client. The
client shuts down and terminates when it reads EOF (^D) on its console.

The test server creates a HTTP tunnel server listening at localhost:8080 and
registers a callback with the HTTP tunneling library to notify it whenever a
HTTP tunnel client connects to it. Any text entered on the console at the
server is sent over the tunnels to all currently connected clients, and any
text received from a client is echoed on the console at the server. The server
shuts down and terminates when it reads EOF (^D) on its console.


