| |
| BOOL Connect( |
| |
LPCTSTR lpszRemoteHost, |
|
| |
UINT nRemotePort |
|
| ); |
| BOOL Connect( |
| |
LPCTSTR lpszRemoteHost, |
|
| |
UINT nRemotePort, |
|
| |
UINT nProtocol, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions, |
|
| |
LPCTSTR lpszLocalAddress, |
|
| |
UINT nLocalPort |
|
| ); |
The Connect method is used to establish a connection with a
server.
Parameters
- lpszHostName
- 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
method 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 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:
| 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_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 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 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.
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 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 NormalizeHostName
method for more information. To establish a connection using a URL
rather than a host name, use the ConnectUrl method.
This method will block the current thread until a connection has
been established or the timeout period has elapsed. To prevent it from
blocking the main user interface thread, the application should create
a background worker thread and establish a connection by calling the
Connect method in that thread. If the application
requires multiple simultaneous connections, it is recommended you
create a worker thread for each connection.
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
EnableSecurity method 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 class instance is initially attached to the thread
that created it. From that point on, until the handle 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 File: cswsock11.h
Import Library: cswskv11.lib
Unicode: Implemented as Unicode and ANSI versions
See Also
ConnectUrl,
Disconnect,
EnableSecurity,
Read,
ReadLine,
RegisterEvent,
Write,
WriteLine
|
|