| |
| INT WINAPI PopLogin( |
| |
HCLIENT hClient, |
|
| |
UINT nAuthType, |
|
| |
LPCTSTR lpszUserName, |
|
| |
LPCTSTR lpszPassword |
|
| ); |
The PopLogin 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:
| Value |
Description |
| POP_AUTH_DEFAULT |
The default authentication scheme which sends the username
and password as cleartext to the server. Because the user
credentials are not encrypted, this method should only be used
over a secure connection. This is the same as specifying
POP_AUTH_PASS as the authentication method. |
| POP_AUTH_PASS |
The username and password is sent to the server using the
USER and PASS commands. This authentication method is supported
by most servers and is the default authentication type. The
credentials are not encrypted and this method should only be
used over secure connections. |
| POP_AUTH_APOP |
The APOP authentication method which uses an MD5 digest of
the password. This method has been deprecated is not supported by
all servers. It should only be used if required by legacy mail
servers which do not support the SASL authentication methods. |
| POP_AUTH_LOGIN |
This authentication type will use the LOGIN method to
authenticate the client session. This encodes the username and
password in a specific format, but the credentials are not
encrypted and should only be used over a secure connection. The
server must support the Simple Authentication and Security Layer
(SASL) mechanism as defined in RFC 4422. |
| POP_AUTH_PLAIN |
This authentication type will use the PLAIN method to
authenticate the client session. This encodes the username and
password in a specific format, but the credentials are not
encrypted and should only be used over a secure connection. The
server must support the PLAIN Simple Authentication and Security
Layer (SASL) mechanism as defined in RFC 4616. |
| POP_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. |
| POP_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. |
- lpszUserName
- A null-terminated string which specifies the user name
to be used to authenticate the current client session. For many
service providers, the user name is the full email address of the
user which owns the mailbox. In some cases, this may only be the
portion of their email address before the domain name.
- lpszPassword
- A null-terminated string which specifies the password to be
used when authenticating the current client session. If you are
using the POP_AUTH_XOAUTH2 or POP_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 POP_ERROR. To get extended error
information, call PopGetLastError.
Remarks
The POP_AUTH_LOGIN and POP_AUTH_PLAIN authentication methods
require the mail server support the Simple Authentication and Security
Layer (SASL) AUTH command as defined in RFC 5034. Most modern mail
servers do support one or both of these methods, and they are
generally preferred over the POP_AUTH_PASS method when possible.
However, for backwards compatibility with legacy servers, the API
will default to using POP_AUTH_PASS for client authentication.
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 POP_AUTH_XOAUTH2 and POP_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: cstools11.h
Import Library: cspopv11.lib
Unicode: Implemented as Unicode and ANSI versions
See Also
PopConnect,
PopGetMessage,
PopGetMessageCountEx,
PopInitialize
|
|