| |
| BOOL Connect( |
| |
LPCTSTR lpszRemoteHost, |
|
| |
UINT nRemotePort, |
|
| |
UINT nProtocol, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions, |
|
| |
LPCTSTR lpszLocalAddress, |
|
| |
UINT nLocalPort, |
|
| |
HWND hEventWnd, |
|
| |
UINT uEventMsg |
|
| ); |
The Connect method is used to establish a connection with a
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.
- nProtocol
- The protocol to be used when establishing the connection. This
may be one of the following values:
| Constant |
Description |
| INET_PROTOCOL_TCP |
Specifies the Transmission Control Protocol. This protocol
provides a reliable, bi-directional byte stream. This is the
default protocol. |
| INET_PROTOCOL_UDP |
Specifies the User Datagram Protocol. This protocol is
message oriented, sending data in discrete packets. Note that
UDP is unreliable in that there is no way for the sender to
know that the receiver has actually received the datagram. |
- nTimeout
- The number of seconds to wait for a response before failing the
current operation.
- dwOptions
- An unsigned integer used to specify one or more socket
options. This parameter is constructed by using the bitwise Or
operator with any of the following values:
| Constant |
Description |
| INET_OPTION_BROADCAST |
This option specifies that broadcasting should be enabled
for datagrams. This option is invalid for stream sockets. |
| INET_OPTION_DONTROUTE |
This option specifies default routing should not be used.
This option should not be specified unless absolutely necessary. |
| INET_OPTION_KEEPALIVE |
This option specifies that packets are to be sent to the
remote system when no data is being exchanged to keep the
connection active. This is only valid for stream sockets. |
| INET_OPTION_NODELAY |
This option disables the Nagle algorithm. By default, small
amounts of data written to the socket are buffered, increasing
efficiency and reducing network congestion. However, this
buffering can negatively impact the responsiveness of certain
applications. This option disables this buffering and
immediately sends data packets as they are written to the
socket. |
| INET_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 either
the SSL or TLS protocols. |
| INET_OPTION_SECURE |
This option specifies that a secure connection should be
established with the remote host. The specific version of TLS
and other security related options are provided in the
lpCredentials parameter. If the lpCredentials
parameter is NULL, the connection will default to using TLS 1.2
and the strongest cipher suites available. Older versions
of Windows prior to Windows 7 and Windows Server 2008 R2 only
support TLS 1.0 and secure connections will automatically
downgrade on those platforms. |
| INET_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. |
| INET_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. |
| INET_OPTION_FREETHREAD |
This option specifies that this instance of the class 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 class instance is synchronized across multiple
threads. |
- lpszLocalAddress
- A pointer to a null terminated string that specifies the local
IP address that the socket should be bound to. If this parameter is
NULL, then an appropriate address will automatically be used. A
specific address should only be used if it is required by the
application.
- nLocalPort
- The local port number that the socket should be bound to. If
this parameter is set to zero, then an appropriate port number will
automatically be used. A specific port number should only be used
if it is required by the application.
- hEventWnd
- The handle to the event notification window. This window
receives messages which notify the application of various
asynchronous socket events that occur. If this argument is NULL,
then the connection will be blocking and no network events will be
sent to the client.
- uEventMsg
- The message identifier that is used when an asynchronous socket
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
The use of Windows event notification messages has been deprecated
and may be unavailable in future releases. It was designed for use in
legacy single-threaded applications and requires the application to
have a message pump to process event messages. It should not be used
with applications which are designed to execute as a service or those
which do not have a graphical user interface.
To prevent this method from blocking the main user interface thread,
the application should create a background worker thread and establish
a connection by calling Connect in that thread. If
the application requires multiple simultaneous connections, it is
recommended you create a worker thread for each client session.
If you specify an event notification window, then the connection
will be asynchronous. When a message is posted to the notification
window, the low word of the lParam parameter contains the
event identifier. The high word of lParam contains the low
word of the error code, if an error has occurred. The wParam
parameter contains the socket handle. One or more of the following
event identifiers may be sent:
| Constant |
Description |
| INET_EVENT_CONNECT |
The connection to the remote host has completed. The high
word of the lParam parameter should be checked, since this
notification message will be posted if an error has
occurred. |
| INET_EVENT_DISCONNECT |
The remote host has closed the connection. The process should
read any remaining data and disconnect. |
| INET_EVENT_READ |
Data is available to read by the calling process. No
additional messages will be posted until the process has read at
least some of the data from the socket. This event is only
generated if the socket is in asynchronous mode. |
| INET_EVENT_WRITE |
The process can now write data. This notification is sent
after a connection has been established, or after a previous
attempt to write data has failed because it would result in a
blocking operation. This event is only generated if the socket is
in asynchronous mode. |
To cancel asynchronous notification and return the socket to a
blocking mode, use the DisableEvents method.
It is not recommend that you disable the Nagle algorithm by
specifying the INET_OPTION_NODELAY flag unless it is absolutely
required. Doing so can have a significant, negative impact on the
performance of the application and network.
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 INET_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: Include cswsock10.h
Import Library: cswskv10.lib
Unicode: Implemented as Unicode and ANSI versions.
See Also
DisableEvents,
Disconnect,
EnableEvents
|
|