Implements an IOHandler used to restrict throughput to a targeted number of bytes per second.

TIdIOHandlerThrottle = class(TIdIOHandler)

TIdIOHandlerThrottle is a TIdIOHandler descendant used to restrict the throughput for an associated IOHandler to a targeted number of bytes per second for Send and Receive operations. TIdIOHandlerThrottle attaches to an existing IOHandler to perform its specific function.

TIdIOHandlerThrottle overrides methods in the ancestor class, like :

• Close

• ConnectClient

• Connected

• Open

• Readable

• Recv

• Send

TIdIOHandlerThrottle also publishes properties like:

• BytesPerSec

• BitsPerSec

• ChainedHandler

Get or Set the throughput of the IOHandler using a targeted number of Bits per Second.

property BitsPerSec: Cardinal;

BitsPerSec is a Cardinal property that indicates the throughtput for the Send and Recv for the associated IOHandler in ChainedHandler expressed in Bits per Second (as opposed to Bytes per Second). BitsPerSec is a calculated product using the formula BytesPerSec multiplied by 8. Changing the value in BitsPerSec will result in BytesPerSec being updated to contain the integer result of the new value divided by 8.

Use BytesPerSec to examine or change the target throughput of the IOHandler using an 8-bit Bytes per Second value.

Indicates the targeted throughput for Send and Recv operations for the IOHandler.

property BytesPerSec: Cardinal;

BytesPerSec is a Cardinal property that represents the targeted throughput for Send and Recv using the associated IOHandler in ChainedHandler. BytesPerSec is used in Recv and Send to determine when the throughput for the associated IOHandler in ChainedHandler needs to be restricted in order to meet the target value in the property.

When BytesPerSec contains the value 0 (zero), no bandwidth restriction is performed for the associated IOHandler in ChainedHandler. In this situation, ChainedHandler calls its Recv or Send method immediately.

Use BitsPerSec to get or set the targeted throughput using bits per second instead of bytes per second.

Represents the actual IOHandler used for send and receive operations for a socket connection.

property ChainedHandler: TIdIOHandler;

ChainedHandler is a TIdIOHandler property that represents the actual IOHandler performing Recv and Send operations. ChainedHandler is used in ConnectClient to establish the connection using the desired Host, Port, and BoundPort number for the client. ChainedHandler is used in methods like Open, Close, Connected, and Readable.

ChainedHandler must be assigned a valid TIdIOHandler instance, or an EIdThrottleNoChainedIOHandler exception wil be raised during execution in ConnectClient and Open.

Closes the chained IOHandler.

procedure Close; override;

Close is an overridden procedure in TIdIOHandlerThrottle, and allows the associated IOHandler descendant in ChainedHandler to be closed. When a valid IOHandler instance has been assigned to ChainedHandler, its Close method is called prior to exiting from the method.

Prepares and opens the client connection for a chained IOHandler.

procedure ConnectClient(const AHost: string; const APort: Integer; const ABoundIP: string; const ABoundPort: Integer; const ABoundPortMin: Integer; const ABoundPortMax: Integer; const ATimeout: Integer = IdTimeoutDefault); override;

Address of the remote system for the client connection.

Port number for the remote connection.

IP Address bound to the local system.

Integer - Port number bound to the local computer.

Minimum bound port number for the local system.

Maximum bound port number for the local system.

Number of milliseconds to wait before a connection attempt fails. Default value is IdTimeoutDefault.

ConnectClient is an overriden procedure in TIdIOHandlerThrottle that prepares and established the client connection for the associated IOHandler in ChainedHandler. ConnectClient calls the inherited ConnectClient method.

When a valid instance of an IOHandler descendant has been assigned to ChainedHandler, its ConnectClient mehod is called using the parameters for the method. Note: ConnectClient will raised an EIdThrottleNoChainedIOHandler exception with the message RSIHTChainedNotAssigned if a valid IOHandler instance is not assigned to ChainedHandler.

Indicates if physical connection for the chained IOHandler is prepared and opened.

function Connected: Boolean; override;

Connected is an overridden Boolean function in TIdIOHandlerThrottle, and determines when the physical connection for the associated IOHandler in ChainedHandler has been established. When a valid instance of a TIdIOHandler descendant has been assigned to ChainedHandler, its Connected method is called. When ChainedHandler is unassigned, Connected returns the value False.

Use Open to prepare the physical connection for the chained IOHandler, and ConnectClient to establish the connection used by the chained IOHandler.

Constructor for the object instance.

constructor Create(AOwner: TComponent); override;

Owner of the object instance.

Create is the constructor for the object instance. Create calls the inherited Create method using AOwner as the owner of the object instance.

Frees an object instance.

destructor Destroy; override;

Destroy is the destructor for the object instance. Destroy calls the inherited Destroy method prior to exiting from the method.

Prepares and binds the connection for a chained IOHandler.

procedure Open; override;

Open is an overriden method in TIdIOHandlerThrottle that prepares and binds the connection for the chained IOHandler. Open calls the inherited Open method.

When a valid instance of a TIdIOHandler descendant has been assigned to ChainedHandler, its Open method is called. Note: When ChainedHandler is unassigned, Open will raised an EIdThrottleNoChainedIOHandler exception with the message RSIHTChainedNotAssigned.

Use ConnectClient to establish the connection on the socket handle used by the handler. Use Close to disconnect the client connection in the chained IOHandler.

Indicates that the chained IOHandler is ready to send or receive data.

function Readable(AMSec: integer = IdTimeoutDefault): boolean; override;

Milliseconds to wait for the IOHandler to become ready. Default value is IdTimeoutDefault.

Boolean - True when ready.

Readable is an overidden Boolean function in TIdIOHandlerThrottle that indicates if associated IOHandler in ChainedHandler is ready for input/output operations.

When ChainedHandler contains a valid instance of a TIdIOHandler descendant, its Readable method is called using the value in AMSec as a parameter. The return value for the method is set to the result of the operation. When ChainedHandler is unassigned, the return value for the method is set to False.

Reads data from a chained IOHandler.

function Recv(var ABuf; ALen: integer): integer; override;

Destination buffer for values read from the chained IOHandler.

Number of bytes to read from the connection.

Integer - Acutal number of bytes read from the chained IOHandler.

Recv is an overridden Integer function that read data using the IOHandler in ChainedHandler. When a valid instance of a TIdIOHandler descendant is assigned to ChainedHandler, Recv will attempt to limit the throughtput for the chained IOHandler when BytesPerSec contains a value greater than 0 (zero).

When BytesPerSec is 0 (or less), no throughput leveling is performed, and the Recv method for the ChainedHandler is called using ABuf and ALen as parameters.

Recv limits throughput by forcing the IOHandler to delay when the elapsed time for a read operation is smaller than the estimated time required to read ALen bytes at the desired BytesPerSec rate. The delay will level the throughput rate, on average, to the desired target.

Use Send to write data using the chained IOHandler.

Writes data using a chained IOHandler.

function Send(var ABuf; ALen: integer): integer; override;

Buffer for values written using the chained IOHandler.

Number of bytes to write using the chained IOHandler.

Integer - Acutal number of bytes written using the chained IOHandler.

Send is an overridden Integer function that writes data using the IOHandler in ChainedHandler. When a valid instance of a TIdIOHandler descendant is assigned to ChainedHandler, Send will attempt to limit the throughtput for the chained IOHandler when BytesPerSec contains a value greater than 0 (zero).

When BytesPerSec is 0 (or less), no throughput leveling is performed, and the Send method for the ChainedHandler is called using ABuf and ALen as parameters.

Send limits throughput by forcing the IOHandler to delay when the elapsed time for a write operation is smaller than the estimated time required to write ALen bytes at the desired BytesPerSec rate. The delay will level the throughput rate, on average, to the desired target.

Use Recv to read data using the chained IOHandler.