| |
| BOOL Connect( |
| |
LPCTSTR lpszRemoteHost, |
|
| |
UINT nRemotePort, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions, |
|
| |
HWND hEventWnd, |
|
| |
UINT uEventMsg |
|
| ); |
The Connect method is used to establish a connection with
the 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. For
standard connections, the default port number is 25. An alternative
port is 587, which is commonly used by authenticated clients to
submit messages for delivery. For implicit SSL connections, the
default port number is 465.
- nTimeout
- The number of seconds that the client will wait for a response
from the server before failing the current operation.
- dwOptions
- An unsigned integer that specifies one or more options. This
parameter is constructed by using a bitwise operator with any of
the following values:
| Constant |
Description |
| SMTP_OPTION_NONE |
No additional options are specified when establishing a
connection with the server. A standard, non-secure connection
will be used and the client will not attempt to use extended
(ESMTP) features of the protocol. Note that if the mail server
requires authentication, the SMTP_OPTION_EXTENDED option must
be specified. |
| SMTP_OPTION_EXTENDED |
Extended SMTP commands should be used if possible. This
option enables features such as authentication and delivery
status notification. If this option is not specified, the
library will not attempt to use any extended features. This
option is automatically enabled if the connection is
established on port 587 because submitting messages for
delivery using this port typically requires client
authentication. |
| SMTP_OPTION_TUNNEL |
This option specifies that a tunneled TCP connection and/or
port-forwarding is being used to establish the connection to
the server. This changes the behavior of the client with
regards to internal checks of the destination IP address and
remote port number, default capability selection and how the
connection is established. |
| SMTP_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. |
| SMTP_OPTION_SECURE |
This option specifies that a secure connection should be
established with the server and requires that the server
support either the SSL or TLS protocol. The client will initiate
the secure session using the STARTTLS command. |
| SMTP_OPTION_SECURE_IMPLICIT |
This option specifies the client should attempt to
establish a secure connection with the server. The server must
support secure connections using either the SSL or TLS
protocol, and the secure session must be negotiated immediately
after the connection has been established. |
| SMTP_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. |
| SMTP_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. |
| SMTP_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. |
- hEventWnd
- The handle to the event notification window. This window
receives messages which notify the client of various asynchronous
socket events that occur. If this argument is NULL, then the client
session 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 client
session 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 client handle. One or more
of the following event identifiers may be sent:
| Constant |
Description |
| SMTP_EVENT_CONNECT |
The connection to the server has completed. The high
word of the lParam parameter should be checked, since this
notification message will be posted if an error has
occurred. |
| SMTP_EVENT_DISCONNECT |
The server has closed the connection to the client. The
client should read any remaining data and disconnect. |
| SMTP_EVENT_READ |
Data is available to read by the client. No additional
messages will be posted until the client has read at least some
of the data. This event is only generated if the calling process
is in asynchronous mode. |
| SMTP_EVENT_WRITE |
The client 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 client is
in asynchronous mode. |
| SMTP_EVENT_TIMEOUT |
The client has timed out while waiting for a response from
the server. Note that under some circumstances this event can be
generated for a non-blocking connection, such as when the client
is establishing a secure connection. |
| SMTP_EVENT_CANCEL |
The client has canceled the current operation. |
| SMTP_EVENT_COMMAND |
The client has processed a command that was sent to the
server. The result code and result string can be used to
determine if the response to the command. The high word of the
lParam parameter should be checked, since this notification
message will also be posed if the command cannot be
executed. |
| SMTP_EVENT_PROGRESS |
This event notification is sent periodically during lengthy
blocking operations, such as retrieving a complete message from
the server. |
To cancel asynchronous notification and return the client to a
blocking mode, use the DisableEvents method.
It is recommended that you only establish an asynchronous
connection if you understand the implications of doing so. In most
cases, it is preferable to create a synchronous connection and create
threads for each additional session if more than one active client
session is required.
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 SMTP_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: cstools10.h
Import Library: csmtpv10.lib
Unicode: Implemented as Unicode and ANSI versions.
See Also
Authenticate,
Disconnect,
GetExtendedOptions
|
|