| |
| SOCKET WINAPI InetConnect( |
| |
LPCTSTR lpszHostName, |
|
| |
UINT nPort, |
|
| |
UINT nProtocol, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions, |
|
| |
LPSECURITYCREDENTIALS lpCredentials |
|
| ); |
The InetConnect function is used to establish a
connection with a server.
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. This value
must be greater than zero.
- 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 the connection to complete
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_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_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 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. |
- 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.
Return Value
If the function succeeds, the return value is a handle to a
socket. If the function fails, the return value is INVALID_SOCKET. To
get extended error information, call InetGetLastError.
Remarks
To prevent this function from blocking the main user interface
thread, the application should create a background worker thread and
establish a connection by calling InetConnectEx in
that thread. If the application requires multiple simultaneous
connections, it is recommended you create a worker thread for each
client session.
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.
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.
When this function is called with UDP as the specified protocol,
it does not actually establish a connection in the same way that a
TCP stream connection is created. Instead, it simply establishes a
default destination IP address and port that is used with subsequent
InetRead and InetWrite calls.
To enable event notification, use the InetRegisterEvent
function.
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
InetConnectEx,
InetDisableEvents,
InetDisconnect,
InetInitialize,
InetRead,
InetRegisterEvent,
InetWrite
|
|