TIPBaseAsyncSocket

Overview

The TIPBaseAsyncSocket class implements the base functionality to perform nonblocking data transference on any transport layer. A nonblocking operating is reachable by using a background TIPSocketWorkerThread and Begin*/End* callbacks. The independency of the transport layer is accomplished by using the instumental IntBeginReceive, IntEndReceive, IntBeginSend and IntEndSend methods. This class is used by the TIPAsyncContext and TIPAsyncHTTPServer classes to provide data exchange in an event-driven approach.

Location

  • Unit: uIPAsyncSocket.pas


 

constructor Create

Creates a new instance.

constructor Create

BeginAccept  virtual abstract

Initiates the acceptance of client requests on this socket and calls aCallback when an accept occurs.

procedure BeginAccept(aCallback: TIPSocketCallback)

Parameters:

  • aCallback: Callback method

BeginConnect  virtual abstract

Initiates a connect operation to the given aIp and aPort endpoint on this socket and call aCallback when a connect occurs.

procedure BeginConnect(const aIp: string; aPort: Integer; aCallback: TIPSocketCallback)

Parameters:

  • aIp: IP address of the peer to which the socket is to be connected.
  • aPort: Numeric value of required service.
  • aCallback: Callback to be notified of the event.

BeginDisconnect  virtual abstract

Initiates a disconnect on this socket and call aCallback when a disconnect occurs.

procedure BeginDisconnect(aCallback: TIPSocketCallback)

Parameters:

  • aCallback: Callback method that will receive and correctly process the result of disconnect.

BeginReadLine

Initiates the reading of a sequence of chars until (optional CR (#13)) LF (#10) and registers aCallback to call when the line is ready. BeginReadLine is allowed for buffered sockets (Buffered=True) only.
If a received line already exists, aCallback is called immediately in the context of the current thread. Otherwise, the instrumental IntBeginReceive method is called with the ReadLineCallback as argument.

procedure BeginReadLine(aCallback: TIPSocketCallback)

Parameters:

  • aCallback:

BeginReceive

Initiates the receiving of the aLength data block to store in aData by the aStart offset and registers aCallback to call when the whole block (for buffered sockets) or part of the block is ready. If the socket is not buffered (Buffered=False), the job is delegated to the instrumental IntBeginReceive method. Otherwise, the job is delegated to the BufferedBeginReceive with the BufferedReceiveCallback as argument.

procedure BeginReceive(aData: Pointer; aStart: Integer; aLength: Integer; aCallback: TIPSocketCallback)

Parameters:

  • aData: Destination base address
  • aStart: Offset from aData to store received data.
  • aLength: Size of the block to be received.
  • aCallback:

BeginSend

Initiates the sending of the aLength data block from aData by the aStart offset and registers aCallback to call when the whole block (for buffered sockets) or part of the block is sent. If the socket is not buffered (Buffered=False), the job is delegated to the instrumental IntBeginSend method with aCallback, otherwise with BufferedSendCallback as argument.

procedure BeginSend(aData: Pointer; aStart: Integer; aLength: Integer; aCallback: TIPSocketCallback)

Parameters:

  • aData: Base address for sending data
  • aStart: Offset from aData
  • aLength: Size of the block to be sent
  • aCallback:

Bind  virtual abstract

An abstract method intended to associate a local aIp and aPort address with a socket. This routine is used on an unconnected socket, before the subsequent BeginConnect or Listen. For an example of the implementation, please refer to TIPAsyncSocket.

procedure Bind(const aIp: string; aPort: Integer)

Parameters:

  • aIp: IP address to assign to this socket
  • aPort: Numeric value of the offered service

Buffered

Controls if background data collecting is enabled. The *ReadLine methods are disabled when Buffered is false.

property Buffered: Boolean read write

BufferReadLine

If the buffer contains data with a terminating LF (#10), it is copied into aLine and true is returned. Otherwise, false is returned. This method raises an EIPSocketError, if Buffered=False.

function BufferReadLine(var aLine: AnsiString): Boolean

Parameters:

  • aLine: Resulting string

EndAccept  virtual abstract

An abstract method (a complement to BeginAccept) intended to initiate an accept on the transport layer. For an example of the implementation, please refer to TIPAsyncSocket.

function EndAccept: TIPBaseAsyncSocket

EndConnect  virtual abstract

Ends the connection to the remote socket with the specified address.

function EndConnect: Boolean

EndDisconnect  virtual abstract

Clean up a broken connection.

procedure EndDisconnect

EndReadLine

Copies the string collected by the ReadLineCallback into aLine and returns true, if any unread data remains. Note that the return value applies to further read operations.

function EndReadLine(var aLine: string): Boolean

Parameters:

  • aLine: Resulting string

EndReceive

If the socket is not buffered (Buffered=False), this method returns the result of calling the instrumental IntEndReceive method. Otherwise, it returns the amount of data collected by the BufferedEndReceive.

function EndReceive: Integer

EndSend

If the socket is not buffered (Buffered=False), this method returns the result of calling the instrumental IntEndSend method. Otherwise, it returns the amount of data recorded by the BufferedSendCallback and clears the callback registered by BeginSend.

function EndSend: Integer

GetLocalIp  virtual abstract

Retrieves the local endpoint of the transport layer.

function GetLocalIp: string

GetLocalPort  virtual abstract

Retrieves the numeric value associated with the offered service by the transport layer.

function GetLocalPort: Integer

GetRemoteIp  virtual abstract

Retrieves the IP of the peer.

function GetRemoteIp: string

GetRemotePort  virtual abstract

Gets the port of the peer used for communication.

function GetRemotePort: Integer

IdleTimeout

Determines the admissible interval in seconds between send or receive operations.

property IdleTimeout: Integer read write

Listen  virtual abstract

Establishes a socket to listen for an incoming connection.

procedure Listen(aBacklog: Integer)

Parameters:

  • aBacklog: Desired maximum length of the queue of pending connections. This value may be changed by the transport layer.

MaxLineLength

property MaxLineLength: Integer read write

NoDelay

Controls TCP packet batching (Nagle's algorithm).
TCP normally batches small logical packets into single larger physical packets (by briefly delaying packets) to fill physical network frames with as much data as possible. This is intended to improve network throughput in terminal emulation environments where mostly keystrokes are being sent across the network. Setting NoDelay to true disables TCP packet batching. Disabling TCP packet batching means that packets are sent regardless of size; this increases the volume of network traffic.

property NoDelay: Boolean read write

OnDisconnected

Allows access to the callback that is called when the transport layer detects a connection break.

property OnDisconnected: TIPSocketCallback read write
delegate: procedure OnDisconnected(Sender: TIPBaseAsyncSocket)

OnTimeout

Allows access to a callback which is called when IdleTimeout is not 0 and interval inactivity is greater than IdleTimeout. Note that with the TIPAsyncSocket class, an OnTimeout will be called in a TIPSocketWorkerThread context.

property OnTimeout: TIPSocketCallback read write
delegate: procedure OnTimeout(Sender: TIPBaseAsyncSocket)

ReceiverBufferSize

Controls the size of the receiving data buffer of the transport layer. Note that the transport layer may not provide the requested size, so you have to read ReceiverBufferSize to check the buffer size actually provided.

property ReceiverBufferSize: Integer read write

SendBufferSize

Controls the size of the sending data buffer of the transport layer. Note that the transport layer may not provide the requested size, so you have to read SendBufferSize to check the buffer size actually provided.

property SendBufferSize: Integer read write

 

Buffered

Controls if background data collecting is enabled. The *ReadLine methods are disabled when Buffered is false.

property Buffered: Boolean read write

IdleTimeout

Determines the admissible interval in seconds between send or receive operations.

property IdleTimeout: Integer read write

MaxLineLength

property MaxLineLength: Integer read write

NoDelay

Controls TCP packet batching (Nagle's algorithm).
TCP normally batches small logical packets into single larger physical packets (by briefly delaying packets) to fill physical network frames with as much data as possible. This is intended to improve network throughput in terminal emulation environments where mostly keystrokes are being sent across the network. Setting NoDelay to true disables TCP packet batching. Disabling TCP packet batching means that packets are sent regardless of size; this increases the volume of network traffic.

property NoDelay: Boolean read write

ReceiverBufferSize

Controls the size of the receiving data buffer of the transport layer. Note that the transport layer may not provide the requested size, so you have to read ReceiverBufferSize to check the buffer size actually provided.

property ReceiverBufferSize: Integer read write

SendBufferSize

Controls the size of the sending data buffer of the transport layer. Note that the transport layer may not provide the requested size, so you have to read SendBufferSize to check the buffer size actually provided.

property SendBufferSize: Integer read write

 

constructor Create

Creates a new instance.

constructor Create

BeginAccept  virtual abstract

Initiates the acceptance of client requests on this socket and calls aCallback when an accept occurs.

procedure BeginAccept(aCallback: TIPSocketCallback)

Parameters:

  • aCallback: Callback method

BeginConnect  virtual abstract

Initiates a connect operation to the given aIp and aPort endpoint on this socket and call aCallback when a connect occurs.

procedure BeginConnect(const aIp: string; aPort: Integer; aCallback: TIPSocketCallback)

Parameters:

  • aIp: IP address of the peer to which the socket is to be connected.
  • aPort: Numeric value of required service.
  • aCallback: Callback to be notified of the event.

BeginDisconnect  virtual abstract

Initiates a disconnect on this socket and call aCallback when a disconnect occurs.

procedure BeginDisconnect(aCallback: TIPSocketCallback)

Parameters:

  • aCallback: Callback method that will receive and correctly process the result of disconnect.

BeginReadLine

Initiates the reading of a sequence of chars until (optional CR (#13)) LF (#10) and registers aCallback to call when the line is ready. BeginReadLine is allowed for buffered sockets (Buffered=True) only.
If a received line already exists, aCallback is called immediately in the context of the current thread. Otherwise, the instrumental IntBeginReceive method is called with the ReadLineCallback as argument.

procedure BeginReadLine(aCallback: TIPSocketCallback)

Parameters:

  • aCallback:

BeginReceive

Initiates the receiving of the aLength data block to store in aData by the aStart offset and registers aCallback to call when the whole block (for buffered sockets) or part of the block is ready. If the socket is not buffered (Buffered=False), the job is delegated to the instrumental IntBeginReceive method. Otherwise, the job is delegated to the BufferedBeginReceive with the BufferedReceiveCallback as argument.

procedure BeginReceive(aData: Pointer; aStart: Integer; aLength: Integer; aCallback: TIPSocketCallback)

Parameters:

  • aData: Destination base address
  • aStart: Offset from aData to store received data.
  • aLength: Size of the block to be received.
  • aCallback:

BeginSend

Initiates the sending of the aLength data block from aData by the aStart offset and registers aCallback to call when the whole block (for buffered sockets) or part of the block is sent. If the socket is not buffered (Buffered=False), the job is delegated to the instrumental IntBeginSend method with aCallback, otherwise with BufferedSendCallback as argument.

procedure BeginSend(aData: Pointer; aStart: Integer; aLength: Integer; aCallback: TIPSocketCallback)

Parameters:

  • aData: Base address for sending data
  • aStart: Offset from aData
  • aLength: Size of the block to be sent
  • aCallback:

Bind  virtual abstract

An abstract method intended to associate a local aIp and aPort address with a socket. This routine is used on an unconnected socket, before the subsequent BeginConnect or Listen. For an example of the implementation, please refer to TIPAsyncSocket.

procedure Bind(const aIp: string; aPort: Integer)

Parameters:

  • aIp: IP address to assign to this socket
  • aPort: Numeric value of the offered service

BufferReadLine

If the buffer contains data with a terminating LF (#10), it is copied into aLine and true is returned. Otherwise, false is returned. This method raises an EIPSocketError, if Buffered=False.

function BufferReadLine(var aLine: AnsiString): Boolean

Parameters:

  • aLine: Resulting string

EndAccept  virtual abstract

An abstract method (a complement to BeginAccept) intended to initiate an accept on the transport layer. For an example of the implementation, please refer to TIPAsyncSocket.

function EndAccept: TIPBaseAsyncSocket

EndConnect  virtual abstract

Ends the connection to the remote socket with the specified address.

function EndConnect: Boolean

EndDisconnect  virtual abstract

Clean up a broken connection.

procedure EndDisconnect

EndReadLine

Copies the string collected by the ReadLineCallback into aLine and returns true, if any unread data remains. Note that the return value applies to further read operations.

function EndReadLine(var aLine: string): Boolean

Parameters:

  • aLine: Resulting string

EndReceive

If the socket is not buffered (Buffered=False), this method returns the result of calling the instrumental IntEndReceive method. Otherwise, it returns the amount of data collected by the BufferedEndReceive.

function EndReceive: Integer

EndSend

If the socket is not buffered (Buffered=False), this method returns the result of calling the instrumental IntEndSend method. Otherwise, it returns the amount of data recorded by the BufferedSendCallback and clears the callback registered by BeginSend.

function EndSend: Integer

GetLocalIp  virtual abstract

Retrieves the local endpoint of the transport layer.

function GetLocalIp: string

GetLocalPort  virtual abstract

Retrieves the numeric value associated with the offered service by the transport layer.

function GetLocalPort: Integer

GetRemoteIp  virtual abstract

Retrieves the IP of the peer.

function GetRemoteIp: string

GetRemotePort  virtual abstract

Gets the port of the peer used for communication.

function GetRemotePort: Integer

Listen  virtual abstract

Establishes a socket to listen for an incoming connection.

procedure Listen(aBacklog: Integer)

Parameters:

  • aBacklog: Desired maximum length of the queue of pending connections. This value may be changed by the transport layer.

 

OnDisconnected

Allows access to the callback that is called when the transport layer detects a connection break.

property OnDisconnected: TIPSocketCallback read write
delegate: procedure OnDisconnected(Sender: TIPBaseAsyncSocket)

OnTimeout

Allows access to a callback which is called when IdleTimeout is not 0 and interval inactivity is greater than IdleTimeout. Note that with the TIPAsyncSocket class, an OnTimeout will be called in a TIPSocketWorkerThread context.

property OnTimeout: TIPSocketCallback read write
delegate: procedure OnTimeout(Sender: TIPBaseAsyncSocket)