| |
| SOCKET WINAPI InetConnect( |
| |
LPCTSTR lpszHostName, |
|
| |
UINT nRemotePort, |
|
| |
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 a null-terminated string which specifies the host
name or IP address of the system you want to connect with. This
parameter cannot be a URL and must only specify the name of the
remote host. If this parameter is NULL or an empty string, the
function will fail with an error indicating the host name is
invalid.
- nRemotePort
- The port number used to establish the connection. Valid port
numbers range in value from 1 through 65535 and a value outside if
this range will cause the function to fail. Port numbers in the
range of 49152 and 65535 are referred to as dynamic ports and are
generally reserved for private use by client applications. You
cannot specify a port number of zero when establishing an outbound
connection.
- 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 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:
| 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
or later and the strongest cipher suites available. |
| 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
The lpszHostName parameter must specify a valid host name or
IP address. Host names are resolved into an IP address by first
checking the local hosts file and if the name is not found, a name
server query will be performed to determine the IP address. If the
Unicode version of this function is called and the host name includes
non-ASCII characters, the host name will be automatically converted to
an ASCII compatible format. Refer to the InetNormalizeHostName
function for more information. To establish a connection using a URL
rather than a host name, use the InetConnectUrl function.
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 InetConnect in
that thread. If the application requires multiple simultaneous
connections, it is recommended you create a worker thread for each
client session.
If you use the INET_OPTION_SECURE option to enable a secure
connection, the connection will always use implicit TLS. This means a
secure session will be initiated immediately after the socket
connection has been established with the server. A common example of a
service which uses implicit TLS is the HTTPS protocol. Another type of
secure connection is one that uses explicit TLS. This is when the
client establishes a normal (non-secure) connection with the server
and then explicitly switches to using a secure connection, typically
by sending a command. If the server you are connecting to requires
explicit TLS, you should not specify the INET_OPTION_SECURE option.
Instead, connect without this option and then call the
InetEnableSecurity function when you are ready to initiate the TLS
handshake.
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.
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.
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
InetConnectEx,
InetConnectUrl,
InetDisconnect,
InetEnableSecurity,
InetInitialize,
InetRead,
InetRegisterEvent,
InetWrite
|
|