| |
| HCLIENT WINAPI SmtpConnect(
|
| |
LPCTSTR lpszRemoteHost, |
|
| |
UINT nRemotePort, |
|
| |
UINT nTimeout, |
|
| |
DWORD dwOptions, |
|
| |
LPCTSTR lpszLocalName, |
|
| |
LPSECURITYCREDENTIALS lpCredentials |
|
| );
|
The SmtpConnect function 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 feature selection and how the connection is
established. |
| SMTP_OPTION_TRUSTEDSITE |
This option specifies that 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 that 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_FREETHREAD |
This option specifies that the handle 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 handle is synchronized across multiple threads. |
- lpszLocalName
- A pointer to a null-terminated string which specifies the
domain name of the local host. This parameter can be NULL or point
to an empty string, in which case the local domain name is
determined automatically from the system configuration. This
parameter should be used if the mail server only accepts messages
from a client that identifies itself using a specific domain
name.
- lpCredentials
- A pointer to a SECURITYCREDENTIALS structure which
is used to establish the client credentials for a secure connection
to the server. The function SmtpCreateSecurityCredentials
can be used to create this structure if necessary. If a standard
non-secure connection is being established, or client credentials
are not required by the server, this parameter can be NULL.
Return Value
If the function succeeds, the return value is a handle to a
client session. If the function fails, the return value is
INVALID_CLIENT. To get extended error information, call
SmtpGetLastError.
Remarks
The lpszLocalName argument should only point to a
specific domain name if it is absolutely necessary. In most cases,
it is preferable to pass this parameter as NULL or an empty string
and allow the library to automatically determine the correct domain
name to use. Providing an invalid domain name may cause the mail
server to reject the connection.
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 SmtpAttachThread function.
Specifying the SMTP_OPTION_FREETHREAD option enables any thread
to call any function using the 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 handle
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 handle.
Requirements
Client: Requires Windows 7, Windows Vista or Windows
XP.
Server: Requires Windows Server 2008 or Windows Server
2003.
Header: Include cstools7.h.
Library: Use csmtpav7.lib.
Unicode: Implemented as Unicode and ANSI versions.
See Also
SmtpAsyncConnect, SmtpAuthenticate, SmtpDisconnect, SmtpInitialize, SmtpUninitialize
|
|