Indy 9 | Content | Index | Reference

TIdTunnelSlave
Hierarchy, Properties, Methods, Events, See Also, Unit: IdTunnelSlave
Implements a server that arbitrates client access using tunnel connections.

    TIdTunnelSlave = class(TIdTCPServer)

Unit
IdTunnelSlave
Description
TIdTunnelSlave is a TIdTCPServer descendant that implements a server for communicating with tunnel client connections. TIdTunnelSlave utilizes TCP connections to establish an internal link to the tunnel master server that hosts connections to service threads for the client connections.

The following diagram is a general diagram of the relationship between client connection threads, the Tunnel Slave Server, the Tunnel Master Server, and service threads used to support encapsulated tunnel connections:

      +---+       +-----+       +-----+       +---+
      | C |<=====>|     |       |     |<=====>| V |
      +---+       |     |       |     |       +---+
      +---+       |     |       |     |       +---+
      | C |<=====>|  S  |<=====>|  M  |<=====>| V |
      +---+       |     |       |     |       +---+
      +---+       |     |       |     |       +---+
      | C |<=====>|     |       |     |<=====>| V |
      +---+       +-----+       +-----+       +---+

      C: Client connection thread
      S: Tunnel Slave Server
      M: TUnnel Master Server
      V: Service Thread

TIdTunnelSlave provides event handlers that allow responses to changes in both server state and client connection state. TIdTunnelSlave also provides event handlers for data transformation and session link control of the tunnel for associated TIdTunnelMaster server.

When a TIdTunnelSlave becomes active, it initializes the Host and Port properties for the server's internal TCP connection that will acts as the encapsulated tunnel link tot he TIdTunnelMaster server. The connection to the tunnel master server is opened.

TIdTunnelSlave maintains SlaveThread to listen for data from the TIdTunnelMaster server service threads. SlaveThread is also used to authenticate the tunnel connection to the master server. If no exception is raised, then the TIdTunnelSlave server will begin to listen for client connections.

When a client requests a connection to TIdTunnelSlave, the server must indicate that AcceptConnections is allowed. When Socks4 indicates that client connection are using a Socks proxy, the server expects to read the IP address and Socks authentication information from the client connection. Socks authentication data cannot exceed 255 characters, and must be zero-terminated. The server will write a Socks response to the client connection and forward the connection request to the tunnel master server.

When a client connection executes a request on a connection to the tunnel slave server, TIdTunnelSlave will prepare encapsulated tunnel headers for the request and write the encapsulated message to the connection for the tunnel master server. The client connection will be closed if an exception is raised during execution of the request.

When a client connection request disconnect from the TIdTunnelSlave, the serve will prepare encapsulated tunnel headers for the request and send the message to the tunnel master server to allow closing of service threads for the client connection.

TIdTunnelSlave.Active
TIdTunnelSlave
Indicates if the server is accepting client connections or requests.

    property Active: Boolean;

Description
Active is a Boolean property that indicates if the server can accept new clients connections, or process requests from existing client connections.

When Active is set to True, the server will attempt to create the TIdTCPClient that acts as the tunnel link to the TIdTunnelMaster identified in MasterHost and MasterPort. An RSTunnelConnectToMasterFailed exception will be raised if the connection to the master server cannot be opened.

When the connection is created, a TSlaveThread is created and started for the server to allow authentication of the TIdTunnelSlave connection to the TIdTunnelMaster. When the connection to the master server is complete, the TIdTunnelSlave is ready to begin accepting client connections.

When Active is set to False, the server will indicate that it is neither accepting new client connections or transmitting data for existing client connections. Existing client connections are closed, and the tunnel connection to TIdTunnelMaster is closed. Finally, the TSlaveThread instance for the server is terminated prior to completion of the change in the property state.

TIdTunnelSlave.Logger
TIdTunnelSlave, See Also
Represents the activity logging component for the server.

    property Logger: TLogger;

Description
Logger is a TLogger property that represents the activity logging component for the server. Logger provides the capability to write log messages to a text files, and uses the exposed LogEvent event handler to customize the information logging action.

TIdTunnelSlave.MasterHost
TIdTunnelSlave
Specifies the Host that is the Tunnel Master server.

    property MasterHost: string;

Description
MasterHost is a String property that specifies the host name or IP address of the TIdTunnelMaster server.

MasterHost is used, with MasterPort, when creating the TCP connection that acts as the encapsulated tunnel to the master server in Create.

TIdTunnelSlave.MasterPort
TIdTunnelSlave
Specifies the port number for the Tunnel Master server.

    property MasterPort: Integer;

Description
MasterPort is an Integer property that specifies the port number for the TIdTunnelMaster server.

MasterPort is used, with MasterHost, when creating the TCP connection that acts as the encapsulated tunnel to the master server in Create.

TIdTunnelSlave.NumClients
TIdTunnelSlave
Indicates the number of client connections to the server.

    property NumClients: Integer;

Description
NumClients is a read-only Integer property that indicates the number of client connections for the TIdTunnelSlave server. NumClients is maintained by the server when a new client connection is requested, or a client connection is closed.

TIdTunnelSlave.Socks4
TIdTunnelSlave
Indicates that the server uses Socks authentication for client connections.

    property Socks4: Boolean;

Description
Socks4 is a Boolean property that indicates that the server uses Socks authentication for newly established client connections.

When Sock4 is True, a new client connection may contain the Socks version, OpCode, Port number and IP Address for the Socks proxy, as well as the null-terminated Socks user ID. A Socks response is written to the client connection using the Socks OpCode 90.

When Sock4 is False, the client connection uses the DefaultPort for the server.

TIdTunnelSlave.Create
TIdTunnelSlave
Constructor for the object instance.

    constructor Create(AOwner: TComponent); override;

Parameters
AOwner: TComponent
Component that owns the object instance.
Description
Create is the constructor for the object instance, and relies on the inherited Create constructor. Create also initializes properties of the new object instance, including:

- Active - False

- NumClients - 0

- Socks4 - False

TIdTunnelSlave.Destroy
TIdTunnelSlave
Frees the object instance.

    destructor Destroy; override;

Description
Destroy is the destructor for the object instance, and is responsible for releasing object properties of the TIdTunnelSlave. Destroy will insure that the server is not AcceptingConnections and Active.

Destroy closes the TCP connection that serves as the tunnel link to the TIdTunnelMaster server.

Destroy terminates the SlaveThread that listens for data on the tunnel connection.

Destroy will free and release the TCriticalSection instances uses to protect the resources of the TIdTunnelSlave server.

Destroy relies on the inherited Destroy method to complete destruction of the object instance.

TIdTunnelSlave.GetStatistics
TIdTunnelSlave
Gets statistical measurements for the server.

    procedure GetStatistics(Module: Integer; var Value: Integer);

Parameters
Module: Integer
Statistic type requested.
var Value: Integer
Value for the requested statistic type.
Description
GetStatistics is a procedure used to retrieve statistical information for the TIdTunnelSlave instance.

Module is an Integer that represents one of the statistic type constant values from IdTunnelCommon.pas, and normally contains on of the following values:

- NumberOfConnectionsType - 1

- NumberOfPacketsType - 2

- CompressionRatioType - 3

- CompressedBytesType - 4

- BytesReadType - 5

- BytesWriteType - 6

CompressionRatioType returns a calculated value that represents the ratio of total number of bytes read to compressed bytes read.

Value is an Integer variable used to return the value for the selected statistic type.

GetStatistics uses the StatisticsLocker cortical section to protect access to the server resources from multiple threads.

TIdTunnelSlave.SetStatistics
TIdTunnelSlave
Updates statistics for connections to the server.

    procedure SetStatistics(Module: Integer; Value: Integer);

Parameters
Module: Integer
Statistical category to update.
Value: Integer
Delta value for the statistical category.
Description
SetStatistics is a procedure that allows the tunnel slave server to update variables that track active connections, packets transmitted, compression ratio, total number of compressed bytes, total bytes read, and total bytes written for the connection.

SetStatistics is called when the number of client connections is updated, or during SlaveThread execution.

TIdTunnelSlave.OnBeforeTunnelConnect
TIdTunnelSlave
Specifies the event handler for creating the connection to TIdTunnelMaster.

    property OnBeforeTunnelConnect: TSendTrnEventC;

Parameters
CustomMsg
Custom message for the event handler.
Header
UserID and Message type header information.
Description
OnBeforeTunnelConnect is a TSendTrnEventC event handler that allows the TIdTunnelSlave to respond prior to creating the TCP tunnel connection for TIdTunnelMaster.

OnBeforeTunnelConnect is signalled when SlaveThread is initialized for the server. Use OnBeforeTunnelConnect to override the UserID or message type in Header used to authenticate the server connection to TIdTunnelMaster, or to update user interface elements upon receipt of the notification.

Applications must assign a procedure to the event handler to allow the server to respond to the event notification.

TIdTunnelSlave.OnDisconnect
TIdTunnelSlave
Specifies the event handler for server disconnection.

    property OnDisconnect: TIdServerThreadEvent;

Parameters
AThread
- Thread requesting the event.
Description
OnDisconnect is a TIdServerThreadEvent event handler that allows the server to respond to disconnect requests from connections identified by the TIdPeerThread.

OnDisconnect can be used to perform housekeeping and maintenance required to reflect the change in the connection state.

Application must assign a procedure to the event handler to allow a response to the event notification.

TIdTunnelSlave.OnInterpretMsg
TIdTunnelSlave
Specifies the event handler for interpreting the session connection message.

    property OnInterpretMsg: TSendMsgEventC;

Parameters
CustomMsg
Message generated by the slave thread.
Description
OnInterpretMsg is a TSendMsgEventC event handler that allows the server to interpret the session connection message generating by the SlaveThread for the server instance. OnInterpretMsg can be generated by the slave thread when a connection message type is detected in the header for the encapsulated tunnel message.

Applications must assign a procedure to the event handler to allow a response to the event notification.

TIdTunnelSlave.OnStatus
TIdTunnelSlave
Specifies the event handler for a change in the tunnel connection state.

    property OnStatus: TIdStatusEvent;

Parameters
asStatusText
Message to be associated with the state.
axSender
Connection generating the event notification.
axStatus
Constant value reflecting the connection state.
Description
OnStatus is a TIdStatusEvent event handler that allows the server to respond to a change in the state of TCP connection to the TIdTunnelMaster server. For TIdTunnelSlave, OnStatus will be signalled when the TCP connection to the tunnel master server has been connected. Other state changes are not signalled.

TIdTunnelSlave.OnTransformRead
TIdTunnelSlave
Specifies the event handler for data transformations on a new message.

    property OnTransformRead: TTunnelEventC;

Parameters
Receiver
Message handler for the recipient of the message.
Description
OnTransformRead is a TTunnelEventC event handler that allows the TIdTunnelSlave to respond to a data transformation requests for a message received from the message handler.

OnTransformRead is invoked from TSlaveThread.Run when a new message is received.

Applications must assign a procedure to the event handler to allow a response to the event notification.

TIdTunnelSlave.OnTransformSend
TIdTunnelSlave
Specifies the event handler for data transformation prior to transmission.

    property OnTransformSend: TSendTrnEventC;

Parameters
CustomMsg
Message to be transformed.
Header
UserID and IP Address headers for the encapsulated message.
Description
OnTransformSend is a TSendTrnEventC event handler that allows the server to perform data transformation for a message prior to transmission to the tunnel master server.

Update CustomMsg to reflect the contents of the message after data transformation.

Applications must assign a procedure to the event handler to allow a response to the event notification.

TIdTunnelSlave.OnTunnelDisconnect
TIdTunnelSlave
Specifies the event handler for closing the connection to TIdTunnelMaster.

    property OnTunnelDisconnect: TTunnelEvent;

Parameters
Thread
Slave thread closing the tunnel connection.
Description
OnTunnelDisconnect is a TTunnelEvent event handler that allows the TIdTunnelSlave to respond to a notification that the TCP tunnel connection for TIdTunnelMaster has been closed.

OnTunnelDisconnect is signalled when the server is no longer accepting connections and has stopped transmitted to existing client connections.

Applications must assign a procedure to the event handler to allow the server to respond to the event notification.

Created with Doc-O-Matic 2 donated to Project JEDI. Commercial license available from the Doc-O-Matic site.