TChilkatSsh

Set to 1 to request that the currently running Chilkat operation abort. This applies to synchronous and asynchronous methods that may block on network or lengthy processing.

A synchronous call can be interrupted by setting this property from another thread. When the abort is observed, the current method returns failure, but the SSH connection and channel are not automatically closed. Bytes already buffered remain available, the remote process can continue running, and a later receive call can continue on the same channel. The same object and connection can also be used to open new channels afterward.

An aborted receive does not set DisconnectCode or DisconnectReason, and object-level configuration settings remain unchanged. An aborted Connect leaves the object disconnected but reusable for a later connection attempt.

When the abort is observed, Chilkat resets the property to 0. If no operation is running, it is reset when the next method begins.

Contains the result code from the most recent call to an SSH authentication method, including AuthenticatePw, AuthenticatePk, AuthenticatePwPk, and their SecureString variants. The initial value is 0, and a successful authentication resets it to 0. A failed attempt sets one of the following values.

Controls whether recognized caret notation is converted to ASCII control characters in strings passed to SendReqExec and ChannelSendString. The default is 0.

Caret  Dec  Hex  Name  Description
^@       0   00   NUL   Null
^A       1   01   SOH   Start of Heading
^B       2   02   STX   Start of Text
^C       3   03   ETX   End of Text
^D       4   04   EOT   End of Transmission
^E       5   05   ENQ   Enquiry
^F       6   06   ACK   Acknowledge
^G       7   07   BEL   Bell
^H       8   08   BS    Backspace
^I       9   09   HT    Horizontal Tab
^J      10   0A   LF    Line Feed
^K      11   0B   VT    Vertical Tab
^L      12   0C   FF    Form Feed
^M      13   0D   CR    Carriage Return
^N      14   0E   SO    Shift Out
^O      15   0F   SI    Shift In
^P      16   10   DLE   Data Link Escape
^Q      17   11   DC1   Device Control One (XON)
^R      18   12   DC2   Device Control Two
^S      19   13   DC3   Device Control Three (XOFF)
^T      20   14   DC4   Device Control Four
^U      21   15   NAK   Negative Acknowledge
^V      22   16   SYN   Synchronous Idle
^W      23   17   ETB   End of Transmission Block
^X      24   18   CAN   Cancel
^Y      25   19   EM    End of Medium
^Z      26   1A   SUB   Substitute
^[      27   1B   ESC   Escape
^\      28   1C   FS    File Separator
^]      29   1D   GS    Group Separator
^^      30   1E   RS    Record Separator
^_      31   1F   US    Unit Separator
^?     127   7F   DEL   Delete

Contains the SSH channel-open failure code when the server rejects a request to open a channel. The values are defined by RFC 4254.

The initial value is 0. A local failure, such as attempting to open a channel before connecting, can also leave this property at 0 because no SSH channel-open failure message was received. Read this property immediately after a channel-open method returns -1.

Contains the descriptive text associated with ChannelOpenFailCode when the server rejects a channel-open request. The text is supplied by the server and may be empty or generic. The initial value is an empty string.

A rejected channel-open request normally leaves the underlying SSH connection open. Local failures that occur before a request reaches the server may leave both this property and ChannelOpenFailCode unchanged.

Specifies the SSH client-identification string sent when a connection is established. The default is SSH-2.0-Chilkat_ followed by the Chilkat version, for example SSH-2.0-Chilkat_11.6.0.

This property is normally left unset. Set it only when the computer has multiple network interfaces or multiple local IP addresses and the application needs to use a specific one.

The value may be a numeric IPv4 or IPv6 address. Do not specify a domain name. When this property is empty, Chilkat and the operating system automatically select the appropriate local address.

The specified address must be available on the local computer and must be compatible with the address family used for the connection. If the address is invalid or unavailable, the connection fails.

This setting applies to all connection paths, including direct SSH connections, HTTP and SOCKS proxy connections, ConnectThroughSsh, and multi-hop SSH connections.

This property is normally left at its default value of 0. In this case, the operating system automatically chooses an unused local port from its ephemeral-port range. Applications should set a specific local port only when a remote system or network policy requires the connection to originate from that port.

When set to a nonzero value, Chilkat requests that exact local port. The connection fails if the port is already in use or is otherwise unavailable. A specifically chosen port might also be temporarily unavailable for reuse after a connection closes because of operating-system TCP connection management. These port-reuse concerns do not normally apply when this property remains 0.

This property applies to all connection paths, including direct SSH connections, HTTP and SOCKS proxy connections, ConnectThroughSsh, and multi-hop SSH connections.

Starting in Chilkat v11.6.0, assigned values must be in the range 0 through 65535. If a negative value or a value greater than 65535 is assigned, it is ignored and the existing property value remains unchanged.

Specifies the maximum number of milliseconds allowed for the remote endpoint to accept the TCP connection. The default is 30000 (30 seconds).

A value of 0 removes the Chilkat-imposed connect timeout; in practice, the attempt ends when the operating system reports that the connection failed. Negative values are treated as 0.

This timeout applies whether the destination is specified by a DNS hostname or an IP address, and to direct connections and connections made through HTTP proxies, SOCKS proxies, and ConnectThroughSsh. For ConnectThroughSsh, the inner Ssh object’s value is used.

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.

Contains the reason code from the most recent SSH DISCONNECT message received from the server. The values are defined by RFC 4253.

The initial value is 0. It also remains 0 after a normal local Disconnect, an ordinary TCP connection loss that did not include an SSH DISCONNECT message, a failed connection attempt, authentication rejection, receive timeout, receive abort, or rejected channel-open request.

When the server sends an SSH DISCONNECT, this property contains the server-provided code and remains available after CheckConnection. A subsequent call to Connect clears the value to 0, whether that new attempt succeeds or fails.

Contains the descriptive text sent with the most recent server SSH DISCONNECT message. See DisconnectCode for the corresponding RFC 4253 reason code.

The initial value is an empty string. It remains empty after a normal local Disconnect, an ordinary TCP connection loss without an SSH DISCONNECT message, a failed connection attempt, authentication rejection, receive timeout, receive abort, or rejected channel-open request.

When a server-sent SSH DISCONNECT is received, the text remains available after CheckConnection. A subsequent call to Connect clears it, whether the new attempt succeeds or fails. The returned string is empty rather than null when no reason is available.

Controls whether SSH compression may be negotiated. The default is 1, meaning compression is used when the server supports it.

Enables automatic resolution of secret specification strings from secure operating-system storage. The default is 0.

When 1, supported password properties and authentication methods may receive a value beginning with !! instead of a literal credential. Chilkat resolves the secret from Windows Credential Manager on Windows or Apple Keychain on macOS.

Secret specification format:

!![appName|]service[|domain]|username

This feature applies to HttpProxyPassword, SocksPassword, AuthenticatePw, and AuthenticatePwPk.

Restricts SSH cipher negotiation to one cipher or a comma-separated preference list. Leave this property empty to let Chilkat choose the first mutually supported cipher from its normal preference order.

Specifies the interval, in milliseconds, between AbortCheck event callbacks during operations that support progress events. The callback gives the application an opportunity to abort an operation before it completes.

The default is 0, which disables periodic AbortCheck callbacks.

Specifies the preferred host-key algorithm used during SSH connection establishment. The default is DSS; set it to RSA only when required for compatibility with a particular server.

Contains the connected server’s host-key fingerprint in Chilkat’s legacy MD5 format:

ssh-ed25519 256 c8:73:22:c7:82:aa:09:f1:1c:4e:99:8a:a0:62:a7:87

The value consists of the SSH host-key type, key size, and the MD5 digest represented as colon-separated hexadecimal bytes. It is empty before a successful connection and after a normal Disconnect, a server-sent SSH DISCONNECT, or a failed connection attempt.

After an abrupt TCP loss, a previously obtained fingerprint can temporarily remain even when IsConnected is 0. Therefore, a nonempty value is not proof that the connection is currently usable. Check IsConnected before relying on per-session state.

Specifies the authentication method used by an HTTP proxy. Matching is case-insensitive.

Basic and NTLM are the supported methods. Chilkat automatically handles a 407 Proxy Authentication Required response and performs the required authentication exchange.

NTLMv2 is used unless NTLMv1 is explicitly selected by setting Global.DefaultNtlmVersion to 1.

Specifies the optional Windows domain used for NTLM authentication with an HTTP proxy.

The value is the legacy Windows NetBIOS domain name. It is not a DNS domain name and is not the workstation name. This property is ignored unless NTLM proxy authentication is used.

Specifies the hostname or numeric IP address of an HTTP proxy.

Chilkat uses the HTTP CONNECT method to establish the SSH tunnel through the proxy. The TCP connection to the proxy is not itself protected by TLS for this SSH use case.

The HTTP proxy is used only when SocksVersion is 0, this property is nonempty, and HttpProxyPort is nonzero. A configured SOCKS proxy takes precedence. These settings apply to both Connect and ConnectThroughSsh.

Specifies the password used to authenticate with an HTTP proxy.

If the proxy requires authentication and this property is empty, the connection fails.

Specifies the HTTP proxy port.

An HTTP proxy is used only when SocksVersion is 0, HttpProxyHostname is nonempty, and this property is nonzero. A configured SOCKS proxy takes precedence.

Common proxy ports are:

• 8080 — the most common general-purpose HTTP proxy port. It is non-privileged, so the proxy service typically does not require administrator or root privileges to bind to it.
• 3128 — commonly used by Squid and enterprise proxy infrastructure.
• 8888 — commonly used by development and debugging proxies such as Charles Proxy, Fiddler, and Burp Suite.

Specifies the username used to authenticate with an HTTP proxy.

If the proxy requires authentication and this property is empty, the connection fails.

Specifies an inactivity interval, in milliseconds, for SSH receive waits that use this property. The default is 0, meaning no inactivity limit.

This is not simply an application-output timeout. Receiving any SSH packet, including transport or channel-control traffic that contains no stdout or stderr bytes, counts as communication and restarts the interval. A remote command can therefore remain silent longer than this value without necessarily causing a timeout.

Timeout handling is method-specific. Methods having an explicit timeout argument, such as ChannelPoll and WaitForChannelMessage, use that argument for the corresponding wait. In v11.6.0 testing, ChannelReadAndPoll used IdleTimeoutMs for its initial read when ReadTimeoutMs was 0.

This property governs receiving. It is not a send-progress timeout.

Returns 1 when Chilkat currently considers the SSH transport connected. It becomes 1 after Connect establishes the secure transport. It is 0 before connecting, after Disconnect, after a failed connection attempt, after a server-sent SSH DISCONNECT, or when socket closure is detected.

An authentication failure, channel-open rejection, receive timeout, or aborted receive does not by itself set this property to 0. If the underlying transport remains usable, the application can retry the operation on the same connection.

Reading this property can reflect a remote close that the operating system has already reported. In testing, it became 0 before CheckConnection was called. However, 1 does not prove that the remote server is responsive or that a silent network failure has not occurred.

After abrupt transport loss or a server protocol disconnect, retained per-channel state can be stale even though this property is 0. Treat IsConnected = 0 as authoritative for network I/O. Bytes received before the loss can remain available in a retained channel buffer.

Controls whether SSH protocol traffic is accumulated in SessionLog. The default is 0. This object-level setting persists across disconnects, failed operations, and subsequent connections until changed by the application.

The log for a completed session remains available after disconnect or transport loss. A later successful connection begins a new session log.

This property is mainly used in SQL Server stored procedures to retrieve binary data from the last method call that returned binary data. It is only accessible if Chilkat.Global.KeepBinaryResult is set to 1. This feature allows for the retrieval of large varbinary results in an SQL Server environment, which has restrictions on returning large data via method calls, though temp tables can handle binary properties.

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.

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.

In SQL Server stored procedures, this property holds the string return value of the most recent method call that returns a string. It is accessible only when Chilkat.Global.KeepStringResult is set to TRUE. SQL Server has limitations on string lengths returned from methods and properties, but temp tables can be used to access large strings.

The length, in characters, of the string contained in the LastStringResult property.

Specifies the maximum SSH channel packet size advertised in the SSH_MSG_CHANNEL_OPEN message. The default is 8192.

For high-volume transfers, a value such as 32768 may improve performance.

Returns the number of channel records in the active SSH channel collection. A channel is normally added after its open request is accepted and removed when final remote-close processing occurs.

After Disconnect or transport loss, this property returns 0 because former channels are no longer active or enumerable. Buffered data for a former channel can nevertheless remain retrievable by its channel number until it is released or a new connection clears it.

A channel closed locally with ChannelSendClose can have ChannelIsOpen return 0 while it is still counted until final cleanup. Conversely, a remotely closed channel can cease to be counted while its results are only temporarily retained.

Use GetChannelNumber and GetChannelType with zero-based indexes from 0 through NumOpenChannels - 1. Do not assume every enumerated channel is still open for application I/O.

Indicates that the server rejected password authentication because it requires the user to change the password. This property is set by AuthenticatePw and AuthenticatePwPk.

When 1, call the authentication method again and pass both passwords in this form:

|oldPassword|newPassword|

Controls which address family is selected when DNS resolution for a hostname returns both an IPv4 address and an IPv6 address.

• When 0 (the default), Chilkat selects the IPv4 address when one is available.
• When 1, Chilkat selects the IPv6 address when one is available.

This property expresses a preference; it does not prohibit use of the other address family when the preferred family is unavailable.

Specifies a receive timeout, in milliseconds, for SSH methods that use this property. The default is 0, meaning no ReadTimeoutMs limit.

The exact scope is method-specific:

A receive timeout does not discard bytes already received. The connection and channel can remain usable, and a later receive call can continue. Always inspect and preserve buffered stdout and stderr after a timeout.

Specifies the character encoding used for command text sent by SendReqExec, QuickCommand, and QuickCmdSend. The default is ANSI.

On Windows, ANSI uses the Windows ANSI code page returned by GetACP, not the OEM code page. Its exact meaning on non-Windows platforms is environment-dependent. For portable behavior, specify an explicit charset such as utf-8 or windows-1252.

This property applies to the command string itself. It does not override the explicit charset argument passed to ChannelSendString.

Contains the SSH server-identification string received during connection establishment. For example:

SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.16

The initial value is an empty string. After a successful connection, the value remains available after a normal Disconnect, a server-sent SSH DISCONNECT, or an abrupt transport loss.

A subsequent failed connection attempt clears this property rather than retaining the identifier from an earlier session. A successful reconnect replaces it with the newly received identifier. The empty result is an empty string, not null.

Contains the in-memory SSH protocol log for the current or most recently completed successful session. Enable logging by setting KeepSessionLog to 1.

The initial value is an empty string. A normal disconnect, server disconnect, or transport loss leaves the existing session log available. A later successful Connect starts a new session log rather than appending indefinitely to the previous session. A failed TCP connection attempt does not necessarily replace an existing session log; inspect LastErrorText for the failed call.

Authentication passwords and private-key passphrases are not included in the log. The log may contain server identifiers, negotiated algorithms, authentication method names, and other connection diagnostics.

Specifies the SOCKS proxy hostname or IPv4 address. This property is used only when SocksVersion is 4 or 5. An IPv6 address cannot be used for the SOCKS proxy.

SOCKS4a is not supported. With SOCKS5, the destination hostname is sent to the proxy and resolved remotely by the proxy. IPv6 destination addresses are not supported through SOCKS5.

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

SOCKS5 supports either no authentication or username/password authentication. Leave both SocksUsername and this property empty to request no authentication. The connection fails if the proxy requires an unsupported authentication method.

Specifies the SOCKS proxy port. The default is 1080. This property is used only when SocksVersion is 4 or 5.

Specifies the SOCKS username. For SOCKS4, it is sent as the SOCKS user ID. For SOCKS5, it is used with SocksPassword for username/password authentication.

For SOCKS5, leave both properties empty to request no authentication.

Selects whether and how a SOCKS proxy is used.

Assigning a value other than 4 or 5 sets the property to 0. These proxy settings apply to both Connect and ConnectThroughSsh.

Specifies the socket receive-buffer size. The default is 4194304 bytes. Normally this property should remain unchanged.

When download throughput is unexpectedly low, testing a larger value may help. Values should generally be multiples of 4096.

When a proxy is used, this setting applies to the TCP connection made to the proxy.

Specifies the socket send-buffer size. The default is 262144 bytes. Normally this property should remain unchanged.

When upload throughput is unexpectedly low, testing values such as 524288 or 1048576 may help. Values should generally be multiples of 4096.

When a proxy is used, this setting applies to the TCP connection made to the proxy.

Controls whether SSH extended-data received as stderr is merged into the normal channel receive buffer. The default is 1.

When 1, retrieve combined stdout and stderr with GetReceivedData, GetReceivedDataN, GetReceivedText, or GetReceivedTextS. When 0, retrieve SSH stderr separately with GetReceivedStderr or GetReceivedStderrText.

The setting is applied when each incoming stderr packet is processed. Changing it while a channel is active affects only stderr received afterward. Already separated stderr is not moved into stdout, and already merged stderr cannot later be separated.

Read-method return values count bytes in both the normal and separate stderr buffers. GetReceivedNumBytes counts only the normal receive buffer.

This setting also affects QuickCommand. When 0, its returned string contains stdout but does not include separately received stderr.

Controls whether ANSI SGR color and text-style sequences are removed from normal received text returned by GetReceivedText and GetReceivedTextS. The default is 1.

It removes ESC-prefixed CSI sequences ending in m, including empty, semicolon-separated, and colon-separated parameter forms such as ESC[m, ESC[1;31m, ESC[38;5;196m, and ESC[38:5:196m.

It does not remove non-SGR CSI sequences such as ESC[2J, OSC sequences, 8-bit C1 CSI sequences beginning with byte 0x9B, or an incomplete trailing SGR sequence.

For GetReceivedTextS, stripping applies to both the literal substring search and the returned value; the corresponding original raw escape-sequence bytes are consumed.

It does not affect raw-byte getters, PeekReceivedText, GetReceivedStderrText, pattern matching in ChannelReceiveUntilMatch, or the string returned by QuickCommand.

Controls the TCP_NODELAY setting for the underlying TCP connection. The default is 1, which disables the Nagle algorithm and generally improves responsiveness when many small messages are exchanged.

When a proxy is used, this setting applies to the TCP connection made to the proxy.

Provides comma-separated compatibility and security options for uncommon SSH scenarios. The default is an empty string, which is appropriate for most applications.

Contains a user-authentication banner received from the server during authentication. Check this property after StartKeyboardAuth or another authentication attempt and display it to the user when appropriate.

This is per-authentication runtime state, not a persistent connection setting. A value assigned by the application can remain before authentication begins, including across a failed connection attempt, but an authentication attempt clears or replaces the value. In testing, both successful and rejected password authentication cleared a previously assigned value when the server sent no banner.

When no banner is available, the property returns an empty string rather than null.

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"

Authenticates an active, unauthenticated SSH connection using public-key authentication. username identifies the server account, and privateKey must contain the corresponding private key. The public key must already be authorized for that account on the server.

An empty or public-only SshKey is rejected locally with AuthFailReason equal to 2; this local validation failure does not close the SSH connection.

If the server rejects the key but keeps the connection open, the application may retry on the same connection with another private key or a different authentication method. The server may instead disconnect after an authentication-attempt limit is reached. Reconnect before retrying when IsConnected is 0.

Calling this method before Connect fails with reason 1. Calling it after the session is already authenticated fails with reason 6.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Authenticates an active, unauthenticated SSH connection using login and password.

Call Connect first. Calling this method without a connection fails with AuthFailReason equal to 1. Calling it after the session is already authenticated fails with reason 6.

If authentication fails and the server keeps the SSH connection open, IsConnected remains 1 and the application may retry on the same connection with corrected credentials or a different authentication method. A later correct password succeeded on the same connection in testing. A server can disconnect after too many failed attempts; reconnect before retrying when IsConnected is 0.

An authentication attempt clears or replaces UserAuthBanner. Object-level configuration settings remain unchanged.

If the server requests a password change, see PasswordChangeRequested.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Authenticates with a server that requires both a password and a private key. username is the username, password is the password, and privateKey is the private key.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Performs the same authentication as AuthenticatePw, but receives the login and password in SecureString objects.

The connection-state, retry, timeout, and AuthFailReason behavior is the same as for AuthenticatePw.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Performs the same combined password/private-key authentication as AuthenticatePwPk, but receives the username and password in SecureString objects.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Returns 1 when channelNum identifies a channel that Chilkat currently considers open for application I/O; otherwise returns 0. It returns 0 for invalid or nonexistent channel numbers, after a normal local Disconnect, after remote closure is processed, and immediately after ChannelSendClose closes the channel locally.

NumOpenChannels can temporarily continue counting a locally closed channel until final remote-close processing occurs.

Polls channelNum for incoming SSH channel messages, waiting at most pollTimeoutMs milliseconds. Pass 0 for a nonblocking poll. The explicit pollTimeoutMs controls this wait; shorter values of ReadTimeoutMs or IdleTimeoutMs do not shorten it.

Data received is appended to the normal receive buffer or separate stderr buffer according to StderrToStdout.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Reads incoming SSH channel messages for channelNum. A nonzero ReadTimeoutMs limits the wait for channel input. Received data is appended to the normal receive buffer or separate stderr buffer according to StderrToStdout.

A timeout returns -2 rather than closing the channel. A later read can continue on the same channel.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Reads channelNum in two phases:

1. Waits for the first applicable channel message. A nonzero ReadTimeoutMs limits this initial wait. When ReadTimeoutMs is 0, IdleTimeoutMs can provide the initial-read timeout.
2. After data begins arriving, continues processing until no additional data arrives for pollTimeoutMs milliseconds.

The second phase is governed by pollTimeoutMs; a shorter ReadTimeoutMs does not shorten that quiet-period wait.

The method can return 0 or -2 while bytes remain buffered. Drain the normal and stderr buffers based on their actual contents, not solely on the method return value.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Works like ChannelReadAndPoll, but also returns after newly processed data causes the total buffered channel data to reach or exceed maxNumBytes.

maxNumBytes is a return threshold, not a hard receive-buffer limit. An entire SSH packet can be buffered, so the amount returned can exceed the requested threshold. Data already buffered before the call does not by itself cause an immediate threshold return.

A value of 0 or a negative value does not impose a useful threshold. For streaming large output, use a positive threshold, drain the buffer after each call, and perform a final drain when EOF or CLOSE is observed.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Returns 1 if an SSH CLOSE message has been received for channelNum. Remote CLOSE is distinct from EOF and closes the channel in both directions. When it is processed, ChannelIsOpen becomes 0 and the channel is normally removed from NumOpenChannels.

Returns 0 for an invalid, released, locally disconnected, or no-longer-retained channel number. A transport can be lost without receiving a channel CLOSE; check IsConnected separately.

Retrieve buffered output, stderr, and exit status promptly after the receive method completes and before calling ChannelRelease.

Returns 1 if an SSH EOF message has been received for channelNum. EOF means the server will send no more ordinary channel data. It does not close the channel.

The server can send EOF before it sends CLOSE. During that interval, this method is 1, ChannelReceivedClose is 0, and the channel can remain open and counted by NumOpenChannels. Exit status and CLOSE can arrive later.

Returns 0 for an invalid, released, disconnected, or no-longer-retained channel number. After transport failure, channel flags can be stale or unavailable; check IsConnected first.

Returns 1 if the server supplied an exit-status value for channelNum. When 1, call GetChannelExitStatus.

Exit status is independent of EOF and CLOSE. It can arrive after EOF and before or with CLOSE. The server is not required to send an exit status for every channel type or command.

Returns 0 for an invalid, released, disconnected, or no-longer-retained channel number. A connection failure does not synthesize an exit status.

Receives data on channelNum until the server sends and Chilkat processes channel CLOSE. The server can send EOF earlier; EOF alone does not complete this method.

Both normal data and stderr are processed. Stderr is merged or kept separate according to StderrToStdout. A nonzero ReadTimeoutMs limits the receive operation. IdleTimeoutMs is not a simple stdout/stderr inactivity timer because any SSH communication can restart it.

If the method times out or is canceled, bytes received before the failure remain buffered, the SSH connection and channel can remain open, and a later call can continue receiving on the same channel. These outcomes do not set DisconnectCode or DisconnectReason. If the SSH transport is lost, the method fails and IsConnected becomes 0, but bytes received before the loss can still remain retrievable.

This method buffers all received output in memory. It successfully accumulated at least 8 MiB in testing, but no upper limit was established. For potentially large or unbounded output, use incremental reads and drain the buffers as data arrives.

A 1 return means the SSH receive operation completed. It does not mean the remote command exited successfully.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Receives text on channelNum until the accumulated text matches matchPattern. Existing buffered text is checked before waiting for additional network data.

The supported pattern syntax consists of literal characters plus *, which matches zero or more characters and can span line breaks. It can appear anywhere in the pattern. The ? wildcard and bracket character classes are not supported, and backslash does not escape a literal *. A pattern containing only * waits until at least some text has arrived rather than matching an empty buffer immediately.

charset specifies the character encoding, and caseSensitive controls comparison. The method can read beyond the matched text because an entire SSH packet may already be available.

Matching considers stderr even when StderrToStdout is 0. StripColorCodes is not applied before matching.

A nonzero ReadTimeoutMs limits the wait. IdleTimeoutMs is not a substitute for this limit because unrelated SSH traffic can restart the inactivity interval.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Works like ChannelReceiveUntilMatch, but returns when any pattern in matchPatterns is matched. The array must contain at least one element.

The first matching content encountered in the received stream determines when the method returns; array order does not override an earlier token in the stream. Existing buffered text is checked before waiting. Empty elements are ignored, and duplicate patterns are allowed.

The method does not return the index or value of the pattern that matched, and GetLastJsonData does not identify it. After success, inspect the buffered text or use distinct nonoverlapping sentinels that the application can identify reliably.

The same pattern grammar, stderr behavior, and ReadTimeoutMs behavior described for ChannelReceiveUntilMatch apply.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Releases Chilkat’s retained local resources for channelNum after all required output and exit information has been retrieved. It does not send EOF or CLOSE and is not a channel-closing method.

Calling it while a channel is still protocol-open has no effect. It can also be called after Disconnect to discard buffered data retained for a former channel. After release, methods such as GetReceivedNumBytes report that the channel is unavailable.

Calling this method with an invalid channel number is a harmless no-op. Repeated calls are harmless.

ChannelReceiveToClose(channelNum)
GetReceivedText(...)
GetReceivedStderrText(...)
if (ChannelReceivedExitStatus(channelNum))
    GetChannelExitStatus(channelNum)
ChannelRelease(channelNum)

Sends an SSH CLOSE message for channelNum and immediately marks the channel locally closed. The method does not wait for remote EOF, remote CLOSE, or an exit status, and it does not guarantee that the remote process has terminated.

After a successful call, ChannelIsOpen returns 0, but NumOpenChannels can continue counting the channel until final remote-close processing occurs. A repeated call can succeed while the local channel record remains; after the remote CLOSE removes the channel, another call fails because the channel no longer exists.

For normal exec completion, prefer receiving through the remote CLOSE so all output and exit information can be collected. Use this method when the application intentionally abandons or closes the channel early.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Sends the exact bytes in byteData on channelNum. Binary values, including embedded zero bytes, are preserved. A zero-length byte array is valid and sends no data.

Chilkat splits large inputs into SSH packets and waits for channel-window adjustments as needed. A multi-megabyte input can be passed in one call.

Do not call this method after ChannelSendEof. A successful return after EOF does not guarantee delivery.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Sends an SSH EOF message on channelNum. This closes only the client-to-server data direction. The application may continue receiving stdout, stderr, exit status, EOF, and CLOSE from the server.

After EOF is sent, do not call ChannelSendData or ChannelSendString again for that channel. A later send call can return 1 even though the data is not delivered to the remote process. Repeated calls to ChannelSendEof are harmless but unnecessary.

For an exec request that reads standard input, EOF is the normal way to indicate that all input has been supplied.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Encodes textData using charset, then sends the resulting bytes on channelNum. No line ending or terminator is added automatically.

An empty string is valid and sends zero bytes. When CaretControl is 1, recognized caret sequences are translated to control characters before sending.

On Windows, ANSI uses the Windows ANSI code page returned by GetACP, not the OEM code page. Its meaning on other platforms is environment-dependent. Use an explicit charset such as utf-8 or windows-1252 for portable behavior.

Use a supported charset name. In v11.6.0, an unrecognized charset name was observed to fall back to UTF-8 rather than fail; applications should not rely on that fallback.

The method handles SSH packet sizing and channel-window flow control internally. It does not expose a partial-byte count if an error occurs.

Do not call this method after ChannelSendEof. A successful return after EOF does not guarantee that the text was delivered.

See Supported Charsets.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Returns 1 when the underlying SSH transport currently appears connected, and 0 when the object is unconnected, has been disconnected, a connection attempt failed, or transport loss has already been detected.

In testing, this method returned immediately and matched IsConnected. It should not be treated as an end-to-end SSH round trip or proof that the remote server is responsive. Use SendIgnore when an active SSH exchange is required.

This method does not authenticate the session. A failed authentication, receive timeout, receive abort, or rejected channel-open request can leave it returning 1 because those failures do not necessarily close the transport.

Returns 1 if the underlying TCP socket does not currently appear to be closed, or 0 if the connection is known to be closed or invalid.

Unlike IsConnected, which reports the connection state already known by the Ssh object, this method performs an additional non-consuming check of the socket. It calls the operating system's recv function with MSG_PEEK to inspect up to one byte without removing any data from the socket's receive buffer.

A receive timeout, aborted operation, authentication failure, or rejected channel request does not necessarily close the socket. In those cases, CheckConnection may continue to return 1.

A 0 result can simply mean that no connection exists. This method may not replace LastErrorText when no new socket error is generated, so the existing diagnostic text can describe an earlier operation.

Clears all TTY mode settings previously added with SetTtyMode. The next SendReqPty request will not include those cleared modes.

Establishes an SSH connection to domainName on the TCP port specified by port. The domainName may be a DNS hostname or a numeric IPv4 or IPv6 address. A null or empty domainName is treated as a zero-length hostname and causes the call to fail.

Proxy selection: If SocksVersion is 4 or 5, Chilkat connects through the configured SOCKS proxy. Otherwise, if HttpProxyHostname is nonempty and HttpProxyPort is nonzero, Chilkat connects through the HTTP proxy. If neither condition applies, Chilkat connects directly to the SSH server.

If this method is called while the object is already connected, Chilkat first disconnects the existing session and then establishes a new connection. This occurs even when connecting again to the same server. The existing connection and active channel collection are replaced. A new connection attempt also clears retained data belonging to channels from an earlier disconnected or lost session.

The same Ssh object may be reused after Disconnect, connection refusal, connect timeout, connect abort, server protocol disconnect, or abrupt transport loss. A failed call leaves IsConnected equal to 0. Every successful new connection is unauthenticated and must be authenticated again. Channel numbers are opaque and can continue increasing across reconnects; do not assume they restart at zero.

Supported negotiation algorithms include:

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Connects to another SSH server through the already connected and authenticated Ssh object in ssh. hostname and port identify the destination host and port.

application  →  first SSH server  →  destination SSH server

After this method succeeds, authenticate separately with the destination server by calling one of its Authenticate* methods.

The proxy properties, ClientIpAddress, ClientPort, and socket options on the inner object apply to this connection. SOCKS takes precedence over HTTP proxy settings, using the same selection rules as Connect.

The inner object’s ConnectTimeoutMs controls the timeout for establishing this connection.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Continues keyboard-interactive authentication by submitting the response in response. For a single prompt, response may be the response text. When the preceding information request contains multiple prompts, supply an XML response:

<response>
  <response1>response to first prompt</response1>
  <response2>response to second prompt</response2>
  ...
</response>

The returned XML has one of three forms: authentication success, authentication failure, or another information request containing additional prompts.

<success>success message</success>

<error>error message</error>

<infoRequest numPrompts="N">
  <name>name</name>
  <instruction>instructions</instruction>
  <prompt1 echo="1_or_0">prompt text</prompt1>
  ...
</infoRequest>

Returns a zero-length WideString on failure

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Closes the current SSH transport. It is harmless to call when no connection exists and may be called repeatedly.

After this method returns, IsConnected is 0, NumOpenChannels is 0, and former channels are no longer open or enumerated. However, bytes that were already buffered for a former channel can remain retrievable by its channel number after the disconnect. Retrieve the data and call ChannelRelease, or allow the next Connect call to clear retained old-channel data.

A local disconnect does not set DisconnectCode or DisconnectReason; they remain 0 and an empty string. ServerIdentifier remains available, while HostKeyFingerprint is cleared.

The Ssh object remains reusable. Writable configuration settings are not reset and remain in effect for subsequent calls to Connect. Every new connection begins unauthenticated.

Queries a connected, unauthenticated SSH server for its advertised user-authentication methods. The result is a lowercase, comma-separated list without spaces, such as publickey,password,keyboard-interactive.

Returns a zero-length WideString on failure

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Returns the remote process exit status received for channelNum. Call this method only after ChannelReceivedExitStatus returns 1.

Retrieve the value immediately after the receive operation and before calling unrelated SSH methods, querying NumOpenChannels, or releasing the channel. After the completed channel record is removed, a returned numeric 0 is not a valid substitute for checking method success.

An exit status of 0 conventionally indicates success on Unix-like systems; nonzero meanings are determined by the remote program and operating system. A nonzero exit status is not a Chilkat API failure and does not cause SendReqExec or ChannelReceiveToClose to fail.

Returns the channel number at zero-based enumeration index in the active channel collection. The index is an enumeration position, not a channel number. Use NumOpenChannels to determine the valid range from 0 through NumOpenChannels - 1.

Returns -1 when index is negative or otherwise out of range, including index 0 when the collection is empty. Channel numbers are opaque identifiers; do not assume they start at 0, reset after reconnect, are sequential, or are reused predictably.

The active collection can temporarily include a channel that was closed locally and is awaiting final remote-close processing. Former channels retained only for buffered-result retrieval after disconnect are not enumerated.

Returns the type of the channel at zero-based enumeration index in the active channel collection. The index is an enumeration position, not a channel number. Possible values include session, x11, forwarded-tcpip, and direct-tcpip.

If index is negative or otherwise out of range, the string-returning method reports failure, returns null, and sets LastMethodSuccess to 0. This includes index 0 when NumOpenChannels is 0.

The active collection can temporarily include a channel that was closed locally but is still awaiting final remote-close processing. Former channels retained only for buffered-result retrieval after disconnect are not enumerated.

Returns a zero-length WideString on failure

Returns the active connection’s server host-key fingerprint. hashAlg specifies the hash algorithm. Hash-algorithm names are case-insensitive. Common choices include SHA256, SHA384, SHA512, SHA1, MD5, and the supported SHA-3 algorithms.

The digest is Base64 encoded without trailing padding characters. includeKeyType controls whether the host-key type is included, and includeHashName controls whether the canonical hash name is included.

An active SSH connection is required. The method fails when called before connecting or after disconnecting. For MD5, this method still returns an unpadded Base64 digest; it does not return the colon-separated hexadecimal form used by HostKeyFingerprint.

Returns a zero-length WideString on failure

Copies structured diagnostic information from the most recently called method into the JsonObject in json. Many methods do not produce additional JSON details; in those cases the object may contain little or no information.

Authentication passwords and private-key passphrases are not included in this diagnostic JSON.

Appends all bytes currently accumulated in the normal receive buffer for channelNum to bd, then clears the channel receive buffer.

Existing bytes in bd are preserved and the received bytes are appended. If the method fails, such as for an invalid channel, bd is left unchanged.

Returns 1 for success, 0 for failure.

Returns all bytes currently accumulated in the normal receive buffer for channelNum, then clears that buffer.

For a valid retained channel with no buffered data, the method succeeds and returns a zero-length byte array. For an invalid or no-longer-retained channel, it fails. The separate stderr buffer is not affected.

Data received before a timeout, cancellation, or abrupt transport loss can still be returned. After normal channel completion, call this method before unrelated SSH operations that can finalize and remove the completed channel record.

Returns a zero-length byte array (as an OleVariant) on failure.
An empty array will have a VarArrayHighBound of -1 meaning 0 elements.

Returns and removes up to maxNumBytes bytes from the beginning of the normal receive buffer for channelNum. Any remaining bytes stay buffered.

If maxNumBytes is 0, the method succeeds, returns zero bytes, and consumes nothing. If it is negative or greater than the available amount, all currently buffered bytes are returned and removed. An empty valid buffer returns success with a zero-length result.

Returns a zero-length byte array (as an OleVariant) on failure.
An empty array will have a VarArrayHighBound of -1 meaning 0 elements.

Returns the number of bytes currently available in the normal receive buffer for channelNum. It does not include bytes in the separate stderr buffer when StderrToStdout is 0.

Returns -1 when the channel number is invalid or its retained resources have been released. After a normal Disconnect or abrupt transport loss, bytes received earlier can remain available and this method can still return their count even though the channel is no longer active or enumerable. A subsequent Connect clears retained data from the previous session.

Buffered bytes can also remain after a timeout or cancellation. After normal channel completion, a later unrelated SSH operation can finalize and discard the completed channel record. Query and drain the buffer promptly.

Retrieve normal bytes with GetReceivedData, GetReceivedDataN, GetReceivedBd, or a text getter. Retrieve separate stderr with GetReceivedStderr or GetReceivedStderrText.

Returns all bytes currently accumulated in the separate stderr buffer for channelNum, then clears that buffer.

For a valid retained channel with no separate stderr, the method succeeds and returns a zero-length byte array. For an invalid or no-longer-retained channel, it fails. Retrieve stderr immediately after completion, before another SSH operation can discard the completed channel record.

Returns a zero-length byte array (as an OleVariant) on failure.
An empty array will have a VarArrayHighBound of -1 meaning 0 elements.

Decodes and returns all text currently accumulated in the separate stderr buffer for channelNum, using charset. The stderr buffer is cleared after the text is returned.

For a valid retained channel with no separate stderr, an empty string is returned successfully. For an invalid or no-longer-retained channel, the string-returning API reports failure. Retrieve stderr immediately after completion, before another SSH operation can discard the completed channel record.

StripColorCodes is not applied to stderr text. Text getters do not retain an incomplete multibyte sequence for a later call; use raw bytes and a stateful application decoder for streaming multibyte data.

See Supported Charsets.

Returns a zero-length WideString on failure

Decodes and returns all text currently accumulated in the normal receive buffer for channelNum, using charset. The receive buffer is cleared after the text is returned.

For a valid retained channel with no buffered data, an empty string is returned successfully. For an invalid or no-longer-retained channel, the string-returning API reports failure. After channel completion, retrieve text immediately before unrelated SSH operations can discard the completed channel record.

When StripColorCodes is 1, ANSI SGR color/style sequences are removed from the returned normal text. Other terminal-control sequences can remain.

See Supported Charsets.

Returns a zero-length WideString on failure

Decodes text in the normal receive buffer for channelNum and performs a literal, case-sensitive search for substr using charset.

If found, the method returns and removes everything through and including the first occurrence. If not found, it returns an empty string successfully and leaves the buffer unchanged. An empty substr is invalid and causes failure without consuming the buffer.

When StripColorCodes is 1, SGR sequences are removed for both the substring search and the returned value. The method consumes the corresponding original raw bytes, including the stripped escape sequences.

As with other destructive text getters, incomplete multibyte sequences are not retained as decoder state for a later call. Retrieve completed-channel text before unrelated SSH operations can remove the retained channel record.

Returns a zero-length WideString on failure

Loads into this object the caller state associated with the asynchronous method represented by task. This is used by generated asynchronous wrappers to recover the object that initiated the task.

Returns 1 for success, 0 for failure.

Requests a custom SSH channel whose application-defined channel type is supplied in channelType. The SSH server must implement that channel type. On success, returns the channel number used by the normal channel send, receive, EOF, CLOSE, and release methods.

Returns -1 if the server rejects the channel. In that case, ChannelOpenFailCode and ChannelOpenFailReason contain the server-provided failure information. The underlying SSH connection normally remains open, CheckConnection remains 1, and other channels can be opened and used afterward.

A channel-open rejection does not set DisconnectCode or DisconnectReason unless the server also sends an SSH DISCONNECT. Object-level configuration settings are unchanged.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Opens a direct-tcpip channel through the SSH server to targetHostname and targetPort. The target name is sent to and resolved by the SSH server, not by the client computer. It must therefore be resolvable and reachable from the server's network environment. A numeric IPv4 address may be supplied to avoid remote DNS-name resolution.

Each successful call creates one independent raw TCP byte stream. Multiple channels to the same target may be open concurrently. Bytes sent with ChannelSend* methods are forwarded to the target, and bytes returned by the target are read with ChannelRead* or ChannelReceive* methods. For example, when the target is an SSH server, its SSH identification line is received as ordinary channel data. The channel is enumerated with type direct-tcpip.

Returns the new channel number on success, or -1 if the SSH server rejects or cannot establish the target connection. On server rejection, inspect ChannelOpenFailCode and ChannelOpenFailReason. Name-resolution and target-connection failures normally leave the underlying SSH connection open.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Opens a new SSH session channel. The SSH transport must already be connected and user authentication must have completed successfully. Calling this method before Connect or before authentication returns -1. A failure caused by missing authentication does not by itself close the SSH transport.

Opening a session channel does not start a shell, execute a command, or start a subsystem. After opening the channel, send the appropriate session request.

1. Connect
2. Authenticate
3. OpenSessionChannel
4. Optionally send preparatory requests such as SendReqPty or SendReqSetEnv
5. Send one primary request: SendReqExec, SendReqShell, or SendReqSubsystem

Returns an opaque channel number on success, or -1 on failure. Do not assume channel numbers start at 0, are sequential, or are reused in a predictable way.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Returns the text currently buffered in the normal receive buffer for channelNum, decoded using charset, without removing any bytes.

For a valid empty buffer, it returns an empty string successfully. StripColorCodes is not applied; terminal escape sequences are returned as buffered. Because the operation is nondestructive, it is useful for checking whether a complete multibyte sequence or logical delimiter has arrived before calling a destructive text getter.

Returns a zero-length WideString on failure

Waits up to pollTimeoutMs milliseconds for any command previously started by QuickCmdSend to complete. A value of 0 performs a nonblocking check. Manually opened exec channels are not returned by this method.

After a channel number is returned, retrieve its stdout, stderr, and exit status with the normal channel methods. The channel is not returned again on the next check, even before ChannelRelease is called.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Starts a remote command and immediately returns its channel number, allowing multiple commands to run concurrently on the same authenticated SSH connection. Internally, this method opens a session channel and sends an exec request.

command is encoded according to ReqExecCharset. The returned channel is visible through NumOpenChannels, GetChannelNumber, and GetChannelType, and remains owned by the application. Use QuickCmdCheck to detect completion, retrieve output and exit status with the normal channel methods, and then call ChannelRelease. Returns -1 on failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Executes one noninteractive remote command and returns the stdout collected as text. Internally, this method opens a session channel, sends an exec request, receives the command output through EOF, and decodes the stdout using charset. ReqExecCharset controls the encoding used to send command.

The final SSH channel CLOSE can still be pending when this method returns. The internal channel may therefore remain temporarily visible in NumOpenChannels, often with EOF already received but CLOSE not yet processed. Simply sleeping does not process pending SSH messages. A later SSH operation, such as WaitForChannelMessage or another QuickCommand, processes the final close and removes the previous channel.

Use QuickCmdSend/QuickCmdCheck or the explicit channel workflow when the application must reliably inspect stderr, provide stdin, or obtain the remote exit status. Do not depend on the temporary internal channel created by this convenience method.

Returns a zero-length WideString on failure

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Starts a remote shell using the simplified sequence OpenSessionChannel → SendReqPty → SendReqShell. The default PTY size is 80 columns by 24 rows. Returns the open shell channel number on success, or -1 on failure.

The method returns after the shell request is accepted; it does not wait for or consume the initial login text or shell prompt. Use the returned channel with the normal send and receive methods, then allow the shell to close and call ChannelRelease after retrieving the required output and exit information.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Initiates SSH key re-exchange and waits for it to complete. Either client or server may initiate rekeying at any time.

RFC 4253 recommends changing keys after approximately one gigabyte of transferred data or one hour of connection time, whichever occurs first. In normal use, servers initiate rekeying as needed and Chilkat handles it transparently.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Sends an SSH IGNORE message. The server does not reply, but a successful send helps verify that the connection is still writable. No channel is required.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Requests execution of commandLine on the session channel identified by channelNum. The command text is sent using ReqExecCharset.

An exec channel is used for one command. Open a new session channel for each independent command. A second exec request on the same channel is normally rejected, while the first command continues running.

After the request is accepted, data sent with ChannelSendData or ChannelSendString becomes the command’s standard input. Call ChannelSendEof when no more input will be sent; stdout and stderr may still be received afterward.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Requests a pseudo-terminal for session channel channelNum. The request must be sent before the primary SendReqExec or SendReqShell request.

The termType argument identifies the terminal type and normally becomes the remote session's TERM environment variable. The server and remote applications use this value to look up terminal capabilities in their terminfo or termcap database. The character and pixel dimensions describe the terminal window. Terminal modes previously added with SetTtyMode are included in the request.

When no PTY is requested, the remote shell or command normally sees standard input and output as pipes rather than a terminal. Shells and programs commonly detect this using a check such as isatty() and operate in non-interactive mode. In that mode, the server normally does not send a shell prompt, does not echo submitted commands, and avoids terminal-oriented output such as ANSI color and cursor-control sequences. Shell startup behavior can vary according to the remote shell and its configuration.

Without a prompt, an application must not wait for text such as user@host:~$ to determine when a command is finished. For an exec request, use the SSH protocol state: receive through channel EOF/CLOSE and inspect the exit status with ChannelReceivedExitStatus and GetChannelExitStatus. For a long-lived shell channel, append a unique sentinel to each submitted command and receive until that sentinel is found.

The terminal type is a declaration of capabilities, not a filter applied by Chilkat. A remote application can ignore TERM, force color, or emit escape sequences regardless of the selected type. If needed, also try sending environment requests such as NO_COLOR=1 with SendReqSetEnv. Servers commonly restrict client-supplied environment variables, so setting termType to dumb in the PTY request is generally more reliable than attempting to set TERM separately.

A PTY changes remote-process behavior. Programs may display prompts, echo input, enable line buffering, execute interactive startup logic, emit terminal-control sequences, or alter formatting. Chilkat does not perform terminal emulation. A PTY also normally combines the remote process's stdout and stderr into one terminal stream, so StderrToStdout cannot preserve separate stderr on such a channel.

Recommended automation workflow:
1. OpenSessionChannel
2. Do not call SendReqPty unless terminal behavior is required
3. If a PTY is required but plain text is preferred, use termType = "dumb"
4. SendReqExec, or SendReqShell when multiple commands are required
5. Receive output and use SSH channel state, exit status, or a unique sentinel to detect completion

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Requests that the server set environment variable name to value for the session channel identified by channelNum. Send environment requests before the primary exec, shell, or subsystem request.

Multiple variables may be requested. If the server accepts repeated requests for the same name, the later value is used. An empty value is allowed. The server controls which names are accepted; for example, an OpenSSH configuration can accept selected locale variables while rejecting arbitrary names.

A 1 return means the server accepted this environment request. A rejected request returns 0 but normally leaves the channel and SSH connection usable, so the application can continue with the primary request. A request sent after the primary request has started is normally rejected.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Starts a remote shell on the open session channel identified by channelNum. A shell can be requested without a PTY when the server permits it. For an interactive terminal session, call SendReqPty first.

A 1 return means the server accepted the shell request. This method does not wait for, detect, or remove a shell prompt. Login messages, prompts, command echo, and command output all arrive as ordinary channel data.

Send commands with ChannelSendString using the line ending expected by the remote shell or device. Unix-like shells normally accept LF; other systems may require CRLF or another terminator. Multiple commands may be sent sequentially until the shell exits or the channel closes.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Requests delivery of signalName to the remote process running on channelNum. Send the request after the exec process, shell, or subsystem has started. Supported signal names are:

ABRT  ALRM  FPE  HUP  ILL  INT  KILL
PIPE  QUIT  SEGV TERM USR1 USR2

These are Unix-style signals and are effective only when supported by the SSH server, remote operating system, and target process. A 1 return indicates that the SSH request succeeded; the process may handle, ignore, or otherwise respond to the signal according to remote behavior.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Requests the predefined subsystem named by subsystemName on session channel channelNum. A 1 return means the server accepted the subsystem request; subsequent protocol data is exchanged with the normal channel send and receive methods.

If the server rejects the subsystem, this method returns 0 and the channel normally remains open and reusable for another primary request such as SendReqExec. Once a subsystem request is accepted, do not send an exec, shell, or second subsystem request on that channel.

For example, the SSH sftp subsystem can be started this way, but applications should normally use the SFtp class instead of implementing the SFTP protocol directly over an Ssh channel.

Returns 1 for success, 0 for failure.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Notifies the server that the terminal dimensions changed for the PTY associated with channelNum. widthInChars and heightInRows specify the character dimensions; pixWidth and pixHeight specify the pixel dimensions.

This request may be sent after the PTY is allocated, either before or after starting the shell or exec process. The tested OpenSSH servers applied the new character dimensions to an active shell.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Sends an SSH X11-forwarding request on the session channel in channelNum. singleConnection controls whether forwarding is limited to a single connection; authProt through screenNum provide the X11 authentication protocol, cookie, and screen number.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Deprecated for practical use. This method should not be used.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Applies an explicit allow-list of SSH negotiation algorithms supplied in json. Use this method before Connect when security policy or server compatibility requires precise control over accepted host-key, key-exchange, cipher, MAC, or compression algorithms.

Returns 1 for success, 0 for failure.

Adds or updates one TTY mode to be included in a later SendReqPty request. ttyName is the mode name and ttyValue is its integer value. Call this method before SendReqPty, once for each mode to set. For example, SetTtyMode("ECHO", 0) requests that command input not be echoed by the allocated terminal.

Supported mode names include:

VINTR VQUIT VERASE VKILL VEOF VEOL VEOL2 VSTART VSTOP
VSUSP VDSUSP VREPRINT VWERASE VLNEXT VFLUSH VSWTCH VSTATUS
VDISCARD IGNPAR PARMRK INPCK ISTRIP INLCR IGNCR ICRNL IUCLC
IXON IXANY IXOFF IMAXBEL ISIG ICANON XCASE ECHO ECHOE ECHOK
ECHONL NOFLSH TOSTOP IEXTEN ECHOCTL ECHOKE PENDIN OPOST OLCUC
ONLCR OCRNL ONOCR ONLRET CS7 CS8 PARENB PARODD
TTY_OP_ISPEED TTY_OP_OSPEED

Begins keyboard-interactive authentication for the login in login. The returned XML describes the server’s prompts and whether each response should be echoed.

<infoRequest numPrompts="N">
  <name>name</name>
  <instruction>instructions</instruction>
  <prompt1 echo="1_or_0">prompt text</prompt1>
  ...
</infoRequest>

If authentication immediately succeeds or fails, the returned XML instead has one of these forms:

<success>success message</success>

<error>error message</error>

Submit responses with ContinueKeyboardAuth.

Returns a zero-length WideString on failure

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

Waits for the next SSH channel message on any channel. The pollTimeoutMs argument controls this method:

• 0: nonblocking check.
• > 0: wait up to the specified number of milliseconds.
• < 0: wait without a method-level timeout.

The explicit argument governs the wait; shorter values of ReadTimeoutMs or IdleTimeoutMs do not shorten it.

The method processes one pending channel message. Ordinary data is appended to the appropriate channel buffer, and control messages can update EOF, CLOSE, and exit-status state. It does not consume bytes already buffered for the application.

A channel is not returned again merely because unread bytes remain buffered, but it can be returned again for a later stderr, EOF, exit-status, or CLOSE message.

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

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

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.

Delphi ActiveX Event callback implementation:

procedure TForm1.sshAbortCheck(ASender: TObject;  out abort: Integer);
begin
    // Application code goes here...
end;


procedure TForm1.Button1Click(Sender: TObject);
var
  ssh: TChilkatSsh;

begin
  ssh := TChilkatSsh.Create(Self);
  ssh.OnAbortCheck := sshAbortCheck;
  // ...

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 1. This will cause the method to terminate and return a failure status or corresponding failure value.

Delphi ActiveX Event callback implementation:

procedure TForm1.sshPercentDone(ASender: TObject;  pctDone: Integer; out abort: Integer);
begin
    // Application code goes here...
end;


procedure TForm1.Button1Click(Sender: TObject);
var
  ssh: TChilkatSsh;

begin
  ssh := TChilkatSsh.Create(Self);
  ssh.OnPercentDone := sshPercentDone;
  // ...

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.

Delphi ActiveX Event callback implementation:

procedure TForm1.sshProgressInfo(ASender: TObject;  const name: WideString; const value: WideString);
begin
    // Application code goes here...
end;


procedure TForm1.Button1Click(Sender: TObject);
var
  ssh: TChilkatSsh;

begin
  ssh := TChilkatSsh.Create(Self);
  ssh.OnProgressInfo := sshProgressInfo;
  // ...

Called from the background thread when an asynchronous task completes.

Delphi ActiveX Event callback implementation:

procedure TForm1.sshTaskCompleted(ASender: TObject;  const task: IChilkatTask);
begin
    // Application code goes here...
end;


procedure TForm1.Button1Click(Sender: TObject);
var
  ssh: TChilkatSsh;

begin
  ssh := TChilkatSsh.Create(Self);
  ssh.OnTaskCompleted := sshTaskCompleted;
  // ...

This method is deprecated. Call GetLastJsonData instead.

Returns structured diagnostic information about the most recently called method when such information is available. Authentication passwords and private-key passphrases are not included.

Returns nil on failure