SshConnect Function  
 
HCLIENT WINAPI SshConnect(
  LPCTSTR lpszRemoteHost,  
  UINT nRemotePort,  
  LPCTSTR lpszUserName,  
  LPCTSTR lpszPassword,  
  UINT nTimeout,  
  DWORD dwOptions,  
  LPSSHOPTIONDATA lpOptions,  
  LPSECURITYCREDENTIALS lpCredentials  
);

The SshConnect function is used to establish a connection with the server.

Parameters

lpszRemoteHost
A pointer to a string which specifies the name of the server to connect to. This may either be a fully-qualified domain name or an IP address. This parameter cannot be NULL.
nRemotePort
The port number the server is listening on. A value of zero specifies that the default port number 22 should be used.
lpszUserName
A pointer to a string which specifies the user name which will be used to authenticate the client session. This parameter must specify a valid user name and cannot be NULL or an empty string.
lpszPassword
A pointer to a string which specifies the password which will be used to authenticate the client session. If the user does not have a password, this parameter can be NULL or an empty string.
nTimeout
The number of seconds that the client will wait for a response from the server before failing the current operation.
dwOptions
An unsigned integer that specifies one or more options. This parameter is constructed by using a bitwise operator with any of the following values:
Constant Description
SSH_OPTION_NONE No options specified. A standard terminal session will be established with the default terminal type.
SSH_OPTION_KEEPALIVE This option specifies the library should attempt to maintain an idle client session for long periods of time. This option is only necessary if you expect that the connection will be held open for more than two hours.
SSH_OPTION_NOPTY This option specifies that a pseudoterminal (PTY) should not be created for the client session. This option is automatically set if the SSH_OPTION_COMMAND option has been specified.
SSH_OPTION_NOSHELL This option specifies that a command shell should not be used when executing a command on the server.
SSH_OPTION_NOAUTHRSA This option specifies that RSA authentication should not be used with SSH-1 connections. This option is ignored with SSH-2 connections and should only be specified if required by the server.
SSH_OPTION_NOPWDNULL This option specifies the user password cannot be terminated with a null character. This option is ignored with SSH-2 connections and should only be specified if required by the server.
SSH_OPTION_NOREKEY This option specifies the client should never attempt a repeat key exchange with the server. Some SSH servers do not support rekeying the session, and this can cause the client to become non-responsive or abort the connection after being connected for an hour.
SSH_OPTION_COMPATSID This compatibility option changes how the session ID is handled during public key authentication with older SSH servers. This option should only be specified when connecting to servers that use OpenSSH 2.2.0 or earlier versions.
SSH_OPTION_COMPATHMAC This compatibility option changes how the HMAC authentication codes are generated. This option should only be specified when connecting to servers that use OpenSSH 2.2.0 or earlier versions.
SSH_OPTION_TERMINAL This option specifies the client session will use terminal emulation and the SSHOPTIONDATA structure specifies the characteristics of the virtual terminal. This enables the caller to specify the dimensions of the virtual display (in columns and rows) and the type of terminal that will be emulated. If this option is omitted, the session will default to a virtual display that is 80 columns, 25 rows.
SSH_OPTION_COMMAND This option specifies the client session will be used to issue a command that is executed on the server, and the output will be returned to the caller. If this option is specified, the session will not be interactive and no pseudoterminal is created for the client. The szCommandLine member of the SSHOPTIONDATA structure specifies the command string that will be sent to the server.
SSH_OPTION_PROXYSERVER This option specifies the client should establish a connection through a proxy server. The two protocols that are supported are SSH_PROXY_HTTP and SSH_PROXY_TELNET, which specifies the protocol that the proxy connection is created through. The proxy-related members of the SSHOPTIONDATA structure should be set to the appropriate values.
SSH_OPTION_PREFER_IPV6 This option specifies the client should prefer the use of IPv6 if the server hostname can be resolved to both an IPv6 and IPv4 address. This option is ignored if the local system does not have IPv6 enabled, or when the hostname can only be resolved to an IPv4 address. If the server hostname can only be resolved to an IPv6 address, the client will attempt to establish a connection using IPv6 regardless if this option has been specified.
SSH_OPTION_FREETHREAD This option specifies the handle returned by this function may be used by any thread, and is not limited to the thread which created it. The application is responsible for ensuring that access to the handle is synchronized across multiple threads.
lpOptions
A pointer to a SSHOPTIONDATA structure which specifies additional information for one or more options. If no optional data is required, a NULL pointer may be specified.
lpCredentials
A pointer to a SECURITYCREDENTIALS structure which specifies additional security-related information required to establish the connection. This parameter may be NULL, in which case default values will be used. Note that the dwSize member must be initialized to the size of the SECURITYCREDENTIALS structure that is being passed to the function.

Return Value

If the function succeeds, the return value is a handle to a client session. If the function fails, the return value is INVALID_CLIENT. To get extended error information, call SshGetLastError.

Remarks

To prevent this function from blocking the main user interface thread, the application should create a background worker thread and establish a connection by calling SshConnect in that thread. If the application requires multiple simultaneous connections, it is recommended you create a worker thread for each client session.

The dwOptions argument can be used to specify the threading model that is used by the library when a connection is established. By default, the handle is initially attached to the thread that created it. From that point on, until the it is released, only the owner may call functions using that handle. The ownership of the handle may be transferred from one thread to another using the SshAttachThread function.

Specifying the SSH_OPTION_FREETHREAD option enables any thread to call any function using the handle, regardless of which thread created it. It is important to note that this option disables certain internal safety checks which are performed by the library and may result in unexpected behavior unless access to the handle is synchronized. If one thread calls a function in the library, it must ensure that no other thread will call another function at the same time using the same handle.

Example

HCLIENT hClient;
SSHOPTIONDATA sshOptions;

// Initialize the SSHOPTIONDATA structure and specify the
// command that should be executed on the server
ZeroMemory(&sshOptions, sizeof(sshOptions));
lstrcpyn(sshOptions.szCommandLine, lpszCommand, SSH_MAXCOMMANDLEN);

// Establish a connection with the SSH server

hClient = SshConnect(lpszHostName,
                     SSH_PORT_DEFAULT,
                     lpszUserName,
                     lpszPassword,
                     SSH_TIMEOUT,
                     SSH_OPTION_COMMAND,
                     &sshOptions,
                     NULL);

// If the connection attempt fails, then get a description of
// the error and display it in a message box

if (hClient == INVALID_CLIENT)
{
    DWORD dwError;
    TCHAR szError[128];

    dwError = SshGetLastError();
    if (dwError > 0)
    {
        SshGetErrorString(dwError, szError, 128);
        MessageBox(NULL, szError, _T("Error"), MB_ICONEXCLAMATION);
    }

    return;
}

Requirements

Minimum Desktop Platform: Windows 7 (Service Pack 1)
Minimum Server Platform: Windows Server 2008 R2 (Service Pack 1)
Header File: cstools10.h
Import Library: cstshv10.lib
Unicode: Implemented as Unicode and ANSI versions.

See Also

SshCreateSecurityCredentials, SshDeleteSecurityCredentials, SshDisconnect, SshExecute, SshInitialize, SshUninitialize, SECURITYCREDENTIALS, SSHOPTIONDATA

 
 

Copyright © 2023 Catalyst Development Corporation. All rights reserved.