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 null-terminated 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 null-terminated string which specifies the user name which will be used to authenticate the client session.
lpszPassword
A pointer to a null-terminated string which specifies the password which will be used to authenticate the client session.
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 that 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 options specifies that the user password cannot be terminated with a null byte. This option is ignored with SSH-2 connections and should only be specified if required by the server.
SSH_OPTION_NOREKEY This option specifies that 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 that 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 that 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 that 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_FREETHREAD This option specifies that 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

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

Client: Requires Windows 7, Windows Vista or Windows XP.
Server: Requires Windows Server 2008 or Windows Server 2003.
Header: Include cstools7.h.
Library: Use cstshav7.lib.
Unicode: Implemented as Unicode and ANSI versions.

See Also

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

  
 

Copyright © 2012 Catalyst Development Corporation. All rights reserved.