| |
| SOCKET WINAPI InetAsyncConnectEx( |
| |
LPCTSTR lpszHostName, |
|
| |
UINT nPort, |
|
| |
UINT nProtocol, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions, |
|
| |
LPCTSTR lpszLocalAddress, |
|
| |
UINT nLocalPort, |
|
| |
LPSECURITYCREDENTIALS lpCredentials, |
|
| |
HWND hEventWnd, |
|
| |
UINT uEventMsg |
|
| ); |
The InetAsyncConnectEx function is used to establish a
connection with a server.
This function 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.
The application should create a background worker thread and establish
a connection by calling InetConnectEx within that thread.
If the application requires multiple simultaneous connections, it is
recommended you create a worker thread for each connection.
Parameters
- lpszHostName
- A pointer to the name of the server to connect to; this
may be a fully-qualified domain name or an IP address.
- nPort
- 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:
| Value |
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. The following values are recognized:
| Value |
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_RESERVEDPORT |
This option specifies the socket should be bound to an
unused port number less than 1024, which is typically reserved
for well-known system services. If this option is specified, the
process may require administrative privileges. |
| INET_OPTION_NOINHERIT |
This option prevents the socket handle from being inherited
by child processes created by the application. Using this option
can mitigate situations in which a child process does not close
the handle, leaving it open after the parent process has
disconnected from the server. |
| 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 TLS protocol. |
| 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 the socket 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 socket is synchronized across
multiple threads. |
- lpszLocalAddress
- A pointer to a 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.
- lpCredentials
- A pointer to a SECURITYCREDENTIALS structure. This
parameter is only used if INET_OPTION_SECURE is specified for a TCP
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.
- hEventWnd
- The handle to the event notification window. This window
receives messages which notify the application of various
asynchronous socket events that occur.
- 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.
Return Value
If the function succeeds, the return value is a handle to the
socket. If the function fails, the return value is INVALID_SOCKET. To
get extended error information, call InetGetLastError.
Remarks
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:
| Value |
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. |
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
InetAttachThread function.
Specifying the INET_OPTION_FREETHREAD option enables any thread to
call any function using the socket 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 socket 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 socket handle.
Requirements
Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cswsock11.h
Import Library: cswskv11.lib
Unicode: Implemented as Unicode and ANSI versions
See Also
InetAsyncConnect,
InetConnect,
InetDisableEvents,
InetDisconnect,
InetEnableEvents,
InetInitialize
|
|