|
|
| HCLIENT
TelnetConnect(
|
|
|
LPCTSTR
lpszRemoteHost, |
|
|
|
|
UINT
nRemotePort, |
|
|
|
|
UINT nTimeout, |
|
|
|
|
DWORD
dwOptions, |
|
|
|
|
LPSECURITYCREDENTIALS
lpCredentials |
|
|
| );
|
The TelnetConnect function is used to establish a
connection with the remote server.
Parameters
- lpszRemoteHost
- A pointer to the name of the remote host to connect to; this
may be a fully-qualified domain name, or an IP address.
- nRemotePort
- The port number the remote 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
before failing the operation; a value of zero indicates that the
client should wait an indefinite period of time.
- dwOptions
- A bitmask which specifies one or more options. This parameter
is constructed by using a bitwise operator with any of the
following values:
| Constant |
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_SECURE |
This option specifies that the
client should attempt to establish a secure connection with the
server. Note that the server must support secure connections using
either the SSL or TLS protocol. This option is only available in
the Secure Editions of SocketTools. |
|
TELNET_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. |
- 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
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
Client: Requires Windows Vista, Windows XP or Windows
2000 Professional.
Server: Requires Windows Server 2008, Windows Server 2003 or
Windows 2000 Server.
Header: Include cstools6.h.
Library: Use cstntav6.lib.
Unicode: Implemented as Unicode and ANSI versions.
See Also
TelnetAsyncConnect,
TelnetCreateSecurityCredentials,
TelnetDeleteSecurityCredentials,
TelnetDisconnect, TelnetInitialize, TelnetUninitialize
|
|