Indy 9 | Content | Index | Reference

TIdSocketHandle
Hierarchy, Properties, Methods, See Also, Unit: IdSocketHandle
Represents a low-level socket binding.

    TIdSocketHandle = class(TCollectionItem)

Unit
IdSocketHandle
Description
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.

TIdSocketHandle.ClientPortMax
TIdSocketHandle, See Also
Indicates the minimum port number allowed for binding a socket handle.

    property ClientPortMax: Integer;

Description
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.

TIdSocketHandle.ClientPortMin
TIdSocketHandle, See Also
Indicates the minimum port number allowed for binding a socket handle.

    property ClientPortMin: Integer;

Description
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.

TIdSocketHandle.Handle
TIdSocketHandle, See Also
Specifies the low-level socket handle for the binding.

    property Handle: TIdStackSocketHandle;

Description
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.

TIdSocketHandle.HandleAllocated
TIdSocketHandle, See Also
Specifies the validity of the socket handle.

    property HandleAllocated: Boolean;

Description
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.

TIdSocketHandle.IP
TIdSocketHandle, See Also
Specifies the address of the local connection.

    property IP: string;

Description
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.

TIdSocketHandle.PeerIP
TIdSocketHandle, See Also
Specifies the address of the remote connection.

    property PeerIP: string;

Description
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.

TIdSocketHandle.PeerPort
TIdSocketHandle, See Also
Specifies the port number used by a peer connection.

    property PeerPort: integer;

Description
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.

TIdSocketHandle.Port
TIdSocketHandle, See Also
Specifies the port number used by the local connection.

    property Port: integer;

Description
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.

TIdSocketHandle.Accept
TIdSocketHandle, See Also
Accepts a connection on a listening socket.

    function Accept(ASocket: TIdStackSocketHandle): boolean;

Parameters
ASocket: TIdStackSocketHandle
Socket descriptor with the connection request.
Description
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.

TIdSocketHandle.AllocateSocket
TIdSocketHandle, See Also
Creates a socket descriptor.

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

Parameters
const ASocketType: Integer = Id_SOCK_STREAM
Socket family. Default is Id_SOCK_STREAM.
const AProtocol: Integer = Id_IPPROTO_IP
Protocol family. Default is Id_IPPROTO_IP.
Description
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.

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

    procedure Assign(Source: TPersistent); override;

Parameters
Source: TPersistent
The object instance containing the values to copy.
Description
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

TIdSocketHandle.Bind
TIdSocketHandle, See Also
Associates a local address with a socket.

    procedure Bind;

Description
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.

TIdSocketHandle.CloseSocket
TIdSocketHandle, See Also
Closes a socket.

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

Parameters
const AResetLocal: boolean = True
Clears the local IP address and Port number when True.
Description
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.

TIdSocketHandle.Connect
TIdSocketHandle, See Also
Establish a connection to a peer.

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

Parameters
const AFamily: Integer = Id_PF_INET
Internet protocol family. Default is Id_PF_INET.
Return Value
Integer - 0 on success.
Description
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.

TIdSocketHandle.Create
TIdSocketHandle, See Also
Creates and initializes the binding instance.

    constructor Create(ACollection: TCollection); override;

Parameters
ACollection: TCollection
Owner of the collection item instance.
Description
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.

TIdSocketHandle.Destroy
TIdSocketHandle, See Also
Disposes of the collection item instance.

    destructor Destroy; override;

Description
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.

TIdSocketHandle.GetSockOpt
TIdSocketHandle, See Also
Retrieves socket options for a socket descriptor.

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

Parameters
level: Integer
Option level Id_SOL_SOCKET, Id_IPPROTO_TCP, or Id_IPPROTO_IP.
optname: Integer
Socket option to retrieve.
optval: PChar
Value for the requested option.
optlen: Integer
Length of the option value buffer.
Description
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.

TIdSocketHandle.Listen
TIdSocketHandle, See Also
Instructs a socket to listen for incoming connection.

    procedure Listen(const anQueueCount: integer = 5);

Parameters
const anQueueCount: integer = 5
Number of pending connection requests to allow. Default is 5.
Description
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.

TIdSocketHandle.Readable
TIdSocketHandle, See Also
Determines the read status of a socket.

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

Parameters
AMSec: Integer = IdTimeoutDefault
Time-out value in milliseconds. Default is IdTimeoutDefault.
Return Value
Boolean - True when the socket can be read.
Description
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.

TIdSocketHandle.Recv
TIdSocketHandle, See Also
Receives data from a socket.

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

Parameters
var ABuf
Buffer for the read operation.
ALen: Integer
Length of the read buffer.
AFlags: Integer
Flags to modify socket options.
Return Value
Integer - Number of bytes read.
Description
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.

TIdSocketHandle.RecvFrom
TIdSocketHandle, See Also
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;

Parameters
var ABuffer
Buffer for the read operation.
const ALength: Integer
Length of the read buffer.
const AFlags: Integer
Flags to modify socket options.
var VIP: string
IP Address of the remote connection.
var VPort: Integer
Port number of the remote connection.
Return Value
Integer - Number of bytes read.
Description
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.

TIdSocketHandle.Reset
TIdSocketHandle
Restores the socket handle to an uninitialized state.

    procedure Reset(const AResetLocal: boolean = True);

Parameters
const AResetLocal: boolean = True
Indicates that IP and Port are cleared for the connection.
Description
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.

TIdSocketHandle.Select
TIdSocketHandle, See Also
Determines if a socket handle is available for reading and writing.

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

Parameters
ASocket: TIdStackSocketHandle
Protocol stack socket handle for the operation.
ATimeOut: Integer
Number of milliseconds to wait for completion of the operation.
Description
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.

TIdSocketHandle.Send
TIdSocketHandle, See Also
Sends data using a connected socket.

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

Parameters
var Buf
Buffer to write to the socket.
len: Integer
Length of the write buffer.
flags: Integer
Flags to modify socket options.
Return Value
Integer - Number of bytes read.
Description
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.

TIdSocketHandle.SendTo
TIdSocketHandle, See Also
Sends data to a specific address.

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

Parameters
const AIP: string
IP address of the remote system.
const APort: Integer
Port number of the remote system.
var ABuffer
Buffer to send over the socket connection.
const ABufferSize: Integer
Size of the send buffer.
Description
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.

TIdSocketHandle.SetPeer
TIdSocketHandle, See Also
Updates the remote address of a socket connection.

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

Parameters
const asIP: string
IP address for the remote connection.
anPort: integer
Port number for the remote connection.
Description
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.

TIdSocketHandle.SetSockOpt
TIdSocketHandle
Sets socket options.

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

Parameters
level: Integer
Option level Id_SOL_SOCKET, Id_IPPROTO_TCP, or Id_IPPROTO_IP.
optname: Integer
Socket option to receive the option value.
optval: PChar
Value for the requested option.
optlen: Integer
Length of the option value buffer.
Description
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.

TIdSocketHandle.UpdateBindingLocal
TIdSocketHandle, See Also
Updates the protocol family, and address for a socket handle.

    procedure UpdateBindingLocal;

Description
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.

TIdSocketHandle.UpdateBindingPeer
TIdSocketHandle, See Also
Updates the protocol family and remote address for a socket connection.

    procedure UpdateBindingPeer;

Description
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.

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