310 lines
12 KiB
C#
310 lines
12 KiB
C#
//
|
|
// IPop3Client.cs
|
|
//
|
|
// Author: Jeffrey Stedfast <jestedfa@microsoft.com>
|
|
//
|
|
// Copyright (c) 2013-2020 .NET Foundation and Contributors
|
|
//
|
|
// Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
// of this software and associated documentation files (the "Software"), to deal
|
|
// in the Software without restriction, including without limitation the rights
|
|
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
// copies of the Software, and to permit persons to whom the Software is
|
|
// furnished to do so, subject to the following conditions:
|
|
//
|
|
// The above copyright notice and this permission notice shall be included in
|
|
// all copies or substantial portions of the Software.
|
|
//
|
|
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
// THE SOFTWARE.
|
|
//
|
|
|
|
using System.Threading;
|
|
using System.Threading.Tasks;
|
|
using System.Collections.Generic;
|
|
|
|
namespace MailKit.Net.Pop3 {
|
|
/// <summary>
|
|
/// An interface for a POP3 client.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Implemented by <see cref="MailKit.Net.Pop3.Pop3Client"/>.
|
|
/// </remarks>
|
|
public interface IPop3Client : IMailSpool
|
|
{
|
|
/// <summary>
|
|
/// Gets the capabilities supported by the POP3 server.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// The capabilities will not be known until a successful connection has been made
|
|
/// and may change once the client is authenticated.
|
|
/// </remarks>
|
|
/// <example>
|
|
/// <code language="c#" source="Examples\Pop3Examples.cs" region="Capabilities"/>
|
|
/// </example>
|
|
/// <value>The capabilities.</value>
|
|
/// <exception cref="System.ArgumentException">
|
|
/// Capabilities cannot be enabled, they may only be disabled.
|
|
/// </exception>
|
|
Pop3Capabilities Capabilities { get; set; }
|
|
|
|
/// <summary>
|
|
/// Gets the expiration policy.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>If the server supports the EXPIRE capability (<see cref="Pop3Capabilities.Expire"/>), the value
|
|
/// of the <see cref="ExpirePolicy"/> property will reflect the value advertized by the server.</para>
|
|
/// <para>A value of <c>-1</c> indicates that messages will never expire.</para>
|
|
/// <para>A value of <c>0</c> indicates that messages that have been retrieved during the current session
|
|
/// will be purged immediately after the connection is closed via the <c>QUIT</c> command.</para>
|
|
/// <para>Values larger than <c>0</c> indicate the minimum number of days that the server will retain
|
|
/// messages which have been retrieved.</para>
|
|
/// </remarks>
|
|
/// <example>
|
|
/// <code language="c#" source="Examples\Pop3Examples.cs" region="Capabilities"/>
|
|
/// </example>
|
|
/// <value>The expiration policy.</value>
|
|
int ExpirePolicy { get; }
|
|
|
|
/// <summary>
|
|
/// Gets the implementation details of the server.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// If the server advertizes its implementation details, this value will be set to a string containing the
|
|
/// information details provided by the server.
|
|
/// </remarks>
|
|
/// <value>The implementation details.</value>
|
|
string Implementation { get; }
|
|
|
|
/// <summary>
|
|
/// Gets the minimum delay, in milliseconds, between logins.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// If the server supports the LOGIN-DELAY capability (<see cref="Pop3Capabilities.LoginDelay"/>), this value
|
|
/// will be set to the minimum number of milliseconds that the client must wait between logins.
|
|
/// </remarks>
|
|
/// <example>
|
|
/// <code language="c#" source="Examples\Pop3Examples.cs" region="Capabilities"/>
|
|
/// </example>
|
|
/// <value>The login delay.</value>
|
|
int LoginDelay { get; }
|
|
|
|
/// <summary>
|
|
/// Enable UTF8 mode.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// The POP3 UTF8 extension allows the client to retrieve messages in the UTF-8 encoding and
|
|
/// may also allow the user to authenticate using a UTF-8 encoded username or password.
|
|
/// </remarks>
|
|
/// <param name="cancellationToken">The cancellation token.</param>
|
|
/// <exception cref="System.ObjectDisposedException">
|
|
/// The <see cref="Pop3Client"/> has been disposed.
|
|
/// </exception>
|
|
/// <exception cref="ServiceNotConnectedException">
|
|
/// The <see cref="Pop3Client"/> is not connected.
|
|
/// </exception>
|
|
/// <exception cref="System.InvalidOperationException">
|
|
/// The <see cref="Pop3Client"/> has already been authenticated.
|
|
/// </exception>
|
|
/// <exception cref="System.OperationCanceledException">
|
|
/// The operation was canceled via the cancellation token.
|
|
/// </exception>
|
|
/// <exception cref="System.NotSupportedException">
|
|
/// The POP3 server does not support the UTF8 extension.
|
|
/// </exception>
|
|
/// <exception cref="System.IO.IOException">
|
|
/// An I/O error occurred.
|
|
/// </exception>
|
|
/// <exception cref="Pop3CommandException">
|
|
/// The POP3 command failed.
|
|
/// </exception>
|
|
/// <exception cref="Pop3ProtocolException">
|
|
/// A POP3 protocol error occurred.
|
|
/// </exception>
|
|
void EnableUTF8 (CancellationToken cancellationToken = default (CancellationToken));
|
|
|
|
/// <summary>
|
|
/// Asynchronously enable UTF8 mode.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// The POP3 UTF8 extension allows the client to retrieve messages in the UTF-8 encoding and
|
|
/// may also allow the user to authenticate using a UTF-8 encoded username or password.
|
|
/// </remarks>
|
|
/// <returns>An asynchronous task context.</returns>
|
|
/// <param name="cancellationToken">The cancellation token.</param>
|
|
/// <exception cref="System.ObjectDisposedException">
|
|
/// The <see cref="Pop3Client"/> has been disposed.
|
|
/// </exception>
|
|
/// <exception cref="ServiceNotConnectedException">
|
|
/// The <see cref="Pop3Client"/> is not connected.
|
|
/// </exception>
|
|
/// <exception cref="System.InvalidOperationException">
|
|
/// The <see cref="Pop3Client"/> has already been authenticated.
|
|
/// </exception>
|
|
/// <exception cref="System.OperationCanceledException">
|
|
/// The operation was canceled via the cancellation token.
|
|
/// </exception>
|
|
/// <exception cref="System.NotSupportedException">
|
|
/// The POP3 server does not support the UTF8 extension.
|
|
/// </exception>
|
|
/// <exception cref="System.IO.IOException">
|
|
/// An I/O error occurred.
|
|
/// </exception>
|
|
/// <exception cref="Pop3CommandException">
|
|
/// The POP3 command failed.
|
|
/// </exception>
|
|
/// <exception cref="Pop3ProtocolException">
|
|
/// A POP3 protocol error occurred.
|
|
/// </exception>
|
|
Task EnableUTF8Async (CancellationToken cancellationToken = default (CancellationToken));
|
|
|
|
/// <summary>
|
|
/// Get the list of languages supported by the POP3 server.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// If the POP3 server supports the LANG extension, it is possible to
|
|
/// query the list of languages supported by the POP3 server that can
|
|
/// be used for error messages.
|
|
/// </remarks>
|
|
/// <returns>The supported languages.</returns>
|
|
/// <param name="cancellationToken">The cancellation token.</param>
|
|
/// <exception cref="System.ObjectDisposedException">
|
|
/// The <see cref="Pop3Client"/> has been disposed.
|
|
/// </exception>
|
|
/// <exception cref="ServiceNotConnectedException">
|
|
/// The <see cref="Pop3Client"/> is not connected.
|
|
/// </exception>
|
|
/// <exception cref="System.OperationCanceledException">
|
|
/// The operation was canceled via the cancellation token.
|
|
/// </exception>
|
|
/// <exception cref="System.NotSupportedException">
|
|
/// The POP3 server does not support the LANG extension.
|
|
/// </exception>
|
|
/// <exception cref="System.IO.IOException">
|
|
/// An I/O error occurred.
|
|
/// </exception>
|
|
/// <exception cref="Pop3CommandException">
|
|
/// The POP3 command failed.
|
|
/// </exception>
|
|
/// <exception cref="Pop3ProtocolException">
|
|
/// A POP3 protocol error occurred.
|
|
/// </exception>
|
|
IList<Pop3Language> GetLanguages (CancellationToken cancellationToken = default (CancellationToken));
|
|
|
|
/// <summary>
|
|
/// Asynchronously get the list of languages supported by the POP3 server.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// If the POP3 server supports the LANG extension, it is possible to
|
|
/// query the list of languages supported by the POP3 server that can
|
|
/// be used for error messages.
|
|
/// </remarks>
|
|
/// <returns>The supported languages.</returns>
|
|
/// <param name="cancellationToken">The cancellation token.</param>
|
|
/// <exception cref="System.ObjectDisposedException">
|
|
/// The <see cref="Pop3Client"/> has been disposed.
|
|
/// </exception>
|
|
/// <exception cref="ServiceNotConnectedException">
|
|
/// The <see cref="Pop3Client"/> is not connected.
|
|
/// </exception>
|
|
/// <exception cref="System.OperationCanceledException">
|
|
/// The operation was canceled via the cancellation token.
|
|
/// </exception>
|
|
/// <exception cref="System.NotSupportedException">
|
|
/// The POP3 server does not support the LANG extension.
|
|
/// </exception>
|
|
/// <exception cref="System.IO.IOException">
|
|
/// An I/O error occurred.
|
|
/// </exception>
|
|
/// <exception cref="Pop3CommandException">
|
|
/// The POP3 command failed.
|
|
/// </exception>
|
|
/// <exception cref="Pop3ProtocolException">
|
|
/// A POP3 protocol error occurred.
|
|
/// </exception>
|
|
Task<IList<Pop3Language>> GetLanguagesAsync (CancellationToken cancellationToken = default (CancellationToken));
|
|
|
|
/// <summary>
|
|
/// Set the language used by the POP3 server for error messages.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// If the POP3 server supports the LANG extension, it is possible to
|
|
/// set the language used by the POP3 server for error messages.
|
|
/// </remarks>
|
|
/// <param name="lang">The language code.</param>
|
|
/// <param name="cancellationToken">The cancellation token.</param>
|
|
/// <exception cref="System.ArgumentNullException">
|
|
/// <paramref name="lang"/> is <c>null</c>.
|
|
/// </exception>
|
|
/// <exception cref="System.ArgumentException">
|
|
/// <paramref name="lang"/> is empty.
|
|
/// </exception>
|
|
/// <exception cref="System.ObjectDisposedException">
|
|
/// The <see cref="Pop3Client"/> has been disposed.
|
|
/// </exception>
|
|
/// <exception cref="ServiceNotConnectedException">
|
|
/// The <see cref="Pop3Client"/> is not connected.
|
|
/// </exception>
|
|
/// <exception cref="System.OperationCanceledException">
|
|
/// The operation was canceled via the cancellation token.
|
|
/// </exception>
|
|
/// <exception cref="System.NotSupportedException">
|
|
/// The POP3 server does not support the LANG extension.
|
|
/// </exception>
|
|
/// <exception cref="System.IO.IOException">
|
|
/// An I/O error occurred.
|
|
/// </exception>
|
|
/// <exception cref="Pop3CommandException">
|
|
/// The POP3 command failed.
|
|
/// </exception>
|
|
/// <exception cref="Pop3ProtocolException">
|
|
/// A POP3 protocol error occurred.
|
|
/// </exception>
|
|
void SetLanguage (string lang, CancellationToken cancellationToken = default (CancellationToken));
|
|
|
|
/// <summary>
|
|
/// Asynchronously set the language used by the POP3 server for error messages.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// If the POP3 server supports the LANG extension, it is possible to
|
|
/// set the language used by the POP3 server for error messages.
|
|
/// </remarks>
|
|
/// <returns>An asynchronous task context.</returns>
|
|
/// <param name="lang">The language code.</param>
|
|
/// <param name="cancellationToken">The cancellation token.</param>
|
|
/// <exception cref="System.ArgumentNullException">
|
|
/// <paramref name="lang"/> is <c>null</c>.
|
|
/// </exception>
|
|
/// <exception cref="System.ArgumentException">
|
|
/// <paramref name="lang"/> is empty.
|
|
/// </exception>
|
|
/// <exception cref="System.ObjectDisposedException">
|
|
/// The <see cref="Pop3Client"/> has been disposed.
|
|
/// </exception>
|
|
/// <exception cref="ServiceNotConnectedException">
|
|
/// The <see cref="Pop3Client"/> is not connected.
|
|
/// </exception>
|
|
/// <exception cref="System.OperationCanceledException">
|
|
/// The operation was canceled via the cancellation token.
|
|
/// </exception>
|
|
/// <exception cref="System.NotSupportedException">
|
|
/// The POP3 server does not support the LANG extension.
|
|
/// </exception>
|
|
/// <exception cref="System.IO.IOException">
|
|
/// An I/O error occurred.
|
|
/// </exception>
|
|
/// <exception cref="Pop3CommandException">
|
|
/// The POP3 command failed.
|
|
/// </exception>
|
|
/// <exception cref="Pop3ProtocolException">
|
|
/// A POP3 protocol error occurred.
|
|
/// </exception>
|
|
Task SetLanguageAsync (string lang, CancellationToken cancellationToken = default (CancellationToken));
|
|
}
|
|
}
|