| |
| BOOL Connect( |
| |
LPCTSTR lpszRemoteHost, |
|
| |
UINT nRemotePort, |
|
| |
LPCTSTR lpszUserName, |
|
| |
LPCTSTR lpszPassword, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions, |
|
| |
LPSSHOPTIONDATA lpOptions |
|
| ); |
The Connect method establishes a connection with the
specified server.
Parameters
- lpszRemoteHost
- A pointer to the name of the server to connect to; this
may be a fully-qualified domain name or an IP address.
- 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:
| Value |
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 an extended period of time. The actual client idle
timeout period is determined by the server configuration. |
| 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. This option should never be used with interactive
client sessions. |
| SSH_OPTION_NOSHELL |
This option specifies that a command shell should not be
used when executing a command on the server. You should not use
this option unless you require the command to execute without
the normal shell environment. In most cases you should not use
this option because it may cause commands to fail unexpectedly. |
| 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.
- hEventWnd
- The handle to the event notification window. This window
receives messages which notify the client of various asynchronous
network events that occur. If this argument is NULL, then the
client session will be blocking and no network events will be sent
to the client.
- uEventMsg
- The message identifier that is used when an asynchronous
network event occurs. This value should be greater than WM_USER as
defined in the Windows header files. If the hEventWnd
argument is NULL, this argument should be specified as
WM_NULL.
Return Value
If the method succeeds, the return value is a non-zero. If the
method fails, the return value is zero. To get extended error
information, call GetLastError.
Remarks
This method will block the current thread until a connection has
been established or the timeout period has elapsed. To prevent it from
blocking the main user interface thread, the application should create
a background worker thread and establish a connection by calling the
Connect method in that thread. If the application
requires multiple simultaneous connections, it is recommended you
create a worker thread for each connection.
By default, the client session will be authenticated using standard
password authentication. If you prefer to authenticate using a private
key file, you must create a
SECURITYCREDENTIALS structure which specifies the path to the
private key and optionally the password used when creating it. The
private key file must be in the standard PEM format defined in RFC
1422. Both the standard RSA private key format and the proprietary
OpenSSH format are supported. To determine how the private key was
created, you can open the file in a text editor and the first line of
the file will identify the format.
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 class instance is initially attached to the thread
that created it. From that point on, until the it is released, only
the owner may call methods using that instance of the class. The
ownership of the class instance may be transferred from one thread to
another using the AttachThread method.
Specifying the SSH_OPTION_FREETHREAD option enables any thread to
call any method in that instance of the class, 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 class instance
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 instance.
Example
CSshClient sshClient;
SSHOPTIONDATA sshOptions;
BOOL bConnected;
ZeroMemory(&sshOptions, sizeof(sshOptions));
lstrcpyn(sshOptions.szCommandLine, strCommand, SSH_MAXCOMMANDLEN);
bConnected = sshClient.Connect(strHostName,
SSH_PORT_DEFAULT,
strUserName,
strPassword,
SSH_TIMEOUT,
SSH_OPTION_COMMAND,
&sshOptions);
if (!bConnected)
{
sshClient.ShowError();
return;
}
Requirements
Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Import Library: cstshv11.lib
Unicode: Implemented as Unicode and ANSI versions
See Also
CreateSecurityCredentials,
Disconnect,
GetSecurityInformation,
SECURITYCREDENTIALS,
SSHOPTIONDATA
|
|