| |
| INT WINAPI ImapLogin( |
| |
HCLIENT hClient, |
|
| |
UINT nAuthType, |
|
| |
LPCTSTR lpszUserName, |
|
| |
LPCTSTR lpszPassword |
|
| ); |
The ImapLogin function authenticates the specified user in
on the server. This function must be called after the
connection has been established, and before attempting to retrieve
messages or perform any other function on the server.
Parameters
- hClient
- Handle to the client session.
- nAuthType
- Identifies the type of authentication that should be used when
the client logs in to the mail server. The following authentication
methods are supported:
| Constant |
Description |
| IMAP_AUTH_LOGIN |
Standard cleartext username and password is sent to the
server. This authentication method is supported by all servers.
Note that some servers may only support LOGIN authentication if
a secure connection has been established. |
| IMAP_AUTH_PLAIN |
Login using the PLAIN authentication mechanism as defined in
RFC 4959. This authentication method is supported by most
servers, although some may require that client establish a
secure connection. |
| IMAP_AUTH_XOAUTH2 |
This authentication type will use the XOAUTH2 method
to authenticate the client session. This authentication method
does not require the user password, instead the lpszPassword
parameter must specify the OAuth 2.0 bearer token issued by the
service provider. The application must provide a valid
access token which has not expired, or this function will fail. |
| IMAP_AUTH_BEARER |
This authentication type will use the OAUTHBEARER method
to authenticate the client session as defined in RFC 7628. This
authentication method does not require the user password,
instead the lpszPassword parameter must specify the
OAuth 2.0 bearer token issued by the service provider. The application
must provide a valid access token which has not expired, or
this function will fail. |
| IMAP_AUTH_ANONYMOUS |
Login using the anonymous Simple Authentication and Security
Layer (SASL) mechanism as defined in RFC 4505. If this
authentication method is specified, the lpszUserName
parameter should specify a name or email address acceptable to
the mail server. The lpszPassword parameter is ignored and
may be NULL. |
- lpszUserName
- A null terminated string which specifies the user name
to be used to authenticate the current client session.
- lpszPassword
- A null terminated string which specifies the password to be
used when authenticating the current client session. If you are
using the IMAP_AUTH_XOAUTH2 or IMAP_AUTH_BEARER authentication methods,
this parameter is not a password, instead it specifies the OAuth 2.0
bearer token provided by the mail service.
Return Value
If the function succeeds, the return value is zero. If the
function fails, the return value is IMAP_ERROR. To get extended error
information, call ImapGetLastError.
Remarks
In some cases, the user may be pre-authenticated by the server. In
this case, the function will fail with the last error set to
ST_ERROR_ALREADY_AUTHENTICATED. If a particular authentication method
is not supported by the server, the last error will be set to
ST_ERROR_INVALID_AUTHENTICATION_TYPE. For compatibility with the
greatest number of servers, it is recommended that you use
IMAP_AUTH_LOGIN as the authentication method.
You should only use an OAuth 2.0 authentication method if
you understand the process of how to request the access token. Obtaining
an access token requires registering your application with the mail
service provider (e.g.: Microsoft or Google), getting a unique
client ID associated with your application and then requesting the
access token using the appropriate scope for the service. Obtaining
the initial token will typically involve interactive confirmation
on the part of the user, requiring they grant permission to your
application to access their mail account.
The IMAP_AUTH_XOAUTH2 and IMAP_AUTH_BEARER authentication methods are
similar, but they are not interchangeable. Both use an OAuth 2.0 bearer
token to authenticate the client session, but they differ in how the
token is presented to the server. It is currently preferable to use the
XOAUTH2 method because it is more widely available and some service
providers do not yet support the OAUTHBEARER method.
Your application should not store an OAuth 2.0 bearer token for later
use. They have a relatively short lifespan, typically about an hour, and
are designed to be used with that session. You should specify offline
access as part of the OAuth 2.0 scope if necessary and store the refresh
token provided by the service. The refresh token has a much longer
validity period and can be used to obtain a new bearer token when needed.
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: csmapv10.lib
Unicode: Implemented as Unicode and ANSI versions.
See Also
ImapAsyncConnect,
ImapConnect,
ImapDisconnect,
ImapInitialize,
ImapUninitialize
|
|