Represents a low-level socket binding.

TIdSocketHandle = class(TCollectionItem)

TIdSocketHandle encapsulates the low-level socket binding and its associated functions. A socket binding is the handle used for sending and receiving data, making and closing a connection, or waiting for a connection (listening).

TIdSocketHandle is used by TIdTCPConnection descendants in Indy to encapsulate the low-level connection and methods used to access the protocol stack in Binding.

Indicates the minimum port number allowed for binding a socket handle.

property ClientPortMax: Integer;

ClientPortMax is an Integer property that indicates the maximum port number allowed when Bind is called for a socket handle with the value 0 (zero) in Port. ClientPortMax is used in conjunction with ClientPortMin to determine the range of port numbers allowed for the bound socket handle. The value of ClientPortMax should be larger than the value of ClientPortMin.

Indicates the minimum port number allowed for binding a socket handle.

property ClientPortMin: Integer;

ClientPortMin is an Integer property that indicates the minimum port number allowed when Bind is called for a socket handle with the value 0 (zero) in Port. ClientPortMin is used in conjunction with ClientPortMax to determine the range of port numbers allowed for the bound socket handle. The value of ClientPortMin should not exceed the value of ClientPortMax.

Specifies the low-level socket handle for the binding.

property Handle: TIdStackSocketHandle;

Handle is a read-only TIdStackSocketHandle property that encapsulate the low-level socket handle required to perform protocol stack API operations. Handle is also referred to as the socket descriptor in UNIX parlance. Socket descriptors are not presumed to correspond to a regular file handle, and native file operations such as read(), write(), and close() cannot be assumed to work correctly when applied to socket descriptors.

Handle is assigned a valid value in Accept, and AllocateSocket. The value in Handle is Id_INVALID_SOCKET prior to calling one of these methods. Handle is release in CloseSocket.

HandleAllocated reflects the current state of Handle.

Specifies the validity of the socket handle.

property HandleAllocated: Boolean;

HandleAllocated is a read-only Boolean property that indicates if Handle is a valid socket descriptor.

HandleAlocated is True when a valid socket descriptor has been created in AllocateSocket or Accept. HandleAllocated is False when a socket descriptor has not been selected, or the value of Handle is Id_INVALID_SOCKET.

HandleAllocated is used to allow sockets, altered using SetSockOpt, to indicate that the socket handle is no longer available for send and receive operations.

Specifies the address of the local connection.

property IP: string;

IP is a String property that identifies the address of the computer on the local connection. IP can be a computer name, such as "wvnvm.wvnet.edu", or an IP address in dotted-decimal format, such as "129.71.2.4".

IP is used in Bind and Connect to initialize or open a socket descriptor for the connection. IP is used in conjunction with Port to determine the local association used to identify the connection endpoint.

Specifies the address of the remote connection.

property PeerIP: string;

PeerIP is a read-only String property that identifies the address of the computer on the remote connection. PeerIP can be a computer name, such as "wvnvm.wvnet.edu", or an IP address in dotted-decimal format, such as "129.71.2.4".

PeerIP is used in conjunction with PeerPort to determine the association used to identify the remote connection endpoint.

PeerIP is updated in SetPeer, and as a result of Accept, SendTo, and RecvFrom operations.

Specifies the port number used by a peer connection.

property PeerPort: integer;

PeerPort is a read-only Integer property that identifies the port number on the remote system where data is sent and received. PeerIP identifies the host name or dotted-decimal address of the remote system.

Note: Many port numbers are associated, by convention, with a particular service such as ftp or http as described in IdPorts. Some protocols use pre-defined port numbers. Port numbers below 1024 are reserved, but using a number above 1024 does not guarantee there will be no conflict.

PeerPort is updated using SetPeer, or when Accept is used to bind a connection to a remote system.

Specifies the port number used by the local connection.

property Port: integer;

Port is an Integer property that identifies the port number on the local system where data is sent and received. IP identifies the host name or dotted-decimal address of the local system.

Note: Many port numbers are associated, by convention, with a particular service such as ftp or http as described in IdPorts. Some protocols use pre-defined port numbers. Port numbers below 1024 are reserved, but using a number above 1024 does not guarantee there will be no conflict.

Port is used in conjunction with IP to determine the local association used to identify the connection endpoint from Bind and Connect.

Accepts a connection on a listening socket.

function Accept(ASocket: TIdStackSocketHandle): boolean;

Socket descriptor with the connection request.

Accept is a procedure that extracts a pending connection request for a socket descriptor, creates a new socket with the properties of the listening socket, an returns the socket handle of the new socket to Handle.

Accept is used by the listening thread of server applications that spawn new threads for each connection request, like TIdListenerThread and TIdUDPListenerThread.

Accept assigns the new socket descriptor to Handle and sets HandleAllocated to True.

Accept calls UpdateBindingLocal to insure that the protocol stack handler uses the correct protocol family, IP, and Port for servers that may listen on more than one local IP address.

Accept calls UpdateBindingPeer to insure that the protocol stack handler uses the correct protocol family, PeerIP, and PeerPort for the client connection.

If no pending connections are present on the socket descriptor, Accept will wait until a connection is present before exiting from the method.

Creates a socket descriptor.

procedure AllocateSocket(const ASocketType: Integer = Id_SOCK_STREAM; const AProtocol: Integer = Id_IPPROTO_IP);

Socket family. Default is Id_SOCK_STREAM.

Protocol family. Default is Id_IPPROTO_IP.

AllocateSocket is a procedure that allocates a socket descriptor of the desired socket type and Internet protocol family as specified in the parameters.

ASocketType determines address family used for the connection, and indicates the valid protocol family options for the socket type. The following socket types are supported:

• Id_SOCK_STREAM (Default)

• Id_SOCK_DGRAM

• Id_SOCK_RAW

AProtocol identifies the Internet protocol to be used for the given socket type. Only a single protocol exists to support a particular socket type using a given address format. The following protocol families are supported:

• Id_IPPROTO_IP (Default)

• Id_IPPROTO_ICMP

• Id_IPPROTO_IGMP

• Id_IPPROTO_TCP

• Id_IPPROTO_UDP

• Id_IPPROTO_RAW

AllocateSocket will call CloseSocket if the socket handle is already allocated.

AllocateSocket will set HandleAllocated to True to reflect the state of the socket handle.

Copies the value of an object instance to the current instance.

procedure Assign(Source: TPersistent); override;

The object instance containing the values to copy.

Assign is a procedure used to copy the value of properties in the TPersistent descendant Source to the current object instance. Assign updates the following property values:

• IP

• Port

• PeerIP

• PeerPort

Associates a local address with a socket.

procedure Bind;

Bind is used on an unconnected socket to associate the IP and Port of the local host with Handle prior to Connect or Listen operations.

If the application does not care what address is assigned to it, it may use a blank IP (''). This allows the protocol stack to assign the Internet address Id_INADDR_ANY, and an any appropriate network interface will be used.

If the application does not care what port is assigned to it, it may use Port 0. This allows the protocol stack to assign a unique port to the application with a value between 1024 and 5000.

Use SetSockOpt to alter socket-level settings including broadcast, linger, buffering, and Nagle options.

Bind will raise an EIdException if the address in IP and Port is already in use.

Closes a socket.

procedure CloseSocket(const AResetLocal: boolean = True); virtual;

Clears the local IP address and Port number when True.

CloseSocket is a procedure to close a socket. CloseSocket allows the protocol stack to shutdown and release the socket handle for the descriptor. HandleAllocated is set to False to indicate to that the socket is no longer available to other threads of execution. CloseSocket has no effect if HandleAllocated is False.

AResetLocal indicates that rest should be called for the local connection.

CloseSocket is affected by options used in SetSockOpt for Id_SO_LINGER.

Establish a connection to a peer.

function Connect(const AFamily: Integer = Id_PF_INET): Integer; virtual;

Internet protocol family. Default is Id_PF_INET.

Integer - 0 on success.

Connect is an Integer function that opens a connection to a remote system using the specified Internet protocol family.

Connect uses IP and Port, and the parameter AFamily, to call the Connect facilities of the protocol stack. When Connect has successfully completed, the socket will be ready to send and receive data using Send, SendTo, Recv, and RecvFrom.

Use Readable, any time following a successful Connect, to determine if the socket is in a valid input/output state.

Creates and initializes the binding instance.

constructor Create(ACollection: TCollection); override;

Owner of the collection item instance.

Create is the constructor for the collection item TIdSocketHandle, and relies on the inherited Create constructor to initialize the collection item.

The ACollection parameter is the TIdSocketHandles collection that owns the collection item instance. ACollection is used to retrieve the value in DefaultPort, and to assign that value to Port in the TIdSocketHandle instance.

Disposes of the collection item instance.

destructor Destroy; override;

Destroy is the destructor for the collection item. Destroy will call CloseSocket prior to invoking the inherited Destroy destructor.

Note: Do not call Destroy directly. Call Free instead.

Retrieves socket options for a socket descriptor.

procedure GetSockOpt(level: Integer; optname: Integer; optval: PChar; optlen: Integer);

Option level Id_SOL_SOCKET, Id_IPPROTO_TCP, or Id_IPPROTO_IP.

Socket option to retrieve.

Value for the requested option.

Length of the option value buffer.

GetSockOpt is a procedure used to retrieve socket options for the socket descriptor represented by Handle. Options can control socket operations such as receiving Out-Of-Band data, broadcasting datagram packets, and much more.

OptNames is one of the constant values declared in IdStackConts.pas.

OptVal is the resulting socket option after a call to WSGetSockOpt using the global stack instance GStack.

Use SetSockOpt to update the options for a socket descriptor.

Instructs a socket to listen for incoming connection.

procedure Listen(const anQueueCount: integer = 5);

Number of pending connection requests to allow. Default is 5.

Listen is a procedure that allows a bound socket descriptor to wait for incoming connections. Listen is normally used in server applications that allow multiple simultaneous connections.

anQueueCount identifies the maximum number of pending connection requests to allow for the socket descriptor. Use care when specifying a larger value for anQueueCount; most protocol stacks limit the number of pending connections requests allowed per socket descriptor to a small value. Use Accept to service a pending connection request.

Handle identifies the socket descriptor used to listen for connections, and must not be connected prior to calling Listen.

Determines the read status of a socket.

function Readable(AMSec: Integer = IdTimeoutDefault): boolean;

Time-out value in milliseconds. Default is IdTimeoutDefault.

Boolean - True when the socket can be read.

Readable is a Boolean function that is used to determine the status of the socket connection for read operations. Readable provides access to the Select API of the protocol stack. Readable returns True when the socket descriptor is ready for read operations using Recv, RecvFrom, or Accept.

Readable will raise an EIdConnClosedGraceful exception if HandleAllocated contains False.

Readable detects the use of a TIdAntifreeze instance in an application. When present, Readable yields processing cycles during the lifetime of the method call to the TIdAntifreeze.DoProcess method.

When AMSec is IdTimeoutInfinite, Readable uses the IdleTimeout value in TIdAntifreeze as its time-out value. Readable will continue executing until the socket is ready to read.

When AMsec is larger than the IdleTimeout value in TIdAntifreeze, Readable is called using the difference between the two time-out values. If the socket is ready to read, no further processing is performed. If the socket is not ready to read, the time-out value is set to the IdleTimeout value in TIdAntifreeze and Readable is called again to determine the socket status. Readable yields processing cycles to the TIdAntifreeze.DoProcess method if the socket is still not ready to read.

Readable does not yield processing cycles when an instance of TIdAntifreeze has not been used in the application.

Receives data from a socket.

function Recv(var ABuf; ALen: Integer; AFlags: Integer): Integer;

Buffer for the read operation.

Length of the read buffer.

Flags to modify socket options.

Integer - Number of bytes read.

Recv is an Integer function used to read incoming data from a connected socket descriptor. Recv is used on streaming sockets, to read all available data up to the size of the read buffer. Recv can also retrieve Out-of-Band data on sockets configured using Id_SO_OOBINLINE in SetSockOpt. If no data is available on the socket, Recv waits for data to arrive.

AFlags can be used to alter the behavior of the Recv method beyond the options specified in SetSockOpt. The supported values of AFlags includes:

• MSG_OOB - Process out-of-band data.

• MSG_PEEK - Peek at the incoming data. The data is copied into the read buffer, but is not removed from the input queue.

Receive data from a socket and store the remote system address.

function RecvFrom(var ABuffer; const ALength: Integer; const AFlags: Integer; var VIP: string; var VPort: Integer): Integer; virtual;

Buffer for the read operation.

Length of the read buffer.

Flags to modify socket options.

IP Address of the remote connection.

Port number of the remote connection.

Integer - Number of bytes read.

RecvFrom is an Integer function used to read incoming data from a socket connection, and to store the address of the remote system in the variable parameters VIP and VPort.

RecvFrom is used on streaming sockets, to read all available data up to the size of the read buffer. RecvFrom can also retrieve Out-of-Band data on sockets configured using Id_SO_OOBINLINE in SetSockOpt. If no data is available on the socket, RecvFrom waits for data to arrive.

AFlags can be used to alter the behavior of the RecvFrom method beyond the options specified in SetSockOpt. The supported values of AFlags includes:

• MSG_OOB - Process out-of-band data.

• MSG_PEEK - Peek at the incoming data. The data is copied into the read buffer, but is not removed from the input queue.

Restores the socket handle to an uninitialized state.

procedure Reset(const AResetLocal: boolean = True);

Indicates that IP and Port are cleared for the connection.

Reset is a procedure used to insure that TIdSocketHandle is in an uninitialized state. Reset clears the following properties to their uninitialized values:

• HandleAllocated - False

• Handle - Id_INVALID_SOCKET

• PeerIP - '' (empty string)

• PeerPort - 0

When aResetLocal is True, the IP and Port for the socket descriptor are reset to the following values:

• IP = '' (empty string)

• Port - 0

Reset is called from Create and CloseSocket.

Determines if a socket handle is available for reading and writing.

function Select(ASocket: TIdStackSocketHandle; ATimeOut: Integer): boolean;

Protocol stack socket handle for the operation.

Number of milliseconds to wait for completion of the operation.

Select is a Boolean function that determines if the protocol stack socket handle in ASocket is available for reading and writing. ATimeOut is the number of milliseconds that the protocol stack should wait for completion of the operation. Select calls the TIdStack.WSSelect method to access the protocol stack routines that implements the select operation.

On successful compeletion of TIdStack.WSSelect, TIdAntiFreezeBase.DoProcess is called to force an idle state in the main thread of execution, and to allow message processing for other threads of execution.

Sends data using a connected socket.

function Send(var Buf; len: Integer; flags: Integer): Integer;

Buffer to write to the socket.

Length of the write buffer.

Flags to modify socket options.

Integer - Number of bytes read.

Send is an Integer function used to write outgoing data to a connected socket. Send returns the total number of bytes sent over the socket connection.

Datagram sockets cannot write datagrams that are larger than the MAXUDPDG constant declared by the protocol stack. Streaming socket connections will attempt to write all data in the buffer up to the size specified.

AFlags can be used to alter the behavior of the Send method beyond the options specified in SetSockOpt. The supported values of Flags includes:

• MSG_OOB - Send out-of-band data .

• MSG_DONTROUTE - Do not route the data.

Sends data to a specific address.

procedure SendTo(const AIP: string; const APort: Integer; var ABuffer; const ABufferSize: Integer);

IP address of the remote system.

Port number of the remote system.

Buffer to send over the socket connection.

Size of the send buffer.

SendTo is a procedure used to write outgoing data to a socket connected to the remote system specified in IP address and Port number.

SendTo will raise an EIdException exception if the number of bytes sent does not match the value in ABufferSize, or if the number of bytes sent is Id_SOCKET_ERROR.

SendTo is used on datagram or stream sockets. For datagram sockets, care must be taken not to exceed the maximum packet size of the protocol stack declared in MAXUDPDG. Streaming sockets will attempt to write all data in the buffer to the socket connection.

To send a broadcast datagram, the IP address parameter must contain Id_INADDR_ANY.

Updates the remote address of a socket connection.

procedure SetPeer(const asIP: string; anPort: integer);

IP address for the remote connection.

Port number for the remote connection.

SetPeer is a procedure used to update the PeerIP and PeerPort properties of the socket connection. SetPeer is a convenience method provided for TIdTCPConnection descendants that may need to update the Binding property, like TIdTCPClient and TIdUDPBase.

SetPeer is also used by the listening thread of server applications that spawn new threads for each connection request, like TIdListenerThread and TIdUDPListenerThread.

Sets socket options.

procedure SetSockOpt(level: Integer; optname: Integer; optval: PChar; optlen: Integer);

Option level Id_SOL_SOCKET, Id_IPPROTO_TCP, or Id_IPPROTO_IP.

Socket option to receive the option value.

Value for the requested option.

Length of the option value buffer.

SetSockOpt is a procedure used to set the value of socket-level options for a socket descriptor. Options can control socket operations such as receiving Out-Of-Band data, broadcasting datagram packets, and much more.

There are two types of socket options: Boolean and Data. Boolean options enable or disable a specific feature. Use a zero value in OptVal to disable a feature, and a non-zero value in OptVal to enable the feature.

Data options require the address used to store the value or structure in OptVal. OptNames use the contant values declared in IdStackConts.pas, including:

• Id_SO_BROADCAST - Boolean

Allow transmission of broadcast messages on the socket.

• Id_SO_DEBUG - Booean

Record debugging information.

• Id_SO_DONTLINGER - Boolean

Don't block CloseSocket for unsent data.

• Id_SO_DONTROUTE - Boolean

Don't route dsata, send it directly to the interface.

• Id_SO_KEEPALIVE - Boolean

Send keepalive packets.

• Id_SO_LINGER - Data Linger

Linger on close if unsent data is present.

• Id_SO_OOBINLINE - Boolean

Receive out-of-band data in the normal data stream.

• Id_SO_RCVBUF - Data Integer

Specify buffer size for receives.

• Id_SO_REUSEADDR - Boolean

Allow the socket to be bound to an address which is already in use.

• Id_SO_SNDBUF - Data Integer

Specify buffer size for sends.

• Id_SO_RCVTIMEO - Data Integer

Receive timeout.

• Id_SO_SNDTIMEO - Data Integer

Send timeout.

• Id_IP_TTL - Data Integer

Set Time-To-Live in IP header fields.

• Id_TCP_NODELAY - Boolean

Disables the Nagle algorithm for send coalascing.

Updates the protocol family, and address for a socket handle.

procedure UpdateBindingLocal;

UpdateBindingLocal is a procedure used to insure that the socket handle allocated for a connection uses the proper Protocol family, IP, and Port. UpdateBindingLocal is generally used for connections that can Listen on multiple IP addresses.

Updates the protocol family and remote address for a socket connection.

procedure UpdateBindingPeer;

UpdateBindingPeer is a procedure used to update the Protocol family, PeerIP, and PeerPort for the peer connection on a socket handle. UpdateBindingPeer is generally used for connections that can accept client connections using multiple local IP addresses.