| |
| HCLIENT WINAPI TelnetConnect( |
| |
LPCTSTR lpszRemoteHost, |
|
| |
UINT nRemotePort, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions, |
|
| |
LPSECURITYCREDENTIALS lpCredentials |
|
| ); |
The TelnetConnect function is used to establish a
connection with the 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 should be used.
- 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. |
- lpCredentials
- Pointer to credentials structure SECURITYCREDENTIALS. This parameter
is only used if the TELNET_OPTION_SECURE option is specified for
the connection. This parameter may be NULL, in which case no client
credentials will be provided to the server. If client credentials
are required, the fields dwSize, lpszCertStore, and
lpszCertName must be defined, while other fields may be left
undefined. Set dwSize to the size of the
SECURITYCREDENTIALS structure.
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
TelnetGetLastError.
Remarks
This function 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
TelnetConnect 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 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
TelnetAttachThread function.
Specifying the TELNET_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.
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
TelnetCreateSecurityCredentials,
TelnetDeleteSecurityCredentials,
TelnetDisconnect,
TelnetInitialize,
TelnetUninitialize
|
|