--- product: Chilkat product_version: 11.7.0 language: pascal language_label: Lazarus Pascal class: Socket license: bundle deprecated: false reference_html: https://www.chilkatsoft.com/refdoc/pascal_SocketRef.html --- # Chilkat Socket — Lazarus Pascal — v11.7.0 > Chilkat 11.7.0 · language=pascal · class=Socket > Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0//classes/Socket.md`. > Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/guide.md`. ## Purpose **Build custom TCP, TLS, proxy, SSH-tunneled, client/server, and socket-level protocols.** `Chilkat.Socket` is the low-level networking class for applications that need direct control over TCP and TLS communication. It can connect as a client, accept incoming connections, send and receive text or binary data, use proxies or SSH tunnels, configure TLS certificates and socket options, manage timeouts, work with socket sets, collect performance counters, and produce detailed diagnostics and session logs for custom protocol troubleshooting. **TCP client connections** Connect to remote hosts and ports for custom protocols or direct socket-level communication. **TLS and certificates** Use SSL/TLS, inspect certificates, provide client certificates, and control TLS-related behavior when secure sockets are required. **Send and receive data** Send and receive strings, byte data, files, fixed-size blocks, delimiter-terminated messages, or protocol-specific data patterns. **Server-side sockets** Listen for and accept incoming client connections when implementing simple socket servers or custom listener workflows. **Proxy and SSH tunneling** Route socket connections through HTTP proxies, SOCKS proxies, or SSH-tunneled connections when network topology requires it. **Timeouts and diagnostics** Configure connection and read/write timeouts, monitor counters, and use logs and `LastErrorText` to diagnose connection or protocol failures. **Common pattern:** Use `Socket` when the application is implementing a custom protocol or needs lower-level control than higher-level Chilkat classes provide. Configure the connection, TLS, proxy, timeout, and logging options, connect or accept a client, then send and receive data according to the protocol. Use higher-level classes such as `Http`, `Rest`, `Ssh`, `SFtp`, or `MailMan` when the protocol is already directly supported. For an extended overview, see [Socket Class Overview](https://www.chilkatsoft.com/socket_class_overview.asp). ## Object creation, unlocking and error handling **Create / Free** ```pascal uses Chilkat.Socket; var obj: TSocket; begin obj := TSocket.Create; try if not obj.IsValid then raise Exception.Create('Failed to create a TSocket instance.'); // ... use obj ... finally obj.Free; end; end; ``` `constructor Create;` Allocates the underlying CkSocket object and returns a new TSocket instance. Simply adding **Chilkat.Socket** to the unit's `uses` clause is enough to locate and bind to the Chilkat shared library (DLL / .so / .dylib) at runtime — no separate load step is required. Check `obj.IsValid` after calling `Create`; it is `False` if the underlying library could not be found/loaded or the object could not be allocated (for example, when unlicensed). `destructor Destroy; override;` Every TSocket created by calling `Create` should eventually be released by calling `.Free` (inherited from `TObject`). The destructor automatically disposes the underlying CkSocket handle. A native (unmanaged) memory leak occurs if the object is never freed. Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in Lazarus Pascal. ## Members common to every Chilkat class Documented once per language in `common-members.md`; listed here so this page is self-contained. | Property | Signature | Access | Meaning | |---|---|---|---| | `DebugLogFilePath` | `property DebugLogFilePath: string read GetDebugLogFilePath write SetDebugLogFilePath;` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. | | `LastErrorHtml` | `property LastErrorHtml: string read GetLastErrorHtml;` | read-only | Provides HTML-formatted information about the last called method or property. | | `LastErrorText` | `property LastErrorText: string read GetLastErrorText;` | read-only | Provides plain text information about the last called method or property. | | `LastErrorXml` | `property LastErrorXml: string read GetLastErrorXml;` | read-only | Provides XML-formatted information about the last called method or property. | | `LastMethodSuccess` | `property LastMethodSuccess: Boolean read GetLastMethodSuccess write SetLastMethodSuccess;` | read/write | Indicates the success or failure of the most recent method call: `True` means success, `False` means failure. | | `VerboseLogging` | `property VerboseLogging: Boolean read GetVerboseLogging write SetVerboseLogging;` | read/write | If set to `True`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. | | `Version` | `property Version: string read GetVersion;` | read-only | Version of the component/library, such as "10.1.0" | ## Member index | Member | Kind | Signature | |---|---|---| | `AbortCurrent` | property, read/write | `property AbortCurrent: Boolean read GetAbortCurrent write SetAbortCurrent;` | | `AcceptFailReason` | property, read-only | `property AcceptFailReason: Integer read GetAcceptFailReason;` | | `AlpnProtocol` | property, read/write | `property AlpnProtocol: string read GetAlpnProtocol write SetAlpnProtocol;` | | `AlpnProtocols` | property, read/write | `property AlpnProtocols: string read GetAlpnProtocols write SetAlpnProtocols;` | | `BandwidthThrottleDown` | property, read/write | `property BandwidthThrottleDown: Integer read GetBandwidthThrottleDown write SetBandwidthThrottleDown;` | | `BandwidthThrottleUp` | property, read/write | `property BandwidthThrottleUp: Integer read GetBandwidthThrottleUp write SetBandwidthThrottleUp;` | | `BigEndian` | property, read/write | `property BigEndian: Boolean read GetBigEndian write SetBigEndian;` | | `ClientIpAddress` | property, read/write | `property ClientIpAddress: string read GetClientIpAddress write SetClientIpAddress;` | | `ClientPort` | property, read/write | `property ClientPort: Integer read GetClientPort write SetClientPort;` | | `ConnectFailReason` | property, read-only | `property ConnectFailReason: Integer read GetConnectFailReason;` | | `ElapsedSeconds` | property, read-only | `property ElapsedSeconds: Integer read GetElapsedSeconds;` | | `HeartbeatMs` | property, read/write | `property HeartbeatMs: Integer read GetHeartbeatMs write SetHeartbeatMs;` | | `HttpProxyAuthMethod` | property, read/write | `property HttpProxyAuthMethod: string read GetHttpProxyAuthMethod write SetHttpProxyAuthMethod;` | | `HttpProxyDomain` | property, read/write | `property HttpProxyDomain: string read GetHttpProxyDomain write SetHttpProxyDomain;` | | `HttpProxyForHttp` | property, read/write | `property HttpProxyForHttp: Boolean read GetHttpProxyForHttp write SetHttpProxyForHttp;` | | `HttpProxyHostname` | property, read/write | `property HttpProxyHostname: string read GetHttpProxyHostname write SetHttpProxyHostname;` | | `HttpProxyPassword` | property, read/write | `property HttpProxyPassword: string read GetHttpProxyPassword write SetHttpProxyPassword;` | | `HttpProxyPort` | property, read/write | `property HttpProxyPort: Integer read GetHttpProxyPort write SetHttpProxyPort;` | | `HttpProxyUsername` | property, read/write | `property HttpProxyUsername: string read GetHttpProxyUsername write SetHttpProxyUsername;` | | `IsConnected` | property, read-only | `property IsConnected: Boolean read GetIsConnected;` | | `KeepAlive` | property, read/write | `property KeepAlive: Boolean read GetKeepAlive write SetKeepAlive;` | | `KeepSessionLog` | property, read/write | `property KeepSessionLog: Boolean read GetKeepSessionLog write SetKeepSessionLog;` | | `LastMethodFailed` | property, read-only | `property LastMethodFailed: Boolean read GetLastMethodFailed;` | | `ListenPort` | property, read-only | `property ListenPort: Integer read GetListenPort;` | | `LocalIpAddress` | property, read-only | `property LocalIpAddress: string read GetLocalIpAddress;` | | `LocalPort` | property, read-only | `property LocalPort: Integer read GetLocalPort;` | | `MaxReadIdleMs` | property, read/write | `property MaxReadIdleMs: Integer read GetMaxReadIdleMs write SetMaxReadIdleMs;` | | `MaxSendIdleMs` | property, read/write | `property MaxSendIdleMs: Integer read GetMaxSendIdleMs write SetMaxSendIdleMs;` | | `MyIpAddress` | property, read-only | `property MyIpAddress: string read GetMyIpAddress;` | | `NumBytesAvailable` | property, read-only | `property NumBytesAvailable: Integer read GetNumBytesAvailable;` | | `NumReceivedClientCerts` | property, read-only | `property NumReceivedClientCerts: Integer read GetNumReceivedClientCerts;` | | `NumSocketsInSet` | property, read-only | `property NumSocketsInSet: Integer read GetNumSocketsInSet;` | | `NumSslAcceptableClientCAs` | property, read-only | `property NumSslAcceptableClientCAs: Integer read GetNumSslAcceptableClientCAs;` | | `ObjectId` | property, read-only | `property ObjectId: Integer read GetObjectId;` | | `PercentDoneScale` | property, read/write | `property PercentDoneScale: Integer read GetPercentDoneScale write SetPercentDoneScale;` | | `PreferIpv6` | property, read/write | `property PreferIpv6: Boolean read GetPreferIpv6 write SetPreferIpv6;` | | `RcvBytesPerSec` | property, read-only | `property RcvBytesPerSec: Integer read GetRcvBytesPerSec;` | | `ReceivedCount` | property, read/write | `property ReceivedCount: Integer read GetReceivedCount write SetReceivedCount;` | | `ReceivedInt` | property, read/write | `property ReceivedInt: Integer read GetReceivedInt write SetReceivedInt;` | | `ReceiveFailReason` | property, read-only | `property ReceiveFailReason: Integer read GetReceiveFailReason;` | | `ReceivePacketSize` | property, read/write | `property ReceivePacketSize: Integer read GetReceivePacketSize write SetReceivePacketSize;` | | `RemoteIpAddress` | property, read-only | `property RemoteIpAddress: string read GetRemoteIpAddress;` | | `RemotePort` | property, read-only | `property RemotePort: Integer read GetRemotePort;` | | `RequireSniMatch` | property, read/write | `property RequireSniMatch: Boolean read GetRequireSniMatch write SetRequireSniMatch;` | | `RequireSslCertVerify` | property, read/write | `property RequireSslCertVerify: Boolean read GetRequireSslCertVerify write SetRequireSslCertVerify;` | | `SelectorIndex` | property, read/write | `property SelectorIndex: Integer read GetSelectorIndex write SetSelectorIndex;` | | `SelectorReadIndex` | property, read/write | `property SelectorReadIndex: Integer read GetSelectorReadIndex write SetSelectorReadIndex;` | | `SelectorWriteIndex` | property, read/write | `property SelectorWriteIndex: Integer read GetSelectorWriteIndex write SetSelectorWriteIndex;` | | `SendBytesPerSec` | property, read-only | `property SendBytesPerSec: Integer read GetSendBytesPerSec;` | | `SendFailReason` | property, read-only | `property SendFailReason: Integer read GetSendFailReason;` | | `SendPacketSize` | property, read/write | `property SendPacketSize: Integer read GetSendPacketSize write SetSendPacketSize;` | | `SessionLog` | property, read-only | `property SessionLog: string read GetSessionLog;` | | `SessionLogEncoding` | property, read/write | `property SessionLogEncoding: string read GetSessionLogEncoding write SetSessionLogEncoding;` | | `SniHostname` | property, read/write | `property SniHostname: string read GetSniHostname write SetSniHostname;` | | `SocksHostname` | property, read/write | `property SocksHostname: string read GetSocksHostname write SetSocksHostname;` | | `SocksPassword` | property, read/write | `property SocksPassword: string read GetSocksPassword write SetSocksPassword;` | | `SocksPort` | property, read/write | `property SocksPort: Integer read GetSocksPort write SetSocksPort;` | | `SocksUsername` | property, read/write | `property SocksUsername: string read GetSocksUsername write SetSocksUsername;` | | `SocksVersion` | property, read/write | `property SocksVersion: Integer read GetSocksVersion write SetSocksVersion;` | | `SoRcvBuf` | property, read/write | `property SoRcvBuf: Integer read GetSoRcvBuf write SetSoRcvBuf;` | | `SoReuseAddr` | property, read/write | `property SoReuseAddr: Boolean read GetSoReuseAddr write SetSoReuseAddr;` | | `SoSndBuf` | property, read/write | `property SoSndBuf: Integer read GetSoSndBuf write SetSoSndBuf;` | | `Ssl` | property, read/write | `property Ssl: Boolean read GetSsl write SetSsl;` | | `SslAllowedCiphers` | property, read/write | `property SslAllowedCiphers: string read GetSslAllowedCiphers write SetSslAllowedCiphers;` | | `SslProtocol` | property, read/write | `property SslProtocol: string read GetSslProtocol write SetSslProtocol;` | | `StringCharset` | property, read/write | `property StringCharset: string read GetStringCharset write SetStringCharset;` | | `TcpNoDelay` | property, read/write | `property TcpNoDelay: Boolean read GetTcpNoDelay write SetTcpNoDelay;` | | `TlsCipherSuite` | property, read-only | `property TlsCipherSuite: string read GetTlsCipherSuite;` | | `TlsPinSet` | property, read/write | `property TlsPinSet: string read GetTlsPinSet write SetTlsPinSet;` | | `TlsSessionResumed` | property, read-only | `property TlsSessionResumed: Boolean read GetTlsSessionResumed;` | | `TlsTicketLifetimeSeconds` | property, read/write | `property TlsTicketLifetimeSeconds: Integer read GetTlsTicketLifetimeSeconds write SetTlsTicketLifetimeSeconds;` | | `TlsVersion` | property, read-only | `property TlsVersion: string read GetTlsVersion;` | | `UncommonOptions` | property, read/write | `property UncommonOptions: string read GetUncommonOptions write SetUncommonOptions;` | | `UserData` | property, read/write | `property UserData: string read GetUserData write SetUserData;` | | `AcceptNext` | method | `// socket is a TSocket object. function AcceptNext(maxWaitMs: Integer;     socket: TChilkatBase): Boolean;` | | `AddSslAcceptableClientCaDn` | method | `function AddSslAcceptableClientCaDn(const certAuthDN: string): Boolean;` | | `AddSslServerCert` | method | `// cert is a TCert object. function AddSslServerCert(cert: TChilkatBase;     const hostname: string): Boolean;` | | `BindAndListen` | method | `function BindAndListen(port: Integer;     backLog: Integer): Boolean;` | | `BindAndListenPortRange` | method | `function BindAndListenPortRange(beginPort: Integer;     endPort: Integer;     backLog: Integer): Integer;` | | `BuildHttpGetRequest` | method | `function BuildHttpGetRequest(const url: string): string;` | | `CheckWriteable` | method | `function CheckWriteable(maxWaitMs: Integer): Integer;` | | `ClearSessionLog` | method | `procedure ClearSessionLog;` | | `ClearSslServerCerts` | method | `procedure ClearSslServerCerts;` | | `Close` | method | `function Close(maxWaitMs: Integer): Boolean;` | | `Connect` | method | `function Connect(const hostname: string;     port: Integer;     ssl: Boolean;     maxWaitMs: Integer): Boolean;` | | `ConvertFromSsl` | method | `function ConvertFromSsl: Boolean;` | | `ConvertToSsl` | method | `function ConvertToSsl: Boolean;` | | `DnsCacheClear` | method | `procedure DnsCacheClear;` | | `DnsLookup` | method | `function DnsLookup(const hostname: string;     maxWaitMs: Integer): string;` | | `DupSocket` | method | `// dest is a TSocket object. function DupSocket(dest: TChilkatBase): Boolean;` | | `GetAdaptersAddresses` | method | `// json is a TJsonObject object. function GetAdaptersAddresses(json: TChilkatBase): Boolean;` | | `GetLastJsonData` | method | `// json is a TJsonObject object. procedure GetLastJsonData(json: TChilkatBase);` | | `GetMyServerCert` | method | `// cert is a TCert object. function GetMyServerCert(cert: TChilkatBase): Boolean;` | | `GetRcvdClientCert` | method | `// cert is a TCert object. function GetRcvdClientCert(index: Integer;     cert: TChilkatBase): Boolean;` | | `GetServerCert` | method | `// cert is a TCert object. function GetServerCert(cert: TChilkatBase): Boolean;` | | `GetSslAcceptableClientCaDn` | method | `function GetSslAcceptableClientCaDn(index: Integer): string;` | | `InitSslServer` | method | `// cert is a TCert object. function InitSslServer(cert: TChilkatBase): Boolean;` | | `LoadTaskCaller` | method | `// task is a TTask object. function LoadTaskCaller(task: TChilkatBase): Boolean;` | | `LoadTaskResult` | method | `// task is a TTask object. function LoadTaskResult(task: TChilkatBase): Boolean;` | | `PollDataAvailable` | method | `function PollDataAvailable: Boolean;` | | `ReceiveBd` | method | `// binData is a TBinData object. function ReceiveBd(binData: TChilkatBase): Boolean;` | | `ReceiveBdN` | method | `// binData is a TBinData object. function ReceiveBdN(numBytes: LongWord;     binData: TChilkatBase): Boolean;` | | `ReceiveByte` | method | `function ReceiveByte(bUnsigned: Boolean): Boolean;` | | `ReceiveBytesENC` | method | `function ReceiveBytesENC(const encodingAlg: string): string;` | | `ReceiveBytesToFile` | method | `function ReceiveBytesToFile(const appendFilename: string): Boolean;` | | `ReceiveCount` | method | `function ReceiveCount: Integer;` | | `ReceiveInt16` | method | `function ReceiveInt16(bigEndian: Boolean;     bUnsigned: Boolean): Boolean;` | | `ReceiveInt32` | method | `function ReceiveInt32(bigEndian: Boolean): Boolean;` | | `ReceiveNBytesENC` | method | `function ReceiveNBytesENC(numBytes: LongWord;     const encodingAlg: string): string;` | | `ReceiveSb` | method | `// sb is a TStringBuilder object. function ReceiveSb(sb: TChilkatBase): Boolean;` | | `ReceiveString` | method | `function ReceiveString: string;` | | `ReceiveStringMaxN` | method | `function ReceiveStringMaxN(maxByteCount: Integer): string;` | | `ReceiveStringUntilByte` | method | `function ReceiveStringUntilByte(lookForByte: Integer): string;` | | `ReceiveToCRLF` | method | `function ReceiveToCRLF: string;` | | `ReceiveUntilByteBd` | method | `// bd is a TBinData object. function ReceiveUntilByteBd(lookForByte: Integer;     bd: TChilkatBase): Boolean;` | | `ReceiveUntilMatch` | method | `function ReceiveUntilMatch(const matchStr: string): string;` | | `ReceiveUntilMatchSb` | method | `// sb is a TStringBuilder object. function ReceiveUntilMatchSb(const matchStr: string;     sb: TChilkatBase): Boolean;` | | `ResetPerf` | method | `procedure ResetPerf(rcvPerf: Boolean);` | | `SelectForReading` | method | `function SelectForReading(timeoutMs: Integer): Integer;` | | `SelectForWriting` | method | `function SelectForWriting(timeoutMs: Integer): Integer;` | | `SendBd` | method | `// binData is a TBinData object. function SendBd(binData: TChilkatBase;     offset: LongWord;     numBytes: LongWord): Boolean;` | | `SendByte` | method | `function SendByte(value: Integer): Boolean;` | | `SendBytesENC` | method | `function SendBytesENC(const encodedBytes: string;     const encodingAlg: string): Boolean;` | | `SendCount` | method | `function SendCount(byteCount: Integer): Boolean;` | | `SendInt16` | method | `function SendInt16(value: Integer;     bigEndian: Boolean): Boolean;` | | `SendInt32` | method | `function SendInt32(value: Integer;     bigEndian: Boolean): Boolean;` | | `SendSb` | method | `// sb is a TStringBuilder object. function SendSb(sb: TChilkatBase): Boolean;` | | `SendString` | method | `function SendString(const stringToSend: string): Boolean;` | | `SendWakeOnLan` | method | `function SendWakeOnLan(const macAddress: string;     port: Integer;     const ipBroadcastAddr: string): Boolean;` | | `SendWakeOnLan2` | method | `function SendWakeOnLan2(const macAddress: string;     port: Integer;     const ipBroadcastAddr: string;     const password: string): Boolean;` | | `SetSslClientCert` | method | `// cert is a TCert object. function SetSslClientCert(cert: TChilkatBase): Boolean;` | | `SetSslClientCertPem` | method | `function SetSslClientCertPem(const pemDataOrFilename: string;     const pemPassword: string): Boolean;` | | `SetSslClientCertPfx` | method | `function SetSslClientCertPfx(const pfxFilename: string;     const pfxPassword: string): Boolean;` | | `SetTlsTicketKey` | method | `// binKey is a TBinData object. function SetTlsTicketKey(binKey: TChilkatBase): Boolean;` | | `SleepMs` | method | `procedure SleepMs(millisec: Integer);` | | `SshAuthenticatePk` | method | `// privateKey is a TSshKey object. function SshAuthenticatePk(const sshLogin: string;     privateKey: TChilkatBase): Boolean;` | | `SshAuthenticatePw` | method | `function SshAuthenticatePw(const sshLogin: string;     const sshPassword: string): Boolean;` | | `SshCloseTunnel` | method | `function SshCloseTunnel: Boolean;` | | `SshNewChannel` | method | `// channel is a TSocket object. function SshNewChannel(const hostname: string;     port: Integer;     ssl: Boolean;     maxWaitMs: Integer;     channel: TChilkatBase): Boolean;` | | `SshOpenTunnel` | method | `function SshOpenTunnel(const sshHostname: string;     sshPort: Integer): Boolean;` | | `StartTiming` | method | `procedure StartTiming;` | | `TakeConnection` | method | `// sock is a TSocket object. function TakeConnection(sock: TChilkatBase): Boolean;` | | `TakeSocket` | method | `// sock is a TSocket object. function TakeSocket(sock: TChilkatBase): Boolean;` | | `TlsRenegotiate` | method | `function TlsRenegotiate: Boolean;` | | `UseSsh` | method | `// ssh is a TSsh object. function UseSsh(ssh: TChilkatBase): Boolean;` | ## Properties ### Socket.AbortCurrent `Chilkat 11.7.0 · pascal · Socket · AbortCurrent · property · read/write · since 9.5.0.58` ```pascal property AbortCurrent: Boolean read GetAbortCurrent write SetAbortCurrent; ``` Set this property to `True` to request cancellation of the method currently executing on this object. It affects operations that can block or take significant time, such as network reads, writes, connection establishment, and long-running asynchronous methods. Fast, nonblocking methods may finish before the cancellation request is observed. After an operation aborts, Chilkat automatically resets this property to `False`. If no operation is running, the next method call clears a previously set value before it begins. **Note:** A synchronous call can be cancelled from another thread by setting this property on the same object. The method returns its normal failure value, and `LastErrorText` describes the abort. ### Socket.AcceptFailReason `Chilkat 11.7.0 · pascal · Socket · AcceptFailReason · property · read-only · since 9.5.0.50` ```pascal property AcceptFailReason: Integer read GetAcceptFailReason; ``` Contains the numeric result for the most recent `AcceptNext` or deprecated `AcceptNextConnection` operation. The initial value is `0`. It is reset to `0` when an accept begins, remains `0` on success, and is set to a reason code on failure. **May describe an older accept:** Connect, send, receive, and ordinary property operations do not clear this property. Read it immediately after the accept operation whose result is being examined. | Code | Meaning | | --- | --- | | 0 | Success. | | 1 | An asynchronous accept operation is already in progress. | | 3 | Internal failure, such as an allocation failure. | | 5 | No incoming connection was accepted before the wait interval expired. | | 6 | The operation was aborted by the application. | | 9 | An unspecified fatal socket error occurred. | | 20 | The socket has not first been bound and placed into listening mode. | | 99 | The Chilkat component is not unlocked. | | 100 | TLS internal error. | | 102 | Unexpected TLS handshake message. | | 109 | Failed to read TLS handshake messages. | | 114 | Failed to send the ChangeCipherSpec message. | | 115 | Failed to send the Finished message. | | 116 | The client's Finished message was invalid. | | 117 | Unable to agree on a TLS protocol version. | | 118 | Unable to agree on a cipher suite. | | 119 | Failed to read the client's ClientHello message. | | 120 | Failed to send TLS handshake messages. | | 121 | Failed to process the client certificate message. | | 122 | Failed to process the client certificate URL message. | | 123 | Failed to process the client key-exchange message. | | 124 | Failed to process the CertificateVerify message. | | 125 | An SSL 2.0 connection attempt was received and rejected. | | 129 | The client and server share no ALPN protocol. (Added in 11.7.0. See `AlpnProtocols`.) | | 130 | The client's SNI hostname matched no server certificate and `RequireSniMatch` is set. (Added in 11.7.0.) | | 131 | The client offered a session ticket for a session that used the extended master secret, but its ClientHello did not offer that extension. (Added in 11.7.0.) | ### Socket.AlpnProtocol `Chilkat 11.7.0 · pascal · Socket · AlpnProtocol · property · read/write · since 9.5.0.82` ```pascal property AlpnProtocol: string read GetAlpnProtocol write SetAlpnProtocol; ``` A single application-layer protocol name for the TLS ALPN extension, such as `h2` or `http/1.1`. Leave it empty when ALPN is not required. Setting this property sets the ALPN list to this one protocol, replacing anything previously set by it or by `AlpnProtocols`. Setting an empty string clears the list. To offer or support more than one protocol, use `AlpnProtocols` instead. Getting this property returns the protocol that was negotiated for the connection. Before a handshake has completed, and on a connection where ALPN was not negotiated, it returns the first protocol in the ALPN list, which for an application that set a single protocol is the protocol it set. **Changed in 11.7.0:** After a handshake this property returns the negotiated protocol rather than the configured one. For a connection that negotiated the protocol that was set – which is every case prior to 11.7.0, because only one protocol could be offered – the value is unchanged. Prior to 11.7.0 a TLS server ignored ALPN entirely, and a TLS client could offer only one protocol. **Note:** ALPN negotiation does not implement the selected application protocol. The application must still speak that protocol over the established TLS connection. ### Socket.AlpnProtocols `Chilkat 11.7.0 · pascal · Socket · AlpnProtocols · property · read/write · since 11.7.0` ```pascal property AlpnProtocols: string read GetAlpnProtocols write SetAlpnProtocols; ``` The list of ALPN (Application-Layer Protocol Negotiation) protocols, in preference order, as JSON. On a TLS client this is the set of protocols offered. On a TLS listener it is the set of protocols the server supports. Setting this property accepts either a JSON array, such as `["h2","http/1.1"]`, or a JSON object with a `protocols` member, such as `{"protocols":["h2","http/1.1"]}`. Setting an empty string clears the list. Getting this property returns the object form, so a value read from it can be passed back to it unchanged. This property and `AlpnProtocol` address the same underlying list. Setting `AlpnProtocol` replaces the list with that single protocol id, and setting this property replaces the whole list. An application normally uses one or the other. An object that leaves the list empty does not use ALPN at all. **Server behavior when nothing matches:** A TLS server that sets this list and shares no protocol with the client refuses the connection with the `no_application_protocol` alert, as RFC 7301 requires, and `AcceptFailReason` is set to 129. A server that leaves the list empty ignores ALPN and accepts the connection. **Note:** ALPN negotiation does not implement the selected application protocol. The application must still speak that protocol over the established TLS connection. ### Socket.BandwidthThrottleDown `Chilkat 11.7.0 · pascal · Socket · BandwidthThrottleDown · property · read/write · since 9.5.0.49` ```pascal property BandwidthThrottleDown: Integer read GetBandwidthThrottleDown write SetBandwidthThrottleDown; ``` Limits receive throughput to approximately the specified number of bytes per second. The default value is `0`, which disables receive throttling. **Note:** The limit is approximate and is applied over time; it does not define socket packet sizes or message boundaries. ### Socket.BandwidthThrottleUp `Chilkat 11.7.0 · pascal · Socket · BandwidthThrottleUp · property · read/write · since 9.5.0.49` ```pascal property BandwidthThrottleUp: Integer read GetBandwidthThrottleUp write SetBandwidthThrottleUp; ``` Limits send throughput to approximately the specified number of bytes per second. The default value is `0`, which disables send throttling. **Note:** The limit is approximate and is applied over time; it does not define socket packet sizes or message boundaries. ### Socket.BigEndian `Chilkat 11.7.0 · pascal · Socket · BigEndian · property · read/write` ```pascal property BigEndian: Boolean read GetBigEndian write SetBigEndian; ``` Controls the byte order used by `SendCount` and `ReceiveCount`. The default is `True`, which uses big-endian byte order (network byte order). Set it to `False` to use little-endian byte order. **Note:** This property applies only to the four-byte count methods. The `SendInt16`, `SendInt32`, `ReceiveInt16`, and `ReceiveInt32` methods receive their byte-order choice as an argument. ### Socket.ClientIpAddress `Chilkat 11.7.0 · pascal · Socket · ClientIpAddress · property · read/write` ```pascal property ClientIpAddress: string read GetClientIpAddress write SetClientIpAddress; ``` Specifies a numeric local IP address to use when binding the socket to a local interface. - **Outbound connections:** Before `Connect` establishes the connection, the local socket is bound to this address. Leave the property empty to let the operating system choose the local source address. - **Listeners:** `BindAndListen` and `BindAndListenPortRange` bind to exactly this address. Leave the property empty to listen on all interfaces: `0.0.0.0` for IPv4 or `::` for IPv6. | `ClientIpAddress` | IPv6 preference | Listener bind address | | --- | --- | --- | | Empty | `False` | `0.0.0.0` (all IPv4 interfaces) | | Empty | `True` | `::` (all IPv6 interfaces) | | Explicit address | Not used to choose the family | Exactly the specified address | **Important:** Supply a numeric IPv4 or IPv6 address assigned to the local computer, not a DNS hostname or remote address. Setting `127.0.0.1` or `::1` creates a loopback-only listener that remote computers cannot reach. ### Socket.ClientPort `Chilkat 11.7.0 · pascal · Socket · ClientPort · property · read/write` ```pascal property ClientPort: Integer read GetClientPort write SetClientPort; ``` Specifies the local TCP port to bind before initiating an outbound connection. The default value is `0`, which asks the operating system to choose an available ephemeral port. **Important:** Setting a fixed client port is unusual and can cause connection failures when the port is already in use or unavailable. Use a nonzero value only when the remote system or network policy explicitly requires a particular source port. ### Socket.ConnectFailReason `Chilkat 11.7.0 · pascal · Socket · ConnectFailReason · property · read-only` ```pascal property ConnectFailReason: Integer read GetConnectFailReason; ``` Contains the numeric result for the most recent connect-family operation, including TCP connection and SSH connection/channel setup. The initial value is `0`. It is reset to `0` when a connect-family call begins, remains `0` on success, and is set to a reason code on failure. **May describe an older connection attempt:** Send, receive, accept, and ordinary property operations do not clear this property. Read it immediately after the connect-family operation whose result is being examined; otherwise it may still contain a reason from an earlier attempt. | Code | Meaning | | --- | --- | | 0 | Success. | | 1 | The hostname is empty. | | 2 | DNS lookup failed. | | 3 | DNS lookup timed out. | | 4 | The operation was aborted by the application. | | 5 | Internal failure. | | 6 | The TCP connection attempt timed out. | | 7 | The connection was rejected or otherwise could not be established. | | 100 | TLS internal error. | | 101 | Failed to send ClientHello. | | 102 | Unexpected TLS handshake message. | | 103 | Failed to read ServerHello. | | 104 | The server did not provide a certificate. | | 105 | Unexpected TLS protocol version. | | 106 | Server-certificate verification failed. | | 107 | The negotiated TLS protocol version was not permitted. | | 108 | An application-defined server-certificate requirement failed. | | 109 | Failed to read TLS handshake messages. | | 110 | Failed to send the client-certificate message. | | 111 | Failed to send the client key-exchange message. | | 112 | The client certificate's private key was not accessible. | | 113 | Failed to send the client CertificateVerify message. | | 114 | Failed to send the ChangeCipherSpec message. | | 115 | Failed to send the Finished message. | | 116 | The server's Finished message was invalid. | **Note:** The TCP connection timeout supplied to `Connect` is distinct from DNS, proxy, and TLS-handshake inactivity limits. See `MaxReadIdleMs` and `MaxSendIdleMs`. ### Socket.ElapsedSeconds `Chilkat 11.7.0 · pascal · Socket · ElapsedSeconds · property · read-only` ```pascal property ElapsedSeconds: Integer read GetElapsedSeconds; ``` Returns the whole number of seconds elapsed since the most recent call to `StartTiming`. It returns `0` if timing has not been started or less than one second has elapsed. **Note:** This convenience timer is associated with the object; it is not a network timeout and does not affect socket operations. ### Socket.HeartbeatMs `Chilkat 11.7.0 · pascal · Socket · HeartbeatMs · property · read/write` ```pascal property HeartbeatMs: Integer read GetHeartbeatMs write SetHeartbeatMs; ``` **Full documentation for this property (same in every language):** [Event Callback Examples](https://www.chilkatsoft.com/ai-docs/v/11.7.0/articles/event_callback_examples.md) Specifies the interval, in milliseconds, between `AbortCheck` callbacks during supported long-running operations. The default is `0`, which disables periodic `AbortCheck` callbacks. **Note:** This setting does not send network heartbeat packets and does not implement TCP keepalive. It only controls application callbacks that provide an opportunity to cancel an operation. ### Socket.HttpProxyAuthMethod `Chilkat 11.7.0 · pascal · Socket · HttpProxyAuthMethod · property · read/write` ```pascal property HttpProxyAuthMethod: string read GetHttpProxyAuthMethod write SetHttpProxyAuthMethod; ``` Specifies the authentication method used with an HTTP proxy. Supported values are `Basic` and `NTLM`. Leave it empty when the proxy does not require authentication. **Important:** Basic proxy credentials are only encoded, not encrypted. Protect them by using an appropriate secure network path to the proxy. ### Socket.HttpProxyDomain `Chilkat 11.7.0 · pascal · Socket · HttpProxyDomain · property · read/write` ```pascal property HttpProxyDomain: string read GetHttpProxyDomain write SetHttpProxyDomain; ``` Specifies the optional Windows domain used for NTLM authentication to an HTTP proxy. It is ignored unless `HttpProxyAuthMethod` is `NTLM`. ### Socket.HttpProxyForHttp `Chilkat 11.7.0 · pascal · Socket · HttpProxyForHttp · property · read/write · since 9.5.0.70` ```pascal property HttpProxyForHttp: Boolean read GetHttpProxyForHttp write SetHttpProxyForHttp; ``` Set this property to `True` when the proxied connection will carry HTTP requests, such as when a `Rest` object uses this socket through `UseConnection`. The default is `False`. An HTTP client can communicate with a proxy differently from a non-HTTP protocol. For example, plain HTTP commonly sends an absolute request URI to the proxy, whereas other protocols generally require an HTTP `CONNECT` tunnel. **Important:** Set this before connecting through the HTTP proxy. An incorrect value can produce a connection that is established using the wrong proxy mode for the application protocol. ### Socket.HttpProxyHostname `Chilkat 11.7.0 · pascal · Socket · HttpProxyHostname · property · read/write` ```pascal property HttpProxyHostname: string read GetHttpProxyHostname write SetHttpProxyHostname; ``` Specifies the hostname or numeric IP address of the HTTP proxy. Leave it empty to connect directly without an HTTP proxy. ### Socket.HttpProxyPassword `Chilkat 11.7.0 · pascal · Socket · HttpProxyPassword · property · read/write` ```pascal property HttpProxyPassword: string read GetHttpProxyPassword write SetHttpProxyPassword; ``` Specifies the password used to authenticate with the HTTP proxy. It is used together with `HttpProxyUsername` and the selected `HttpProxyAuthMethod`. **Important:** Do not write proxy passwords to logs or expose them in diagnostic output. ### Socket.HttpProxyPort `Chilkat 11.7.0 · pascal · Socket · HttpProxyPort · property · read/write` ```pascal property HttpProxyPort: Integer read GetHttpProxyPort write SetHttpProxyPort; ``` Specifies the TCP port of the HTTP proxy. Common values include `8080` and `3128`, but the correct port is determined by the proxy configuration. ### Socket.HttpProxyUsername `Chilkat 11.7.0 · pascal · Socket · HttpProxyUsername · property · read/write` ```pascal property HttpProxyUsername: string read GetHttpProxyUsername write SetHttpProxyUsername; ``` Specifies the username used to authenticate with the HTTP proxy. It is ignored when the proxy does not require authentication. ### Socket.IsConnected `Chilkat 11.7.0 · pascal · Socket · IsConnected · property · read-only` ```pascal property IsConnected: Boolean read GetIsConnected; ``` Returns `True` when the socket is in its last known connected state; otherwise returns `False`. Explicitly closing the socket updates this property immediately. **Important:** TCP does not continuously notify an idle application that a peer or network path has disappeared. This property can remain `True` until a read, write, or other socket operation detects the loss. Treat it as a cached state indicator, not a guarantee that the next operation will succeed. ### Socket.KeepAlive `Chilkat 11.7.0 · pascal · Socket · KeepAlive · property · read/write · since 9.5.0.49` ```pascal property KeepAlive: Boolean read GetKeepAlive write SetKeepAlive; ``` Controls the operating system `SO_KEEPALIVE` option for the underlying TCP socket. The default is `True`. **Note:** TCP keepalive is distinct from an application-protocol heartbeat. The operating system controls the keepalive timing and retry policy unless configured by platform-specific means. ### Socket.KeepSessionLog `Chilkat 11.7.0 · pascal · Socket · KeepSessionLog · property · read/write` ```pascal property KeepSessionLog: Boolean read GetKeepSessionLog write SetKeepSessionLog; ``` Set this property to `True` to record bytes sent and received through this wrapper in `SessionLog`. The default is `False`. Use `SessionLogEncoding` to choose how bytes are rendered. **Important:** Session logs can contain credentials, tokens, private application data, or decrypted TLS payloads. Enable logging only for diagnostics and protect or remove the resulting data. ### Socket.LastMethodFailed `Chilkat 11.7.0 · pascal · Socket · LastMethodFailed · property · read-only` ```pascal property LastMethodFailed: Boolean read GetLastMethodFailed; ``` Returns `True` if the most recent action method called through this wrapper failed; otherwise returns `False`. The initial value is `False`. An action method clears this state when it begins and leaves it `False` on success or sets it to `True` on failure. Ordinary value-property getters, such as the local and remote address/port properties, timeout properties, `Ssl`, `BigEndian`, and the failure-reason properties, do not change this state. Methods that perform work do change it, including certificate-retrieval methods, `BuildHttpGetRequest`, and `ClearSessionLog`. **Check immediately:** This property describes only the most recent action method. Another method call may overwrite it before it is examined. Prefer the method's own Boolean return value when one is available. ### Socket.ListenPort `Chilkat 11.7.0 · pascal · Socket · ListenPort · property · read-only · since 9.5.0.59` ```pascal property ListenPort: Integer read GetListenPort; ``` Returns the port on which the socket is listening. This is especially useful after calling `BindAndListen` with port `0`, which asks the operating system to select an available port. ### Socket.LocalIpAddress `Chilkat 11.7.0 · pascal · Socket · LocalIpAddress · property · read-only` ```pascal property LocalIpAddress: string read GetLocalIpAddress; ``` Returns the local numeric IP address for the socket connection currently held by this object. For an outbound connection, this is the source address selected or explicitly bound. For a listener, it is the address on which the socket is listening. Returns an empty string when the object holds no connection or listener. The value is read from the current connection and is never retained from an earlier connection. ### Socket.LocalPort `Chilkat 11.7.0 · pascal · Socket · LocalPort · property · read-only` ```pascal property LocalPort: Integer read GetLocalPort; ``` Returns the local TCP port for the socket connection or listener currently held by this object. When binding to port `0`, read this property or `ListenPort` after success to discover the operating-system-selected port. Returns `0` when the object holds no connection or listener. The value is read from the current connection and is never retained from an earlier connection. ### Socket.MaxReadIdleMs `Chilkat 11.7.0 · pascal · Socket · MaxReadIdleMs · property · read/write` ```pascal property MaxReadIdleMs: Integer read GetMaxReadIdleMs write SetMaxReadIdleMs; ``` Specifies the maximum number of milliseconds that a read-related operation may make no receive progress. A positive value is an *inactivity* timeout, not a total-operation deadline. The timer restarts each time a successful low-level read transfers at least one byte. - `0` means no read-idle timeout and permits an indefinite wait. - A positive value limits the longest continuous period with no received data. - Negative values have no defined meaning and should not be used. This property applies to socket receive methods and to protocol exchanges that read from the connection, including TLS handshakes. It also ordinarily governs read inactivity during HTTP/SOCKS proxy negotiation and SSH tunnel setup when no separate timeout is provided. **Idle timeout versus total duration:** A long transfer can continue for longer than this value as long as data keeps arriving. The timeout occurs only when no read progress is made for the full configured interval. **Indefinite waits:** The default is `0`. For operations involving an externally controlled peer, proxy, TLS handshake, or SSH service, consider setting a finite value so an unresponsive endpoint cannot block the operation forever. ### Socket.MaxSendIdleMs `Chilkat 11.7.0 · pascal · Socket · MaxSendIdleMs · property · read/write` ```pascal property MaxSendIdleMs: Integer read GetMaxSendIdleMs write SetMaxSendIdleMs; ``` Specifies the maximum number of milliseconds that a send-related operation may make no write progress. A positive value is an *inactivity* timeout, not a total-operation deadline. The timer restarts each time a successful low-level write transfers at least one byte. - `0` means no send-idle timeout and permits an indefinite wait. - A positive value limits the longest continuous period with no send progress. - Negative values have no defined meaning and should not be used. This property applies to socket send methods and to protocol exchanges that write to the connection, including TLS handshakes. It also ordinarily governs write inactivity during HTTP/SOCKS proxy negotiation and SSH tunnel setup when no separate timeout is provided. **Idle timeout versus total duration:** A large send can continue for longer than this value while bytes continue to move. The timeout occurs only after the full configured interval passes with no write progress. ### Socket.MyIpAddress `Chilkat 11.7.0 · pascal · Socket · MyIpAddress · property · read-only` ```pascal property MyIpAddress: string read GetMyIpAddress; ``` Returns a local IP address for the computer. On a multihomed system, this is a default or preferred local address and may not be the address used by a particular connection. **Note:** This is normally a private or internal address and is not a reliable way to discover a public Internet address behind NAT. For an actual bound or connected socket, use `LocalIpAddress` and `LocalPort`. ### Socket.NumBytesAvailable `Chilkat 11.7.0 · pascal · Socket · NumBytesAvailable · property · read-only · since 9.5.0.94` ```pascal property NumBytesAvailable: Integer read GetNumBytesAvailable; ``` Returns the number of bytes immediately available to the socket layer without waiting. On a TLS connection, the value can include encrypted TLS record overhead and therefore does not necessarily equal the amount of application plaintext available. **Important:** Do not use this value as a message length. TCP is a byte stream, and a complete application message can arrive in multiple reads or multiple messages can be available together. ### Socket.NumReceivedClientCerts `Chilkat 11.7.0 · pascal · Socket · NumReceivedClientCerts · property · read-only` ```pascal property NumReceivedClientCerts: Integer read GetNumReceivedClientCerts; ``` Returns the number of client certificates associated with the connection currently held by this object. On a TLS server, read this property on the accepted connection populated by `AcceptNext`, then call `GetRcvdClientCert` with indexes from `0` through `NumReceivedClientCerts - 1`. Returns `0` when the current connection has no received client certificates or when the object holds no connection. The value is read from the current connection and is never retained from an earlier connection. If `ConvertFromSsl` removes TLS while preserving the underlying connection, the certificate information can remain associated with that same connection. **Important:** Read this property on the accepted connection, not on the listener. Client certificates are normally present only when the server requested mutual TLS authentication. ### Socket.NumSocketsInSet `Chilkat 11.7.0 · pascal · Socket · NumSocketsInSet · property · read-only` ```pascal property NumSocketsInSet: Integer read GetNumSocketsInSet; ``` Returns the number of sockets contained in this object's socket set. A normal `Socket` object becomes a socket set after one or more successful calls to `TakeSocket`. Listener sockets and connected sockets may coexist in the same set. A socket whose peer has closed may remain in the set, and remain included in this count, until the next `SelectForReading` or `SelectForWriting`. A select operation rebuilds the set and automatically prunes members that no longer have a usable descriptor. **Selection:** Use `SelectorIndex` for a direct set position. After a select call, use `SelectorReadIndex` or `SelectorWriteIndex` directly; do not translate the ready index into `SelectorIndex`. **Socket sets overview:** See [Socket Sets Overview](https://www.chilkatsoft.com/socket_sets.asp) for an explanation of socket sets, selectors, readiness, ownership, and common usage patterns. ### Socket.NumSslAcceptableClientCAs `Chilkat 11.7.0 · pascal · Socket · NumSslAcceptableClientCAs · property · read-only` ```pascal property NumSslAcceptableClientCAs: Integer read GetNumSslAcceptableClientCAs; ``` Returns the number of acceptable certificate-authority distinguished names supplied by the TLS server for the connection currently held by this object. Use `GetSslAcceptableClientCaDn` to retrieve each DN by zero-based index. Returns `0` when the current connection supplied no acceptable-CA list or when the object holds no connection. This value is read from the current connection and is never retained from an earlier connection. **Note:** The list is guidance from the server for selecting a client certificate. It does not itself authenticate the server or guarantee that a particular client certificate will be accepted. ### Socket.ObjectId `Chilkat 11.7.0 · pascal · Socket · ObjectId · property · read-only` ```pascal property ObjectId: Integer read GetObjectId; ``` Returns the unique identifier assigned to this socket object. The identifier is included in event callbacks so an application can associate a callback with the originating object. **Note:** The value is for runtime correlation only and should not be persisted as a durable identifier. ### Socket.PercentDoneScale `Chilkat 11.7.0 · pascal · Socket · PercentDoneScale · property · read/write · since 9.5.0.49` ```pascal property PercentDoneScale: Integer read GetPercentDoneScale write SetPercentDoneScale; ``` Defines the numeric value that represents 100 percent in `PercentDone` callbacks. The default is `100`. For example, a scale of `1000` permits tenths-of-a-percent values, so `453` represents 45.3 percent. Values are clamped to the range `10` through `100000`. The property affects only operations whose progress can be measured and only language bindings that expose callbacks. ### Socket.PreferIpv6 `Chilkat 11.7.0 · pascal · Socket · PreferIpv6 · property · read/write` ```pascal property PreferIpv6: Boolean read GetPreferIpv6 write SetPreferIpv6; ``` This property and `ListenIpv6` are two names for the same underlying setting. Reading or writing either property reads or changes the same value. The default is `False`. - **Outbound connections:** When a hostname resolves to both IPv4 and IPv6 addresses, `False` prefers IPv4 and `True` prefers IPv6. - **Listeners:** When `ClientIpAddress` is empty, `False` binds to `0.0.0.0` and `True` binds to `::`. When an explicit `ClientIpAddress` is set, its literal address determines the family. **Note:** A preference does not guarantee that the selected address family is usable. Connection success still depends on DNS results, local routing, firewall policy, and peer availability. ### Socket.RcvBytesPerSec `Chilkat 11.7.0 · pascal · Socket · RcvBytesPerSec · property · read-only · since 9.5.0.78` ```pascal property RcvBytesPerSec: Integer read GetRcvBytesPerSec; ``` Returns the average raw receive rate, in bytes per second, since receive performance measurement began or was last reset. The measurement includes TLS or SSH framing overhead. Call `ResetPerf` with `True` to restart receive measurement. ### Socket.ReceivedCount `Chilkat 11.7.0 · pascal · Socket · ReceivedCount · property · read/write` ```pascal property ReceivedCount: Integer read GetReceivedCount write SetReceivedCount; ``` Tracks the cumulative number of application bytes actually received from the connection by receive operations. The application may assign `0` at any time to restart the count. Bytes pulled from the connection remain included even when the receive method ultimately returns failure. A failed call does not roll the counter back. For example, partial bytes consumed before a timeout, abort, close, or reset are still counted, even when the method does not return those bytes to the caller. The count can be greater than the number of bytes returned by a particular method because Chilkat may read beyond a delimiter or exact requested length and buffer the excess for a later receive call. TLS and SSH framing overhead is not included. **Note:** Use `RcvBytesPerSec` when measuring raw transfer rate including protocol overhead. ### Socket.ReceivedInt `Chilkat 11.7.0 · pascal · Socket · ReceivedInt · property · read/write · since 9.5.0.50` ```pascal property ReceivedInt: Integer read GetReceivedInt write SetReceivedInt; ``` Contains the value produced by the most recent successful call through this wrapper to `ReceiveByte`, `ReceiveInt16`, or `ReceiveInt32`. The initial value is `0`. The signedness and byte order are determined by the arguments supplied to the receive method. This property is never cleared automatically. It changes only after a successful integer receive or when the application explicitly assigns a value to it. A failed integer receive leaves the previous value unchanged. **May contain a stale value:** Read `ReceivedInt` only after the corresponding receive method has returned success. After a failed call it may still contain a valid-looking value from an earlier operation. ### Socket.ReceiveFailReason `Chilkat 11.7.0 · pascal · Socket · ReceiveFailReason · property · read-only · since 9.5.0.49` ```pascal property ReceiveFailReason: Integer read GetReceiveFailReason; ``` Contains the numeric result for the most recent receive-side operation. The initial value is `0`. It is reset to `0` when a receive begins, remains `0` on success, and is set to a reason code on failure. **May describe an older receive:** Connect, accept, send, and ordinary property operations do not clear this property. Read it immediately after the receive operation whose result is being examined. | Code | Meaning | | --- | --- | | 0 | Success. | | 1 | An asynchronous receive operation is already in progress. | | 2 | The socket is not connected. | | 3 | Internal failure, such as an allocation failure. | | 4 | Invalid parameters were supplied. For delimiter-based receives, this includes an empty match string or a match string that encodes to zero bytes. | | 5 | No additional data arrived within `MaxReadIdleMs`. | | 6 | The operation was aborted by the application. | | 7 | The peer reset the connection. | | 8 | The host operating system aborted the established connection. | | 9 | An unspecified fatal socket error occurred. | | 10 | The peer closed the connection normally. The method reports failure, but its output may still contain final data received immediately before the close. | **Failure does not imply zero received bytes:** A receive method may consume bytes before it fails. Those bytes remain counted by `ReceivedCount`. Depending on the receive method, partial data may be returned, appended to the destination, or discarded. Consult the specific method description. **Connection state after failure:** A timeout or application abort generally leaves the connection open. A peer close or reset leaves it unavailable for further I/O, although the `Socket` object may still be closed or reused for a new `Connect` operation. ### Socket.ReceivePacketSize `Chilkat 11.7.0 · pascal · Socket · ReceivePacketSize · property · read/write` ```pascal property ReceivePacketSize: Integer read GetReceivePacketSize write SetReceivePacketSize; ``` Controls the maximum number of bytes requested by availability-based receive methods when Chilkat must perform a direct read from a plain TCP connection. The default value is `4096`. - For plain TCP, methods such as `ReceiveBytes`, `ReceiveBd`, `ReceiveString`, and `ReceiveSb` obtain at most this many bytes from one underlying socket read. - For TLS and SSH connections, the amount returned is governed by the TLS record or SSH packet and is not limited by this property. - Data already buffered internally by Chilkat is returned in full, even when it exceeds `ReceivePacketSize`. **TCP framing:** This property is not a message-size setting. TCP is a byte stream and does not preserve application message boundaries. ### Socket.RemoteIpAddress `Chilkat 11.7.0 · pascal · Socket · RemoteIpAddress · property · read-only` ```pascal property RemoteIpAddress: string read GetRemoteIpAddress; ``` Returns the numeric IP address of the peer for the connection currently held by this object. This is the address actually used by the established connection, which may differ from the hostname originally supplied to `Connect`. Returns an empty string when the object holds no connected peer. The value is read from the current connection and is never retained from an earlier connection. ### Socket.RemotePort `Chilkat 11.7.0 · pascal · Socket · RemotePort · property · read-only` ```pascal property RemotePort: Integer read GetRemotePort; ``` Returns the TCP port of the peer for the connection currently held by this object. Returns `0` when the object holds no connected peer. The value is read from the current connection and is never retained from an earlier connection. ### Socket.RequireSniMatch `Chilkat 11.7.0 · pascal · Socket · RequireSniMatch · property · read/write · since 11.7.0` ```pascal property RequireSniMatch: Boolean read GetRequireSniMatch write SetRequireSniMatch; ``` Controls what a TLS server does when the client's SNI (Server Name Indication) hostname matches no certificate added by `AddSslServerCert`. The default is `False`. When `False`, the connection is served the default certificate, which is the one passed to `InitSslServer`. When `True`, the handshake is refused with the `unrecognized_name` alert and `AcceptFailReason` is set to 130. **Applies to the listener:** Set this property on the listening socket before `AcceptNext`. It has no effect on a client-side connection. ### Socket.RequireSslCertVerify `Chilkat 11.7.0 · pascal · Socket · RequireSslCertVerify · property · read/write` ```pascal property RequireSslCertVerify: Boolean read GetRequireSslCertVerify write SetRequireSslCertVerify; ``` Controls verification of a server certificate when this object acts as a TLS client. The default is `False`. When `True`, the TLS connection is rejected if the server certificate is expired, not yet valid, has an invalid signature, or cannot be verified through a trusted certificate chain. When `False`, these normal certificate-validity and trust-chain checks are not required. **Independent checks:** `RequireSslCertVerify` controls normal certificate verification. Public-key pinning configured by `TlsPinSet` is a separate check and is enforced whenever a pin set is present, even when this property is `False`. ### Socket.SelectorIndex `Chilkat 11.7.0 · pascal · Socket · SelectorIndex · property · read/write` ```pascal property SelectorIndex: Integer read GetSelectorIndex write SetSelectorIndex; ``` Selects a socket by its direct zero-based position in this object's socket set. Valid values range from `0` through `NumSocketsInSet - 1`. While this selector is active, ordinary connection methods and properties are routed to that contained socket. **Mutually exclusive selectors:** `SelectorIndex`, `SelectorReadIndex`, and `SelectorWriteIndex` are mutually exclusive. Assigning any one clears the other two. Do not copy a read-ready or write-ready index into `SelectorIndex`; setting `SelectorReadIndex` or `SelectorWriteIndex` already routes operations to the corresponding ready socket. **Index lifetime:** Direct set positions are renumbered whenever a member is removed. After a selected member is closed or another member is pruned, later positions shift down and an old `SelectorIndex` can identify a different socket or become out of range. **Socket sets overview:** See [Socket Sets Overview](https://www.chilkatsoft.com/socket_sets.asp) for an explanation of socket sets, selectors, readiness, ownership, and common usage patterns. ### Socket.SelectorReadIndex `Chilkat 11.7.0 · pascal · Socket · SelectorReadIndex · property · read/write` ```pascal property SelectorReadIndex: Integer read GetSelectorReadIndex write SetSelectorReadIndex; ``` Selects a zero-based position in the read-ready result produced by the most recent call to `SelectForReading`. If that call returned `n`, valid values are `0` through `n - 1`. After assigning this property, call `AcceptNext`, a receive method, or another ordinary connection operation on this socket-set object; the operation is routed directly to that ready socket. Reading this property returns exactly the ready-set position last assigned. It does not return or translate to the socket's direct position in the contained set, and no such translation is required. **Mutually exclusive selectors:** Assigning `SelectorReadIndex` clears `SelectorIndex` and `SelectorWriteIndex`. Do not set `SelectorIndex` afterward, because doing so discards the read selection and interprets the number as a direct set position. **Ready-set lifetime:** The ready-set and its ordering remain stable for the current select result, but the order is arbitrary and need not match insertion order. The next call to `SelectForReading` or `SelectForWriting` invalidates prior ready indices. **Socket sets overview:** See [Socket Sets Overview](https://www.chilkatsoft.com/socket_sets.asp) for an explanation of socket sets, selectors, readiness, ownership, and common usage patterns. ### Socket.SelectorWriteIndex `Chilkat 11.7.0 · pascal · Socket · SelectorWriteIndex · property · read/write` ```pascal property SelectorWriteIndex: Integer read GetSelectorWriteIndex write SetSelectorWriteIndex; ``` Selects a zero-based position in the write-ready result produced by the most recent call to `SelectForWriting`. If that call returned `n`, valid values are `0` through `n - 1`. After assigning this property, ordinary connection operations on this socket-set object are routed directly to that ready socket. Reading this property returns exactly the ready-set position last assigned. It does not return or translate to the socket's direct position in the contained set. **Mutually exclusive selectors:** Assigning `SelectorWriteIndex` clears `SelectorIndex` and `SelectorReadIndex`. Do not set `SelectorIndex` afterward. **Ready-set lifetime:** The ready-set and its ordering remain stable for the current select result, but the order is arbitrary and need not match insertion order. The next select call invalidates prior ready indices. **Socket sets overview:** See [Socket Sets Overview](https://www.chilkatsoft.com/socket_sets.asp) for an explanation of socket sets, selectors, readiness, ownership, and common usage patterns. ### Socket.SendBytesPerSec `Chilkat 11.7.0 · pascal · Socket · SendBytesPerSec · property · read-only · since 9.5.0.78` ```pascal property SendBytesPerSec: Integer read GetSendBytesPerSec; ``` Returns the average raw send rate, in bytes per second, since send performance measurement began or was last reset. The measurement includes TLS or SSH framing overhead. Call `ResetPerf` with `False` to restart send measurement. ### Socket.SendFailReason `Chilkat 11.7.0 · pascal · Socket · SendFailReason · property · read-only · since 9.5.0.49` ```pascal property SendFailReason: Integer read GetSendFailReason; ``` Contains the numeric result for the most recent send-side operation. The initial value is `0`. It is reset to `0` when a send begins, remains `0` on success, and is set to a reason code on failure. **May describe an older send:** Connect, accept, receive, and ordinary property operations do not clear this property. Read it immediately after the send operation whose result is being examined. | Code | Meaning | | --- | --- | | 0 | Success. | | 1 | An asynchronous send operation is already in progress. | | 2 | The socket is not connected. | | 3 | Internal failure, such as an allocation failure. | | 4 | Invalid parameters were supplied. | | 5 | The socket made no send progress for longer than `MaxSendIdleMs`. | | 6 | The operation was aborted by the application. | | 7 | The peer reset the connection. | | 8 | The host operating system aborted the established connection. | | 9 | An unspecified fatal socket error occurred. | | 10 | The peer closed the connection. | | 11 | Text or encoded input could not be converted or decoded, such as an invalid `StringCharset` conversion or malformed encoded data. | **A failed send may be partial:** Failure does not prove that zero bytes were sent. Chilkat does not retain the unsent remainder and does not report how much was transmitted. After a failed send, a framed protocol should normally discard the connection because the peer may have received a truncated message. **Connection state after failure:** A timeout or application abort generally leaves the TCP connection open, even though the protocol stream may no longer be safe to reuse. A peer close or reset leaves the connection unavailable for further I/O. ### Socket.SendPacketSize `Chilkat 11.7.0 · pascal · Socket · SendPacketSize · property · read/write` ```pascal property SendPacketSize: Integer read GetSendPacketSize write SetSendPacketSize; ``` Specifies the internal chunk size used when sending a large amount of data over a plain TCP connection. The default is `65535` bytes. TLS connections use TLS record handling rather than this setting. **Note:** This value does not preserve message boundaries and does not determine IP packet sizes. TCP remains a continuous byte stream. ### Socket.SessionLog `Chilkat 11.7.0 · pascal · Socket · SessionLog · property · read-only` ```pascal property SessionLog: string read GetSessionLog; ``` Returns the accumulated send/receive session log for this wrapper when `KeepSessionLog` is `True`. Use `SessionLogEncoding` to choose an escaped or hexadecimal representation and `ClearSessionLog` to reset it. **Important:** The log can contain sensitive plaintext even when the network connection uses TLS. Treat it as diagnostic data and protect it accordingly. ### Socket.SessionLogEncoding `Chilkat 11.7.0 · pascal · Socket · SessionLogEncoding · property · read/write` ```pascal property SessionLogEncoding: string read GetSessionLogEncoding write SetSessionLogEncoding; ``` Controls how bytes are rendered in `SessionLog`. The default is `esc`. | Value | Format | | --- | --- | | `esc` | Compact C-style escaped text. Printable ASCII remains readable; control and nonprintable bytes are escaped, such as `\r`, `\n`, and `\xHH`. | | `hex` | Every byte is represented in hexadecimal, which is larger but unambiguous for binary protocols. | ### Socket.SniHostname `Chilkat 11.7.0 · pascal · Socket · SniHostname · property · read/write · since 9.5.0.82` ```pascal property SniHostname: string read GetSniHostname write SetSniHostname; ``` Sets the Server Name Indication (SNI) hostname sent in the TLS ClientHello. By default, Chilkat uses the hostname passed to `Connect`. Set this property when connecting to a numeric IP address or alternate network endpoint while the TLS server expects a particular virtual-host name. **Scope:** This property changes only the SNI name in the TLS handshake. It does not change the DNS lookup, TCP destination, or any hostname carried by the application protocol. **Added in 11.7.0 – server side:** On the socket returned by `AcceptNext`, this property is the hostname the client asked for, or empty if the client sent no SNI. Use `AddSslServerCert` to present a different certificate per hostname. ### Socket.SocksHostname `Chilkat 11.7.0 · pascal · Socket · SocksHostname · property · read/write` ```pascal property SocksHostname: string read GetSocksHostname write SetSocksHostname; ``` Specifies the hostname or numeric IP address of the SOCKS proxy. It is used only when `SocksVersion` is `4` or `5`. ### Socket.SocksPassword `Chilkat 11.7.0 · pascal · Socket · SocksPassword · property · read/write` ```pascal property SocksPassword: string read GetSocksPassword write SetSocksPassword; ``` Specifies the password for SOCKS5 username/password authentication. SOCKS4 does not define a password field, so this property is ignored for SOCKS4. **Important:** SOCKS5 username/password authentication does not itself encrypt credentials. Security depends on the network path to the proxy. ### Socket.SocksPort `Chilkat 11.7.0 · pascal · Socket · SocksPort · property · read/write` ```pascal property SocksPort: Integer read GetSocksPort write SetSocksPort; ``` Specifies the TCP port of the SOCKS proxy. The default is `1080`. It is used only when `SocksVersion` is `4` or `5`. ### Socket.SocksUsername `Chilkat 11.7.0 · pascal · Socket · SocksUsername · property · read/write` ```pascal property SocksUsername: string read GetSocksUsername write SetSocksUsername; ``` Specifies the SOCKS proxy username. For SOCKS4 it is the user ID sent in the request; for SOCKS5 it is used when username/password authentication is negotiated. ### Socket.SocksVersion `Chilkat 11.7.0 · pascal · Socket · SocksVersion · property · read/write` ```pascal property SocksVersion: Integer read GetSocksVersion write SetSocksVersion; ``` Selects whether connections are routed through a SOCKS proxy. | Value | Behavior | | --- | --- | | 0 | Do not use a SOCKS proxy. This is the default. | | 4 | Connect through a SOCKS4 proxy. | | 5 | Connect through a SOCKS5 proxy. | ### Socket.SoRcvBuf `Chilkat 11.7.0 · pascal · Socket · SoRcvBuf · property · read/write` ```pascal property SoRcvBuf: Integer read GetSoRcvBuf write SetSoRcvBuf; ``` Requests the operating-system receive-buffer size for the TCP socket. The default requested value is `4194304` bytes. Most applications should leave it unchanged. **Note:** The operating system may round, clamp, or internally scale the requested value. Increasing the buffer does not by itself guarantee higher throughput; measure performance before changing it. See also: - [More Information about TCP performance and Buffer Sizes](http://www.cknotes.com/?p=446) ### Socket.SoReuseAddr `Chilkat 11.7.0 · pascal · Socket · SoReuseAddr · property · read/write` ```pascal property SoReuseAddr: Boolean read GetSoReuseAddr write SetSoReuseAddr; ``` Controls the `SO_REUSEADDR` option for a socket that will bind and listen. The default is `True`. Set it before `BindAndListen`, `BindAndListenPortRange`, or `InitSslServer`. **Important:** The exact meaning of `SO_REUSEADDR` differs across operating systems. It can help restart a listener after a previous connection, but it is not a portable substitute for exclusive-port ownership. ### Socket.SoSndBuf `Chilkat 11.7.0 · pascal · Socket · SoSndBuf · property · read/write` ```pascal property SoSndBuf: Integer read GetSoSndBuf write SetSoSndBuf; ``` Requests the operating-system send-buffer size for the TCP socket. The default requested value is `262144` bytes. Most applications should leave it unchanged. **Note:** The operating system may round, clamp, or internally scale the value. Test representative workloads before increasing it. See also: - [More Information about TCP performance and Buffer Sizes](http://www.cknotes.com/?p=446) ### Socket.Ssl `Chilkat 11.7.0 · pascal · Socket · Ssl · property · read/write` ```pascal property Ssl: Boolean read GetSsl write SetSsl; ``` Controls whether incoming connections accepted by this listener must complete a TLS handshake. The default is `False`. Set it to `True` for a TLS server listener. **Important:** This is a listener requirement, not a connection-state indicator. Configure the server certificate with `InitSslServer` before accepting TLS clients. Do not use `TlsVersion` or `TlsCipherSuite` alone to determine whether the current connection is protected by TLS, because those properties retain the results of the object's most recent successful TLS handshake even after the connection changes. ### Socket.SslAllowedCiphers `Chilkat 11.7.0 · pascal · Socket · SslAllowedCiphers · property · read/write · since 9.5.0.48` ```pascal property SslAllowedCiphers: string read GetSslAllowedCiphers write SetSslAllowedCiphers; ``` Restricts the cipher suites permitted for TLS connections. This property has the same behavior as `Chilkat.Http.SslAllowedCiphers` and applies to TLS client connections and TLS server handshakes. The default empty string allows all cipher suites implemented and enabled by the Chilkat build. To restrict negotiation, provide a comma-separated list of cipher-suite names in preference order, for example: ``` TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ``` The negotiated suite must be in the intersection supported by both peers. A TLS client supplies its allowed list to the server; the server ultimately chooses from that list. The following policy keywords are also recognized: - `rsa1024` — when acting as a client, reject a server certificate whose RSA key is smaller than 1024 bits. - `rsa2048` — when acting as a client, reject a server certificate whose RSA key is smaller than 2048 bits. - `secure-renegotiation` — require secure renegotiation. - `best-practices` — use Chilkat's current best-practices policy. The exact policy may change in later Chilkat versions. Legacy filter keywords such as `aes256-cbc`, `aes128-cbc`, `3des-cbc`, and `rc4` remain recognized for compatibility. **Security:** Avoid obsolete suites based on RC4, DES, or 3DES. The set of implemented suites and the meaning of `best-practices` can change with Chilkat versions and platform capabilities. ### Socket.SslProtocol `Chilkat 11.7.0 · pascal · Socket · SslProtocol · property · read/write` ```pascal property SslProtocol: string read GetSslProtocol write SetSslProtocol; ``` **Full documentation for this property (same in every language):** [SSL/TLS Protocol Version Negotiation](https://www.chilkatsoft.com/ai-docs/v/11.7.0/articles/tweet_tls_version_negotiation.md) Selects the SSL/TLS protocol version allowed for secure connections. This property has the same behavior as `Chilkat.Http.SslProtocol` and applies to TLS client connections and TLS server handshakes. Accepted values are: - `default` - `TLS 1.3` - `TLS 1.2` - `TLS 1.1` - `TLS 1.0` - `SSL 3.0` - `TLS 1.3 or higher` - `TLS 1.2 or higher` - `TLS 1.1 or higher` - `TLS 1.0 or higher` The default value is `default`, which allows the protocol to be selected dynamically according to what the peer and Chilkat support. Choosing an exact version causes the connection to fail unless that exact version is negotiated. A minimum-version form such as `TLS 1.2 or higher` is generally preferable to an exact version. **Security:** Avoid SSL 3.0, TLS 1.0, and TLS 1.1 unless compatibility with a legacy peer is unavoidable. ### Socket.StringCharset `Chilkat 11.7.0 · pascal · Socket · StringCharset · property · read/write` ```pascal property StringCharset: string read GetStringCharset write SetStringCharset; ``` Specifies the character encoding used by text-oriented socket methods. Examples include `utf-8`, `windows-1252`, `shift_jis`, and `iso-8859-1`. The default is `ansi`. The value `ansi` means the system default encoding determined by the default system locale. It is not a fixed encoding such as Windows-1252, ISO-8859-1, or ASCII; the actual encoding is platform- and system-configuration-dependent. Sending methods such as `SendString` and `SendSb` encode text using this charset. String receive methods decode incoming bytes from this charset, including `ReceiveString`, `ReceiveSb`, `ReceiveToCRLF`, and delimiter-based string methods. **Important:** TCP transports bytes, not text. Both peers must agree on the encoding and message framing. For portable protocols, prefer an explicit charset such as `utf-8` rather than `ansi`. Use byte-oriented methods when the protocol is binary or exact byte preservation is required. See also: - [Chilkat Socket Programming: Important "Must Know" Concepts](http://www.cknotes.com/?p=302) ### Socket.TcpNoDelay `Chilkat 11.7.0 · pascal · Socket · TcpNoDelay · property · read/write` ```pascal property TcpNoDelay: Boolean read GetTcpNoDelay write SetTcpNoDelay; ``` Controls the `TCP_NODELAY` option. The default is `False`, allowing the Nagle algorithm. Set it to `True` to send small writes with lower latency rather than waiting to coalesce them. **Note:** Disabling Nagle can improve interactive request/response latency but may increase packet overhead. It is not universally faster for bulk transfers. ### Socket.TlsCipherSuite `Chilkat 11.7.0 · pascal · Socket · TlsCipherSuite · property · read-only · since 9.5.0.49` ```pascal property TlsCipherSuite: string read GetTlsCipherSuite; ``` Returns the cipher suite from the most recent successful TLS handshake performed by this `Socket` object, for example `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`. It is empty until the object has completed its first successful TLS handshake. **Cached handshake result:** This property does not necessarily describe the current connection. Its value is retained after `Close`, a failed connection attempt, a later plain-TCP connection, and `ConvertFromSsl`. It is replaced only when this object completes another successful TLS handshake. Do not use this property alone to determine whether the current connection is protected by TLS. ### Socket.TlsPinSet `Chilkat 11.7.0 · pascal · Socket · TlsPinSet · property · read/write · since 9.5.0.55` ```pascal property TlsPinSet: string read GetTlsPinSet write SetTlsPinSet; ``` **Full documentation for this property (same in every language):** [Encodings Supported by Chilkat](https://www.chilkatsoft.com/ai-docs/v/11.7.0/articles/binary_encodings.md) Specifies one or more expected SubjectPublicKeyInfo (SPKI) fingerprints for TLS public-key pinning. If the certificate presented by the server does not match any configured fingerprint, the TLS handshake is aborted and the connection fails. The format is: ``` hash_algorithm, encoding, fingerprint1, fingerprint2, ... ``` For example, a single SHA-256 base64 pin is: ``` sha256, base64, lKg1SIqyhPSK19tlPbjl8s02yChsVTDklQpkMCHvsTE= ``` Supported hash algorithms include `sha1`, `sha256`, `sha384`, `sha512`, `md2`, `md5`, `haval`, `ripemd128`, `ripemd160`, `ripemd256`, and `ripemd320`. Supported encodings include `base64`, `hex`, and other Chilkat-supported binary encodings. **Independent enforcement:** Pin matching is enforced whenever this property is nonempty, even if `RequireSslCertVerify` is `False`. Normal certificate validity and trust-chain verification remain separately controlled by `RequireSslCertVerify`. **Key rotation:** Pinning is operationally strict. Add backup pins before rotating the server key, or a legitimate certificate replacement can break connectivity. ### Socket.TlsSessionResumed `Chilkat 11.7.0 · pascal · Socket · TlsSessionResumed · property · read-only · since 11.7.0` ```pascal property TlsSessionResumed: Boolean read GetTlsSessionResumed; ``` Returns `True` when this connection was resumed from a session ticket instead of being fully handshaked; otherwise returns `False`. Read it on the socket returned by `AcceptNext` for a server-side connection, or after `Connect` for a client-side connection. It applies to both TLS 1.2 and TLS 1.3 resumption. **A resumed connection exchanges no certificates:** Neither side sends a Certificate message when the session is resumed. On the server, the client certificate from the original handshake is restored, so `GetRcvdClientCert` and `NumReceivedClientCerts` still work, but only the client's own certificate is restored and not the rest of its chain. ### Socket.TlsTicketLifetimeSeconds `Chilkat 11.7.0 · pascal · Socket · TlsTicketLifetimeSeconds · property · read/write · since 11.7.0` ```pascal property TlsTicketLifetimeSeconds: Integer read GetTlsTicketLifetimeSeconds write SetTlsTicketLifetimeSeconds; ``` The number of seconds a session ticket issued by this TLS server remains valid. The default is `7200` (2 hours). The maximum is `604800` (7 days, the limit set by RFC 8446); a larger value is reduced to that maximum. Set it to `0` to issue no tickets, which disables session resumption for this server. Applies to both TLS 1.2 session tickets (RFC 5077) and TLS 1.3 session tickets (RFC 8446). A resuming client skips the certificate exchange and the server's signature, so a resumed handshake is both smaller and faster than a full one. **No configuration required:** A random ticket key is generated automatically, so resumption works for the life of a listener without calling `SetTlsTicketKey`. That method is only needed when tickets must stay valid across processes or restarts. ### Socket.TlsVersion `Chilkat 11.7.0 · pascal · Socket · TlsVersion · property · read-only · since 9.5.0.49` ```pascal property TlsVersion: string read GetTlsVersion; ``` Returns the protocol version from the most recent successful TLS handshake performed by this `Socket` object, such as `TLS 1.2` or `TLS 1.3`. It is empty until the object has completed its first successful TLS handshake. **Cached handshake result:** This property does not necessarily describe the current connection. Its value is retained after `Close`, a failed connection attempt, a later plain-TCP connection, and `ConvertFromSsl`. It is replaced only when this object completes another successful TLS handshake. Do not use this property alone to determine whether the current connection is protected by TLS. ### Socket.UncommonOptions `Chilkat 11.7.0 · pascal · Socket · UncommonOptions · property · read/write · since 9.5.0.80` ```pascal property UncommonOptions: string read GetUncommonOptions write SetUncommonOptions; ``` Provides comma-separated compatibility or platform-specific options. The default is the empty string and should normally remain unchanged. | Keyword | Behavior | | --- | --- | | `ProtectFromVpn` | On Android, attempts to route the socket outside an active VPN. | | `EnableTls13` | Historical compatibility option introduced when TLS 1.3 was not yet enabled by default. It is generally unnecessary in current versions. | **Important:** These options are intentionally uncommon and may be platform- or version-specific. Use only when the documented behavior is required. ### Socket.UserData `Chilkat 11.7.0 · pascal · Socket · UserData · property · read/write` ```pascal property UserData: string read GetUserData write SetUserData; ``` Stores arbitrary application text with the socket object. Chilkat does not transmit, interpret, or otherwise use this value. It is useful for associating a label, connection ID, or other application metadata with a socket. ## Methods ### Socket.AcceptNext `Chilkat 11.7.0 · pascal · Socket · AcceptNext · method · since 11.0.0` ```pascal // socket is a TSocket object. function AcceptNext(maxWaitMs: Integer;     socket: TChilkatBase): Boolean; ``` Waits for and accepts the next incoming connection on a socket previously configured by `BindAndListen` or `BindAndListenPortRange`. For a TLS listener, acceptance includes the server-side TLS handshake. - `maxWaitMs = 0` waits indefinitely for an incoming connection. - A positive value waits up to that many milliseconds. - Negative values have no defined meaning and should not be used. **Destination replacement:** On success, the accepted connection replaces any connection already owned by `socket`; a prior call to `Close` is not required. The destination keeps its existing property values, while only its connection is replaced. If the destination is actively performing another operation, the accept fails rather than interrupting that operation. **Failure is non-destructive:** On any failure, including a timeout, missing listener, or TLS handshake failure, the destination `socket` is left completely unchanged. The listening socket also remains active after a timeout or a per-client TLS failure, so the application may immediately call `AcceptNext` again without rebinding. The accepted connection is independent of the listener and all other accepted connections. Listener properties are not copied to the accepted socket. Configure the destination before or after a successful accept as needed. | Setting | Inherited from listener? | | --- | --- | | `MaxReadIdleMs` / `MaxSendIdleMs` | No | | Verbose logging and debug-log path | No | | Upload/download bandwidth throttling | No | | Socket buffers and TCP no-delay options | No | | `SslAllowedCiphers` / `SslProtocol` | No | **TLS state:** The server certificate configuration created by `InitSslServer` remains on the listener and is used for each handshake. The accepted socket contains that connection's negotiated TLS state, peer information, and any received client certificate. Examine those values on the accepted socket. **TLS handshake timeout:** `maxWaitMs` governs the wait for the incoming TCP connection. Handshake inactivity is governed by `MaxReadIdleMs` and `MaxSendIdleMs` on the listener. Returns True for success, False for failure. ### Socket.AddSslAcceptableClientCaDn `Chilkat 11.7.0 · pascal · Socket · AddSslAcceptableClientCaDn · method` ```pascal function AddSslAcceptableClientCaDn(const certAuthDN: string): Boolean; ``` Adds a certificate-authority distinguished name to the list advertised by a TLS server when requesting a client certificate for mutual TLS. Call this method once for each acceptable CA distinguished name. **Required order:** Call every `AddSslAcceptableClientCaDn` before `InitSslServer`. The acceptable-CA list is captured when `InitSslServer` creates the TLS server configuration. Names added afterward are not included in that configuration's CertificateRequest and therefore do not affect its handshakes. Skip this method when the server does not request client certificates. If no CA distinguished names are added, client certificates issued by any root CA are accepted by this CA-name filter. **Authorization remains application-defined:** The CA-name list is only one part of mutual TLS. After `AcceptNext` succeeds, inspect the client certificates on the accepted socket and apply the application's authorization policy. Returns True for success, False for failure. ### Socket.AddSslServerCert `Chilkat 11.7.0 · pascal · Socket · AddSslServerCert · method · since 11.7.0` ```pascal // cert is a TCert object. function AddSslServerCert(cert: TChilkatBase;     const hostname: string): Boolean; ``` Adds a server certificate to be presented when a TLS client's SNI (Server Name Indication) hostname matches `hostname`. This allows one listening socket to serve more than one hostname, each with its own certificate. The certificate must have access to its corresponding private key. `hostname` may be an exact name such as `www.example.com`, a leading wildcard such as `*.example.com`, or an empty string to add a default certificate. Call this method once for each certificate. The certificate for a connection is chosen after the client's ClientHello has been read, in this order, with the first match winning: 1. an exact, case-insensitive match on the hostname; 2. a leading-wildcard match, where `*.example.com` matches `a.example.com` but neither `example.com` nor `a.b.example.com`; 3. a default certificate added by this method with an empty hostname; 4. the certificate passed to `InitSslServer`. A client that sends no SNI hostname goes directly to step 3. Two certificates may be added for the same hostname, in which case the first one added is used. **Call order does not matter:** Unlike `AddSslAcceptableClientCaDn`, this method may be called before or after `InitSslServer`, and also while the socket is already listening. `InitSslServer` is still required: it installs the default certificate and configures the socket for server-side TLS. **The certificate object may be released:** This method keeps its own reference to the certificate, so the application may discard `cert` as soon as the call returns. The hostname the client asked for can be read from the `SniHostname` property of the socket returned by `AcceptNext`. To refuse a connection whose requested hostname matches nothing, set `RequireSniMatch`. Returns `True` for success, `False` for failure. Failure includes a certificate with no accessible private key, which is reported here rather than during a later handshake. Returns True for success, False for failure. ### Socket.BindAndListen `Chilkat 11.7.0 · pascal · Socket · BindAndListen · method` ```pascal function BindAndListen(port: Integer;     backLog: Integer): Boolean; ``` Binds a TCP listener to `port` and places it into listening mode. After this method succeeds, call `AcceptNext` to accept incoming connections. When `ClientIpAddress` is empty, the listener binds to all interfaces: `0.0.0.0` when the shared `ListenIpv6`/`PreferIpv6` setting is `False`, or `::` when it is `True`. To restrict the listener to one local interface, set `ClientIpAddress` to that interface's numeric address before calling this method. The explicit address also determines whether the listener is IPv4 or IPv6. `backLog` is the requested operating-system queue length for connections that have completed or are completing the TCP handshake but have not yet been accepted. It is a queue hint, not a limit on the total number of clients the application can serve. Pass `0` for `port` to let the operating system choose an available port, then read `ListenPort`. **Remote access by default:** Because an empty `ClientIpAddress` binds to all interfaces, remote computers can connect by default, subject to routing and firewall rules. Set `ClientIpAddress` to `127.0.0.1` or `::1` for a loopback-only listener. **State replacement:** If this object currently has an outbound connection, that connection is discarded and the object becomes a listener. A prior call to `Close` is not required. If another operation is actively using the socket, this call fails with an in-use error. **TLS server call order:** When client-certificate CA names are needed, call `AddSslAcceptableClientCaDn` first. Then call `InitSslServer`, `BindAndListen`, and `AcceptNext`, in that order. Calling `InitSslServer` after binding discards the listener and leaves the object unbound. **Backlog:** The operating system may cap or adjust the requested backlog. Choose a value based on burst arrival rate and how quickly the application returns to accepting connections. Returns True for success, False for failure. ### Socket.BindAndListenPortRange `Chilkat 11.7.0 · pascal · Socket · BindAndListenPortRange · method · since 9.5.0.69` ```pascal function BindAndListenPortRange(beginPort: Integer;     endPort: Integer;     backLog: Integer): Integer; ``` Searches the inclusive range `beginPort` through `endPort` for an available TCP port, binds it, and begins listening. The method returns the selected port, or `-1` when no port can be bound or another error occurs. When `ClientIpAddress` is empty, the listener binds to all interfaces: `0.0.0.0` when the shared `ListenIpv6`/`PreferIpv6` setting is `False`, or `::` when it is `True`. Set `ClientIpAddress` to a numeric local address to bind only to that interface; the explicit address determines the address family. `backLog` is the requested operating-system pending-connection queue length. The operating system may cap or adjust it. **Next step:** After a port is successfully selected, call `AcceptNext` to accept incoming connections. For TLS listeners, complete `AddSslAcceptableClientCaDn`, if needed, and `InitSslServer` before calling this method. ### Socket.BuildHttpGetRequest `Chilkat 11.7.0 · pascal · Socket · BuildHttpGetRequest · method · since 9.5.0.35` ```pascal function BuildHttpGetRequest(const url: string): string; ``` Builds and returns a simple HTTP `GET` request for `url`. The method only constructs the request text; it does not connect, send the request, follow redirects, or read a response. **Tip:** Use the higher-level `Http` or `Rest` class for normal HTTP work. This helper is intended for low-level socket examples or custom HTTP handling. Returns True for success, False for failure. ### Socket.CheckWriteable `Chilkat 11.7.0 · pascal · Socket · CheckWriteable · method` ```pascal function CheckWriteable(maxWaitMs: Integer): Integer; ``` Waits for the connected socket to become writable. - `maxWaitMs = 0` performs a nonblocking poll and returns immediately. - A positive value waits up to that many milliseconds. - Negative values have no defined meaning and should not be used. | Return value | Meaning | | --- | --- | | 1 | The socket is connected and currently writable. | | 0 | The socket was not writable before the timeout, or the operation was aborted. | | -1 | The socket is not connected or an error occurred. | **Write readiness:** Writable means the operating system can presently accept more bytes into its send buffer. It does not mean the remote application has received or processed them. ### Socket.ClearSessionLog `Chilkat 11.7.0 · pascal · Socket · ClearSessionLog · method` ```pascal procedure ClearSessionLog; ``` Clears the accumulated text returned by `SessionLog` for this wrapper. It does not change `KeepSessionLog` or close the connection. ### Socket.ClearSslServerCerts `Chilkat 11.7.0 · pascal · Socket · ClearSslServerCerts · method · since 11.7.0` ```pascal procedure ClearSslServerCerts; ``` Removes every certificate added by `AddSslServerCert`. The certificate installed by `InitSslServer` is not affected and remains the default for connections whose SNI hostname matches nothing. ### Socket.Close `Chilkat 11.7.0 · pascal · Socket · Close · method` ```pascal function Close(maxWaitMs: Integer): Boolean; ``` Attempts to gracefully terminate and close the current TCP, TLS, or SSH channel connection. `maxWaitMs` controls how long the method waits for clean shutdown processing. - `0` waits indefinitely for the clean close. - A positive value waits up to that many milliseconds. - Negative values have no defined meaning and should not be used. The method is safe and idempotent. Calling it on an already closed or never-connected object does nothing and returns `True`. Repeated calls are harmless; the diagnostic log may note that there was no connection to close. **Socket-set removal:** When a socket-set selector is active, `Close` is routed to the selected member, closes it, and removes it from the set immediately. There is no separate remove-without-closing method. Direct `SelectorIndex` positions after the removed member shift down. **Duplicated connections:** When the connection is shared by objects created through `DupSocket`, calling `Close` on any wrapper closes the connection for all wrappers. Merely destroying one duplicate without calling `Close` releases only that wrapper's reference. **Note:** After this call, `IsConnected` is `False` for the closed connection. A graceful transport close cannot guarantee that the remote application processed all data sent before the close. Returns True for success, False for failure. ### Socket.Connect `Chilkat 11.7.0 · pascal · Socket · Connect · method` ```pascal function Connect(const hostname: string;     port: Integer;     ssl: Boolean;     maxWaitMs: Integer): Boolean; ``` Establishes a TCP connection to `hostname`:`port`. Set `ssl` to `True` to perform a TLS handshake after the TCP connection succeeds; set it to `False` for plain TCP. `hostname` may be a DNS name or a numeric IPv4 or IPv6 address. `maxWaitMs` is the overall wait budget for DNS resolution performed by this call and establishment of the TCP connection. Its special values are: - `0` waits indefinitely, subject to an internal effective ceiling of approximately six hours. - A positive value below `100` milliseconds is treated as `100` milliseconds. - Negative values have no defined meaning and should not be used. The later TLS handshake is governed by `MaxReadIdleMs` and `MaxSendIdleMs`, not by `maxWaitMs`. HTTP and SOCKS proxy protocol exchanges ordinarily use those read/write idle timeouts as well; there is no separate proxy-negotiation timeout property. Connection options such as `ClientIpAddress`, `ClientPort`, proxy settings, `PreferIpv6`, TLS policy, SNI, ALPN, certificate verification, pinning, and client certificates must be configured before calling this method. | Connection phase | Timeout | | --- | --- | | DNS resolution performed by `Connect` | `maxWaitMs` overall budget | | TCP connection establishment | `maxWaitMs` | | TLS handshake | `MaxReadIdleMs` and `MaxSendIdleMs` | | HTTP/SOCKS proxy exchanges | Ordinarily the read/write idle timeouts; no separate setting is provided | **Reusing the object:** A prior call to `Close` is not required. If this object is already connected, listening, or contains leftover state from a failed connection or TLS upgrade, `Connect` discards that state and establishes the new connection. An existing TCP or TLS connection is torn down immediately rather than closed gracefully, and an existing listener is stopped. If another operation is actively using the socket, the call fails with an in-use error instead of interrupting that operation. **SSH tunnel exception:** When this object has a live SSH tunnel, the SSH session is preserved. The previous tunneled channel is closed, and the new destination connection is opened through the same SSH tunnel. **Socket sets:** If `SelectorIndex`, `SelectorReadIndex`, or `SelectorWriteIndex` selects a member, this method is routed to that selected member. With no active selector, it creates or replaces the set container object's own direct connection and leaves the contained members unchanged. **Security:** A successful TCP connection only establishes a byte stream. For TLS, enable the certificate-verification and/or pinning policy required by the application. A completed connection does not by itself authenticate an application-level protocol. **Idle connections:** A connected socket does not automatically close merely because no application data is sent. Peers, NAT devices, proxies, firewalls, and operating-system TCP keepalive policies can still close an idle path. Returns True for success, False for failure. See also: - [Chilkat Socket Programming: Important "Must Know" Concepts](http://www.cknotes.com/?p=302) ### Socket.ConvertFromSsl `Chilkat 11.7.0 · pascal · Socket · ConvertFromSsl · method` ```pascal function ConvertFromSsl: Boolean; ``` Ends the TLS layer while leaving the underlying TCP connection open for subsequent unencrypted communication. This is the reverse of a STARTTLS-style upgrade and is valid only when TLS is currently active. If called on a connected plain TCP socket, the method returns `False` because there is no TLS layer to remove. The plain connection remains unchanged. **Important:** The peer and application protocol must explicitly support returning to plaintext. Arbitrarily removing TLS from a normal secure protocol will usually break the session and can expose data. Returns True for success, False for failure. ### Socket.ConvertToSsl `Chilkat 11.7.0 · pascal · Socket · ConvertToSsl · method` ```pascal function ConvertToSsl: Boolean; ``` Upgrades an already connected plain TCP socket to TLS by performing a client-side TLS handshake over the existing connection. **Important:** Use this only at the point where the application protocol permits a STARTTLS-style upgrade. Configure TLS policy, SNI, certificate verification, pinning, and any client certificate before calling it. **Already-TLS connections:** Calling `ConvertToSsl` on a connection that is already protected by TLS is unsupported. The method checks that a connection exists but does not define a second TLS-upgrade operation. Call it only for an established plain connection. Returns True for success, False for failure. ### Socket.DnsCacheClear `Chilkat 11.7.0 · pascal · Socket · DnsCacheClear · method · since 9.5.0.38` ```pascal procedure DnsCacheClear; ``` Clears Chilkat's process-wide in-memory DNS cache. Subsequent hostname resolutions perform a new lookup as needed. **Important:** The cache is shared by Chilkat objects in the process, so clearing it can affect unrelated connections. Normally the cache should be left intact because Chilkat observes DNS record TTL expiration. ### Socket.DnsLookup `Chilkat 11.7.0 · pascal · Socket · DnsLookup · method` ```pascal function DnsLookup(const hostname: string;     maxWaitMs: Integer): string; ``` Resolves `hostname` and returns one numeric IP address. - `maxWaitMs = 0` waits indefinitely. - A positive value waits up to that many milliseconds. - Negative values have no defined meaning and should not be used. **Multiple addresses:** A hostname can resolve to multiple IPv4 and IPv6 addresses. This method returns one selected address, influenced by settings such as `PreferIpv6`; it is not a complete DNS-record enumeration. Returns True for success, False for failure. ### Socket.DupSocket `Chilkat 11.7.0 · pascal · Socket · DupSocket · method · since 11.0.0` ```pascal // dest is a TSocket object. function DupSocket(dest: TChilkatBase): Boolean; ``` Populates `dest` with another `Socket` wrapper that shares this object's underlying connection. The destination first releases its reference to any connection it previously held. The shared connection object is reference-counted, but all wrappers operate on the same live connection and byte stream. The reference count keeps the underlying connection object alive while wrappers still refer to it; it does not prevent an explicit `Close` from shutting down the connection. TLS state, TLS conversion state, and the internal receive/over-read buffer are shared. A TLS renegotiation, `ConvertToSsl`, or `ConvertFromSsl` through one wrapper changes the connection seen by every duplicate. Bytes buffered through one wrapper may be consumed by a receive through another. | State, setting, or result | Scope after `DupSocket` | | --- | --- | | Underlying connection, byte stream, TLS session, TLS conversion state, and receive buffer | Shared by all duplicates. | | `ReceivedCount` | Shared connection-level counter. All duplicates report the same cumulative value, and resetting it through one wrapper resets the value seen by the others. | | `SendBytesPerSec` and `RcvBytesPerSec` | Shared connection-level measurements. Calling `ResetPerf` through one wrapper resets the selected measurement for every duplicate. | | `KeepSessionLog`, `SessionLog`, and session logging | Per wrapper. Enabling logging on one duplicate does not enable it on another. Each wrapper logs only traffic that passes through it, and reading or clearing one wrapper's log does not affect another wrapper's log. | | `LastMethodFailed`, `AcceptFailReason`, `ReceiveFailReason`, `SendFailReason`, and `ReceivedInt` | Per wrapper. An operation performed through one duplicate does not update these values on another duplicate. | **Close affects every duplicate:** Calling `Close` on any wrapper actively closes the shared connection for all wrappers. The other wrapper objects remain alive, but subsequent I/O through them fails because the shared connection is closed. **Threading pattern:** Duplicates are intended to permit one reader and one writer to use the same connection. Two concurrent readers compete for the same stream and shared receive buffer and should be avoided. **Release rule:** When one duplicate is no longer needed but another must continue using the connection, release, destroy, delete, or allow the unused wrapper to be garbage-collected without calling `Close`. This drops only that wrapper's reference and leaves the connection usable through the remaining duplicates. Call `Close` on any one wrapper only when the shared connection should end for everyone. Returns True for success, False for failure. ### Socket.GetAdaptersAddresses `Chilkat 11.7.0 · pascal · Socket · GetAdaptersAddresses · method · since 10.1.3` ```pascal // json is a TJsonObject object. function GetAdaptersAddresses(json: TChilkatBase): Boolean; ``` Populates `json` with information about local network adapters, including IPv4 addresses, IPv6 addresses, and MAC addresses. Existing contents of the destination JSON object are replaced or populated according to the returned structure. **Note:** Adapter data is local system configuration. It does not identify the public Internet address seen through NAT. Returns True for success, False for failure. ### Socket.GetLastJsonData `Chilkat 11.7.0 · pascal · Socket · GetLastJsonData · method · since 11.0.0` ```pascal // json is a TJsonObject object. procedure GetLastJsonData(json: TChilkatBase); ``` Copies additional JSON details from the most recently called method into `json`, when that method produced such information. Many methods produce an empty result. **Important:** Call this immediately after the operation of interest. Any intervening method call can replace the stored details. ### Socket.GetMyServerCert `Chilkat 11.7.0 · pascal · Socket · GetMyServerCert · method · since 11.0.0` ```pascal // cert is a TCert object. function GetMyServerCert(cert: TChilkatBase): Boolean; ``` Copies the TLS server certificate configured by `InitSslServer` into `cert`. This method is intended for a socket acting as a TLS server and returns `False` when no server certificate has been configured. Returns True for success, False for failure. ### Socket.GetRcvdClientCert `Chilkat 11.7.0 · pascal · Socket · GetRcvdClientCert · method · since 11.0.0` ```pascal // cert is a TCert object. function GetRcvdClientCert(index: Integer;     cert: TChilkatBase): Boolean; ``` Copies the client certificate at zero-based `index` into `cert` from the TLS handshake of an accepted server-side connection. Use `NumReceivedClientCerts` to determine the valid index range. Client certificates are normally supplied only when the server requests mutual TLS authentication. The application can inspect the returned certificate and close the connection when it does not satisfy authorization requirements. **Important:** Call this method on the accepted connection object populated by `AcceptNext`, not on the listener socket. Returns True for success, False for failure. ### Socket.GetServerCert `Chilkat 11.7.0 · pascal · Socket · GetServerCert · method · since 11.0.0` ```pascal // cert is a TCert object. function GetServerCert(cert: TChilkatBase): Boolean; ``` Copies the certificate presented by the remote TLS server into `cert` for the current client-side TLS connection. The method returns `False` when the socket is not connected, is not using TLS, or no server certificate is available. **Note:** Retrieving the certificate does not itself establish trust. Use `RequireSslCertVerify` and/or `TlsPinSet` when validation is required. Returns True for success, False for failure. ### Socket.GetSslAcceptableClientCaDn `Chilkat 11.7.0 · pascal · Socket · GetSslAcceptableClientCaDn · method` ```pascal function GetSslAcceptableClientCaDn(index: Integer): string; ``` Returns the certificate-authority distinguished name at zero-based `index` from the list sent by a TLS server when it requests a client certificate. Valid indexes range from `0` through `NumSslAcceptableClientCAs - 1`. Returns True for success, False for failure. ### Socket.InitSslServer `Chilkat 11.7.0 · pascal · Socket · InitSslServer · method` ```pascal // cert is a TCert object. function InitSslServer(cert: TChilkatBase): Boolean; ``` Configures this object for server-side TLS using `cert` as the server certificate. The certificate must have access to its corresponding private key. For a TLS listener that requests client certificates, the required sequence is: ``` AddSslAcceptableClientCaDn (once for each acceptable CA) InitSslServer BindAndListen AcceptNext ``` For a TLS listener without client-certificate requests, omit `AddSslAcceptableClientCaDn`. For a plain non-TLS listener, omit both TLS setup steps. When the object is not already connected, this method also sets `Ssl` to `True`. It may also be used on an already connected socket to begin server-side TLS on that live connection. **Call order:** Do not call `InitSslServer` after `BindAndListen`. A listening socket is not treated as a connected socket, so this method replaces it with a new, unbound TLS-server socket and the existing bind is lost. All calls to `AddSslAcceptableClientCaDn` must also occur before this method. **Listener versus accepted socket:** The server certificate configuration remains on the listener and is used for each accepted TLS handshake. Per-connection negotiated TLS information and received client certificates are stored on the accepted socket. Returns True for success, False for failure. ### Socket.LoadTaskCaller `Chilkat 11.7.0 · pascal · Socket · LoadTaskCaller · method · since 9.5.0.80` ```pascal // task is a TTask object. function LoadTaskCaller(task: TChilkatBase): Boolean; ``` Loads this object with the state of the object that initiated the asynchronous operation represented by `task`. This is useful when the task has completed on a worker thread and the caller state must be recovered into another wrapper object. **Important:** Use a task created by a compatible `Socket` asynchronous method and call this after completion. Returns True for success, False for failure. ### Socket.LoadTaskResult `Chilkat 11.7.0 · pascal · Socket · LoadTaskResult · method · since 9.5.0.52` ```pascal // task is a TTask object. function LoadTaskResult(task: TChilkatBase): Boolean; ``` Loads this socket object with the result state produced by a completed asynchronous task whose result is a socket. Call it only after the task has completed successfully. **Important:** The task and result type must correspond to a compatible socket operation. Check the task result and `LastErrorText` when loading fails. Returns True for success, False for failure. ### Socket.PollDataAvailable `Chilkat 11.7.0 · pascal · Socket · PollDataAvailable · method` ```pascal function PollDataAvailable: Boolean; ``` Performs a nonblocking check for readable activity on the socket. It returns `True` when data or another read-ready condition is present and `False` when nothing is immediately available. **Note:** A socket can become read-ready because the peer closed or reset the connection. The next receive operation determines whether bytes are available or the connection ended. ### Socket.ReceiveBd `Chilkat 11.7.0 · pascal · Socket · ReceiveBd · method · since 9.5.0.65` ```pascal // binData is a TBinData object. function ReceiveBd(binData: TChilkatBase): Boolean; ``` Receives one delivery of binary data and appends it to `binData`. Chilkat first appends any data already buffered internally. If no buffered data exists, the method performs one receive operation; it does not loop to drain everything that may be available. - For plain TCP, a direct read obtains at most `ReceivePacketSize` bytes. - For TLS or SSH, the amount is governed by the TLS record or SSH packet and is not limited by `ReceivePacketSize`. - Already-buffered data is appended in full, even if it exceeds `ReceivePacketSize`. - A successful call can append zero bytes during TLS renegotiation. Treat this as no application data yet and call the receive method again. **Inspect the destination even on failure:** An orderly peer close reports `ReceiveFailReason = 10`, but `binData` may contain final bytes received immediately before the close. **TCP framing:** TCP does not preserve message boundaries. Define framing in the application protocol, such as an exact length, delimiter, fixed-size record, or connection close. Returns True for success, False for failure. ### Socket.ReceiveBdN `Chilkat 11.7.0 · pascal · Socket · ReceiveBdN · method · since 9.5.0.65` ```pascal // binData is a TBinData object. function ReceiveBdN(numBytes: LongWord;     binData: TChilkatBase): Boolean; ``` Receives exactly `numBytes` bytes and appends them to `binData`. The method continues receiving until the requested count is satisfied or a receive failure occurs. Inactivity is controlled by `MaxReadIdleMs`. **The destination changes on failure:** If a timeout, application abort, connection close, or reset occurs after only part of the requested data is received, the method returns `false`, but the partial bytes remain appended to `binData`. Those bytes have been consumed from the connection, are included in `ReceivedCount`, and are not retained internally for a later receive call. A timeout or application abort generally leaves the connection open. A peer close or reset leaves it unavailable for further I/O. When the requested count is successfully completed, bytes read beyond that count may remain buffered internally for the next receive operation. Returns True for success, False for failure. ### Socket.ReceiveByte `Chilkat 11.7.0 · pascal · Socket · ReceiveByte · method · since 9.5.0.50` ```pascal function ReceiveByte(bUnsigned: Boolean): Boolean; ``` Reads exactly one byte from the connection and stores its numeric value in `ReceivedInt`. If `bUnsigned` is `True`, the result is in the range `0` through `255`; otherwise it is interpreted as a signed two's-complement byte in the range `-128` through `127`. The method waits according to `MaxReadIdleMs` and returns `False` on timeout, closure, or another receive failure. On failure, `ReceivedInt` is not cleared or changed; it retains the value from the last successful integer receive. **Check the return value:** Use this method's Boolean result to determine whether `ReceivedInt` contains a newly received byte. Returns True for success, False for failure. ### Socket.ReceiveBytesENC `Chilkat 11.7.0 · pascal · Socket · ReceiveBytesENC · method` ```pascal function ReceiveBytesENC(const encodingAlg: string): string; ``` Receives binary data and returns one delivery encoded as text using `encodingAlg`. Chilkat first returns any data already buffered internally. If no buffered data exists, the method performs one receive operation; it does not loop to drain everything that may be available. - For plain TCP, a direct read returns at most `ReceivePacketSize` bytes. - For TLS or SSH, the returned amount is governed by the TLS record or SSH packet rather than `ReceivePacketSize`. - Already-buffered data is returned in full, even if it exceeds `ReceivePacketSize`. - A successful call can receive zero bytes during TLS renegotiation, producing an empty encoded result. Treat this as no application data yet and call the receive method again. Common encoding names include `base64`, `modBase64`, `base32`, `uu`, `qp`, `url`, `hex`, `q`, `b`, `url_oauth`, `url_rfc1738`, `url_rfc2396`, and `url_rfc3986`. See [all supported Chilkat binary encodings](https://cknotes.com/chilkat-binary-encoding-list/). **Inspect the result even on failure:** An orderly peer close reports `ReceiveFailReason = 10`, but the returned encoded string may contain final bytes received immediately before the close. Process those bytes before finishing the receive loop. **Encoding:** The encoding affects only the textual representation returned by this method. It does not change the bytes received from the network. **TCP framing:** TCP does not preserve message boundaries. Define framing in the application protocol, such as an exact length, delimiter, fixed-size record, or connection close. Returns True for success, False for failure. ### Socket.ReceiveBytesToFile `Chilkat 11.7.0 · pascal · Socket · ReceiveBytesToFile · method` ```pascal function ReceiveBytesToFile(const appendFilename: string): Boolean; ``` Receives one available block of bytes and appends it to the file named by `appendFilename`. If Chilkat already has buffered data, that data is used first. Otherwise, the method performs one receive operation; it does not loop until the peer closes or until an entire file has arrived. If no data is immediately available, it waits according to `MaxReadIdleMs`. **The file is appended to, not replaced:** Existing file content is preserved and newly received bytes are written at the end of the file. **Failure and partial-file behavior:** A network receive failure leaves the file unchanged. However, if the network read succeeds and a later file-writing error occurs, such as a disk-full or other filesystem error, the file may contain a partially written block. Bytes consumed by the receive are included in `ReceivedCount` even when the overall method fails. After a timeout or application abort, the connection is generally still open. After a peer close or reset, the connection is no longer usable for I/O. Returns True for success, False for failure. ### Socket.ReceiveCount `Chilkat 11.7.0 · pascal · Socket · ReceiveCount · method` ```pascal function ReceiveCount: Integer; ``` Reads exactly four bytes and interprets them as a signed 32-bit two's-complement integer. Byte order is controlled by `BigEndian`, whose default is `True` for network byte order. Negative values are returned unchanged, with one exception: `-1` is reserved as the failure result. If the incoming four-byte value is `0xFFFFFFFF`, the method deliberately reports failure, sets `LastMethodFailed`, and returns `-1`. A legitimately transmitted value of `-1` therefore cannot be received as ordinary data. There is no unsigned variant, so wire values from `0x80000000` through `0xFFFFFFFE` are returned as negative signed integers. **Partial integer reads:** If the operation fails after receiving only part of the four-byte value, those bytes are consumed and discarded. They cannot be recovered by a later receive call, and the protocol stream may now be misaligned. **Round-trip rule:** `SendCount(N)` followed by `ReceiveCount` round-trips every signed 32-bit value except `-1`. ### Socket.ReceiveInt16 `Chilkat 11.7.0 · pascal · Socket · ReceiveInt16 · method · since 9.5.0.50` ```pascal function ReceiveInt16(bigEndian: Boolean;     bUnsigned: Boolean): Boolean; ``` Reads exactly two bytes, interprets them as a two's-complement integer, and stores the result in `ReceivedInt`. Set `bigEndian` to `True` for network byte order or `False` for little-endian order. Set `bUnsigned` to `True` for a value from `0` through `65535`; otherwise the result ranges from `-32768` through `32767`. **Partial integer reads:** If the operation fails after receiving only part of the two-byte value, the partial bytes are consumed and discarded. They are not retained for a later receive, and the protocol stream may now be misaligned. `ReceivedInt` remains unchanged on failure, so use the Boolean return value before reading it. Returns True for success, False for failure. ### Socket.ReceiveInt32 `Chilkat 11.7.0 · pascal · Socket · ReceiveInt32 · method · since 9.5.0.50` ```pascal function ReceiveInt32(bigEndian: Boolean): Boolean; ``` Reads exactly four bytes, interprets them as a signed two's-complement integer, and stores the result in `ReceivedInt`. Set `bigEndian` to `True` for network byte order or `False` for little-endian order. **Partial integer reads:** If the operation fails after receiving only part of the four-byte value, the partial bytes are consumed and discarded. They are not retained for a later receive, and the protocol stream may now be misaligned. `ReceivedInt` remains unchanged on failure, so use the Boolean return value before reading it. Returns True for success, False for failure. ### Socket.ReceiveNBytesENC `Chilkat 11.7.0 · pascal · Socket · ReceiveNBytesENC · method` ```pascal function ReceiveNBytesENC(numBytes: LongWord;     const encodingAlg: string): string; ``` Receives exactly `numBytes` bytes and returns them encoded using `encodingAlg`. Supported encoding names include `base64`, `modBase64`, `base32`, `uu`, `qp`, `url`, `hex`, `q`, `b`, `url_oauth`, `url_rfc1738`, `url_rfc2396`, and `url_rfc3986`. See [all supported Chilkat binary encodings](https://cknotes.com/chilkat-binary-encoding-list/). Inactivity is controlled by `MaxReadIdleMs`. **Partial data is discarded on failure:** If the exact byte count cannot be obtained, no partial encoded result is returned and the output string is empty. Any partial bytes already read are consumed from the connection and discarded; they are not retained internally and cannot be recovered by a later receive call. This differs from `ReceiveBytesN` and `ReceiveBdN`, which expose partial data on failure. **Validate lengths:** Validate any peer-supplied length before requesting a large amount of data. If the peer sends too few bytes while keeping the connection open, the method waits until the inactivity timeout. Returns True for success, False for failure. ### Socket.ReceiveSb `Chilkat 11.7.0 · pascal · Socket · ReceiveSb · method · since 9.5.0.65` ```pascal // sb is a TStringBuilder object. function ReceiveSb(sb: TChilkatBase): Boolean; ``` Receives text, decodes it using `StringCharset`, and appends it to `sb`. Chilkat first uses any plaintext already buffered internally. Otherwise, it receives until it can append the first nonempty decoded result. The method does not continue reading merely to drain all data that may be available. - For plain TCP, the underlying direct read obtains at most `ReceivePacketSize` bytes. - For TLS or SSH, the amount is governed by the TLS record or SSH packet and is not limited by `ReceivePacketSize`. - Already-buffered plaintext is appended in full, even if it exceeds `ReceivePacketSize`. - On success, at least one received byte contributes to the appended text; this method does not return success with an empty receive result. **Inspect the destination even on failure:** An orderly peer close reports `ReceiveFailReason = 10`, but `sb` may contain final text received immediately before the close. **TCP framing:** TCP does not preserve message boundaries. Use a protocol-defined length or delimiter when a complete text message is required. Returns True for success, False for failure. ### Socket.ReceiveString `Chilkat 11.7.0 · pascal · Socket · ReceiveString · method` ```pascal function ReceiveString: string; ``` Receives text and decodes it using `StringCharset`. Chilkat first uses any plaintext already buffered internally. Otherwise, it receives until it can return the first nonempty decoded result. The method does not continue reading merely to drain all data that may be available. - For plain TCP, the underlying direct read obtains at most `ReceivePacketSize` bytes. - For TLS or SSH, the amount is governed by the TLS record or SSH packet and is not limited by `ReceivePacketSize`. - Already-buffered plaintext is returned in full, even if it exceeds `ReceivePacketSize`. - On success, the returned text represents at least one received byte; this method does not produce a successful empty result. **Inspect the returned text even on failure:** An orderly peer close reports `ReceiveFailReason = 10`, but the returned string may contain final text received immediately before the close. For APIs that return a string directly, check `LastMethodFailed` without discarding the returned value. **Text framing:** A receive can end in the middle of an application message or multibyte text sequence. For framed text protocols, prefer an exact-length or delimiter-based receive method. Returns True for success, False for failure. See also: - [Chilkat Socket Programming: Important "Must Know" Concepts](http://www.cknotes.com/?p=302) ### Socket.ReceiveStringMaxN `Chilkat 11.7.0 · pascal · Socket · ReceiveStringMaxN · method` ```pascal function ReceiveStringMaxN(maxByteCount: Integer): string; ``` Receives and decodes text like `ReceiveString`, but returns at most `maxByteCount` input bytes. The limit is measured in bytes, not Unicode characters. **Important:** A byte limit can split a multibyte character or a protocol message. Choose a limit compatible with the encoding and framing used by the peer. Returns True for success, False for failure. ### Socket.ReceiveStringUntilByte `Chilkat 11.7.0 · pascal · Socket · ReceiveStringUntilByte · method` ```pascal function ReceiveStringUntilByte(lookForByte: Integer): string; ``` Receives bytes until the raw byte value `lookForByte` is found. The delimiter is excluded from the returned string. The bytes preceding the delimiter are then decoded using `StringCharset`. The delimiter search is purely byte-oriented and does not recognize character boundaries. A match may therefore occur inside the encoded representation of a multibyte character. **Multibyte character boundary:** With a multibyte encoding, a non-ASCII delimiter byte can occur inside an encoded character. The receive can stop in the middle of that character, and the incomplete character may be dropped, replaced, or decoded incorrectly. Prefer an ASCII delimiter value below `0x80` with an ASCII-compatible charset such as UTF-8, an ISO-8859 encoding, a Windows-125x encoding, or Shift-JIS. Returns True for success, False for failure. ### Socket.ReceiveToCRLF `Chilkat 11.7.0 · pascal · Socket · ReceiveToCRLF · method` ```pascal function ReceiveToCRLF: string; ``` Receives text through a CRLF line terminator and returns the text including the terminator. Chilkat encodes the CR followed by LF characters using `StringCharset`, then searches the incoming byte stream for that exact encoded sequence. The accumulated bytes are decoded using the same charset after the delimiter is found. **Charset-dependent delimiter:** For ASCII-compatible charsets such as UTF-8, US-ASCII, ISO-8859 encodings, Windows-125x encodings, and Shift-JIS, the delimiter bytes are the usual `0D 0A`. With a wide charset such as UTF-16LE, the encoded delimiter is different, for example `0D 00 0A 00`. **Tip:** This method is useful for line-oriented text protocols. Do not use it for protocols that permit bare LF, binary data, or a different line terminator. Returns True for success, False for failure. ### Socket.ReceiveUntilByteBd `Chilkat 11.7.0 · pascal · Socket · ReceiveUntilByteBd · method · since 9.5.0.76` ```pascal // bd is a TBinData object. function ReceiveUntilByteBd(lookForByte: Integer;     bd: TChilkatBase): Boolean; ``` Reads bytes until `lookForByte` is encountered and appends all bytes up to and including the matching byte to `bd`. The delimiter must be an integer from `0` through `255` and is matched as a raw byte value. **Partial data remains on failure:** If the delimiter is not found before a timeout, application abort, peer close, or connection reset, the method returns `false`, but everything received while searching remains appended to `bd`. These bytes are included in `ReceivedCount`, have been consumed from the connection, and are not retained internally for a later receive call. A timeout or application abort generally leaves the connection open. A peer close or reset leaves it unavailable for further I/O. Returns True for success, False for failure. ### Socket.ReceiveUntilMatch `Chilkat 11.7.0 · pascal · Socket · ReceiveUntilMatch · method` ```pascal function ReceiveUntilMatch(const matchStr: string): string; ``` Receives bytes until the exact byte sequence represented by `matchStr` is found. Chilkat first encodes `matchStr` using `StringCharset`, then performs a case-sensitive, byte-for-byte comparison against the incoming stream. No case folding, Unicode normalization, or text-level comparison is performed. The match may span multiple underlying network reads. After the delimiter is found, the complete accumulated byte sequence is decoded using `StringCharset` and returned as text. The returned text includes the matching delimiter. **Empty match strings:** If `matchStr` is empty, or if it encodes to zero bytes under the current `StringCharset`, the method fails immediately with `ReceiveFailReason = 4`. No data is read from the connection and the returned string is empty. **Partial content is discarded on failure:** If the delimiter is not found before a timeout, application abort, peer close, connection reset, or other failure, the returned string is empty. Bytes already consumed while searching are discarded, are not retained for a later receive, and cannot be recovered. If an orderly peer close is detected, `ReceiveFailReason` is `10`. On success, bytes read beyond the delimiter may remain buffered internally for the next receive call. This is why `ReceivedCount` can increase by more than the number of bytes represented by the returned string. Returns True for success, False for failure. ### Socket.ReceiveUntilMatchSb `Chilkat 11.7.0 · pascal · Socket · ReceiveUntilMatchSb · method · since 10.1.0` ```pascal // sb is a TStringBuilder object. function ReceiveUntilMatchSb(const matchStr: string;     sb: TChilkatBase): Boolean; ``` Receives bytes until the exact byte sequence represented by `matchStr` is found. Chilkat first encodes `matchStr` using `StringCharset`, then performs a case-sensitive, byte-for-byte comparison against the incoming stream. The match may span multiple underlying network reads. After the delimiter is found, the accumulated bytes are decoded using `StringCharset` and appended to `sb`. The appended text includes the matching delimiter. **Empty match strings:** If `matchStr` is empty, or if it encodes to zero bytes under the current `StringCharset`, the method fails immediately with `ReceiveFailReason = 4`. No data is read and `sb` is left unchanged. **The destination remains unchanged on failure:** If the match is not found before a timeout, application abort, peer close, connection reset, or other failure, the method returns `false` and does not modify `sb`. Bytes consumed while searching are included in `ReceivedCount`, are discarded, are not retained for a later receive, and cannot be recovered. If an orderly peer close is detected, `ReceiveFailReason` is `10`. On success, bytes read beyond the delimiter may remain buffered internally for the next receive operation. Returns True for success, False for failure. ### Socket.ResetPerf `Chilkat 11.7.0 · pascal · Socket · ResetPerf · method · since 9.5.0.78` ```pascal procedure ResetPerf(rcvPerf: Boolean); ``` Restarts one direction of connection-level transfer-rate measurement. Set `rcvPerf` to `True` to reset receive measurement for `RcvBytesPerSec`; set it to `False` to reset send measurement for `SendBytesPerSec`. ### Socket.SelectForReading `Chilkat 11.7.0 · pascal · Socket · SelectForReading · method` ```pascal function SelectForReading(timeoutMs: Integer): Integer; ``` Waits for read-ready activity on this socket or, when this object is a socket set, on any contained socket. - `timeoutMs = 0` performs a nonblocking poll and returns immediately. - A positive value waits up to that many milliseconds. - A negative value currently produces an effectively very long wait. Applications should normally use `0` or a positive value rather than depend on this behavior. | Return value | Meaning | | --- | --- | | Positive | The number of sockets in the read-ready result. | | 0 | No socket was ready at the time of the poll or before the timeout. | | -1 | An error occurred. | A connected socket is read-ready when data is available or when a close/error condition can be detected. A listener is read-ready when an incoming connection is pending. Listener and connected sockets may coexist in one set, but the set does not identify which type a ready member is; the application must track that information and call `AcceptNext` or a receive method as appropriate. **Correct socket-set loop:** If this method returns `n`, iterate from `0` through `n - 1`, assign each value directly to `SelectorReadIndex`, and then operate on this socket-set object. Do not assign the value to `SelectorIndex`. **Ready-set lifetime:** The ready-set is fixed for this result, so it can be iterated safely. Its order is arbitrary, is not guaranteed to match insertion order, and can differ on the next select call. Calling either select method again invalidates all prior read/write indices. **Automatic pruning:** Each select rebuilds the underlying descriptor set and removes contained sockets that can no longer contribute a valid descriptor. A dead socket can therefore remain counted only until the next select. **Readiness is not data:** A receive may report that the peer closed or reset the connection instead of returning application data. Within one ready-set iteration, closing a selected socket does not renumber the other ready positions, but the closed socket's own position no longer resolves. **Socket sets overview:** See [Socket Sets Overview](https://www.chilkatsoft.com/socket_sets.asp) for an explanation of socket sets, selectors, readiness, ownership, and common usage patterns. ### Socket.SelectForWriting `Chilkat 11.7.0 · pascal · Socket · SelectForWriting · method` ```pascal function SelectForWriting(timeoutMs: Integer): Integer; ``` Waits for this socket, or sockets in a socket set, to become writable without blocking. - `timeoutMs = 0` performs a nonblocking poll and returns immediately. - A positive value waits up to that many milliseconds. - A negative value currently produces an effectively very long wait. Applications should normally use `0` or a positive value rather than depend on this behavior. | Return value | Meaning | | --- | --- | | Positive | The number of sockets in the write-ready result. | | 0 | No socket was writable at the time of the poll or before the timeout. | | -1 | An error occurred. | **Correct socket-set loop:** If this method returns `n`, iterate from `0` through `n - 1`, assign each value directly to `SelectorWriteIndex`, and then operate on this socket-set object. Do not assign the value to `SelectorIndex`. **Ready-set lifetime:** The result remains stable for the current iteration, but its order is arbitrary and need not match insertion order. Calling either select method again invalidates all prior read/write indices. Each select also prunes contained sockets that no longer have a usable descriptor. **Write readiness:** TCP writes normally complete into the operating-system send buffer. Readiness does not mean the remote application has received or processed the data. **Socket sets overview:** See [Socket Sets Overview](https://www.chilkatsoft.com/socket_sets.asp) for an explanation of socket sets, selectors, readiness, ownership, and common usage patterns. ### Socket.SendBd `Chilkat 11.7.0 · pascal · Socket · SendBd · method · since 9.5.0.65` ```pascal // binData is a TBinData object. function SendBd(binData: TChilkatBase;     offset: LongWord;     numBytes: LongWord): Boolean; ``` Sends bytes from `binData`, beginning at `offset`. If `numBytes` is greater than `0`, that many bytes are selected; if it is `0`, bytes are selected from `offset` through the end. When both values are `0`, the entire `BinData` is selected. The selected range must be valid. The method is synchronous and uses `MaxSendIdleMs` as the maximum period during which no send progress may occur. No application message framing is added. **Partial transmission on failure:** A failed call may already have sent part of the selected range. Chilkat does not retain or queue the unsent remainder and does not report the number of bytes sent. A timeout or application abort may leave the TCP connection open, but the protocol stream may contain a truncated message. For a framed protocol, normally close the connection and reconnect rather than sending the next message on the same stream. A peer close or reset leaves the connection unusable for further I/O. Returns True for success, False for failure. See also: - [Why Sending Can Succeed After Ethernet Cable Disconnected](https://superuser.com/questions/911808/what-happens-to-tcp-connections-when-i-remove-the-ethernet-cable) ### Socket.SendByte `Chilkat 11.7.0 · pascal · Socket · SendByte · method · since 9.5.0.50` ```pascal function SendByte(value: Integer): Boolean; ``` Sends one byte whose value is specified by `value`. The value must be in the range `0` through `255`. The method returns after the byte has been accepted for transmission or a send failure occurs. Returns True for success, False for failure. ### Socket.SendBytesENC `Chilkat 11.7.0 · pascal · Socket · SendBytesENC · method` ```pascal function SendBytesENC(const encodedBytes: string;     const encodingAlg: string): Boolean; ``` Decodes `encodedBytes` using `encodingAlg`, then sends the resulting binary bytes. Supported Chilkat encoding names include `base64`, `modBase64`, `base32`, `base58`, `uu`, `qp`, `url`, `hex`, `q`, `b`, `url_oauth`, `url_rfc1738`, `url_rfc2396`, and `url_rfc3986`. See [all supported Chilkat binary encodings](https://cknotes.com/chilkat-binary-encoding-list/). For example, `encodedBytes="00010203040506"` with `encodingAlg="hex"` sends seven bytes with values 00 through 06. **Important:** Malformed encoded input causes the method to fail before or during sending. Check `SendFailReason` and `LastErrorText`. Returns True for success, False for failure. ### Socket.SendCount `Chilkat 11.7.0 · pascal · Socket · SendCount · method` ```pascal function SendCount(byteCount: Integer): Boolean; ``` Sends `byteCount` as its four-byte signed two's-complement bit pattern. Byte order is controlled by `BigEndian`, whose default is `True` for network byte order. Any signed 32-bit value is serialized without validation. The peer can read the value using `ReceiveCount`, except that `-1` is not usable as an ordinary count because `ReceiveCount` reserves `-1` as its failure result. **Tip:** A length prefix is a common way to frame messages over TCP: send the count first, then exactly that many payload bytes. Validate received lengths before allocating memory or waiting for data. Returns True for success, False for failure. ### Socket.SendInt16 `Chilkat 11.7.0 · pascal · Socket · SendInt16 · method · since 9.5.0.50` ```pascal function SendInt16(value: Integer;     bigEndian: Boolean): Boolean; ``` Sends the low 16 bits of `value` as a two-byte two's-complement bit pattern. Set `bigEndian` to `True` for network byte order or `False` for little-endian order. No range validation is performed. Signed values from `-32768` through `32767` and unsigned values from `0` through `65535` can be represented directly. Any other integer is silently truncated to its low 16 bits, equivalent to taking the value modulo 65536. **Examples:** `40000` writes `0x9C40`, `-1` writes `0xFFFF`, `65536` writes `0x0000`, and `70000` writes `0x1170`. Returns True for success, False for failure. ### Socket.SendInt32 `Chilkat 11.7.0 · pascal · Socket · SendInt32 · method · since 9.5.0.50` ```pascal function SendInt32(value: Integer;     bigEndian: Boolean): Boolean; ``` Sends `value` as its complete four-byte signed two's-complement bit pattern. Set `bigEndian` to `True` for network byte order or `False` for little-endian order. The parameter is a signed 32-bit integer and there is no unsigned overload, but every 32-bit wire pattern can be represented by passing the signed integer having that bit pattern. For example, passing `-1` writes `0xFFFFFFFF`. Because the input is already 32 bits, no bits are truncated. Returns True for success, False for failure. ### Socket.SendSb `Chilkat 11.7.0 · pascal · Socket · SendSb · method · since 9.5.0.65` ```pascal // sb is a TStringBuilder object. function SendSb(sb: TChilkatBase): Boolean; ``` Encodes the contents of `sb` using `StringCharset` and sends the resulting bytes. The method is synchronous and uses `MaxSendIdleMs` as the send-progress inactivity limit. **Important:** No terminator or length prefix is added. Include any protocol framing in the `StringBuilder` content. Returns True for success, False for failure. ### Socket.SendString `Chilkat 11.7.0 · pascal · Socket · SendString · method` ```pascal function SendString(const stringToSend: string): Boolean; ``` Encodes `stringToSend` using `StringCharset` and sends the resulting bytes over the connected TCP or TLS socket. The method is synchronous and uses `MaxSendIdleMs` as the maximum period during which no send progress may occur. No delimiter, terminator, or length prefix is added automatically. **Partial transmission on failure:** A failed call may already have sent part of the encoded byte sequence. Chilkat does not retain or queue the unsent remainder and does not report how many bytes were sent. A timeout or application abort may leave the TCP connection open, but the application-protocol stream may contain a truncated message. For a framed protocol, normally close the connection and reconnect before sending another message. A peer close or reset leaves the connection unusable for further I/O. Returns True for success, False for failure. See also: - [Why Sending Can Succeed After Ethernet Cable Disconnected](https://superuser.com/questions/911808/what-happens-to-tcp-connections-when-i-remove-the-ethernet-cable) ### Socket.SendWakeOnLan `Chilkat 11.7.0 · pascal · Socket · SendWakeOnLan · method · since 9.5.0.69` ```pascal function SendWakeOnLan(const macAddress: string;     port: Integer;     const ipBroadcastAddr: string): Boolean; ``` Sends a Wake-on-LAN magic packet for `macAddress` to the UDP broadcast address `ipBroadcastAddr` and `port`. The MAC address is six bytes written as hexadecimal, for example `000102030405`. Ports `7` and `9` are commonly used. Call this method without first calling `Connect`. The target computer must have Wake-on-LAN enabled in firmware, the network adapter, and the operating system, and the network must permit the broadcast packet. **Important:** Wake-on-LAN generally works within a local network segment. Routers commonly block directed broadcasts, and a successful send does not confirm that the target powered on. Returns True for success, False for failure. See also: - [For more information about Wake-on-LAN](https://en.wikipedia.org/wiki/Wake-on-LAN) ### Socket.SendWakeOnLan2 `Chilkat 11.7.0 · pascal · Socket · SendWakeOnLan2 · method · since 9.5.0.77` ```pascal function SendWakeOnLan2(const macAddress: string;     port: Integer;     const ipBroadcastAddr: string;     const password: string): Boolean; ``` Sends the same Wake-on-LAN magic packet as `SendWakeOnLan` and appends a SecureOn password. `password` is a hexadecimal string representing four or six bytes. **Important:** SecureOn is an optional Wake-on-LAN password field, not encryption and not strong authentication. Support and expected length are device-specific. Returns True for success, False for failure. ### Socket.SetSslClientCert `Chilkat 11.7.0 · pascal · Socket · SetSslClientCert · method` ```pascal // cert is a TCert object. function SetSslClientCert(cert: TChilkatBase): Boolean; ``` Configures `cert` as the client certificate for subsequent TLS connections. The certificate must have access to its private key. Use this only when the server requests or requires client-certificate authentication. **Important:** Configure the client certificate before `Connect` or `ConvertToSsl`. A certificate without its private key cannot prove client identity. Returns True for success, False for failure. ### Socket.SetSslClientCertPem `Chilkat 11.7.0 · pascal · Socket · SetSslClientCertPem · method` ```pascal function SetSslClientCertPem(const pemDataOrFilename: string;     const pemPassword: string): Boolean; ``` Loads and configures a TLS client certificate and private key from PEM data or a PEM filename supplied in `pemDataOrFilename`. Use `pemPassword` when the private key is encrypted. **Important:** The PEM material must include or make available the private key corresponding to the certificate. Configure it before the TLS handshake begins. Returns True for success, False for failure. ### Socket.SetSslClientCertPfx `Chilkat 11.7.0 · pascal · Socket · SetSslClientCertPfx · method` ```pascal function SetSslClientCertPfx(const pfxFilename: string;     const pfxPassword: string): Boolean; ``` Loads and configures a TLS client certificate and private key from the PFX/P12 file `pfxFilename`, using `pfxPassword`. Use this only when the server requests or requires client-certificate authentication. **Important:** Protect PFX files and passwords because they contain private-key material. Returns True for success, False for failure. ### Socket.SetTlsTicketKey `Chilkat 11.7.0 · pascal · Socket · SetTlsTicketKey · method · since 11.7.0` ```pascal // binKey is a TBinData object. function SetTlsTicketKey(binKey: TChilkatBase): Boolean; ``` Sets the key this TLS server uses to encrypt and decrypt session tickets. `binKey` must contain exactly 32 bytes. This is only needed so that tickets issued by one server process remain valid in another process, or after a restart. A random key is generated automatically otherwise, which makes session resumption work for the life of one listener with no configuration at all. Every server instance that should accept one another's tickets must be given the same key. Calling this method a second time with a different key rotates the key: new tickets are issued under the new key, and tickets issued under the key it replaces are still accepted until they expire. Calling it with the key already in use does nothing, so re-reading an unchanged configuration is harmless. **Protect this key:** It encrypts the resumption secret of every session whose ticket it issued. Anyone holding it can decrypt those tickets. Store it as securely as a private key, and rotate it periodically. Set `TlsTicketLifetimeSeconds` to `0` to issue no tickets at all. Returns `True` for success, `False` for failure. Returns True for success, False for failure. ### Socket.SleepMs `Chilkat 11.7.0 · pascal · Socket · SleepMs · method` ```pascal procedure SleepMs(millisec: Integer); ``` Pauses the calling thread for approximately `millisec` milliseconds. This is a convenience method and does not perform network I/O or keep a connection alive. **Important:** Sleeping blocks the current thread. It is not a substitute for socket readiness methods, asynchronous I/O, or protocol timers. ### Socket.SshAuthenticatePk `Chilkat 11.7.0 · pascal · Socket · SshAuthenticatePk · method · since 9.5.0.50` ```pascal // privateKey is a TSshKey object. function SshAuthenticatePk(const sshLogin: string;     privateKey: TChilkatBase): Boolean; ``` Authenticates the SSH tunnel session as `sshLogin` using `privateKey`. Call `SshOpenTunnel` first. The SSH server must have the corresponding public key authorized for that account. **Important:** This authenticates the SSH transport used by the socket tunnel. It does not authenticate the final destination protocol reached through a forwarded channel. Returns True for success, False for failure. ### Socket.SshAuthenticatePw `Chilkat 11.7.0 · pascal · Socket · SshAuthenticatePw · method · since 9.5.0.50` ```pascal function SshAuthenticatePw(const sshLogin: string;     const sshPassword: string): Boolean; ``` Authenticates the SSH tunnel session using `sshLogin` and `sshPassword`. Call `SshOpenTunnel` first and authenticate before opening forwarded channels. **Important:** Do not log or expose the SSH password. Public-key authentication is generally preferable when supported. Returns True for success, False for failure. ### Socket.SshCloseTunnel `Chilkat 11.7.0 · pascal · Socket · SshCloseTunnel · method · since 9.5.0.50` ```pascal function SshCloseTunnel: Boolean; ``` Closes the SSH tunnel opened by `SshOpenTunnel` and terminates its forwarded channels. It does not close unrelated SSH objects or connections. Returns True for success, False for failure. ### Socket.SshNewChannel `Chilkat 11.7.0 · pascal · Socket · SshNewChannel · method · since 11.0.0` ```pascal // channel is a TSocket object. function SshNewChannel(const hostname: string;     port: Integer;     ssl: Boolean;     maxWaitMs: Integer;     channel: TChilkatBase): Boolean; ``` Opens a new port-forwarded channel through the authenticated SSH tunnel to `hostname`:`port` and populates `channel` with the connected socket. If `ssl` is `True`, Chilkat establishes TLS to the destination inside the SSH tunnel. - `maxWaitMs = 0` waits indefinitely for the channel/destination connection to open. - A positive value is used as supplied; unlike `Connect`, values below `100` milliseconds are not raised to a 100-millisecond minimum. - Negative values have no defined meaning and should not be used. Multiple channels can share one authenticated SSH tunnel and can target different destination host/port pairs. **Required sequence:** Call `SshOpenTunnel` and authenticate successfully before opening channels. Returns True for success, False for failure. ### Socket.SshOpenTunnel `Chilkat 11.7.0 · pascal · Socket · SshOpenTunnel · method · since 9.5.0.50` ```pascal function SshOpenTunnel(const sshHostname: string;     sshPort: Integer): Boolean; ``` Connects to the SSH server at `sshHostname`:`sshPort` and initializes an SSH tunneling session. Port `22` is conventional but not required. After this succeeds, authenticate with `SshAuthenticatePw` or `SshAuthenticatePk`, then open forwarded destination channels with `SshNewChannel`. Multiple channels can share the same authenticated tunnel. **Timeouts:** This method has no dedicated wait argument. SSH protocol read and write inactivity are governed by `MaxReadIdleMs` and `MaxSendIdleMs`. The default value of `0` for those properties permits an indefinite wait while no progress is made. Returns True for success, False for failure. ### Socket.StartTiming `Chilkat 11.7.0 · pascal · Socket · StartTiming · method` ```pascal procedure StartTiming; ``` Starts or restarts the object's convenience timer. Read `ElapsedSeconds` to obtain the whole number of seconds since this call. **Note:** This timer does not affect connection, send, or receive timeouts. ### Socket.TakeConnection `Chilkat 11.7.0 · pascal · Socket · TakeConnection · method · since 9.5.0.77` ```pascal // sock is a TSocket object. function TakeConnection(sock: TChilkatBase): Boolean; ``` Moves the active connection from `cSocket` into this object. This object first releases its reference to any connection it previously held. Unlike `TakeSocket`, this method does not add a member to a socket set. After success, `cSocket` holds no connection. It may be closed, destroyed, or reused immediately without affecting the transferred connection. Ownership is exclusive after the move; only this destination object controls the transferred connection. **Move semantics:** This method transfers ownership rather than sharing the connection. Use `DupSocket` only when two wrappers must refer to the same underlying connection. Returns True for success, False for failure. ### Socket.TakeSocket `Chilkat 11.7.0 · pascal · Socket · TakeSocket · method` ```pascal // sock is a TSocket object. function TakeSocket(sock: TChilkatBase): Boolean; ``` Moves the connection out of `sock` and into a newly created member of this object's socket set. After one or more successful calls, this object acts as a set of connected and/or listener sockets. After success, `sock` holds no connection. It may be closed, destroyed, or reused immediately without affecting the transferred connection. The new set member owns the connection independently; there is no shared ownership to coordinate. **Set workflow:** Use `SelectorIndex` to select a direct member. After `SelectForReading` or `SelectForWriting`, assign the ready position directly to `SelectorReadIndex` or `SelectorWriteIndex`. **Different from TakeConnection:** `TakeSocket` adds a new member to the socket set. `TakeConnection` moves a connection into the receiving object itself and is not a set-building method. **Socket sets overview:** See [Socket Sets Overview](https://www.chilkatsoft.com/socket_sets.asp) for an explanation of socket sets, selectors, readiness, ownership, and common usage patterns. Returns True for success, False for failure. ### Socket.TlsRenegotiate `Chilkat 11.7.0 · pascal · Socket · TlsRenegotiate · method · since 9.5.0.55` ```pascal function TlsRenegotiate: Boolean; ``` Requests TLS renegotiation on an established TLS connection, causing another handshake to negotiate new security parameters where the protocol and peer support it. **Important:** TLS 1.3 does not use legacy renegotiation, and many modern TLS 1.2 servers disable it. The method can therefore fail even on an otherwise healthy TLS connection. Returns True for success, False for failure. ### Socket.UseSsh `Chilkat 11.7.0 · pascal · Socket · UseSsh · method · since 9.5.0.55` ```pascal // ssh is a TSsh object. function UseSsh(ssh: TChilkatBase): Boolean; ``` Configures this socket to route subsequent `Connect` calls through the already connected and authenticated `Ssh` object. The destination host and port passed to `Connect` are reached by SSH port forwarding rather than by a direct TCP connection. This is one of several SSH-tunneling models in Chilkat. Alternatives include this class's `SshOpenTunnel`/`SshNewChannel` workflow and the separate `SshTunnel` class for background static or dynamic forwarding. **Important:** The supplied `Ssh` object must remain connected and authenticated while the forwarded socket connection is being established and used. Returns True for success, False for failure. ## Events and callbacks Chilkat for Pascal supports three synchronous event callbacks: `OnAbortCheck`, `OnPercentDone`, and `OnProgressInfo`. Each is a property of the class; assign a method of one of your own objects (an *of object* handler) to receive the callbacks, or assign `nil` to unhook. The handler types are declared in the `Chilkat.Base` unit: ```pascal TChilkatAbortCheckEvent = function(Sender: TChilkatBase): Boolean of object; TChilkatPercentDoneEvent = function(Sender: TChilkatBase; PctDone: Integer): Boolean of object; TChilkatProgressInfoEvent = procedure(Sender: TChilkatBase; const Name, Value: string) of object; ``` All Chilkat methods are synchronous, so callbacks are invoked on the thread that called the method -- if the method was called from the main thread, it is safe to access UI elements from the handler. The `HeartbeatMs` property controls the frequency of `OnAbortCheck` callbacks (the default of 0 means no AbortCheck events fire). Returning `True` from an `OnAbortCheck` or `OnPercentDone` handler aborts the running method. ### Socket.AbortCheck (event) `Chilkat 11.7.0 · pascal · Socket · AbortCheck · event` ```pascal // TChilkatAbortCheckEvent = function(Sender: TChilkatBase): Boolean of object; property OnAbortCheck: TChilkatAbortCheckEvent; ``` Enables a method call to be aborted by triggering the AbortCheck event at intervals defined by the `HeartbeatMs` property. If HeartbeatMs is set to its default value of 0, no events will occur. For instance, set HeartbeatMs to 200 to trigger 5 AbortCheck events per second. **Event callback implementation:** ```pascal // A handler is a method of one of your own classes, e.g. a form: function TMyObject.SocketAbortCheck(Sender: TChilkatBase): Boolean; begin // Called every HeartbeatMs milliseconds while a method is running. // Return True to abort the method; return False to continue. Result := False; end; ``` **To add an event handler:** ```pascal socket := TSocket.Create; socket.HeartbeatMs := 250; // fire OnAbortCheck 4 times per second socket.OnAbortCheck := MyObject.SocketAbortCheck; ``` ### Socket.PercentDone (event) `Chilkat 11.7.0 · pascal · Socket · PercentDone · event` ```pascal // TChilkatPercentDoneEvent = function(Sender: TChilkatBase; PctDone: Integer): Boolean of object; property OnPercentDone: TChilkatPercentDoneEvent; ``` This provides the percentage completion for any method involving network communications or time-consuming processing, assuming the progress can be measured as a percentage. This event is triggered only when it's possible and logical to express the operation's progress as a percentage. The `pctDone` argument will range from 1 to 100. For methods that finish quickly, the number of PercentDone callbacks may vary, but the final callback will have `pctDone` equal to 100. For longer operations, callbacks will not exceed one per percentage point (e.g., 1, 2, 3, ..., 98, 99, 100). The PercentDone callback also acts as an `AbortCheck` event. For fast methods where PercentDone fires, an AbortCheck event may not trigger since the PercentDone callback already provides an opportunity to abort. For longer operations, where time between PercentDone callbacks is extended, AbortCheck callbacks enable more responsive operation termination. To abort the operation, set the `abort` output argument to `True`. This will cause the method to terminate and return a failure status or corresponding failure value. **Event callback implementation:** ```pascal // A handler is a method of one of your own classes, e.g. a form: function TMyObject.SocketPercentDone(Sender: TChilkatBase; PctDone: Integer): Boolean; begin // PctDone ranges from 1 to 100. WriteLn('Percent done: ', PctDone); // Return True to abort the method; return False to continue. Result := False; end; ``` **To add an event handler:** ```pascal socket := TSocket.Create; socket.OnPercentDone := MyObject.SocketPercentDone; ``` ### Socket.ProgressInfo (event) `Chilkat 11.7.0 · pascal · Socket · ProgressInfo · event` ```pascal // TChilkatProgressInfoEvent = procedure(Sender: TChilkatBase; const Name, Value: string) of object; property OnProgressInfo: TChilkatProgressInfoEvent; ``` This event callback provides `tag name`/value pairs that detail what occurs during a method call. To discover existing tag names, create code to handle the event, emit the pairs, and review them. Most tag names are self-explanatory. Note: Some Chilkat methods don't fire any ProgressInfo events. **Event callback implementation:** ```pascal // A handler is a method of one of your own classes, e.g. a form: procedure TMyObject.SocketProgressInfo(Sender: TChilkatBase; const Name, Value: string); begin WriteLn(Name, ': ', Value); end; ``` **To add an event handler:** ```pascal socket := TSocket.Create; socket.OnProgressInfo := MyObject.SocketProgressInfo; ``` ## Related classes [`BinData`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/BinData.md), [`Cert`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/Cert.md), [`JsonObject`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/JsonObject.md), [`Ssh`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/Ssh.md), [`SshKey`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/SshKey.md), [`StringBuilder`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/StringBuilder.md)