| |
| BOOL Connect( |
| |
LPCTSTR lpszRemoteHost, |
|
| |
UINT nRemotePort, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions |
|
| ); |
The Connect method establishes a connection with the
specified server.
Parameters
- lpszRemoteHost
- 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 should be used. For
standard connections, the default port number is 23. For secure
connections, the default port number is 992.
- 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 |
| TELNET_OPTION_NONE |
No connection options specified. A standard connection to
the server will be established using the specified host name
and port number. |
| TELNET_OPTION_TUNNEL |
This option specifies that a tunneled TCP connection and/or
port-forwarding is being used to establish the connection to
the server. This changes the behavior of the client with
regards to internal checks of the destination IP address and
remote port number, default capability selection and how the
connection is established. |
| TELNET_OPTION_TRUSTEDSITE |
This option specifies the server is trusted. The
server certificate will not be validated and the connection
will always be permitted. This option only affects connections
using the TLS protocol. |
| TELNET_OPTION_SECURE |
This option specifies the client should attempt to
establish a secure connection with the server. Note that the
server must support secure connections using the
TLS protocol. |
| TELNET_OPTION_SECURE_EXPLICIT |
This option specifies the client should attempt to
establish a secure connection with the server using the
START_TLS option. The client initiates a standard connection
with the server, then requests a secure connection during the
option negotiation process. |
| TELNET_OPTION_SECURE_FALLBACK |
This option specifies the client should permit the use
of less secure cipher suites for compatibility with legacy
servers. If this option is specified, the client will allow
connections using TLS 1.0 and cipher suites that use RC4, MD5
and SHA1. |
| TELNET_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. |
| TELNET_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. |
- 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 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.
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 handle 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 TELNET_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.
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: cstntv11.lib
Unicode: Implemented as Unicode and ANSI versions
See Also
CreateSecurityCredentials,
Disconnect,
GetSecurityInformation
|
|