CkSocket

Set this property to 1 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 0. If no operation is running, the next method call clears a previously set value before it begins.

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.

Specifies the application-layer protocol name offered in the TLS ALPN extension, such as h2 or http/1.1. Leave it empty when ALPN is not required.

Limits receive throughput to approximately the specified number of bytes per second. The default value is 0, which disables receive throttling.

Limits send throughput to approximately the specified number of bytes per second. The default value is 0, which disables send throttling.

Controls the byte order used by SendCount and ReceiveCount. The default is 1, which uses big-endian byte order (network byte order). Set it to 0 to use little-endian byte order.

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.

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.

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.

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

• A timeout property set to 0, indicating an infinite timeout.
• A hang occurring within an event callback in the application code.
• An internal bug in the Chilkat code causing the hang.

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.

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.

Specifies the optional Windows domain used for NTLM authentication to an HTTP proxy. It is ignored unless HttpProxyAuthMethod is NTLM.

Set this property to 1 when the proxied connection will carry HTTP requests, such as when a Rest object uses this socket through UseConnection. The default is 0.

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.

Specifies the hostname or numeric IP address of the HTTP proxy. Leave it empty to connect directly without an HTTP proxy.

Specifies the password used to authenticate with the HTTP proxy. It is used together with HttpProxyUsername and the selected HttpProxyAuthMethod.

Specifies the TCP port of the HTTP proxy. Common values include 8080 and 3128, but the correct port is determined by the proxy configuration.

Specifies the username used to authenticate with the HTTP proxy. It is ignored when the proxy does not require authentication.

Returns 1 when the socket is in its last known connected state; otherwise returns 0. Explicitly closing the socket updates this property immediately.

Controls the operating system SO_KEEPALIVE option for the underlying TCP socket. The default is 1.

Set this property to 1 to record bytes sent and received through this wrapper in SessionLog. The default is 0. Use SessionLogEncoding to choose how bytes are rendered.

Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

Returns 1 if the most recent action method called through this wrapper failed; otherwise returns 0. The initial value is 0. An action method clears this state when it begins and leaves it 0 on success or sets it to 1 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.

Indicates the success or failure of the most recent method call: 1 means success, 0 means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

• Outbound connections: When a hostname resolves to both IPv4 and IPv6 addresses, 0 prefers IPv4 and 1 prefers IPv6.
• Listeners: When ClientIpAddress is empty, 0 binds to 0.0.0.0 and 1 binds to ::. When an explicit ClientIpAddress is set, its literal address determines the family.

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 1 to restart receive measurement.

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.

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.

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.

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.

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.

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.

Controls verification of a server certificate when this object acts as a TLS client. The default is 0.

When 1, 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 0, these normal certificate-validity and trust-chain checks are not required.

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.

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.

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.

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 0 to restart send measurement.

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.

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.

Returns the accumulated send/receive session log for this wrapper when KeepSessionLog is 1. Use SessionLogEncoding to choose an escaped or hexadecimal representation and ClearSessionLog to reset it.

Controls how bytes are rendered in SessionLog. The default is esc.

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.

Specifies the hostname or numeric IP address of the SOCKS proxy. It is used only when SocksVersion is 4 or 5.

Specifies the password for SOCKS5 username/password authentication. SOCKS4 does not define a password field, so this property is ignored for SOCKS4.

Specifies the TCP port of the SOCKS proxy. The default is 1080. It is used only when SocksVersion is 4 or 5.

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.

Selects whether connections are routed through a SOCKS proxy.

Requests the operating-system receive-buffer size for the TCP socket. The default requested value is 4194304 bytes. Most applications should leave it unchanged.

Controls the SO_REUSEADDR option for a socket that will bind and listen. The default is 1. Set it before BindAndListen, BindAndListenPortRange, or InitSslServer.

Requests the operating-system send-buffer size for the TCP socket. The default requested value is 262144 bytes. Most applications should leave it unchanged.

Controls whether incoming connections accepted by this listener must complete a TLS handshake. The default is 0. Set it to 1 for a TLS server listener.

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.

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.

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.

Controls the TCP_NODELAY option. The default is 0, allowing the Nagle algorithm. Set it to 1 to send small writes with lower latency rather than waiting to coalesce them.

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.

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.

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.

Provides comma-separated compatibility or platform-specific options. The default is the empty string and should normally remain unchanged.

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.

When set to 1, all string arguments and return values are interpreted as UTF-8 strings. When set to 0, they are interpreted as ANSI strings.

In Chilkat v11.0.0 and later, the default value is 1. Before v11.0.0, it was 0.

If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

Version of the component/library, such as "10.1.0"

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.

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the AcceptNext method with the arguments provided.

Returns null on failure

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.

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.

Returns 1 for success, 0 for failure.

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 0, or :: when it is 1. 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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the BindAndListen method with the arguments provided.

Returns null on failure

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 0, or :: when it is 1. 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.

Creates an asynchronous task to call the BindAndListenPortRange method with the arguments provided.

Returns null on failure

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.

Returns 1 for success, 0 for failure.

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.

Creates an asynchronous task to call the CheckWriteable method with the arguments provided.

Returns null on failure

Clears the accumulated text returned by SessionLog for this wrapper. It does not change KeepSessionLog or close the connection.

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 1. Repeated calls are harmless; the diagnostic log may note that there was no connection to close.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the Close method with the arguments provided.

Returns null on failure

Establishes a TCP connection to hostname:port. Set ssl to 1 to perform a TLS handshake after the TCP connection succeeds; set it to 0 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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the Connect method with the arguments provided.

Returns null on failure

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 0 because there is no TLS layer to remove. The plain connection remains unchanged.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ConvertFromSsl method with the arguments provided.

Returns null on failure

Upgrades an already connected plain TCP socket to TLS by performing a client-side TLS handshake over the existing connection.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ConvertToSsl method with the arguments provided.

Returns null on failure

Clears Chilkat's process-wide in-memory DNS cache. Subsequent hostname resolutions perform a new lookup as needed.

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the DnsLookup method with the arguments provided.

Returns null on failure

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.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

Copies additional JSON details from the most recently called method into json, when that method produced such information. Many methods produce an empty result.

Copies the TLS server certificate configured by InitSslServer into cert. This method is intended for a socket acting as a TLS server and returns 0 when no server certificate has been configured.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

Copies the certificate presented by the remote TLS server into cert for the current client-side TLS connection. The method returns 0 when the socket is not connected, is not using TLS, or no server certificate is available.

Returns 1 for success, 0 for failure.

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 1 for success, 0 for failure.

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 1. It may also be used on an already connected socket to begin server-side TLS on that live connection.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

Performs a nonblocking check for readable activity on the socket. It returns 1 when data or another read-ready condition is present and 0 when nothing is immediately available.

Creates an asynchronous task to call the PollDataAvailable method with the arguments provided.

Returns null on failure

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveBd method with the arguments provided.

Returns null on failure

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.

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 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveBdN method with the arguments provided.

Returns null on failure

Reads exactly one byte from the connection and stores its numeric value in ReceivedInt. If bUnsigned is 1, 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 0 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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveByte method with the arguments provided.

Returns null on failure

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveBytesENC method with the arguments provided.

Returns null on failure

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.

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 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveBytesToFile method with the arguments provided.

Returns null on failure

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

Creates an asynchronous task to call the ReceiveCount method with the arguments provided.

Returns null on failure

Reads exactly two bytes, interprets them as a two's-complement integer, and stores the result in ReceivedInt. Set bigEndian to 1 for network byte order or 0 for little-endian order. Set bUnsigned to 1 for a value from 0 through 65535; otherwise the result ranges from -32768 through 32767.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveInt16 method with the arguments provided.

Returns null on failure

Reads exactly four bytes, interprets them as a signed two's-complement integer, and stores the result in ReceivedInt. Set bigEndian to 1 for network byte order or 0 for little-endian order.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveInt32 method with the arguments provided.

Returns null on failure

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. Inactivity is controlled by MaxReadIdleMs.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveNBytesENC method with the arguments provided.

Returns null on failure

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveSb method with the arguments provided.

Returns null on failure

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveString method with the arguments provided.

Returns null on failure

Receives and decodes text like ReceiveString, but returns at most maxByteCount input bytes. The limit is measured in bytes, not Unicode characters.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveStringMaxN method with the arguments provided.

Returns null on failure

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveStringUntilByte method with the arguments provided.

Returns null on failure

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveToCRLF method with the arguments provided.

Returns null on failure

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.

A timeout or application abort generally leaves the connection open. A peer close or reset leaves it unavailable for further I/O.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveUntilByteBd method with the arguments provided.

Returns null on failure

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.

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 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveUntilMatch method with the arguments provided.

Returns null on failure

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.

On success, bytes read beyond the delimiter may remain buffered internally for the next receive operation.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveUntilMatchSb method with the arguments provided.

Returns null on failure

Restarts one direction of connection-level transfer-rate measurement. Set rcvPerf to 1 to reset receive measurement for RcvBytesPerSec; set it to 0 to reset send measurement for SendBytesPerSec.

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.

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.

Creates an asynchronous task to call the SelectForReading method with the arguments provided.

Returns null on failure

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.

Creates an asynchronous task to call the SelectForWriting method with the arguments provided.

Returns null on failure

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the SendBd method with the arguments provided.

Returns null on failure

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 1 for success, 0 for failure.

Creates an asynchronous task to call the SendByte method with the arguments provided.

Returns null on failure

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.

For example, encodedBytes="00010203040506" with encodingAlg="hex" sends seven bytes with values 00 through 06.

Creates an asynchronous task to call the SendBytesENC method with the arguments provided.

Returns null on failure

Sends byteCount as its four-byte signed two's-complement bit pattern. Byte order is controlled by BigEndian, whose default is 1 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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the SendCount method with the arguments provided.

Returns null on failure

Sends the low 16 bits of value as a two-byte two's-complement bit pattern. Set bigEndian to 1 for network byte order or 0 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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the SendInt16 method with the arguments provided.

Returns null on failure

Sends value as its complete four-byte signed two's-complement bit pattern. Set bigEndian to 1 for network byte order or 0 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 1 for success, 0 for failure.

Creates an asynchronous task to call the SendInt32 method with the arguments provided.

Returns null on failure

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the SendSb method with the arguments provided.

Returns null on failure

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the SendString method with the arguments provided.

Returns null on failure

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.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

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.

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the SshAuthenticatePk method with the arguments provided.

Returns null on failure

Authenticates the SSH tunnel session using sshLogin and sshPassword. Call SshOpenTunnel first and authenticate before opening forwarded channels.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the SshAuthenticatePw method with the arguments provided.

Returns null on failure

Closes the SSH tunnel opened by SshOpenTunnel and terminates its forwarded channels. It does not close unrelated SSH objects or connections.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the SshCloseTunnel method with the arguments provided.

Returns null on failure

Opens a new port-forwarded channel through the authenticated SSH tunnel to hostname:port and populates channel with the connected socket. If ssl is 1, 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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the SshNewChannel method with the arguments provided.

Returns null on failure

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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the SshOpenTunnel method with the arguments provided.

Returns null on failure

Starts or restarts the object's convenience timer. Read ElapsedSeconds to obtain the whole number of seconds since this call.

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.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

Requests TLS renegotiation on an established TLS connection, causing another handshake to negotiate new security parameters where the protocol and peer support it.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the TlsRenegotiate method with the arguments provided.

Returns null on failure

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.

Returns 1 for success, 0 for failure.

This property and PreferIpv6 are two names for the same underlying setting. Reading or writing either property reads or changes the same value.

For a listener, when ClientIpAddress is empty, the default 0 value causes BindAndListen and BindAndListenPortRange to bind to 0.0.0.0. Set it to 1 to bind to ::. When ClientIpAddress contains an explicit address, that address determines both the bind address and its IPv4 or IPv6 family.

Waits for and accepts the next incoming connection on a listening socket. On success, a new Socket object is returned.

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

Returns null on failure

Creates an asynchronous task to call the AcceptNextConnection method with the arguments provided.

Returns null on failure

Returns another Socket object that shares the same underlying TCP or TLS connection. Reads and writes made through either object operate on the same byte stream.

Returns null on failure

Returns the certificate configured for this object when it is acting as a TLS server. The certificate is initially supplied to InitSslServer.

Returns null on failure

Returns the client certificate at the zero-based index received during the TLS handshake on an accepted server-side connection. Use NumReceivedClientCerts to determine the valid range.

Returns null on failure

Returns the certificate presented by the remote TLS server for the current client-side TLS connection. It returns a null reference when the socket is not connected or the connection is not using TLS.

Returns null on failure

Returns a JSON object containing additional details produced by the most recently called method when such details are available.

Returns null on failure

Receives binary data and returns one delivery of bytes. 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 return zero bytes during TLS renegotiation. Treat this as no application data yet and call the receive method again.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveBytes method with the arguments provided.

Returns null on failure

Receives exactly numBytes bytes. The method continues receiving until the requested count is satisfied or a receive failure occurs. Inactivity is controlled by MaxReadIdleMs.

When the requested count is successfully completed, bytes read beyond that count may remain buffered internally for the next receive operation.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveBytesN method with the arguments provided.

Returns null on failure

Reads bytes until lookForByte is encountered and returns all bytes up to and including that byte. The argument must identify a one-byte value from 0 through 255.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the ReceiveUntilByte method with the arguments provided.

Returns null on failure

Sends the bytes in data 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.

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the SendBytes method with the arguments provided.

Returns null on failure

Opens a port-forwarded channel through the authenticated SSH tunnel to hostname:port. If ssl is 1, Chilkat performs TLS to the destination inside the SSH tunnel. maxWaitMs limits destination connection establishment.

Returns null on failure

Creates an asynchronous task to call the SshOpenChannel method with the arguments provided.

Returns null on failure