mirror of
https://github.com/apple/swift-nio-imap
synced 2026-11-22 04:30:43 +00:00
Update style in documentation (#822)
This commit is contained in:
1 parent
9c56edfa19
commit
34883bcba6
151 files changed
+580
-590
No files matched your search
@@ -152,7 +152,7 @@ extension EncodeBuffer {
|
||||
}
|
||||
|
||||
/// Writes a collection of bytes in the `literal8` syntax defined in RFC 3516.
|
||||
/// This function allows the `null` byte `\0` to be written.
|
||||
/// Allows the `null` byte `\0` to be written.
|
||||
/// - parameters:
|
||||
/// - bytes: The raw bytes to write to `self`.
|
||||
/// - returns: The number of bytes written.
|
||||
|
||||
@@ -36,7 +36,7 @@ import struct NIO.ByteBuffer
|
||||
public struct CommandEncodeBuffer: Hashable, Sendable {
|
||||
/// The underlying buffer containing data to be written.
|
||||
///
|
||||
/// This provides access to the raw ``EncodeBuffer`` for advanced operations,
|
||||
/// Provides access to the raw ``EncodeBuffer`` for advanced operations,
|
||||
/// though most users should interact through the public API of `CommandEncodeBuffer`.
|
||||
@_spi(NIOIMAPInternal) public var buffer: EncodeBuffer
|
||||
|
||||
@@ -68,7 +68,7 @@ public struct CommandEncodeBuffer: Hashable, Sendable {
|
||||
extension CommandEncodeBuffer {
|
||||
/// The encoding options currently in use.
|
||||
///
|
||||
/// These options determine how protocol elements are encoded (e.g., whether to use
|
||||
/// These options determine how protocol elements are encoded (for example, whether to use
|
||||
/// quoted strings, which literal formats are supported). You can modify these
|
||||
/// options at runtime to change encoding behavior for subsequent write operations.
|
||||
///
|
||||
@@ -88,7 +88,7 @@ extension CommandEncodeBuffer {
|
||||
|
||||
/// Creates a new command encoding buffer from server capabilities.
|
||||
///
|
||||
/// This initializer converts a list of ``Capability`` values into ``CommandEncodingOptions``,
|
||||
/// Converts a list of ``Capability`` values into ``CommandEncodingOptions``,
|
||||
/// which automatically enables extended literal formats and binary support if the
|
||||
/// server advertises the corresponding capabilities.
|
||||
///
|
||||
|
||||
@@ -53,7 +53,7 @@ public struct CommandEncodingOptions: Hashable, Sendable {
|
||||
|
||||
/// Use the RFC 3501 synchronizing literal format (`{20}\r\n`).
|
||||
///
|
||||
/// This is the standard literal format that requires the server to send a `+`
|
||||
/// The standard literal format that requires the server to send a `+`
|
||||
/// continuation request before the client sends the literal data. Set to `true`
|
||||
/// for RFC 3501-compliant encoding.
|
||||
///
|
||||
@@ -82,7 +82,7 @@ public struct CommandEncodingOptions: Hashable, Sendable {
|
||||
|
||||
/// Use binary content literals (`~{20}\r\n`).
|
||||
///
|
||||
/// This format is defined in RFC 3516 and allows sending arbitrary binary data.
|
||||
/// Defined in RFC 3516, this format allows sending arbitrary binary data.
|
||||
/// Note that binary literals can only be used in certain contexts, such as the
|
||||
/// `APPEND` command with the `BINARY` extension.
|
||||
///
|
||||
@@ -142,7 +142,7 @@ public struct CommandEncodingOptions: Hashable, Sendable {
|
||||
extension CommandEncodingOptions {
|
||||
/// Creates encoding options by inspecting server capabilities.
|
||||
///
|
||||
/// This initializer automatically enables extended literal formats based on
|
||||
/// Automatically enables extended literal formats based on
|
||||
/// server capabilities, making it easy to use the best available encoding strategy.
|
||||
///
|
||||
/// The initialization process:
|
||||
|
||||
@@ -22,7 +22,7 @@ import struct NIO.CircularBuffer
|
||||
/// that can be transmitted over the network. It wraps a `ByteBuffer` and tracks
|
||||
/// encoding state, supporting both client commands and server responses.
|
||||
///
|
||||
/// This type is part of the internal SPI and is primarily used by:
|
||||
/// Part of the internal SPI and is primarily used by:
|
||||
/// - ``CommandEncodeBuffer`` for encoding client commands
|
||||
/// - ``ResponseEncodeBuffer`` for encoding server responses
|
||||
///
|
||||
@@ -43,7 +43,7 @@ import struct NIO.CircularBuffer
|
||||
@_spi(NIOIMAPInternal) public struct EncodeBuffer: Hashable, Sendable {
|
||||
/// Determines whether the buffer encodes for a client or server.
|
||||
///
|
||||
/// This affects how the buffer formats protocol elements like literals, strings,
|
||||
/// Affects how the buffer formats protocol elements like literals, strings,
|
||||
/// and response codes. The mode also carries encoding options specific to each role.
|
||||
public enum Mode: Hashable, Sendable {
|
||||
/// Encodes client commands using the specified options.
|
||||
@@ -67,7 +67,7 @@ import struct NIO.CircularBuffer
|
||||
///
|
||||
/// When `true`, methods like ``writeBytes(_:)`` and ``writeBuffer(_:)`` will
|
||||
/// write placeholder text like `[N bytes]` instead of the actual binary content.
|
||||
/// This is useful for logging and debugging without exposing sensitive data.
|
||||
/// Useful for logging and debugging without exposing sensitive data.
|
||||
public var loggingMode: Bool
|
||||
|
||||
internal var mode: Mode
|
||||
@@ -159,7 +159,7 @@ extension EncodeBuffer {
|
||||
public struct Chunk: Hashable, Sendable {
|
||||
/// The encoded bytes ready to write to the network.
|
||||
///
|
||||
/// This buffer contains the next portion of IMAP protocol data to transmit.
|
||||
/// Contains the next portion of IMAP protocol data to transmit.
|
||||
public var bytes: ByteBuffer
|
||||
|
||||
/// Whether a continuation request (`+`) should be expected before sending the next chunk.
|
||||
|
||||
@@ -40,7 +40,7 @@
|
||||
/// Result: imap://user@example.com/INBOX/;uid=20
|
||||
/// ```
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - ``RelativeIMAPURL`` uses absolute message paths as one variant of relative URLs
|
||||
/// - ``URLCommand`` specifies the fetch operation details
|
||||
|
||||
@@ -20,7 +20,7 @@ import struct NIO.ByteBuffer
|
||||
/// It restricts which users or sessions are permitted to access the message data referenced by the URL.
|
||||
/// Each ``AuthenticatedURLRump`` includes an access identifier that determines authorization policy.
|
||||
///
|
||||
/// ### Access Types
|
||||
/// ### Access types
|
||||
///
|
||||
/// - ``anonymous``: Any user, including non-authenticated sessions, may access the URL
|
||||
/// - ``authenticateUser``: Only authenticated (non-anonymous) sessions may access the URL
|
||||
@@ -46,7 +46,7 @@ import struct NIO.ByteBuffer
|
||||
///
|
||||
/// Only sessions authenticated as "fred" may use this URL.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// See ``AuthenticatedURLRump`` for how access identifiers are combined with expiration dates,
|
||||
/// ``AuthenticatedURLVerifier`` for the verification token, and ``AuthenticatedURL`` for
|
||||
|
||||
@@ -61,7 +61,7 @@ public struct AppendData: Hashable, Sendable {
|
||||
/// not MIME content-transfer-encoded.
|
||||
///
|
||||
/// When `false` (default), the data is sent using standard literal syntax `{size}`,
|
||||
/// indicating the bytes are MIME content-transfer-encoded (e.g., base64 for binary content).
|
||||
/// indicating the bytes are MIME content-transfer-encoded (for example, base64 for binary content).
|
||||
///
|
||||
/// **Requires server capability:** ``Capability/binary`` (when `true`)
|
||||
///
|
||||
|
||||
@@ -25,7 +25,7 @@ import struct NIO.ByteBuffer
|
||||
/// Attribute flags are case-insensitive for comparison but preserve their original casing when transmitted.
|
||||
/// They are normalized to lowercase for comparison.
|
||||
///
|
||||
/// ### Standard Attribute Flags
|
||||
/// ### Standard attribute flags
|
||||
///
|
||||
/// - ``answered`` - The message has been replied to.
|
||||
/// - ``flagged`` - The message has been marked for attention.
|
||||
@@ -69,7 +69,7 @@ public struct AttributeFlag: Hashable, Sendable {
|
||||
/// The provided string is automatically lowercased to normalize the flag value, allowing case-insensitive
|
||||
/// comparison while preserving the original casing for transmission.
|
||||
///
|
||||
/// - parameter stringValue: The flag string (e.g., `"\\Answered"`, `"\\SEEN"`). Will be lowercased.
|
||||
/// - parameter stringValue: The flag string (for example, `"\\Answered"` or `"\\SEEN"`). Will be lowercased.
|
||||
public init(_ stringValue: String) {
|
||||
self.stringValue = stringValue.lowercased()
|
||||
}
|
||||
|
||||
@@ -18,7 +18,7 @@
|
||||
/// IMAP URL. It pairs the authorization parameters (expiration and access) with the verification
|
||||
/// information (mechanism and token).
|
||||
///
|
||||
/// This type represents the `;URLAUTH=<access>:<mechanism>:<token>` component appended to IMAP URLs
|
||||
/// The `;URLAUTH=<access>:<mechanism>:<token>` component is appended to IMAP URLs
|
||||
/// according to RFC 4467. It is used when:
|
||||
///
|
||||
/// 1. **Generating URLAUTH URLs** (GENURLAUTH command): Server creates authorization information
|
||||
@@ -63,7 +63,7 @@
|
||||
/// S: a002 OK URLFETCH completed
|
||||
/// ```
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - ``AuthenticatedURLRump`` provides expiration and access information
|
||||
/// - ``AuthenticatedURLVerifier`` provides mechanism and token for verification
|
||||
|
||||
@@ -22,7 +22,7 @@
|
||||
/// Together, ``AuthenticatedURLRump`` and ``AuthenticatedURLVerifier`` form a complete
|
||||
/// ``AuthenticatedURL`` that defines all authorization parameters for a URLAUTH-authorized URL.
|
||||
///
|
||||
/// ### URLAUTH Format
|
||||
/// ### URLAUTH format
|
||||
///
|
||||
/// A complete URLAUTH component has the form:
|
||||
/// ```
|
||||
@@ -58,7 +58,7 @@
|
||||
/// imap://owner@example.com/INBOX/;uid=20;EXPIRE=2025-12-31T23:59:59Z;URLAUTH=anonymous:internal:TOKEN
|
||||
/// ```
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - ``Expire`` wraps the optional expiration date
|
||||
/// - ``Access`` defines the access identifier
|
||||
|
||||
@@ -22,7 +22,7 @@
|
||||
/// The verifier allows the IMAP server to validate that the URL has been properly authorized
|
||||
/// by verifying the token using the specified mechanism and a stored mailbox access key.
|
||||
///
|
||||
/// ### Verification Process (RFC 4467 Section 6)
|
||||
/// ### Verification process (RFC 4467 Section 6)
|
||||
///
|
||||
/// When a URLFETCH command is issued with a URLAUTH-authorized URL:
|
||||
///
|
||||
@@ -49,7 +49,7 @@
|
||||
/// S: * URLFETCH ("imap://user@example.com/INBOX/;uid=20;urlauth=anonymous:internal:91354a473744909de610943775f92038" "message-data")
|
||||
/// ```
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - ``URLAuthenticationMechanism`` specifies the token generation algorithm
|
||||
/// - ``EncodedAuthenticatedURL`` wraps the hexadecimal-encoded token
|
||||
|
||||
@@ -60,7 +60,7 @@ public struct AuthenticationMechanism: Hashable, Sendable {
|
||||
///
|
||||
/// The provided value is uppercased for consistency with IMAP protocol conventions.
|
||||
///
|
||||
/// - parameter value: The mechanism name (e.g., PLAIN, GSSAPI).
|
||||
/// - parameter value: The mechanism name (for example, PLAIN or GSSAPI).
|
||||
public init(_ value: String) {
|
||||
self.rawValue = value.uppercased()
|
||||
}
|
||||
|
||||
@@ -51,7 +51,7 @@ extension MessageAttribute {
|
||||
/// S: A001 OK FETCH completed
|
||||
/// ```
|
||||
///
|
||||
/// This represents a ``singlepart(_:)`` case containing a ``Singlepart`` with media type `text/plain`.
|
||||
/// The response is a ``singlepart(_:)`` case containing a ``Singlepart`` with media type `text/plain`.
|
||||
///
|
||||
/// **Multipart message:**
|
||||
/// ```
|
||||
@@ -60,7 +60,7 @@ extension MessageAttribute {
|
||||
/// S: A002 OK FETCH completed
|
||||
/// ```
|
||||
///
|
||||
/// This represents a ``multipart(_:)`` case containing two parts (text/plain and text/html) with media subtype `alternative`.
|
||||
/// The response is a ``multipart(_:)`` case containing two parts (text/plain and text/html) with media subtype `alternative`.
|
||||
///
|
||||
/// - SeeAlso: [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2)
|
||||
/// - SeeAlso: [RFC 3501 Section 2.6.3](https://datatracker.ietf.org/doc/html/rfc3501#section-2.6.3)
|
||||
@@ -74,7 +74,7 @@ public enum BodyStructure: Hashable, Sendable {
|
||||
|
||||
/// A multipart message body containing one or more sub-parts.
|
||||
///
|
||||
/// Multipart messages have multiple MIME parts (e.g., `multipart/mixed` for mixed content,
|
||||
/// Multipart messages have multiple MIME parts (such as `multipart/mixed` for mixed content or
|
||||
/// `multipart/alternative` for alternative representations).
|
||||
case multipart(Multipart)
|
||||
}
|
||||
@@ -101,7 +101,7 @@ extension BodyStructure: RandomAccessCollection {
|
||||
|
||||
/// Gets the body at the given `position`.
|
||||
///
|
||||
/// This will assert if `position` is not a valid part of this ``BodyStructure``.
|
||||
/// Crashes if `position` is not a valid part of this ``BodyStructure``.
|
||||
///
|
||||
/// - parameter position: The position of the desired body.
|
||||
/// - returns: The body located at the given `position`.
|
||||
|
||||
@@ -26,8 +26,7 @@ extension BodyStructure {
|
||||
public struct DispositionKind: Hashable, RawRepresentable, Sendable {
|
||||
/// The `inline` disposition, indicating the part should be displayed as part of the message body.
|
||||
///
|
||||
/// This is the default disposition when not specified. Inline parts are typically displayed automatically
|
||||
/// by mail clients as part of the message preview.
|
||||
/// The default disposition when not specified.
|
||||
public static let inline = Self(rawValue: "inline")
|
||||
|
||||
/// The `attachment` disposition, indicating the part should be treated as a downloadable attachment.
|
||||
@@ -43,7 +42,7 @@ extension BodyStructure {
|
||||
/// The provided string is automatically lowercased to normalize the disposition value, allowing
|
||||
/// case-insensitive comparison.
|
||||
///
|
||||
/// - parameter rawValue: The disposition kind (e.g., `"inline"`, `"attachment"`). Will be lowercased.
|
||||
/// - parameter rawValue: The disposition kind (for example, `"inline"` or `"attachment"`). Will be lowercased.
|
||||
public init(rawValue: String) {
|
||||
self.rawValue = rawValue.lowercased()
|
||||
}
|
||||
@@ -74,7 +73,7 @@ extension BodyStructure {
|
||||
/// - SeeAlso: [RFC 2183](https://datatracker.ietf.org/doc/html/rfc2183)
|
||||
/// - SeeAlso: [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2)
|
||||
public struct Disposition: Hashable, Sendable {
|
||||
/// The disposition kind (e.g., `inline` or `attachment`).
|
||||
/// The disposition kind, such as `inline` or `attachment`.
|
||||
public var kind: DispositionKind
|
||||
|
||||
/// Optional parameters associated with the disposition.
|
||||
@@ -86,7 +85,7 @@ extension BodyStructure {
|
||||
/// Creates a new disposition.
|
||||
///
|
||||
/// - parameter kind: The disposition kind (`inline` or `attachment`).
|
||||
/// - parameter parameters: An ordered dictionary of disposition parameters (e.g., filename, size).
|
||||
/// - parameter parameters: An ordered dictionary of disposition parameters (for example, filename and size).
|
||||
public init(kind: DispositionKind, parameters: OrderedDictionary<String, String>) {
|
||||
self.kind = kind
|
||||
self.parameters = parameters
|
||||
@@ -112,7 +111,6 @@ extension BodyStructure {
|
||||
/// The `filename` parameter value, if present.
|
||||
///
|
||||
/// The `filename` parameter provides a recommended filename for saving the message part to disk.
|
||||
/// This is commonly used for attachment parts.
|
||||
///
|
||||
/// - Returns: The filename string, or `nil` if the parameter is not present.
|
||||
public var filename: String? {
|
||||
|
||||
@@ -17,12 +17,10 @@ import struct NIO.ByteBuffer
|
||||
extension BodyStructure {
|
||||
/// Content disposition and language information for a message part.
|
||||
///
|
||||
/// This type pairs optional content disposition (indicating how the part should be handled) with optional
|
||||
/// Pairs optional content disposition (indicating how the part should be handled) with optional
|
||||
/// language and location information. Both are optional fields in the body structure defined in
|
||||
/// [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2).
|
||||
///
|
||||
/// This is an API abstraction to simplify working with the disposition and language/location pairing from the raw IMAP message.
|
||||
///
|
||||
/// ### Example
|
||||
///
|
||||
/// ```
|
||||
|
||||
@@ -69,7 +69,7 @@ extension BodyStructure {
|
||||
|
||||
/// The encoding as an uppercase string.
|
||||
///
|
||||
/// - Returns: The encoding name in uppercase (e.g., `"7BIT"`, `"BASE64"`, `"QUOTED-PRINTABLE"`).
|
||||
/// - Returns: The encoding name in uppercase, for example `"7BIT"`, `"BASE64"`, or `"QUOTED-PRINTABLE"`.
|
||||
public var debugDescription: String { stringValue }
|
||||
|
||||
/// Creates a new encoding from a string representation.
|
||||
@@ -77,7 +77,7 @@ extension BodyStructure {
|
||||
/// The provided string is automatically uppercased to normalize the encoding value. This allows
|
||||
/// case-insensitive comparison between encoding values.
|
||||
///
|
||||
/// - parameter stringValue: The encoding name as a string (e.g., `"7bit"`, `"base64"`). Will be uppercased.
|
||||
/// - parameter stringValue: The encoding name as a string (for example, `"7bit"` or `"base64"`). Will be uppercased.
|
||||
public init(_ stringValue: String) {
|
||||
self.stringValue = stringValue.uppercased()
|
||||
}
|
||||
|
||||
@@ -23,7 +23,7 @@ extension BodyStructure {
|
||||
/// transfer encoding, and octet count.
|
||||
///
|
||||
/// These fields are derived from MIME headers (`Content-Type`, `Content-Transfer-Encoding`,
|
||||
/// etc.) and are essential for understanding how to process each message part.
|
||||
/// and so on) and are essential for understanding how to process each message part.
|
||||
///
|
||||
/// ### Example
|
||||
///
|
||||
@@ -58,7 +58,7 @@ extension BodyStructure {
|
||||
|
||||
/// The content transfer encoding from the `Content-Transfer-Encoding` header.
|
||||
///
|
||||
/// Describes how the message part is encoded (e.g., `7bit`, `base64`, `quoted-printable`).
|
||||
/// Describes how the message part is encoded (for example, `7bit`, `base64`, or `quoted-printable`).
|
||||
public var encoding: Encoding?
|
||||
|
||||
/// The size of the body part in octets (bytes).
|
||||
|
||||
@@ -17,13 +17,11 @@ import struct NIO.ByteBuffer
|
||||
extension BodyStructure {
|
||||
/// Language and content location information for a message part.
|
||||
///
|
||||
/// This type pairs one or more language identifiers with an optional content location URI. The language values
|
||||
/// Pairs one or more language identifiers with an optional content location URI. The language values
|
||||
/// follow [BCP 47](https://datatracker.ietf.org/doc/html/bcp47) language tags and the location follows
|
||||
/// [RFC 2557](https://datatracker.ietf.org/doc/html/rfc2557) for MIME content location URIs. Both are optional
|
||||
/// fields in the body structure defined in [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2).
|
||||
///
|
||||
/// This is an API abstraction to simplify working with the language/location pairing from the raw IMAP message.
|
||||
///
|
||||
/// ### Example
|
||||
///
|
||||
/// ```
|
||||
@@ -42,7 +40,7 @@ extension BodyStructure {
|
||||
/// One or more language identifiers for the message part.
|
||||
///
|
||||
/// Language values follow [BCP 47](https://datatracker.ietf.org/doc/html/bcp47) language tag format
|
||||
/// (e.g., `"en"` for English, `"en-US"` for US English, `"fr"` for French).
|
||||
/// (for example, `"en"` for English, `"en-US"` for US English, or `"fr"` for French).
|
||||
public var languages: [String]
|
||||
|
||||
/// Optional content location URI for the message part.
|
||||
|
||||
@@ -17,15 +17,13 @@ import struct NIO.ByteBuffer
|
||||
extension BodyStructure {
|
||||
/// Content location URI and future extension fields for a message part.
|
||||
///
|
||||
/// This type pairs a content location URI (defined in [RFC 2557](https://datatracker.ietf.org/doc/html/rfc2557))
|
||||
/// Pairs a content location URI (defined in [RFC 2557](https://datatracker.ietf.org/doc/html/rfc2557))
|
||||
/// with a list of future extension fields. The location provides a URI where the message part content can be
|
||||
/// retrieved, and extensions allow servers to add new fields without breaking existing clients.
|
||||
///
|
||||
/// Both the location and extensions are optional fields in the body structure defined in
|
||||
/// [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2).
|
||||
///
|
||||
/// This is an API abstraction to simplify working with the location/extension pairing from the raw IMAP message.
|
||||
///
|
||||
/// ### Example
|
||||
///
|
||||
/// ```
|
||||
|
||||
@@ -20,8 +20,8 @@ extension BodyStructure {
|
||||
///
|
||||
/// A multipart body represents a message divided into multiple MIME parts. Common multipart types include:
|
||||
/// - `multipart/mixed`: Parts with different media types mixed together
|
||||
/// - `multipart/alternative`: Alternative representations of the same content (e.g., plain text and HTML)
|
||||
/// - `multipart/related`: Parts that reference each other (e.g., HTML with embedded images)
|
||||
/// - `multipart/alternative`: Alternative representations of the same content (such as plain text and HTML)
|
||||
/// - `multipart/related`: Parts that reference each other (such as HTML with embedded images)
|
||||
///
|
||||
/// Each part in a multipart body is itself a ``BodyStructure``, which may be another multipart, creating
|
||||
/// arbitrarily deep nesting. Optional extension fields provide forward compatibility with future extensions.
|
||||
@@ -32,7 +32,7 @@ extension BodyStructure {
|
||||
/// (("text" "plain" ("charset" "us-ascii") NIL NIL "7bit" 1234 20) ("text" "html" ("charset" "us-ascii") NIL NIL "7bit" 5678 45) "alternative")
|
||||
/// ```
|
||||
///
|
||||
/// This is parsed as a ``Multipart`` with two parts (text/plain and text/html) and media subtype `alternative`.
|
||||
/// The wire format above is parsed as a ``Multipart`` with two parts (text/plain and text/html) and media subtype `alternative`.
|
||||
///
|
||||
/// - SeeAlso: [RFC 3501 Section 6.4.5](https://datatracker.ietf.org/doc/html/rfc3501#section-6.4.5)
|
||||
/// - SeeAlso: [RFC 2045](https://datatracker.ietf.org/doc/html/rfc2045)
|
||||
@@ -43,7 +43,7 @@ extension BodyStructure {
|
||||
/// Parts may be accessed using ``SectionSpecifier/Part`` indices.
|
||||
public var parts: [BodyStructure]
|
||||
|
||||
/// The multipart subtype (e.g., `mixed` for `multipart/mixed`, `alternative` for `multipart/alternative`).
|
||||
/// The multipart subtype (for example, `mixed` for `multipart/mixed` or `alternative` for `multipart/alternative`).
|
||||
///
|
||||
/// The subtype indicates how the parts should be interpreted or presented.
|
||||
public var mediaSubtype: Media.Subtype
|
||||
@@ -56,7 +56,7 @@ extension BodyStructure {
|
||||
|
||||
/// Creates a new multipart body.
|
||||
/// - parameter parts: The MIME parts that comprise this multipart
|
||||
/// - parameter mediaSubtype: The multipart subtype (e.g., `mixed`, `alternative`)
|
||||
/// - parameter mediaSubtype: The multipart subtype (for example, `mixed` or `alternative`)
|
||||
/// - parameter extension: Optional extension fields (defaults to `nil`)
|
||||
public init(parts: [BodyStructure], mediaSubtype: Media.Subtype, extension: Extension? = nil) {
|
||||
self.parts = parts
|
||||
@@ -73,7 +73,7 @@ extension BodyStructure.Multipart {
|
||||
/// (parameters and optional disposition/language information) to support future extensions
|
||||
/// without breaking existing clients.
|
||||
public struct Extension: Hashable, Sendable {
|
||||
/// MIME parameters for the multipart structure itself (e.g., `boundary` parameter).
|
||||
/// MIME parameters for the multipart structure itself (for example, the `boundary` parameter).
|
||||
///
|
||||
/// Contains key/value pairs as an ordered dictionary, preserving the server's order.
|
||||
public var parameters: OrderedDictionary<String, String>
|
||||
|
||||
@@ -18,7 +18,7 @@ extension BodyStructure {
|
||||
/// A single-part MIME message body as defined in RFC 3501.
|
||||
///
|
||||
/// A single-part body represents a message containing only one MIME part. This includes simple
|
||||
/// media types (e.g., `text/plain`, `image/jpeg`), the `message/rfc822` encapsulated message type,
|
||||
/// media types (for example, `text/plain` or `image/jpeg`), the `message/rfc822` encapsulated message type,
|
||||
/// and text-specific types. Single-part bodies may have optional extension fields for forward compatibility.
|
||||
///
|
||||
/// ### Example
|
||||
@@ -27,7 +27,7 @@ extension BodyStructure {
|
||||
/// ("text" "plain" ("charset" "us-ascii") NIL NIL "7bit" 3445 65)
|
||||
/// ```
|
||||
///
|
||||
/// This is parsed as a ``Singlepart`` with `kind: .text(...)`, `fields: Fields(...)`, and no extension.
|
||||
/// The wire format above is parsed as a ``Singlepart`` with `kind: .text(...)`, `fields: Fields(...)`, and no extension.
|
||||
///
|
||||
/// - SeeAlso: [RFC 3501 Section 2.6.3](https://datatracker.ietf.org/doc/html/rfc3501#section-2.6.3)
|
||||
/// - SeeAlso: ``Kind``
|
||||
@@ -65,19 +65,19 @@ extension BodyStructure.Singlepart {
|
||||
/// Represents the three main kinds of single-part bodies: basic media types, encapsulated messages,
|
||||
/// and text-specific types. Each kind may have additional properties specific to that type.
|
||||
public indirect enum Kind: Hashable, Sendable {
|
||||
/// A simple, non-message media type (e.g., `image/jpeg`, `application/pdf`).
|
||||
/// A simple, non-message media type (for example, `image/jpeg` or `application/pdf`).
|
||||
///
|
||||
/// The associated ``Media/MediaType`` specifies the exact MIME type and subtype.
|
||||
case basic(Media.MediaType)
|
||||
|
||||
/// An encapsulated RFC 822 email message (e.g., `message/rfc822`).
|
||||
/// An encapsulated RFC 822 email message (for example, `message/rfc822`).
|
||||
///
|
||||
/// The associated ``Message`` contains the envelope and nested body of the embedded message.
|
||||
case message(Message)
|
||||
|
||||
/// A text-specific body type with optional line count information.
|
||||
///
|
||||
/// The associated ``Text`` specifies the text subtype (e.g., `plain` or `html`).
|
||||
/// The associated ``Text`` specifies the text subtype (for example, `plain` or `html`).
|
||||
case text(Text)
|
||||
}
|
||||
|
||||
@@ -94,12 +94,10 @@ extension BodyStructure.Singlepart {
|
||||
|
||||
/// The hierarchical body structure of the embedded message.
|
||||
///
|
||||
/// This may itself be multipart, creating arbitrarily deep nesting of messages.
|
||||
/// May itself be multipart, creating arbitrarily deep nesting of messages.
|
||||
public var body: BodyStructure
|
||||
|
||||
/// The number of lines in the message (per RFC 2045/RFC 3501).
|
||||
///
|
||||
/// This is the line count of the message in its canonical form.
|
||||
public var lineCount: Int
|
||||
|
||||
/// Creates a new encapsulated message.
|
||||
@@ -117,10 +115,10 @@ extension BodyStructure.Singlepart {
|
||||
|
||||
/// A text-specific body part with MIME type `text/*` (RFC 3501).
|
||||
///
|
||||
/// Text bodies are specialized single-part bodies with a specific subtype (e.g., `plain`, `html`)
|
||||
/// Text bodies are specialized single-part bodies with a specific subtype (for example, `plain` or `html`)
|
||||
/// and an associated line count.
|
||||
public struct Text: Hashable, Sendable {
|
||||
/// The text subtype (e.g., `plain` for `text/plain`, `html` for `text/html`).
|
||||
/// The text subtype (for example, `plain` for `text/plain` or `html` for `text/html`).
|
||||
public var mediaSubtype: Media.Subtype
|
||||
|
||||
/// The number of lines in the text body (per RFC 2045/RFC 3501).
|
||||
@@ -129,7 +127,7 @@ extension BodyStructure.Singlepart {
|
||||
public var lineCount: Int
|
||||
|
||||
/// Creates a new text body.
|
||||
/// - parameter mediaSubtype: The text subtype (e.g., `plain` or `html`)
|
||||
/// - parameter mediaSubtype: The text subtype (for example, `plain` or `html`)
|
||||
/// - parameter lineCount: The number of lines in the text
|
||||
public init(mediaSubtype: Media.Subtype, lineCount: Int) {
|
||||
self.mediaSubtype = mediaSubtype
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
extension MessagePath {
|
||||
/// A byte range suffix for partial IMAP URL fetches.
|
||||
///
|
||||
/// This type wraps a ``/NIOIMAPCore/ByteRange`` for use in IMAP URLs with the `/;PARTIAL=` encoding
|
||||
/// Wraps a ``/NIOIMAPCore/ByteRange`` for use in IMAP URLs with the `/;PARTIAL=` encoding
|
||||
/// (RFC 5092). It enables clients to request only a portion of a message via URL without
|
||||
/// downloading the entire body.
|
||||
///
|
||||
|
||||
@@ -30,7 +30,7 @@ import struct NIO.ByteBuffer
|
||||
/// S: * CAPABILITY IMAP4rev1 STARTTLS AUTH=GSSAPI XPIG-LATIN
|
||||
/// ```
|
||||
///
|
||||
/// This server response advertises capabilities: `IMAP4rev1` (simple), `STARTTLS` (simple), `AUTH=GSSAPI`
|
||||
/// The server response advertises capabilities: `IMAP4rev1` (simple), `STARTTLS` (simple), `AUTH=GSSAPI`
|
||||
/// (configurable with name `AUTH` and value `GSSAPI`), and `XPIG-LATIN` (custom vendor extension).
|
||||
///
|
||||
/// - SeeAlso: [RFC 3501 Section 7.2.1](https://datatracker.ietf.org/doc/html/rfc3501#section-7.2.1)
|
||||
@@ -50,9 +50,9 @@ public struct Capability: Hashable, Sendable {
|
||||
return String(self.rawValue[..<index])
|
||||
}
|
||||
|
||||
/// If the capability is _simple_, e.g. `STARTTLS`, then the value will be `nil`.
|
||||
/// Otherwise, if the capability is configurable such as `AUTH=GSSAPI`, then the value will
|
||||
/// be `GSSAPI`.
|
||||
/// If the capability is _simple_, for example `STARTTLS`, the value is `nil`.
|
||||
/// Otherwise, if the capability is configurable such as `AUTH=GSSAPI`, the value
|
||||
/// is `GSSAPI`.
|
||||
public var value: String? {
|
||||
guard var index = self.splitIndex else {
|
||||
return nil
|
||||
@@ -63,7 +63,7 @@ public struct Capability: Hashable, Sendable {
|
||||
}
|
||||
|
||||
/// Creates a new capability from a `String`, and parses any configuration if present.
|
||||
/// - parameter value: The raw `String` value of the capability, e.g. *STARTTLS* or *AUTH=GSSAPI*.
|
||||
/// - parameter value: The raw `String` value of the capability, for example `STARTTLS` or `AUTH=GSSAPI`.
|
||||
public init(_ value: String) {
|
||||
self.init(unchecked: value)
|
||||
}
|
||||
@@ -98,7 +98,7 @@ extension Capability {
|
||||
///
|
||||
/// The provided value is uppercased for consistency with IMAP protocol conventions.
|
||||
///
|
||||
/// - parameter value: The context kind as a string (e.g., SEARCH, SORT).
|
||||
/// - parameter value: The context kind as a string (for example, SEARCH or SORT).
|
||||
public init(_ value: String) {
|
||||
self.rawValue = value.uppercased()
|
||||
}
|
||||
@@ -125,7 +125,7 @@ extension Capability {
|
||||
///
|
||||
/// The provided value is uppercased for consistency with IMAP protocol conventions.
|
||||
///
|
||||
/// - parameter value: The sort kind as a string (e.g., DISPLAY).
|
||||
/// - parameter value: The sort kind as a string (for example, DISPLAY).
|
||||
public init(_ value: String) {
|
||||
self.rawValue = value.uppercased()
|
||||
}
|
||||
@@ -155,7 +155,7 @@ extension Capability {
|
||||
///
|
||||
/// The provided value is uppercased for consistency with IMAP protocol conventions.
|
||||
///
|
||||
/// - parameter value: The thread kind as a string (e.g., ORDEREDSUBJECT, REFERENCES).
|
||||
/// - parameter value: The thread kind as a string (for example, ORDEREDSUBJECT or REFERENCES).
|
||||
public init(_ value: String) {
|
||||
self.rawValue = value.uppercased()
|
||||
}
|
||||
@@ -182,7 +182,7 @@ extension Capability {
|
||||
///
|
||||
/// The provided value is uppercased for consistency with IMAP protocol conventions.
|
||||
///
|
||||
/// - parameter value: The status kind as a string (e.g., SIZE).
|
||||
/// - parameter value: The status kind as a string (for example, SIZE).
|
||||
public init(_ value: String) {
|
||||
self.rawValue = value.uppercased()
|
||||
}
|
||||
@@ -210,7 +210,7 @@ extension Capability {
|
||||
///
|
||||
/// The provided value is uppercased for consistency with IMAP protocol conventions.
|
||||
///
|
||||
/// - parameter value: The UTF-8 kind as a string (e.g., ACCEPT).
|
||||
/// - parameter value: The UTF-8 kind as a string (for example, ACCEPT).
|
||||
public init(_ value: String) {
|
||||
self.rawValue = value.uppercased()
|
||||
}
|
||||
@@ -237,7 +237,7 @@ extension Capability {
|
||||
///
|
||||
/// The provided value is uppercased for consistency with IMAP protocol conventions.
|
||||
///
|
||||
/// - parameter value: The rights kind as a string (e.g., TEKX).
|
||||
/// - parameter value: The rights kind as a string (for example, TEKX).
|
||||
public init(_ value: String) {
|
||||
self.rawValue = value.uppercased()
|
||||
}
|
||||
@@ -264,7 +264,7 @@ extension Capability {
|
||||
///
|
||||
/// The provided value is uppercased for consistency with IMAP protocol conventions.
|
||||
///
|
||||
/// - parameter value: The compression kind as a string (e.g., DEFLATE).
|
||||
/// - parameter value: The compression kind as a string (for example, DEFLATE).
|
||||
public init(_ value: String) {
|
||||
self.rawValue = value.uppercased()
|
||||
}
|
||||
|
||||
@@ -56,7 +56,7 @@ public struct ChangedSinceModifier: Hashable, Sendable {
|
||||
/// the specified value. If the message has changed (higher mod-sequence), the operation is rejected, preventing
|
||||
/// lost updates in multimailbox environments.
|
||||
///
|
||||
/// This implements optimistic concurrency control, allowing multiple clients to safely modify messages without
|
||||
/// Implements optimistic concurrency control, allowing multiple clients to safely modify messages without
|
||||
/// overwriting each other's changes.
|
||||
///
|
||||
/// **Requires server capability:** ``Capability/condStore``
|
||||
|
||||
@@ -26,7 +26,7 @@ import struct OrderedCollections.OrderedDictionary
|
||||
/// The server responds with untagged data (prefixed with `*`) and a tagged response (using the same tag)
|
||||
/// indicating success (`OK`), failure (`NO`), or protocol error (`BAD`). See ``Response`` for response types.
|
||||
///
|
||||
/// ## Command Structure
|
||||
/// ## Command structure
|
||||
///
|
||||
/// Every IMAP command follows this basic structure:
|
||||
/// ```
|
||||
@@ -39,7 +39,7 @@ import struct OrderedCollections.OrderedDictionary
|
||||
/// A0003 FETCH 1:* (FLAGS BODY)
|
||||
/// ```
|
||||
///
|
||||
/// ## Protocol State Requirements
|
||||
/// ## Protocol state requirements
|
||||
///
|
||||
/// Commands are restricted based on the connection's current state:
|
||||
/// - **Any State**: Commands like ``capability``, ``noop``, and ``logout`` are valid at any time.
|
||||
@@ -50,7 +50,7 @@ import struct OrderedCollections.OrderedDictionary
|
||||
/// - **Selected**: Commands like ``fetch(_:_:_:)`` and ``search(key:charset:returnOptions:)`` work with messages
|
||||
/// in the currently selected mailbox.
|
||||
///
|
||||
/// ## Extension Support
|
||||
/// ## Extension support
|
||||
///
|
||||
/// Many commands support IMAP extensions defined in RFCs beyond [RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501).
|
||||
/// For example, the ``list(_:reference:_:_:)`` command supports extensions from
|
||||
@@ -58,7 +58,7 @@ import struct OrderedCollections.OrderedDictionary
|
||||
/// [RFC 5819](https://datatracker.ietf.org/doc/html/rfc5819) (RETURN option), and
|
||||
/// [RFC 6154](https://datatracker.ietf.org/doc/html/rfc6154) (SPECIAL-USE mailboxes).
|
||||
///
|
||||
/// ## Streaming Commands
|
||||
/// ## Streaming commands
|
||||
///
|
||||
/// Some commands like `APPEND` involve uploading large messages and are handled separately by the
|
||||
/// ``AppendCommand`` type to support streaming of data.
|
||||
@@ -127,7 +127,7 @@ public enum Command: Hashable, Sendable {
|
||||
/// The `LIST` command allows a client to discover what mailboxes are available on the server,
|
||||
/// with support for pattern matching and filtering.
|
||||
///
|
||||
/// ## Base Functionality ([RFC 3501 Section 6.3.8](https://datatracker.ietf.org/doc/html/rfc3501#section-6.3.8))
|
||||
/// ## Base functionality ([RFC 3501 Section 6.3.8](https://datatracker.ietf.org/doc/html/rfc3501#section-6.3.8))
|
||||
///
|
||||
/// The base `LIST` command takes two arguments:
|
||||
/// - **reference**: A mailbox name or hierarchy level that provides context for interpreting the pattern.
|
||||
@@ -150,7 +150,7 @@ public enum Command: Hashable, Sendable {
|
||||
/// pattern as `"*"`. The server responds with zero or more `S: * LIST...` lines (each wrapped as
|
||||
/// ``MailboxData/list(_:)``), followed by the tagged response `S: A001 OK LIST Completed`.
|
||||
///
|
||||
/// ## Selection Options ([RFC 5258](https://datatracker.ietf.org/doc/html/rfc5258))
|
||||
/// ## Selection options ([RFC 5258](https://datatracker.ietf.org/doc/html/rfc5258))
|
||||
///
|
||||
/// The optional `options` parameter uses ``ListSelectOptions`` to control which mailboxes are listed:
|
||||
/// - ``ListSelectBaseOption/subscribed``: Only list mailboxes that the user has subscribed to
|
||||
@@ -159,7 +159,7 @@ public enum Command: Hashable, Sendable {
|
||||
/// - ``ListSelectOption/recursiveMatch``: Include parent mailboxes that don't match but have matching children
|
||||
/// ([RFC 5258](https://datatracker.ietf.org/doc/html/rfc5258)).
|
||||
///
|
||||
/// ## Independent Options ([RFC 5258](https://datatracker.ietf.org/doc/html/rfc5258), [RFC 6154](https://datatracker.ietf.org/doc/html/rfc6154))
|
||||
/// ## Independent options ([RFC 5258](https://datatracker.ietf.org/doc/html/rfc5258), [RFC 6154](https://datatracker.ietf.org/doc/html/rfc6154))
|
||||
///
|
||||
/// When syntax conflicts prevent combining options, use ``listIndependent(_:reference:_:_:)`` instead:
|
||||
/// - ``ListSelectIndependentOption/remote``: Include remote mailboxes in the results
|
||||
@@ -167,7 +167,7 @@ public enum Command: Hashable, Sendable {
|
||||
/// - ``ListSelectIndependentOption/specialUse``: Only return mailboxes with special-use attributes
|
||||
/// like `\Drafts`, `\Sent`, or `\Trash` ([RFC 6154](https://datatracker.ietf.org/doc/html/rfc6154)).
|
||||
///
|
||||
/// ## Return Options ([RFC 5258](https://datatracker.ietf.org/doc/html/rfc5258), [RFC 5819](https://datatracker.ietf.org/doc/html/rfc5819), [RFC 6154](https://datatracker.ietf.org/doc/html/rfc6154))
|
||||
/// ## Return options ([RFC 5258](https://datatracker.ietf.org/doc/html/rfc5258), [RFC 5819](https://datatracker.ietf.org/doc/html/rfc5819), [RFC 6154](https://datatracker.ietf.org/doc/html/rfc6154))
|
||||
///
|
||||
/// The optional `returnOptions` array specifies what additional data should be returned for each mailbox:
|
||||
/// - ``ReturnOption/subscribed``: Include subscription state for each mailbox
|
||||
@@ -179,7 +179,7 @@ public enum Command: Hashable, Sendable {
|
||||
/// - ``ReturnOption/statusOption(_:)``: Request `STATUS` data (mailbox statistics like `MESSAGES`, `UNSEEN`, `UIDVALIDITY`)
|
||||
/// be returned alongside `LIST` responses ([RFC 5819](https://datatracker.ietf.org/doc/html/rfc5819)).
|
||||
///
|
||||
/// ### Example with Return Options
|
||||
/// ### Example with return options
|
||||
///
|
||||
/// ```
|
||||
/// C: A002 LIST "" "INBOX" RETURN (SUBSCRIBED STATUS (MESSAGES UNSEEN))
|
||||
@@ -406,7 +406,7 @@ public enum Command: Hashable, Sendable {
|
||||
|
||||
/// Searches the currently-selected mailbox for messages that match the search criteria.
|
||||
///
|
||||
/// This is a RFC 3501 / RFC 4731 style search. RFC 7377 style searches use `.extendedSearch`.
|
||||
/// Uses RFC 3501 / RFC 4731 style search. RFC 7377 style searches use `.extendedSearch`.
|
||||
///
|
||||
/// If `returnOptions` is empty, this is a RFC 3501 style search. But note that the empty
|
||||
/// RFC 7377 `RETURN ()` maps to `[.all]` — as it’s equivalent to `RETURN (ALL)`.
|
||||
@@ -418,7 +418,7 @@ public enum Command: Hashable, Sendable {
|
||||
/// `MOVE` – Moves each message in the given sequence number set to the destination mailbox.
|
||||
///
|
||||
/// Copies the specified messages to the end of the destination mailbox and removes the copies from the current mailbox.
|
||||
/// This operation is equivalent to performing ``copy(_:_:)`` followed by ``store(_:_:_:)`` with `\Deleted` flag.
|
||||
/// Equivalent to performing ``copy(_:_:)`` followed by ``store(_:_:_:)`` with `\Deleted` flag.
|
||||
///
|
||||
/// - SeeAlso: [RFC 6851](https://datatracker.ietf.org/doc/html/rfc6851)
|
||||
case move(LastCommandSet<SequenceNumber>, MailboxName)
|
||||
@@ -472,7 +472,7 @@ public enum Command: Hashable, Sendable {
|
||||
/// - Parameters:
|
||||
/// - criteria: One or more ``SortCriterion`` values defining the sort order. Later criteria
|
||||
/// are used as tie-breakers when earlier criteria produce equal values.
|
||||
/// - charset: The character set for string comparisons (e.g., `"UTF-8"`, `"US-ASCII"`). Required.
|
||||
/// - charset: The character set for string comparisons (for example, `"UTF-8"` or `"US-ASCII"`). Required.
|
||||
/// - key: The ``SearchKey`` filtering which messages to include in the result.
|
||||
/// - returnOptions: Optional ``SearchReturnOption`` values controlling the response format.
|
||||
///
|
||||
@@ -544,7 +544,7 @@ public enum Command: Hashable, Sendable {
|
||||
|
||||
/// Performs a “multimailbox” search as defined in RFC 7377.
|
||||
///
|
||||
/// This command enables searching across multiple mailboxes in a single request. The search results are
|
||||
/// Enables searching across multiple mailboxes in a single request. The search results are
|
||||
/// returned using the `ESEARCH` response format defined in RFC 4731, which includes optional `MIN`, `MAX`,
|
||||
/// `COUNT`, and `ALL` return options. This command is equivalent to the extended `SEARCH` command but can
|
||||
/// target multiple mailboxes via the ``MailboxFilter`` and ``Mailboxes`` filters.
|
||||
@@ -1119,7 +1119,7 @@ extension Command {
|
||||
}
|
||||
|
||||
/// Convenience for creating a *UID MOVE* command.
|
||||
/// Pass in a `UIDSet`, and if that set is valid (i.e. non-empty) then a command is returned.
|
||||
/// Pass in a `UIDSet`, and if that set is valid (that is, non-empty) then a command is returned.
|
||||
/// - parameter messages: The set of message UIDs to use.
|
||||
/// - parameter mailbox: The destination mailbox.
|
||||
/// - returns: `nil` if `messages` is empty, otherwise a `Command`.
|
||||
@@ -1131,7 +1131,7 @@ extension Command {
|
||||
}
|
||||
|
||||
/// Convenience for creating a *UID COPY* command.
|
||||
/// Pass in a `UIDSet`, and if that set is valid (i.e. non-empty) then a command is returned.
|
||||
/// Pass in a `UIDSet`, and if that set is valid (that is, non-empty) then a command is returned.
|
||||
/// - parameter messages: The set of message UIDs to use.
|
||||
/// - parameter mailbox: The destination mailbox.
|
||||
/// - returns: `nil` if `messages` is empty, otherwise a `Command`.
|
||||
@@ -1143,7 +1143,7 @@ extension Command {
|
||||
}
|
||||
|
||||
/// Convenience for creating a *UID FETCH* command.
|
||||
/// Pass in a `UIDSet`, and if that set is valid (i.e. non-empty) then a command is returned.
|
||||
/// Pass in a `UIDSet`, and if that set is valid (that is, non-empty) then a command is returned.
|
||||
/// - parameter messages: The set of message UIDs to use.
|
||||
/// - parameter attributes: Which attributes to retrieve.
|
||||
/// - parameter modifiers: Fetch modifiers.
|
||||
@@ -1157,7 +1157,7 @@ extension Command {
|
||||
}
|
||||
|
||||
/// Convenience for creating a *UID STORE* command.
|
||||
/// Pass in a `UIDSet`, and if that set is valid (i.e. non-empty) then a command is returned.
|
||||
/// Pass in a `UIDSet`, and if that set is valid (that is, non-empty) then a command is returned.
|
||||
/// - parameter messages: The set of message UIDs to use.
|
||||
/// - parameter modifiers: Store modifiers.
|
||||
/// - parameter data: The store data to apply.
|
||||
@@ -1170,7 +1170,7 @@ extension Command {
|
||||
}
|
||||
|
||||
/// Convenience for creating a *UID EXPUNGE* command.
|
||||
/// Pass in a `UIDSet`, and if that set is valid (i.e. non-empty) then a command is returned.
|
||||
/// Pass in a `UIDSet`, and if that set is valid (that is, non-empty) then a command is returned.
|
||||
/// - parameter messages: The set of message UIDs to use.
|
||||
/// - parameter mailbox: The mailbox on which to perform the expunge.
|
||||
/// - returns: `nil` if `messages` is empty, otherwise a `Command`.
|
||||
|
||||
@@ -34,7 +34,7 @@ import struct NIO.ByteBuffer
|
||||
/// S: A001 OK APPEND completed
|
||||
/// ```
|
||||
///
|
||||
/// This wire format is managed through multiple `AppendCommand` values:
|
||||
/// The wire format above is managed through multiple `AppendCommand` values:
|
||||
/// - `start(tag: "A001", appendingTo: "INBOX")` produces the command prefix
|
||||
/// - `beginMessage(...)` produces the metadata (flags, date, size)
|
||||
/// - `messageBytes(buffer)` streams the message data
|
||||
@@ -137,7 +137,7 @@ public enum AppendCommand: Hashable, Sendable {
|
||||
extension AppendCommand {
|
||||
/// Management of inline data catenation using the `CATENATE` extension (RFC 4469).
|
||||
///
|
||||
/// This enum manages the lifecycle of sending inline data as part of a catenation.
|
||||
/// Manages the lifecycle of sending inline data as part of a catenation.
|
||||
/// One `begin(size:)` message must be sent before exactly one `end` message, with
|
||||
/// zero or more `bytes(_:)` messages in between.
|
||||
///
|
||||
@@ -250,7 +250,7 @@ public enum CommandStreamPart: Hashable, Sendable {
|
||||
|
||||
/// Sends data in response to a server continuation request (`+`).
|
||||
///
|
||||
/// When a server sends a continuation request (e.g., during authentication or
|
||||
/// When a server sends a continuation request (for example, during authentication or
|
||||
/// literal data upload), the client responds with this case. The buffer typically
|
||||
/// contains base64-encoded credentials for `AUTHENTICATE` commands or raw message
|
||||
/// bytes for message uploads.
|
||||
|
||||
@@ -36,7 +36,7 @@ extension Command {
|
||||
/// literal with `{size}\r\n` prefix followed by the raw bytes. Otherwise, they
|
||||
/// are sent as a quoted string with `"..."` syntax.
|
||||
///
|
||||
/// This is the safer option when the payload should be treated as data rather
|
||||
/// The safer option when the payload should be treated as data rather
|
||||
/// than protocol syntax.
|
||||
///
|
||||
/// ### Example
|
||||
|
||||
@@ -40,7 +40,7 @@ import struct NIO.ByteBuffer
|
||||
/// sequence tracking is enabled for this mailbox. The server responds with `* OK [MODSEQ 12345]`
|
||||
/// indicating the current modification sequence value.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - See ``SearchModificationSequence`` for conditional search operations
|
||||
/// - See ``StoreModifier`` for conditional store modifiers in STORE commands
|
||||
|
||||
@@ -17,12 +17,12 @@ import struct NIO.ByteBuffer
|
||||
/// A calendar day formatted as `dd-MMM-yyyy` as defined in RFC 3501.
|
||||
///
|
||||
/// This type represents a date in the IMAP date format, where the month is represented
|
||||
/// as a three-letter abbreviation (e.g., `Jan`, `Feb`, etc.). This format is used in various
|
||||
/// as a three-letter abbreviation (for example, `Jan` or `Feb`). This format is used in various
|
||||
/// IMAP protocol messages including the `INTERNALDATE` message attribute and `APPEND` commands.
|
||||
///
|
||||
/// The `IMAPCalendarDay` provides basic validation of date components. Note that the
|
||||
/// validation checks component ranges but does not validate whether the combination
|
||||
/// represents a valid calendar date (e.g., February 30 is accepted).
|
||||
/// represents a valid calendar date (for example, February 30 is accepted).
|
||||
///
|
||||
/// ### Example
|
||||
///
|
||||
@@ -37,8 +37,8 @@ import struct NIO.ByteBuffer
|
||||
public struct IMAPCalendarDay: Hashable, Sendable {
|
||||
/// The year, constrained to the range `1900...2500`.
|
||||
///
|
||||
/// This is a 4-digit year value. The range constraint reflects common IMAP server
|
||||
/// implementations which typically support dates in this range.
|
||||
/// A 4-digit year value. The range constraint covers common IMAP server
|
||||
/// implementations.
|
||||
public let year: Int
|
||||
|
||||
/// The month, constrained to the range `1...12`.
|
||||
@@ -49,7 +49,7 @@ public struct IMAPCalendarDay: Hashable, Sendable {
|
||||
/// The day of the month, constrained to the range `1...31`.
|
||||
///
|
||||
/// The range accepts all valid day numbers across different months. No validation
|
||||
/// is performed to verify the day is valid for the specific month (e.g., February 30 is accepted).
|
||||
/// is performed to verify the day is valid for the specific month (for example, February 30 is accepted).
|
||||
public let day: Int
|
||||
|
||||
/// Creates a new `IMAPCalendarDay` and performs basic validation on the input.
|
||||
@@ -88,7 +88,7 @@ extension EncodeBuffer {
|
||||
extension IMAPCalendarDay {
|
||||
/// The three-letter month abbreviation for this calendar day.
|
||||
///
|
||||
/// Returns the month name as used in the IMAP date format (e.g., `Jan`, `Feb`, `Mar`, etc.).
|
||||
/// Returns the month name as used in the IMAP date format (for example, `Jan`, `Feb`, or `Mar`).
|
||||
fileprivate var monthString: String {
|
||||
switch month {
|
||||
case 1: return "Jan"
|
||||
|
||||
@@ -14,7 +14,7 @@
|
||||
|
||||
/// The internal date and time of a message as stored on the server.
|
||||
///
|
||||
/// This type represents the server's record of when a message was received or stored,
|
||||
/// Represents the server's record of when a message was received or stored,
|
||||
/// not the date from the message's headers (which is represented by ``InternetMessageDate``).
|
||||
/// The internal date consists of a calendar date, time of day, and timezone offset.
|
||||
///
|
||||
@@ -28,7 +28,7 @@
|
||||
/// * 1 FETCH (INTERNALDATE “15-Mar-2026 10:30:45 +0100”)
|
||||
/// ```
|
||||
///
|
||||
/// This response indicates the message was received on March 15, 2026 at 10:30:45 AM
|
||||
/// The response indicates the message was received on March 15, 2026 at 10:30:45 AM
|
||||
/// in the UTC+01:00 timezone. This is wrapped as ``ServerMessageDate`` with components
|
||||
/// accessible via the ``components`` property.
|
||||
///
|
||||
@@ -38,7 +38,7 @@ public struct ServerMessageDate: Hashable, Sendable {
|
||||
|
||||
/// The individual date and time components for this internal date.
|
||||
///
|
||||
/// This computed property extracts the encoded date, time, and timezone components
|
||||
/// Extracts the encoded date, time, and timezone components
|
||||
/// from the compact internal representation. The components can be used to
|
||||
/// display or work with individual date and time fields.
|
||||
///
|
||||
@@ -82,7 +82,7 @@ public struct ServerMessageDate: Hashable, Sendable {
|
||||
|
||||
/// Creates a new `ServerMessageDate` from individual date and time components.
|
||||
///
|
||||
/// This initializer constructs a ``ServerMessageDate`` by encoding the provided
|
||||
/// Constructs a ``ServerMessageDate`` by encoding the provided
|
||||
/// components into the compact rawValue representation.
|
||||
///
|
||||
/// - Parameter components: A ``Components`` structure containing the date, time, and timezone information.
|
||||
@@ -139,11 +139,11 @@ extension ServerMessageDate {
|
||||
/// let date = ServerMessageDate(components)
|
||||
/// ```
|
||||
///
|
||||
/// This creates an ``ServerMessageDate`` representing March 15, 2026 at 10:30:45 UTC+01:00.
|
||||
/// Creates a ``ServerMessageDate`` representing March 15, 2026 at 10:30:45 UTC+01:00.
|
||||
public struct Components: Sendable {
|
||||
/// The year, typically represented as a 4-digit integer.
|
||||
///
|
||||
/// This is a full year value (e.g., 2026), constrained to fit within an unsigned 16-bit integer.
|
||||
/// A full year value (for example, 2026), constrained to fit within an unsigned 16-bit integer.
|
||||
public let year: Int
|
||||
|
||||
/// The month, typically represented as a 2-digit integer in the range `1...12`.
|
||||
|
||||
@@ -36,7 +36,7 @@ import struct NIO.ByteBuffer
|
||||
/// `UNSEEN` search criteria. The response is ``Response/untagged(_:)`` containing
|
||||
/// ``ResponsePayload/mailboxData(_:)`` with ``MailboxData/extendedSearch(_:)``.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - See ``SearchKey`` for search criteria
|
||||
/// - See ``SearchReturnOption`` for return options
|
||||
@@ -60,14 +60,14 @@ public struct ExtendedSearchOptions: Hashable, Sendable {
|
||||
|
||||
/// Return options that filter and shape the data returned from the search.
|
||||
///
|
||||
/// Specifies which fields should be returned in the search response (e.g., ``SearchReturnOption/min``,
|
||||
/// ``SearchReturnOption/max``, ``SearchReturnOption/all``, etc.).
|
||||
/// Specifies which fields should be returned in the search response (for example, ``SearchReturnOption/min``,
|
||||
/// ``SearchReturnOption/max``, or ``SearchReturnOption/all``).
|
||||
public var returnOptions: [SearchReturnOption]
|
||||
|
||||
/// The mailboxes and scope to search across.
|
||||
///
|
||||
/// Specifies which mailbox(es) to include in the search operation using mailbox filters
|
||||
/// (e.g., personal namespace, specific mailbox names). When `nil`, the current mailbox context is used.
|
||||
/// (for example, personal namespace or specific mailbox names). When `nil`, the current mailbox context is used.
|
||||
public var sourceOptions: ExtendedSearchSourceOptions?
|
||||
|
||||
/// Creates a new `ExtendedSearchOptions` for multi-mailbox search.
|
||||
|
||||
@@ -24,7 +24,7 @@ import struct OrderedCollections.OrderedDictionary
|
||||
/// These options are specified as key-value pairs and are optional in search commands.
|
||||
/// See [RFC 7377 Section 2.1.1](https://datatracker.ietf.org/doc/html/rfc7377#section-2.1.1) for details.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - See ``ExtendedSearchSourceOptions`` for mailbox selection
|
||||
/// - See ``ExtendedSearchOptions`` for complete search options
|
||||
|
||||
@@ -19,7 +19,7 @@ import struct NIO.ByteBuffer
|
||||
/// **Requires server capability:** ``Capability/multiSearch``
|
||||
///
|
||||
/// Source options define the mailbox context for an extended search operation, allowing searches to span
|
||||
/// multiple mailboxes using mailbox filters (e.g., personal namespace mailboxes, specific named mailboxes).
|
||||
/// multiple mailboxes using mailbox filters (for example, personal namespace mailboxes or specific named mailboxes).
|
||||
/// The `IN` clause specifies one or more mailbox filters, and optional scope options can further refine
|
||||
/// the search context. See [RFC 7377 Section 2.1.1](https://datatracker.ietf.org/doc/html/rfc7377#section-2.1.1).
|
||||
///
|
||||
@@ -35,7 +35,7 @@ import struct NIO.ByteBuffer
|
||||
/// - ``MailboxFilter/personal`` - all personal mailboxes
|
||||
/// - ``MailboxFilter/subtree(_:)`` - the "Archive" mailbox and its subfolders
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - See ``MailboxFilter`` for individual mailbox filter types
|
||||
/// - See ``ExtendedSearchOptions`` for complete search options
|
||||
@@ -46,7 +46,7 @@ public struct ExtendedSearchSourceOptions: Hashable, Sendable {
|
||||
/// Array of mailbox filters specifying which mailboxes to search.
|
||||
///
|
||||
/// At least one mailbox filter must be present. Multiple filters can be combined to search
|
||||
/// across different mailbox categories (e.g., personal mailboxes, specific named mailboxes,
|
||||
/// across different mailbox categories (for example, personal mailboxes, specific named mailboxes, or
|
||||
/// subscribed mailboxes).
|
||||
public let sourceMailbox: [MailboxFilter]
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ import struct NIO.ByteBuffer
|
||||
|
||||
/// An RFC 2822 electronic mail address with structured components.
|
||||
///
|
||||
/// This type represents an address as returned in the `ENVELOPE` structure of a `FETCH` response.
|
||||
/// Represents an address as returned in the `ENVELOPE` structure of a `FETCH` response.
|
||||
/// The `ENVELOPE` address format breaks email addresses into four distinct components to help applications
|
||||
/// display mail headers consistently and reliably.
|
||||
///
|
||||
@@ -30,7 +30,7 @@ import struct NIO.ByteBuffer
|
||||
/// S: * 1 FETCH (ENVELOPE (NIL "Alice Smith" "alice" "example.com" ...))
|
||||
/// ```
|
||||
///
|
||||
/// This response contains an address with nil at-domain-list, personName "Alice Smith", mailbox "alice", and host "example.com".
|
||||
/// The response contains an address with nil at-domain-list, personName "Alice Smith", mailbox "alice", and host "example.com".
|
||||
///
|
||||
/// - SeeAlso: [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2)
|
||||
public struct EmailAddress: Hashable, Sendable {
|
||||
|
||||
@@ -20,7 +20,7 @@ import struct NIO.ByteBuffer
|
||||
/// When the mechanism name contains characters that are not allowed in URLs, the name must be
|
||||
/// percent-encoded using UTF-8 followed by hexadecimal encoding (RFC 2192, RFC 3986).
|
||||
///
|
||||
/// This type wraps a percent-encoded authentication mechanism name for use in URL construction.
|
||||
/// Wraps a percent-encoded authentication mechanism name for use in URL construction.
|
||||
/// The encoded string contains only ASCII-safe characters and can be safely included in IMAP URL syntax.
|
||||
///
|
||||
/// ### Examples
|
||||
@@ -48,7 +48,7 @@ import struct NIO.ByteBuffer
|
||||
/// )
|
||||
/// ```
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// See ``IMAPURLAuthenticationMechanism`` for the authentication mechanism specification,
|
||||
/// ``UserAuthenticationMechanism`` for how mechanisms are combined with user identifiers,
|
||||
|
||||
@@ -21,7 +21,7 @@ import struct NIO.ByteBuffer
|
||||
/// characters), the name must be percent-encoded using UTF-8 followed by hexadecimal encoding
|
||||
/// (RFC 2192, RFC 3986).
|
||||
///
|
||||
/// This type wraps a percent-encoded mailbox name for use in URL construction. The encoded
|
||||
/// Wraps a percent-encoded mailbox name for use in URL construction. The encoded
|
||||
/// string contains only ASCII-safe characters and can be safely included in IMAP URL syntax.
|
||||
///
|
||||
/// ### Example
|
||||
@@ -46,7 +46,7 @@ import struct NIO.ByteBuffer
|
||||
/// )
|
||||
/// ```
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// See ``MailboxUIDValidity`` for mailbox references with UID validity values, and
|
||||
/// ``MessagePath`` for the complete message location specification in URLs.
|
||||
|
||||
@@ -14,7 +14,7 @@
|
||||
|
||||
/// A mailbox reference paired with an optional percent-encoded search query.
|
||||
///
|
||||
/// This type combines a mailbox identifier with UID validity and an optional search query for use
|
||||
/// Combines a mailbox identifier with UID validity and an optional search query for use
|
||||
/// in IMAP URLs (RFC 5092). It specifies both which mailbox to search and what to search for.
|
||||
///
|
||||
/// - SeeAlso: [RFC 5092 IMAP URL Scheme](https://datatracker.ietf.org/doc/html/rfc5092)
|
||||
|
||||
@@ -17,10 +17,10 @@ import struct NIO.ByteBuffer
|
||||
/// A percent-encoded message section reference for use in IMAP URLs.
|
||||
///
|
||||
/// IMAP message sections (as defined in RFC 3501) specify parts of message structures
|
||||
/// using dot-separated numeric notation (e.g., "1", "1.2", "1.2.3"). When used in IMAP URLs,
|
||||
/// using dot-separated numeric notation (for example, "1", "1.2", or "1.2.3"). When used in IMAP URLs,
|
||||
/// section references are percent-encoded to ensure URL safety (RFC 2192, RFC 3986).
|
||||
///
|
||||
/// This type wraps a percent-encoded section reference for use in URL construction.
|
||||
/// Wraps a percent-encoded section reference for use in URL construction.
|
||||
/// The encoded string contains only ASCII-safe characters and can be safely included in IMAP URL syntax.
|
||||
///
|
||||
/// ### Example
|
||||
@@ -42,7 +42,7 @@ import struct NIO.ByteBuffer
|
||||
/// )
|
||||
/// ```
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// See ``URLMessageSection`` for the complete message section specification,
|
||||
/// ``MessagePath`` for the full message location including sections, and
|
||||
|
||||
@@ -24,7 +24,7 @@ import struct NIO.ByteBuffer
|
||||
/// The token appears in the final component of the URLAUTH extension:
|
||||
/// `;URLAUTH=<access>:<mechanism>:<token>`
|
||||
///
|
||||
/// This type wraps the hexadecimal-encoded token string for use in URLAUTH verification
|
||||
/// Wraps the hexadecimal-encoded token string for use in URLAUTH verification
|
||||
/// structures (via ``AuthenticatedURLVerifier``).
|
||||
///
|
||||
/// ### Example
|
||||
@@ -45,7 +45,7 @@ import struct NIO.ByteBuffer
|
||||
/// When a client later uses this URL with URLFETCH, the server re-calculates the token
|
||||
/// to verify authorization before returning the message data.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// See ``URLAuthenticationMechanism`` for the mechanism specification, ``AuthenticatedURLVerifier``
|
||||
/// for the complete mechanism and token pair, and ``AuthenticatedURL`` for the full
|
||||
@@ -57,7 +57,7 @@ import struct NIO.ByteBuffer
|
||||
public struct EncodedAuthenticatedURL: Hashable, Sendable {
|
||||
/// The hexadecimal-encoded authorization token string.
|
||||
///
|
||||
/// This is an ASCII-encoded hexadecimal representation of the token bytes. The RFC 4467
|
||||
/// An ASCII-encoded hexadecimal representation of the token bytes. The RFC 4467
|
||||
/// specification recommends using hexadecimal instead of Base64 to avoid URL-problematic
|
||||
/// padding characters.
|
||||
public var data: String
|
||||
|
||||
@@ -20,7 +20,7 @@ import struct NIO.ByteBuffer
|
||||
/// characters. This encoding is applied when a user identifier contains non-ASCII characters,
|
||||
/// spaces, or special characters that are not allowed in URL syntax (RFC 2192, RFC 3986).
|
||||
///
|
||||
/// This type wraps a percent-encoded user identifier for use in server specifications
|
||||
/// Wraps a percent-encoded user identifier for use in server specifications
|
||||
/// (via ``UserAuthenticationMechanism`` and ``IMAPServer``) and in URLAUTH access identifiers
|
||||
/// (via ``Access`` with `user+` and `submit+` prefixes).
|
||||
///
|
||||
@@ -43,7 +43,7 @@ import struct NIO.ByteBuffer
|
||||
/// imap://owner@example.com/INBOX/;uid=20;urlauth=submit+Fr%C3%A9d%C3%A9ric:internal:...
|
||||
/// ```
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// See ``Access`` for how encoded users are used in URLAUTH access identifiers,
|
||||
/// ``UserAuthenticationMechanism`` for server-level user specifications, and
|
||||
|
||||
@@ -16,7 +16,7 @@
|
||||
///
|
||||
/// **Requires server capability:** ``Capability/metadata`` or ``Capability/metadataServer``
|
||||
///
|
||||
/// This type wraps an ``AttributeFlag`` to represent it as a metadata entry name in the special
|
||||
/// Wraps an ``AttributeFlag`` to represent it as a metadata entry name in the special
|
||||
/// `/flags/` namespace. Flag entries allow metadata operations on flag modification sequences
|
||||
/// through the entry name format `/flags/flagname`. See [RFC 5464](https://datatracker.ietf.org/doc/html/rfc5464)
|
||||
/// for details on metadata entry organization.
|
||||
@@ -32,7 +32,7 @@
|
||||
/// The entry name `/flags/\Seen` is represented using ``EntryFlagName`` wrapping the
|
||||
/// ``AttributeFlag`` for `\Seen`. The value `12345` is the modification sequence for that flag.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - See ``AttributeFlag`` for system flag representation
|
||||
/// - See ``MetadataEntryName`` for general metadata entry names
|
||||
@@ -42,7 +42,7 @@
|
||||
public struct EntryFlagName: Hashable, Sendable {
|
||||
/// The flag wrapped as a metadata entry.
|
||||
///
|
||||
/// Represents a system flag (e.g., `\Seen`, `\Flagged`, `\Deleted`) in metadata entry form.
|
||||
/// Represents a system flag (for example, `\Seen`, `\Flagged`, or `\Deleted`) in metadata entry form.
|
||||
public var flag: AttributeFlag
|
||||
|
||||
/// Creates a new `EntryFlagName` wrapping an `AttributeFlag`.
|
||||
|
||||
@@ -33,7 +33,7 @@ import struct NIO.ByteBuffer
|
||||
/// The `ALL` option in the command queries modification sequences for the specified flags,
|
||||
/// considering both private and shared metadata sources.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - See ``EntryKindResponse`` for server-returned entry type information
|
||||
/// - See ``MetadataOption`` for other metadata query options
|
||||
|
||||
@@ -20,7 +20,7 @@ import struct NIO.ByteBuffer
|
||||
///
|
||||
/// Entry kind response indicates whether a metadata entry belongs to the private namespace
|
||||
/// (visible only to the authenticated user) or the shared namespace (visible to all users).
|
||||
/// This information is returned by the server when responding to metadata queries.
|
||||
/// The server returns this information when responding to metadata queries.
|
||||
/// See [RFC 5464 Section 3.3](https://datatracker.ietf.org/doc/html/rfc5464#section-3.3).
|
||||
///
|
||||
/// ### Example
|
||||
@@ -34,7 +34,7 @@ import struct NIO.ByteBuffer
|
||||
/// The response includes the entry type `priv` to indicate that the `/flags/\Seen` modification
|
||||
/// sequence metadata is private to the authenticated user.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - See ``EntryKindRequest`` for client-side entry type specification
|
||||
/// - See ``MetadataResponse`` for complete metadata responses
|
||||
|
||||
@@ -46,13 +46,13 @@ public struct Envelope: Hashable, Sendable {
|
||||
|
||||
/// The sender(s) of the message, as from the `From:` header.
|
||||
///
|
||||
/// This is the author or originator of the message content. Multiple addresses indicate
|
||||
/// The author or originator of the message content. Multiple addresses indicate
|
||||
/// multiple authors are credited with writing the message.
|
||||
public var from: [EmailAddressListElement]
|
||||
|
||||
/// The actual sender on behalf of the author, as from the `Sender:` header.
|
||||
///
|
||||
/// This is used when one entity sends a message on behalf of another (e.g., an assistant
|
||||
/// Used when one entity sends a message on behalf of another (for example, an assistant
|
||||
/// sending mail on behalf of their boss). If absent, the `from` field should be used.
|
||||
public var sender: [EmailAddressListElement]
|
||||
|
||||
@@ -80,12 +80,12 @@ public struct Envelope: Hashable, Sendable {
|
||||
|
||||
/// The message ID of the message this message is replying to, as from the `In-Reply-To:` header.
|
||||
///
|
||||
/// This field links this message to a previous message in a conversation thread.
|
||||
/// Links this message to a previous message in a conversation thread.
|
||||
public var inReplyTo: MessageID?
|
||||
|
||||
/// The unique message identifier, as from the `Message-ID:` header.
|
||||
///
|
||||
/// This identifier is assigned by the originating SMTP server and is globally unique
|
||||
/// Assigned by the originating SMTP server and globally unique
|
||||
/// for the originating system.
|
||||
public var messageID: MessageID?
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@
|
||||
/// remains valid. After the expiration date and time, the IMAP server must reject the URL
|
||||
/// (RFC 4467 Section 3).
|
||||
///
|
||||
/// This is an optional component appended to IMAP URLs as `;EXPIRE=<datetime>` (in RFC 3339 format).
|
||||
/// An optional component appended to IMAP URLs as `;EXPIRE=<datetime>` (in RFC 3339 format).
|
||||
/// If not specified, the URL has no expiration time, though it can still be revoked by other means
|
||||
/// (such as regenerating the mailbox access key).
|
||||
///
|
||||
@@ -31,7 +31,7 @@
|
||||
///
|
||||
/// The `;expire=2025-12-31T23:59:59Z` component indicates the URL expires at that date and time.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// See ``AuthenticatedURLRump`` for how expiration is combined with ``Access`` identifiers,
|
||||
/// and ``FullDateTime`` for the datetime format specification.
|
||||
@@ -41,7 +41,7 @@ public struct Expire: Hashable, Sendable {
|
||||
/// The latest date and time that a URLAUTH-authorized URL is valid.
|
||||
///
|
||||
/// After this date and time, the URL must be rejected by the IMAP server. The datetime is
|
||||
/// encoded in RFC 3339 format (e.g., `2025-12-31T23:59:59Z`).
|
||||
/// encoded in RFC 3339 format (for example, `2025-12-31T23:59:59Z`).
|
||||
public var dateTime: FullDateTime
|
||||
|
||||
/// Creates a new expiration date and time.
|
||||
|
||||
@@ -20,11 +20,11 @@ import struct NIO.ByteBuffer
|
||||
/// This enum represents all available fetch attributes, including standard RFC 3501 attributes and
|
||||
/// attributes from various IMAP extensions.
|
||||
///
|
||||
/// ### Standard Attributes (RFC 3501)
|
||||
/// ### Standard attributes (RFC 3501)
|
||||
///
|
||||
/// Basic message properties like envelope, flags, internal date, and RFC 822 message format.
|
||||
///
|
||||
/// ### Extension Attributes
|
||||
/// ### Extension attributes
|
||||
///
|
||||
/// - `BODYSTRUCTURE`: Detailed message structure information (RFC 3501)
|
||||
/// - `BINARY`: Raw binary content of message sections (RFC 3516 BINARY extension)
|
||||
@@ -33,7 +33,7 @@ import struct NIO.ByteBuffer
|
||||
/// - `EMAILID` / `THREADID`: Message and thread identifiers (RFC 8474)
|
||||
/// - `X-GM-*`: Gmail-specific attributes (non-standard)
|
||||
///
|
||||
/// ### Attributes with Options
|
||||
/// ### Attributes with options
|
||||
///
|
||||
/// Some attributes support optional parameters:
|
||||
/// - ``bodySection(peek:_:_:)`` supports a `peek` flag (prevents \\Seen flag modification) and partial byte ranges
|
||||
@@ -57,7 +57,7 @@ public enum FetchAttribute: Hashable, Sendable {
|
||||
/// The message envelope structure containing sender, recipient, subject, and date information.
|
||||
///
|
||||
/// Returns an ``Envelope`` structure with the sender, recipient lists, subject, and other message metadata.
|
||||
/// This is a parsed representation of the message headers.
|
||||
/// A parsed representation of the message headers.
|
||||
///
|
||||
/// - SeeAlso: [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2)
|
||||
case envelope
|
||||
@@ -126,7 +126,7 @@ public enum FetchAttribute: Hashable, Sendable {
|
||||
/// their headers. Supports partial byte ranges for efficient fetching of large parts.
|
||||
///
|
||||
/// - parameter peek: If `true`, does not set the `\Seen` flag on the message; if `false`, sets `\Seen`
|
||||
/// - parameter section: The section specifier (e.g., `1`, `1.1`, `HEADER`, `TEXT`)
|
||||
/// - parameter section: The section specifier (for example, `1`, `1.1`, `HEADER`, or `TEXT`)
|
||||
/// - parameter partial: Optional byte range `startOctet..<endOctet` to fetch only a portion
|
||||
/// - SeeAlso: [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2)
|
||||
case bodySection(peek: Bool, _ section: SectionSpecifier, ClosedRange<UInt32>?)
|
||||
@@ -168,7 +168,7 @@ public enum FetchAttribute: Hashable, Sendable {
|
||||
/// **Requires server capability:** ``Capability/binary``
|
||||
///
|
||||
/// - parameter peek: If `true`, does not set the `\Seen` flag; if `false`, sets `\Seen`
|
||||
/// - parameter section: The specific MIME part to fetch (e.g., `1`, `1.1`)
|
||||
/// - parameter section: The specific MIME part to fetch (for example, `1` or `1.1`)
|
||||
/// - parameter partial: Optional byte range to fetch only a portion
|
||||
/// - SeeAlso: [RFC 3516](https://datatracker.ietf.org/doc/html/rfc3516)
|
||||
case binary(peek: Bool, section: SectionSpecifier.Part, partial: ClosedRange<UInt32>?)
|
||||
@@ -185,7 +185,7 @@ public enum FetchAttribute: Hashable, Sendable {
|
||||
|
||||
/// The message's Gmail-assigned message ID (Gmail extension, non-standard).
|
||||
///
|
||||
/// This is a Gmail-specific extension that returns the unique message identifier within
|
||||
/// A Gmail-specific extension that returns the unique message identifier within
|
||||
/// Gmail's system. Not part of the IMAP standard.
|
||||
///
|
||||
/// - SeeAlso: https://developers.google.com/gmail/imap/imap-extensions
|
||||
@@ -193,7 +193,7 @@ public enum FetchAttribute: Hashable, Sendable {
|
||||
|
||||
/// The message's Gmail thread ID (Gmail extension, non-standard).
|
||||
///
|
||||
/// This is a Gmail-specific extension that returns the identifier for the thread/conversation
|
||||
/// A Gmail-specific extension that returns the identifier for the thread/conversation
|
||||
/// this message belongs to. Not part of the IMAP standard.
|
||||
///
|
||||
/// - SeeAlso: https://developers.google.com/gmail/imap/imap-extensions
|
||||
@@ -201,7 +201,7 @@ public enum FetchAttribute: Hashable, Sendable {
|
||||
|
||||
/// The message's Gmail labels (Gmail extension, non-standard).
|
||||
///
|
||||
/// This is a Gmail-specific extension that returns the list of labels (like folders) applied
|
||||
/// A Gmail-specific extension that returns the list of labels (like folders) applied
|
||||
/// to this message. Not part of the IMAP standard.
|
||||
///
|
||||
/// - SeeAlso: https://developers.google.com/gmail/imap/imap-extensions
|
||||
|
||||
@@ -57,7 +57,7 @@ public enum FetchModifier: Hashable, Sendable {
|
||||
|
||||
/// A server extension modifier not defined in this library.
|
||||
///
|
||||
/// This case captures future `FETCH` modifiers defined by extensions, allowing forward compatibility
|
||||
/// Captures future `FETCH` modifiers defined by extensions, allowing forward compatibility
|
||||
/// with new IMAP capabilities without requiring library updates.
|
||||
case other(KeyValue<String, ParameterValue?>)
|
||||
}
|
||||
|
||||
@@ -19,7 +19,7 @@ import struct NIO.ByteBuffer
|
||||
/// Flags are attributes attached to messages that indicate message state or special properties.
|
||||
/// They are part of the base [IMAP protocol](https://datatracker.ietf.org/doc/html/rfc3501).
|
||||
///
|
||||
/// ## Standard Flags
|
||||
/// ## Standard flags
|
||||
///
|
||||
/// [RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501) defines five standard system flags:
|
||||
/// - ``answered`` - The message has been replied to.
|
||||
@@ -28,12 +28,12 @@ import struct NIO.ByteBuffer
|
||||
/// - ``seen`` - The message has been read by the user.
|
||||
/// - ``draft`` - The message is incomplete and has not been sent.
|
||||
///
|
||||
/// ## Case Handling
|
||||
/// ## Case handling
|
||||
///
|
||||
/// Flags are compared case-insensitively, meaning `Flag("\\SEEN")` and `Flag("\\Seen")` are considered equal.
|
||||
/// Flags also preserve their original casing when encoded and decoded.
|
||||
///
|
||||
/// ## Extension Flags
|
||||
/// ## Extension flags
|
||||
///
|
||||
/// Beyond the five standard flags, custom flags can be created. These are defined in
|
||||
/// [RFC 3501 Section 2.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-2.3.2).
|
||||
@@ -94,30 +94,29 @@ extension Flag: CustomDebugStringConvertible {
|
||||
extension Flag {
|
||||
/// `\Answered` - The message has been replied to.
|
||||
///
|
||||
/// This standard flag ([RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501)) indicates that the
|
||||
/// Defined in [RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501). Indicates the
|
||||
/// message is a response to another message.
|
||||
public static let answered = Self("\\Answered")
|
||||
|
||||
/// `\Flagged` - The message has been marked for attention.
|
||||
///
|
||||
/// This standard flag ([RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501)).
|
||||
/// Defined in [RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501).
|
||||
public static let flagged = Self("\\Flagged")
|
||||
|
||||
/// `\Deleted` - The message has been deleted.
|
||||
///
|
||||
/// This standard flag ([RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501)) marks a message for
|
||||
/// deletion. The message is not permanently removed until the ``Command/expunge`` command is executed
|
||||
/// or the mailbox is closed.
|
||||
/// Defined in [RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501). Marks a message for
|
||||
/// deletion until the ``Command/expunge`` command is executed or the mailbox is closed.
|
||||
public static let deleted = Self("\\Deleted")
|
||||
|
||||
/// `\Seen` - The message has been read by the user.
|
||||
///
|
||||
/// This standard flag ([RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501)).
|
||||
/// Defined in [RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501).
|
||||
public static let seen = Self("\\Seen")
|
||||
|
||||
/// `\Draft` - The message is not yet complete.
|
||||
///
|
||||
/// This standard flag ([RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501)).
|
||||
/// Defined in [RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501).
|
||||
public static let draft = Self("\\Draft")
|
||||
|
||||
/// Convenience function to create a new flag from a `Keyword`.
|
||||
|
||||
@@ -51,7 +51,7 @@ extension Flag {
|
||||
|
||||
/// The case-preserved raw string representation of the keyword.
|
||||
///
|
||||
/// This value preserves the original casing for wire format transmission, while comparison operations
|
||||
/// Preserves the original casing for wire format transmission, while comparison operations
|
||||
/// use case-insensitive matching.
|
||||
let rawValue: String
|
||||
|
||||
@@ -119,52 +119,52 @@ extension Flag.Keyword: CustomDebugStringConvertible {
|
||||
extension Flag.Keyword {
|
||||
/// The `$Forwarded` keyword, commonly used to mark messages that have been forwarded.
|
||||
///
|
||||
/// This is a registered keyword in the special-use keywords registry.
|
||||
/// A registered keyword in the special-use keywords registry.
|
||||
public static let forwarded = Self(unchecked: "$Forwarded")
|
||||
|
||||
/// The `$Junk` keyword, commonly used to mark messages as spam or junk mail.
|
||||
///
|
||||
/// This is a registered keyword in the special-use keywords registry.
|
||||
/// A registered keyword in the special-use keywords registry.
|
||||
public static let junk = Self(unchecked: "$Junk")
|
||||
|
||||
/// The `$NotJunk` keyword, commonly used to mark messages as not spam.
|
||||
///
|
||||
/// This is a registered keyword in the special-use keywords registry.
|
||||
/// A registered keyword in the special-use keywords registry.
|
||||
public static let notJunk = Self(unchecked: "$NotJunk")
|
||||
|
||||
/// The `Redirected` keyword (unregistered).
|
||||
///
|
||||
/// This is a non-standard keyword sometimes used by mail systems to mark redirected messages.
|
||||
/// A non-standard keyword sometimes used by mail systems to mark redirected messages.
|
||||
public static let unregistered_redirected = Self(unchecked: "Redirected")
|
||||
|
||||
/// The `Forwarded` keyword (unregistered).
|
||||
///
|
||||
/// This is a non-standard keyword for marking forwarded messages. Prefer ``forwarded`` for standard usage.
|
||||
/// A non-standard keyword for marking forwarded messages. Prefer ``forwarded`` for standard usage.
|
||||
public static let unregistered_forwarded = Self(unchecked: "Forwarded")
|
||||
|
||||
/// The `Junk` keyword (unregistered).
|
||||
///
|
||||
/// This is a non-standard keyword for marking spam. Prefer ``junk`` for standard usage.
|
||||
/// A non-standard keyword for marking spam. Prefer ``junk`` for standard usage.
|
||||
public static let unregistered_junk = Self(unchecked: "Junk")
|
||||
|
||||
/// The `NotJunk` keyword (unregistered).
|
||||
///
|
||||
/// This is a non-standard keyword for marking non-spam messages. Prefer ``notJunk`` for standard usage.
|
||||
/// A non-standard keyword for marking non-spam messages. Prefer ``notJunk`` for standard usage.
|
||||
public static let unregistered_notJunk = Self(unchecked: "NotJunk")
|
||||
|
||||
/// The `$MailFlagBit0` keyword for color marking (bit 0).
|
||||
///
|
||||
/// This keyword is commonly used by mail systems to represent color flags on messages, with different bits representing different colors.
|
||||
/// A color-flag keyword for messages, where different bits represent different colors.
|
||||
public static let colorBit0 = Self(unchecked: "$MailFlagBit0")
|
||||
|
||||
/// The `$MailFlagBit1` keyword for color marking (bit 1).
|
||||
///
|
||||
/// This keyword is commonly used by mail systems to represent color flags on messages.
|
||||
/// A color-flag keyword for messages.
|
||||
public static let colorBit1 = Self(unchecked: "$MailFlagBit1")
|
||||
|
||||
/// The `$MailFlagBit2` keyword for color marking (bit 2).
|
||||
///
|
||||
/// This keyword is commonly used by mail systems to represent color flags on messages.
|
||||
/// A color-flag keyword for messages.
|
||||
public static let colorBit2 = Self(unchecked: "$MailFlagBit2")
|
||||
|
||||
/// The `$MDNSent` keyword, indicating a Message Disposition Notification has been sent for this message.
|
||||
@@ -176,7 +176,7 @@ extension Flag.Keyword {
|
||||
extension Flag: ExpressibleByStringLiteral {
|
||||
/// Creates a flag from a string literal, used for creating static custom keywords.
|
||||
///
|
||||
/// This allows writing flags directly as string literals (e.g., `let flag: Flag = "$Custom"`),
|
||||
/// This allows writing flags directly as string literals (for example, `let flag: Flag = "$Custom"`),
|
||||
/// which is useful for static keyword definitions and testing.
|
||||
///
|
||||
/// - parameter value: The string literal to construct a keyword flag from.
|
||||
|
||||
@@ -106,7 +106,7 @@ public struct StoreGmailLabels: Hashable, Sendable {
|
||||
|
||||
/// Standard IMAP message flags for a `STORE` command.
|
||||
///
|
||||
/// This type specifies a set of flags to add to, remove from, or replace on messages via the `STORE` command.
|
||||
/// Specifies a set of flags to add to, remove from, or replace on messages via the `STORE` command.
|
||||
/// The operation (add/remove/replace) and whether to suppress the server response are configured separately.
|
||||
///
|
||||
/// Flags are described in [RFC 3501 Section 2.3](https://datatracker.ietf.org/doc/html/rfc3501#section-2.3)
|
||||
|
||||
@@ -22,10 +22,10 @@ import struct NIO.ByteBuffer
|
||||
/// 1. **Network Message Path**: Server location and message content reference
|
||||
/// 2. **Authorization Information**: Complete URLAUTH with access, expiration, mechanism, and token
|
||||
///
|
||||
/// This is the endpoint of the GENURL AUTH flow: after GENURLAUTH is issued by the client,
|
||||
/// The endpoint of the GENURL AUTH flow: after GENURLAUTH is issued by the client,
|
||||
/// the server returns one or more ``FullAuthenticatedURL`` structures wrapped in a GENURLAUTH response.
|
||||
///
|
||||
/// ### Complete URL Structure
|
||||
/// ### Complete URL structure
|
||||
///
|
||||
/// A full authenticated URL encompasses:
|
||||
/// ```
|
||||
@@ -66,7 +66,7 @@ import struct NIO.ByteBuffer
|
||||
/// 4. **Client Uses URL**: Submits the complete URL to URLFETCH command
|
||||
/// 5. **Server Validates and Returns Data**: Verifies token and returns message content
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - ``NetworkMessagePath`` provides server and message content specification
|
||||
/// - ``AuthenticatedURL`` provides complete URLAUTH authorization
|
||||
|
||||
@@ -14,7 +14,7 @@
|
||||
|
||||
/// A complete date and time value in RFC 3339 format with an optional fraction-of-second.
|
||||
///
|
||||
/// This type represents a full date-time specification as defined in RFC 3339, combining
|
||||
/// Represents a full date-time specification as defined in RFC 3339, combining
|
||||
/// a ``FullDate`` and ``FullTime`` into a single value. RFC 3339 is used in IMAP extensions
|
||||
/// such as MULTIMAILBOX SEARCH (RFC 7377) and METADATA (RFC 5464) for precise timestamp representation.
|
||||
///
|
||||
@@ -56,11 +56,11 @@ public struct FullDateTime: Hashable, Sendable {
|
||||
|
||||
/// A calendar date in RFC 3339 format (`YYYY-MM-DD`).
|
||||
///
|
||||
/// This type represents a date value as defined in RFC 3339, containing year, month, and day
|
||||
/// Represents a date value as defined in RFC 3339, containing year, month, and day
|
||||
/// components. It is used in combination with ``FullTime`` to form a complete ``FullDateTime``.
|
||||
///
|
||||
/// The initializer uses `precondition` to verify month and day are within valid ranges but does
|
||||
/// not validate whether the day is appropriate for the given month (e.g., February 30 is accepted).
|
||||
/// not validate whether the day is appropriate for the given month (for example, February 30 is accepted).
|
||||
public struct FullDate: Hashable, Sendable {
|
||||
/// The year as any non-negative integer.
|
||||
///
|
||||
@@ -76,12 +76,12 @@ public struct FullDate: Hashable, Sendable {
|
||||
/// The day in the range `1...31`.
|
||||
///
|
||||
/// The range accepts all valid day numbers. No validation is performed to verify
|
||||
/// the day is valid for the specific month (e.g., February 30 is accepted).
|
||||
/// the day is valid for the specific month (for example, February 30 is accepted).
|
||||
public let day: Int
|
||||
|
||||
/// Creates a new `FullDate`.
|
||||
///
|
||||
/// This initializer validates that month is in the range `1...12` and day is in the
|
||||
/// Validates that month is in the range `1...12` and day is in the
|
||||
/// range `1...31` using `precondition`. The year can be any non-negative integer.
|
||||
///
|
||||
/// - Parameters:
|
||||
@@ -99,7 +99,7 @@ public struct FullDate: Hashable, Sendable {
|
||||
|
||||
/// A time of day in RFC 3339 format (`HH:MM:SS[.FRACTION]`).
|
||||
///
|
||||
/// This type represents a time value as defined in RFC 3339, containing hour, minute, second,
|
||||
/// Represents a time value as defined in RFC 3339, containing hour, minute, second,
|
||||
/// and an optional fractional-second component. It is used in combination with ``FullDate``
|
||||
/// to form a complete ``FullDateTime``.
|
||||
///
|
||||
@@ -120,7 +120,7 @@ public struct FullTime: Hashable, Sendable {
|
||||
|
||||
/// The fractional-second component, or `nil` if not included.
|
||||
///
|
||||
/// This is a partially-dynamic field and does not directly represent milliseconds,
|
||||
/// A partially-dynamic field that does not directly represent milliseconds,
|
||||
/// microseconds, or any specific fractional unit. The number you provide is the number
|
||||
/// that will be written directly to the output. For example:
|
||||
/// - `123` encodes as `HH:MM:SS.123`
|
||||
|
||||
@@ -55,7 +55,7 @@ import struct NIO.ByteBuffer
|
||||
/// S: * GENURLAUTH "imap://owner@example.com/INBOX/;uid=20;urlauth=user+fred:internal:..."
|
||||
/// ```
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// See ``UserAuthenticationMechanism`` for the optional user and authentication specification,
|
||||
/// ``IMAPURLAuthenticationMechanism`` for authentication mechanism constraints, and
|
||||
|
||||
@@ -57,7 +57,7 @@
|
||||
/// - **`/`**: Path separator
|
||||
/// - **Command** (``URLCommand``, optional): Mailbox, search, or fetch operation
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - ``IMAPServer`` provides server connection specification
|
||||
/// - ``UserAuthenticationMechanism`` specifies user and auth mechanism
|
||||
|
||||
@@ -52,7 +52,7 @@
|
||||
/// // Represents: imap://user@example.com/;auth=PLAIN
|
||||
/// ```
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - ``UserAuthenticationMechanism`` combines user and mechanism specifications
|
||||
/// - ``IMAPServer`` uses mechanism specifications in server definitions
|
||||
|
||||
@@ -14,7 +14,7 @@
|
||||
|
||||
/// A textual RFC 2822 date as it appears in email message headers.
|
||||
///
|
||||
/// This type represents the date field value from an email message's `Date` header,
|
||||
/// Represents the date field value from an email message's `Date` header,
|
||||
/// formatted according to RFC 2822 section 3.3. Unlike ``ServerMessageDate``, which records
|
||||
/// when the server received the message, this date represents the date the message was
|
||||
/// composed by its sender.
|
||||
@@ -40,7 +40,7 @@ public struct InternetMessageDate: Hashable, Sendable {
|
||||
/// The string is stored as-is without parsing or validation. The caller is responsible
|
||||
/// for ensuring the string represents a valid RFC 2822 date format.
|
||||
///
|
||||
/// - Parameter string: A `String` containing the RFC 2822 date value (e.g., `”Fri, 15 Mar 2026 10:30:45 +0100”`).
|
||||
/// - Parameter string: A `String` containing the RFC 2822 date value (for example, `”Fri, 15 Mar 2026 10:30:45 +0100”`).
|
||||
public init(_ string: String) {
|
||||
self.value = string
|
||||
}
|
||||
@@ -49,7 +49,7 @@ public struct InternetMessageDate: Hashable, Sendable {
|
||||
extension String {
|
||||
/// Creates a new ``Swift/String`` from an ``InternetMessageDate``.
|
||||
///
|
||||
/// This extracts the underlying string value from the ``InternetMessageDate``.
|
||||
/// Extracts the underlying string value from the ``InternetMessageDate``.
|
||||
///
|
||||
/// - Parameter date: The ``InternetMessageDate`` to convert.
|
||||
public init(_ date: InternetMessageDate) {
|
||||
@@ -60,7 +60,7 @@ extension String {
|
||||
extension InternetMessageDate: ExpressibleByStringLiteral {
|
||||
/// Creates a new `InternetMessageDate` from a string literal.
|
||||
///
|
||||
/// This allows you to write RFC 2822 dates as string literals:
|
||||
/// Allows writing RFC 2822 dates as string literals:
|
||||
/// ```swift
|
||||
/// let date: InternetMessageDate = “Fri, 15 Mar 2026 10:30:45 +0100”
|
||||
/// ```
|
||||
|
||||
@@ -14,7 +14,7 @@
|
||||
|
||||
/// A generic key-value pair container.
|
||||
///
|
||||
/// This generic type is used throughout the IMAP protocol implementation to pair related values,
|
||||
/// Used throughout the IMAP protocol implementation to pair related values,
|
||||
/// such as extension names with their parameters, vendor tags with their values, or tagged
|
||||
/// extension data with their content.
|
||||
///
|
||||
|
||||
@@ -47,7 +47,7 @@
|
||||
/// See [RFC 5182](https://datatracker.ietf.org/doc/html/rfc5182) for the full specification
|
||||
/// of the search result reference extension.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - ``LastCommandSet`` allows referencing the last search result as a message set instead of a single identifier.
|
||||
/// - ``MessageIdentifier`` represents a specific message identifier (``UID`` or ``SequenceNumber``).
|
||||
|
||||
@@ -20,7 +20,7 @@
|
||||
///
|
||||
/// **Requires server capability:** ``Capability/searchRes``
|
||||
///
|
||||
/// The `$` marker can be used anywhere a message set is expected (e.g., in `FETCH`, `STORE`,
|
||||
/// The `$` marker can be used anywhere a message set is expected (for example, in `FETCH`, `STORE`,
|
||||
/// `COPY`, `EXPUNGE` commands). It allows clients to pipeline a `SEARCH` command with subsequent
|
||||
/// operations without waiting for results and reformatting them.
|
||||
///
|
||||
@@ -51,7 +51,7 @@
|
||||
/// See [RFC 5182](https://datatracker.ietf.org/doc/html/rfc5182) for the full specification
|
||||
/// of the search result reference extension.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - ``LastCommandMessageID`` allows referencing the last search result as a single identifier instead of a set.
|
||||
/// - ``MessageIdentifierSet`` represents a specific non-empty set of message identifiers.
|
||||
@@ -59,7 +59,7 @@
|
||||
public enum LastCommandSet<N: MessageIdentifier>: Hashable, Sendable {
|
||||
/// A specific non-empty set of message identifiers.
|
||||
///
|
||||
/// This set will be encoded and sent to the IMAP server. Example values: `1`, `5:10`, or `1,3,5:7,9:*`.
|
||||
/// Encoded and sent to the IMAP server. Example values: `1`, `5:10`, or `1,3,5:7,9:*`.
|
||||
case set(MessageIdentifierSetNonEmpty<N>)
|
||||
|
||||
/// References the result of the most recent `SEARCH` command.
|
||||
|
||||
@@ -32,7 +32,7 @@ import struct NIO.ByteBuffer
|
||||
///
|
||||
/// The command `LIST SUBSCRIBED "" "*"` uses the ``subscribed`` base option to return only subscribed mailboxes.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// Combine this with ``ListSelectOption`` values to add additional filtering constraints.
|
||||
/// See ``ListSelectOptions`` for how to construct a complete set of `LIST` selection options.
|
||||
@@ -41,7 +41,7 @@ import struct NIO.ByteBuffer
|
||||
public enum ListSelectBaseOption: Hashable, Sendable {
|
||||
/// The `SUBSCRIBED` base option returns only mailboxes the user has subscribed to.
|
||||
///
|
||||
/// This is the primary filtering mode that controls which mailboxes are included in the response.
|
||||
/// The primary filtering mode that controls which mailboxes are included in the response.
|
||||
/// From [RFC 5258 Section 3.1](https://datatracker.ietf.org/doc/html/rfc5258#section-3.1).
|
||||
case subscribed
|
||||
|
||||
|
||||
@@ -35,7 +35,7 @@ import struct NIO.ByteBuffer
|
||||
/// The command `LIST SUBSCRIBED (REMOTE SPECIAL-USE) "" "*"` uses the independent options
|
||||
/// ``remote`` and ``specialUse`` to return subscribed remote mailboxes marked with special-use attributes.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// These differ from ``ListSelectOption`` which may have syntactic relationships.
|
||||
/// Combine independent options with ``ListSelectBaseOption`` using ``ListSelectOptions``.
|
||||
@@ -44,13 +44,13 @@ import struct NIO.ByteBuffer
|
||||
public enum ListSelectIndependentOption: Hashable, Sendable {
|
||||
/// The `REMOTE` independent option returns information about remote mailbox stores.
|
||||
///
|
||||
/// This asks the server to include mailboxes from remote mailbox stores in addition
|
||||
/// Asks the server to include mailboxes from remote mailbox stores in addition
|
||||
/// to local mailboxes. From [RFC 5258 Section 3.2](https://datatracker.ietf.org/doc/html/rfc5258#section-3.2).
|
||||
case remote
|
||||
|
||||
/// The `SPECIAL-USE` independent option returns only mailboxes with special-use attributes.
|
||||
///
|
||||
/// This filters results to mailboxes marked with attributes like `\All`, `\Archive`, `\Drafts`,
|
||||
/// Filters results to mailboxes marked with attributes like `\All`, `\Archive`, `\Drafts`,
|
||||
/// `\Flagged`, `\Junk`, `\Sent`, or `\Trash` (from [RFC 6154](https://datatracker.ietf.org/doc/html/rfc6154)).
|
||||
case specialUse
|
||||
|
||||
|
||||
@@ -34,7 +34,7 @@ import struct NIO.ByteBuffer
|
||||
/// The command `LIST (SUBSCRIBED) "" "*"` uses the ``subscribed`` selection option to return only subscribed mailboxes.
|
||||
/// The resulting responses wrap mailbox information in ``Response/untagged(_:)`` cases.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// Use ``ListSelectBaseOption`` for options that control the basic filtering mode,
|
||||
/// ``ListSelectIndependentOption`` for options that don't interact syntactically with other options,
|
||||
@@ -44,19 +44,19 @@ import struct NIO.ByteBuffer
|
||||
public enum ListSelectOption: Hashable, Sendable {
|
||||
/// The `SUBSCRIBED` selection option returns only mailboxes that the user has subscribed to.
|
||||
///
|
||||
/// This option filters the mailbox list to show subscription state rather than all mailboxes.
|
||||
/// Filters the mailbox list to show subscription state rather than all mailboxes.
|
||||
/// From [RFC 5258 Section 3.1](https://datatracker.ietf.org/doc/html/rfc5258#section-3.1).
|
||||
case subscribed
|
||||
|
||||
/// The `REMOTE` selection option requests mailbox information from remote mailbox stores.
|
||||
///
|
||||
/// This is used to include both remote and local mailboxes in the response.
|
||||
/// Includes both remote and local mailboxes in the response.
|
||||
/// From [RFC 5258 Section 3.2](https://datatracker.ietf.org/doc/html/rfc5258#section-3.2).
|
||||
case remote
|
||||
|
||||
/// The `SPECIAL-USE` selection option returns only mailboxes with special-use attributes.
|
||||
///
|
||||
/// This filters results to mailboxes marked with attributes like `\All`, `\Archive`, `\Drafts`,
|
||||
/// Filters results to mailboxes marked with attributes like `\All`, `\Archive`, `\Drafts`,
|
||||
/// `\Flagged`, `\Junk`, `\Sent`, or `\Trash` (from [RFC 6154](https://datatracker.ietf.org/doc/html/rfc6154)).
|
||||
case specialUse
|
||||
|
||||
@@ -77,7 +77,7 @@ public enum ListSelectOption: Hashable, Sendable {
|
||||
///
|
||||
/// **Requires server capability:** ``Capability/listExtended``
|
||||
///
|
||||
/// This structure represents the complete set of selection options for a `LIST` command,
|
||||
/// Represents the complete set of selection options for a `LIST` command,
|
||||
/// combining a base mode with additional filtering criteria. The base option determines
|
||||
/// the primary filtering mode, while the selection options provide additional constraints.
|
||||
public struct ListSelectOptions: Hashable, Sendable {
|
||||
@@ -90,14 +90,14 @@ public struct ListSelectOptions: Hashable, Sendable {
|
||||
/// Additional selection criteria to apply.
|
||||
///
|
||||
/// These options further constrain which mailboxes are returned. Multiple options
|
||||
/// can be combined (e.g., both ``ListSelectOption/remote`` and ``ListSelectOption/specialUse``
|
||||
/// can be combined (for example, both ``ListSelectOption/remote`` and ``ListSelectOption/specialUse``
|
||||
/// to get remote special-use mailboxes).
|
||||
public var options: [ListSelectOption]
|
||||
|
||||
/// Creates a new combination of `LIST` selection options.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - baseOption: The base selection mode (e.g., ``ListSelectBaseOption/subscribed``)
|
||||
/// - baseOption: The base selection mode (for example, ``ListSelectBaseOption/subscribed``)
|
||||
/// - options: Additional selection criteria to apply
|
||||
public init(baseOption: ListSelectBaseOption, options: [ListSelectOption]) {
|
||||
self.baseOption = baseOption
|
||||
|
||||
@@ -36,19 +36,19 @@ import struct NIO.ByteBuffer
|
||||
public enum MailboxAttribute: String, CaseIterable, Sendable {
|
||||
/// The `MESSAGES` attribute: the number of messages in the mailbox.
|
||||
///
|
||||
/// This attribute returns the total count of messages in the mailbox.
|
||||
/// Returns the total count of messages in the mailbox.
|
||||
/// See [RFC 3501 Section 7.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.3.2).
|
||||
case messageCount = "MESSAGES"
|
||||
|
||||
/// The `RECENT` attribute: the number of messages with the `\Recent` flag.
|
||||
///
|
||||
/// This attribute returns the count of messages that have been added to the mailbox since
|
||||
/// Returns the count of messages that have been added to the mailbox since
|
||||
/// the last time it was selected. See [RFC 3501 Section 7.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.3.2).
|
||||
case recentCount = "RECENT"
|
||||
|
||||
/// The `UIDNEXT` attribute: the next unique identifier value.
|
||||
///
|
||||
/// This attribute predicts the UID value that will be assigned to the next message appended
|
||||
/// Predicts the UID value that will be assigned to the next message appended
|
||||
/// to the mailbox. See [RFC 3501 Section 7.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.3.2).
|
||||
case uidNext = "UIDNEXT"
|
||||
|
||||
@@ -60,20 +60,20 @@ public enum MailboxAttribute: String, CaseIterable, Sendable {
|
||||
|
||||
/// The `UNSEEN` attribute: the number of messages without the `\Seen` flag.
|
||||
///
|
||||
/// This attribute returns the count of messages in the mailbox that do not have the `\Seen` flag set.
|
||||
/// Returns the count of messages in the mailbox that do not have the `\Seen` flag set.
|
||||
/// See [RFC 3501 Section 7.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.3.2).
|
||||
case unseenCount = "UNSEEN"
|
||||
|
||||
/// The `SIZE` attribute: the total size of the mailbox in octets.
|
||||
///
|
||||
/// This attribute returns the total size of all messages in the mailbox in bytes (octets).
|
||||
/// Returns the total size of all messages in the mailbox in bytes (octets).
|
||||
/// **Requires server capability:** ``Capability/status(_:)`` with ``Capability/StatusKind/size``
|
||||
/// See [RFC 8438](https://datatracker.ietf.org/doc/html/rfc8438).
|
||||
case size = "SIZE"
|
||||
|
||||
/// The `HIGHESTMODSEQ` attribute: the highest modification sequence value.
|
||||
///
|
||||
/// This attribute returns the highest mod-sequence value assigned to any message in the mailbox.
|
||||
/// Returns the highest mod-sequence value assigned to any message in the mailbox.
|
||||
/// The `CONDSTORE` extension uses modification sequences to track message changes.
|
||||
/// **Requires server capability:** ``Capability/condStore``
|
||||
/// See [RFC 7162 Section 3.1](https://datatracker.ietf.org/doc/html/rfc7162#section-3.1).
|
||||
@@ -81,14 +81,14 @@ public enum MailboxAttribute: String, CaseIterable, Sendable {
|
||||
|
||||
/// The `APPENDLIMIT` attribute: the maximum message upload size in octets.
|
||||
///
|
||||
/// This attribute specifies the maximum size (in bytes) of a single message that can be appended to the mailbox.
|
||||
/// Specifies the maximum size (in bytes) of a single message that can be appended to the mailbox.
|
||||
/// **Requires server capability:** ``Capability/mailboxSpecificAppendLimit`` or ``Capability/appendLimit(_:)``
|
||||
/// See [RFC 7889 Section 4](https://datatracker.ietf.org/doc/html/rfc7889#section-4).
|
||||
case appendLimit = "APPENDLIMIT"
|
||||
|
||||
/// The `MAILBOXID` attribute: the server's object identifier for the mailbox.
|
||||
///
|
||||
/// This attribute returns a permanent, server-assigned identifier that uniquely identifies the mailbox.
|
||||
/// Returns a permanent, server-assigned identifier that uniquely identifies the mailbox.
|
||||
/// Unlike `UIDVALIDITY`, this identifier is globally unique and never reused.
|
||||
/// **Requires server capability:** ``Capability/objectID``
|
||||
/// See [RFC 8474 Section 3](https://datatracker.ietf.org/doc/html/rfc8474#section-3).
|
||||
@@ -119,19 +119,19 @@ public enum MailboxAttribute: String, CaseIterable, Sendable {
|
||||
public struct MailboxStatus: Hashable, Sendable {
|
||||
/// The `MESSAGES` attribute: total number of messages in the mailbox.
|
||||
///
|
||||
/// This property is `nil` if the `MESSAGES` attribute was not requested or returned.
|
||||
/// `nil` if the `MESSAGES` attribute was not requested or returned.
|
||||
/// See [RFC 3501 Section 7.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.3.2).
|
||||
public var messageCount: Int?
|
||||
|
||||
/// The `RECENT` attribute: number of messages with the `\Recent` flag.
|
||||
///
|
||||
/// This property is `nil` if the `RECENT` attribute was not requested or returned.
|
||||
/// `nil` if the `RECENT` attribute was not requested or returned.
|
||||
/// See [RFC 3501 Section 7.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.3.2).
|
||||
public var recentCount: Int?
|
||||
|
||||
/// The `UIDNEXT` attribute: the next unique identifier value to be assigned.
|
||||
///
|
||||
/// This property is `nil` if the `UIDNEXT` attribute was not requested or returned.
|
||||
/// `nil` if the `UIDNEXT` attribute was not requested or returned.
|
||||
/// See [RFC 3501 Section 7.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.3.2).
|
||||
public var nextUID: UID?
|
||||
|
||||
@@ -145,20 +145,20 @@ public struct MailboxStatus: Hashable, Sendable {
|
||||
|
||||
/// The `UNSEEN` attribute: number of messages without the `\Seen` flag.
|
||||
///
|
||||
/// This property is `nil` if the `UNSEEN` attribute was not requested or returned.
|
||||
/// `nil` if the `UNSEEN` attribute was not requested or returned.
|
||||
/// See [RFC 3501 Section 7.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.3.2).
|
||||
public var unseenCount: Int?
|
||||
|
||||
/// The `SIZE` attribute: total size of the mailbox in bytes (octets).
|
||||
///
|
||||
/// This property is `nil` if the `SIZE` attribute was not requested or returned.
|
||||
/// `nil` if the `SIZE` attribute was not requested or returned.
|
||||
/// **Requires server capability:** ``Capability/status(_:)`` with ``Capability/StatusKind/size``
|
||||
/// See [RFC 8438](https://datatracker.ietf.org/doc/html/rfc8438).
|
||||
public var size: Int?
|
||||
|
||||
/// The `HIGHESTMODSEQ` attribute: the highest modification sequence value assigned to any message.
|
||||
///
|
||||
/// This property is `nil` if the `HIGHESTMODSEQ` attribute was not requested or returned.
|
||||
/// `nil` if the `HIGHESTMODSEQ` attribute was not requested or returned.
|
||||
/// The `CONDSTORE` extension uses modification sequences to track which messages have changed.
|
||||
/// **Requires server capability:** ``Capability/condStore``
|
||||
/// See [RFC 7162 Section 3.1](https://datatracker.ietf.org/doc/html/rfc7162#section-3.1).
|
||||
@@ -166,7 +166,7 @@ public struct MailboxStatus: Hashable, Sendable {
|
||||
|
||||
/// The `APPENDLIMIT` attribute: maximum size per message in bytes (octets).
|
||||
///
|
||||
/// This property is `nil` if the `APPENDLIMIT` attribute was not requested or returned.
|
||||
/// `nil` if the `APPENDLIMIT` attribute was not requested or returned.
|
||||
/// The `APPENDLIMIT` extension specifies per-mailbox upload limits.
|
||||
/// **Requires server capability:** ``Capability/mailboxSpecificAppendLimit`` or ``Capability/appendLimit(_:)``
|
||||
/// See [RFC 7889 Section 4](https://datatracker.ietf.org/doc/html/rfc7889#section-4).
|
||||
@@ -174,7 +174,7 @@ public struct MailboxStatus: Hashable, Sendable {
|
||||
|
||||
/// The `MAILBOXID` attribute: the server's permanent object identifier for the mailbox.
|
||||
///
|
||||
/// This property is `nil` if the `MAILBOXID` attribute was not requested or returned.
|
||||
/// `nil` if the `MAILBOXID` attribute was not requested or returned.
|
||||
/// The `OBJECTID` extension assigns stable, unique identifiers to mailboxes that persist
|
||||
/// even if the mailbox is renamed or moved.
|
||||
/// **Requires server capability:** ``Capability/objectID``
|
||||
|
||||
@@ -17,7 +17,7 @@ import struct NIO.ByteBuffer
|
||||
/// Untagged response data from the server about mailboxes, messages, or search results.
|
||||
///
|
||||
/// Servers send untagged responses (prefixed with `*`) that convey information about mailboxes, messages, and operation results.
|
||||
/// This enum represents the various types of mailbox-related untagged data that a server can send.
|
||||
/// Represents the various types of mailbox-related untagged data that a server can send.
|
||||
///
|
||||
/// These responses are typically encountered as the data within ``Response`` untagged responses, which may
|
||||
/// be wrapped in ``ResponsePayload/mailboxData(_:)``.
|
||||
|
||||
@@ -43,18 +43,18 @@ import struct NIO.ByteBuffer
|
||||
public struct EmailAddressGroup: Hashable, Sendable {
|
||||
/// The name of the address group.
|
||||
///
|
||||
/// This is the human-readable name for the collection of addresses, such as "Family" or "Work Team".
|
||||
/// The human-readable name for the collection of addresses, such as "Family" or "Work Team".
|
||||
public var groupName: ByteBuffer
|
||||
|
||||
/// The optional source root for the address group.
|
||||
///
|
||||
/// This field may contain additional routing information for the group.
|
||||
/// May contain additional routing information for the group.
|
||||
/// Per [RFC 5322](https://datatracker.ietf.org/doc/html/rfc5322), this is typically `nil`.
|
||||
public var sourceRoot: ByteBuffer?
|
||||
|
||||
/// The nested addresses and groups within this group.
|
||||
///
|
||||
/// This list can contain both individual addresses (``EmailAddressListElement/singleAddress(_:)``)
|
||||
/// Can contain both individual addresses (``EmailAddressListElement/singleAddress(_:)``)
|
||||
/// and nested address groups (``EmailAddressListElement/group(_:)``), allowing for arbitrarily
|
||||
/// deep hierarchies.
|
||||
public var children: [EmailAddressListElement]
|
||||
@@ -78,7 +78,7 @@ public struct EmailAddressGroup: Hashable, Sendable {
|
||||
/// the ENVELOPE structure includes address lists (such as `To:`, `From:`, `Cc:`) that may contain
|
||||
/// both individual email addresses and named address groups.
|
||||
///
|
||||
/// This is an indirect enum, allowing arbitrarily deep nesting of groups within groups.
|
||||
/// An indirect enum, allowing arbitrarily deep nesting of groups within groups.
|
||||
///
|
||||
/// ### Example
|
||||
///
|
||||
@@ -101,12 +101,12 @@ public struct EmailAddressGroup: Hashable, Sendable {
|
||||
public indirect enum EmailAddressListElement: Hashable, Sendable {
|
||||
/// A single email address with no children.
|
||||
///
|
||||
/// This case wraps a single ``EmailAddress`` in the address list.
|
||||
/// Wraps a single ``EmailAddress`` in the address list.
|
||||
case singleAddress(EmailAddress)
|
||||
|
||||
/// A collection of addresses organized under a group name.
|
||||
///
|
||||
/// This case wraps an ``EmailAddressGroup`` containing a group name and nested
|
||||
/// Wraps an ``EmailAddressGroup`` containing a group name and nested
|
||||
/// ``EmailAddressListElement`` children (which can themselves be addresses or groups).
|
||||
case group(EmailAddressGroup)
|
||||
}
|
||||
|
||||
@@ -92,7 +92,7 @@ extension MailboxInfo {
|
||||
public struct Attribute: Hashable, Sendable {
|
||||
/// The mailbox cannot be selected with a `SELECT` command.
|
||||
///
|
||||
/// This attribute indicates that the mailbox exists but is not selectable.
|
||||
/// Indicates that the mailbox exists but is not selectable.
|
||||
/// A common example is a mailbox used only to contain child mailboxes.
|
||||
/// See [RFC 3501 Section 7.2.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.2.2).
|
||||
public static var noSelect: Self { Self(#"\Noselect"#) }
|
||||
@@ -157,7 +157,7 @@ extension MailboxInfo {
|
||||
/// or create custom attributes for extension or server-specific attributes.
|
||||
/// Attribute names are case-insensitive per the IMAP specification.
|
||||
///
|
||||
/// - Parameter str: The attribute name, typically starting with backslash (e.g., "\\Noselect")
|
||||
/// - Parameter str: The attribute name, typically starting with backslash (for example, "\\Noselect")
|
||||
public init(_ str: String) {
|
||||
self.backing = str
|
||||
}
|
||||
|
||||
@@ -29,7 +29,7 @@ public struct MailboxTooBigError: Error, Equatable {
|
||||
|
||||
/// A mailbox name contained invalid characters or violated naming constraints.
|
||||
///
|
||||
/// This error is raised when a mailbox name contains characters that are not permitted by the IMAP protocol,
|
||||
/// Raised when a mailbox name contains characters that are not permitted by the IMAP protocol,
|
||||
/// such as path separators in the display name.
|
||||
public struct InvalidMailboxNameError: Error, Equatable {
|
||||
/// A description of why the mailbox name was considered invalid.
|
||||
@@ -73,7 +73,7 @@ public struct InvalidPathSeparatorError: Error, Equatable {
|
||||
public struct MailboxPath: Hashable, Sendable {
|
||||
/// The full mailbox path in Modified UTF-7 encoding.
|
||||
///
|
||||
/// This name may contain path separator characters and represents the complete hierarchical path
|
||||
/// May contain path separator characters and represents the complete hierarchical path
|
||||
/// to the mailbox as known to the server. The encoding follows
|
||||
/// [RFC 2152](https://datatracker.ietf.org/doc/html/rfc2152) as required by RFC 3501.
|
||||
public let name: MailboxName
|
||||
@@ -99,7 +99,7 @@ public struct MailboxPath: Hashable, Sendable {
|
||||
|
||||
/// Creates a new `MailboxPath` with the given name and optional path separator.
|
||||
///
|
||||
/// This initializer accepts raw bytes and does not perform encoding. Use ``makeRootMailbox(displayName:pathSeparator:)``
|
||||
/// Accepts raw bytes and does not perform encoding. Use ``makeRootMailbox(displayName:pathSeparator:)``
|
||||
/// to create a new mailbox from a display string with automatic encoding, or ``makeSubMailbox(displayName:)``
|
||||
/// to create a hierarchical mailbox path.
|
||||
///
|
||||
@@ -146,7 +146,7 @@ extension MailboxPath {
|
||||
|
||||
/// Splits the mailbox path into human-readable display components using the path separator.
|
||||
///
|
||||
/// This method converts the Modified UTF-7-encoded mailbox name to a display string by splitting on
|
||||
/// Converts the Modified UTF-7-encoded mailbox name to a display string by splitting on
|
||||
/// the path separator. The conversion is lossy and intended for display purposes only. Do not use the
|
||||
/// returned components as mailbox names for protocol operations.
|
||||
///
|
||||
@@ -172,7 +172,7 @@ extension MailboxPath {
|
||||
|
||||
/// Creates a new root mailbox path from a display name.
|
||||
///
|
||||
/// This factory method encodes the display name using Modified UTF-7 (RFC 2152) and validates
|
||||
/// Encodes the display name using Modified UTF-7 (RFC 2152) and validates
|
||||
/// that the resulting mailbox name does not contain the path separator character (if provided).
|
||||
/// Root mailboxes are top-level mailboxes with no parent hierarchy.
|
||||
///
|
||||
@@ -202,7 +202,7 @@ extension MailboxPath {
|
||||
|
||||
/// Creates a nested child mailbox path within this mailbox.
|
||||
///
|
||||
/// This method encodes the display name using Modified UTF-7 and appends it as a child to the current
|
||||
/// Encodes the display name using Modified UTF-7 and appends it as a child to the current
|
||||
/// mailbox path. The path separator is inserted between the parent and child names.
|
||||
///
|
||||
/// **Important:** This method should only be used when creating new mailboxes that do not yet exist
|
||||
|
||||
@@ -26,7 +26,7 @@ import struct NIO.ByteBuffer
|
||||
/// - `*` - matches any sequence of zero or more characters, including the hierarchy delimiter
|
||||
///
|
||||
/// To list **all mailboxes** on the server, use the pattern `*` (the wildcard that matches everything).
|
||||
/// This is the most common LIST usage and returns the complete mailbox hierarchy.
|
||||
/// Using `*` is the most common LIST usage and returns the complete mailbox hierarchy.
|
||||
///
|
||||
/// ### Example
|
||||
///
|
||||
@@ -41,7 +41,7 @@ import struct NIO.ByteBuffer
|
||||
/// LIST request, and the server returns matching mailboxes wrapped as ``Response/untagged(_:)``
|
||||
/// containing ``ResponsePayload/mailboxData(_:)`` entries for each match.
|
||||
///
|
||||
/// ### Listing All Mailboxes
|
||||
/// ### Listing all mailboxes
|
||||
///
|
||||
/// ```
|
||||
/// C: A001 LIST "" "*"
|
||||
|
||||
@@ -16,10 +16,10 @@
|
||||
///
|
||||
/// In IMAP URLs, a mailbox is identified by its percent-encoded name and an optional UID validity value.
|
||||
/// The UID validity (``UIDValidity``) is a server-assigned value that helps detect when messages in a
|
||||
/// mailbox have been invalidated (e.g., after a mailbox has been deleted and recreated).
|
||||
/// mailbox have been invalidated (for example, after a mailbox has been deleted and recreated).
|
||||
/// Including the UID validity in a URL helps ensure the URL is not referencing stale or invalid message UIDs.
|
||||
///
|
||||
/// This type combines a ``EncodedMailbox`` and optional ``UIDValidity`` to create a complete mailbox
|
||||
/// Combines a ``EncodedMailbox`` and optional ``UIDValidity`` to create a complete mailbox
|
||||
/// reference for use in ``MessagePath`` structures. It forms the core of IMAP URL mailbox addressing.
|
||||
///
|
||||
/// ### Examples
|
||||
@@ -40,7 +40,7 @@
|
||||
/// S: * GENURLAUTH "imap://user@example.com/INBOX/;uidvalidity=4294967295/;uid=20;urlauth=anonymous:internal:..."
|
||||
/// ```
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// See ``MessagePath`` for the complete message location (mailbox reference, UID, optional section, optional byte range),
|
||||
/// ``UIDValidity`` for UID validity value details, and ``NetworkMessagePath`` for the full network-accessible URL.
|
||||
|
||||
@@ -16,7 +16,7 @@ import struct NIO.ByteBuffer
|
||||
|
||||
/// An authorization mechanism paired with base64-encoded authentication data.
|
||||
///
|
||||
/// This type is used in URLAUTH contexts (RFC 4467) to specify both the mechanism used to
|
||||
/// Used in URLAUTH contexts (RFC 4467) to specify both the mechanism used to
|
||||
/// generate authorization credentials and the base64-encoded credentials themselves.
|
||||
///
|
||||
/// - SeeAlso: [RFC 4467 IMAP4 Capabilities for SMTP and SUBMIT](https://datatracker.ietf.org/doc/html/rfc4467)
|
||||
|
||||
@@ -14,15 +14,15 @@
|
||||
|
||||
/// Namespace grouping MIME media type related types.
|
||||
///
|
||||
/// This namespace organizes MIME media type components as defined in [RFC 2045](https://datatracker.ietf.org/doc/html/rfc2045).
|
||||
/// Organizes MIME media type components as defined in [RFC 2045](https://datatracker.ietf.org/doc/html/rfc2045).
|
||||
public enum Media {}
|
||||
|
||||
extension Media {
|
||||
/// A MIME media type consisting of a top-level type and subtype.
|
||||
///
|
||||
/// MIME media types (also called MIME types or content types) identify the format of message part content.
|
||||
/// Each media type is composed of a top-level type (e.g., `text`, `image`, `application`) and a subtype
|
||||
/// (e.g., `plain`, `html`, `jpeg`), separated by a slash in standard notation (e.g., `text/plain`).
|
||||
/// Each media type is composed of a top-level type (for example, `text`, `image`, or `application`) and a subtype
|
||||
/// (for example, `plain`, `html`, or `jpeg`), separated by a slash in standard notation (for example, `text/plain`).
|
||||
///
|
||||
/// Media types are defined in [RFC 2045 Section 5](https://datatracker.ietf.org/doc/html/rfc2045#section-5) and
|
||||
/// are included in message body structures retrieved via the `BODYSTRUCTURE` FETCH attribute.
|
||||
@@ -41,10 +41,10 @@ extension Media {
|
||||
/// - SeeAlso: ``TopLevelType``
|
||||
/// - SeeAlso: ``Subtype``
|
||||
public struct MediaType: Hashable, Sendable {
|
||||
/// The top-level type component (e.g., `text`, `image`, `application`).
|
||||
/// The top-level type component (for example, `text`, `image`, or `application`).
|
||||
public var topLevel: TopLevelType
|
||||
|
||||
/// The subtype component (e.g., `plain`, `html`, `jpeg`).
|
||||
/// The subtype component (for example, `plain`, `html`, or `jpeg`).
|
||||
public var sub: Subtype
|
||||
|
||||
/// Creates a media type from top-level type and subtype components.
|
||||
@@ -61,11 +61,11 @@ extension Media {
|
||||
extension Media.MediaType {
|
||||
/// Creates a media type from string components.
|
||||
///
|
||||
/// This is a convenience initializer that creates ``TopLevelType`` and ``Subtype`` instances
|
||||
/// A convenience initializer that creates ``TopLevelType`` and ``Subtype`` instances
|
||||
/// from the provided strings, which are automatically lowercased.
|
||||
///
|
||||
/// - parameter topLevel: The top-level type as a string (e.g., `"text"`, `"image"`).
|
||||
/// - parameter sub: The subtype as a string (e.g., `"plain"`, `"html"`).
|
||||
/// - parameter topLevel: The top-level type as a string (for example, `"text"` or `"image"`).
|
||||
/// - parameter sub: The subtype as a string (for example, `"plain"` or `"html"`).
|
||||
public init(topLevel: String, sub: String) {
|
||||
self.topLevel = Media.TopLevelType(topLevel)
|
||||
self.sub = Media.Subtype(sub)
|
||||
@@ -77,7 +77,7 @@ extension Media.MediaType {
|
||||
extension Media {
|
||||
/// The top-level type component of a MIME media type.
|
||||
///
|
||||
/// The top-level type is the first component of a media type (e.g., `text` in `text/plain`).
|
||||
/// The top-level type is the first component of a media type (for example, `text` in `text/plain`).
|
||||
/// Standard top-level types are registered with IANA and are case-insensitive, normalized to lowercase.
|
||||
///
|
||||
/// Defined in [RFC 2045 Section 5](https://datatracker.ietf.org/doc/html/rfc2045#section-5) with types
|
||||
@@ -130,7 +130,7 @@ extension Media {
|
||||
|
||||
/// The top-level type as a lowercase string.
|
||||
///
|
||||
/// - Returns: The type name in lowercase (e.g., `"text"`, `"image"`, `"multipart"`).
|
||||
/// - Returns: The type name in lowercase (for example, `"text"`, `"image"`, or `"multipart"`).
|
||||
public var debugDescription: String {
|
||||
self.stringValue
|
||||
}
|
||||
@@ -140,7 +140,7 @@ extension Media {
|
||||
/// The provided string is automatically lowercased to normalize the type value. This allows
|
||||
/// case-insensitive comparison between type values.
|
||||
///
|
||||
/// - parameter stringValue: The type name as a string (e.g., `"TEXT"`, `"Image"`, `"text"`). Will be lowercased.
|
||||
/// - parameter stringValue: The type name as a string (for example, `"TEXT"`, `"Image"`, or `"text"`). Will be lowercased.
|
||||
public init(_ stringValue: String) {
|
||||
self.stringValue = stringValue.lowercased()
|
||||
}
|
||||
@@ -150,10 +150,10 @@ extension Media {
|
||||
extension Media.TopLevelType: ExpressibleByStringLiteral {
|
||||
/// Creates a top-level type from a string literal.
|
||||
///
|
||||
/// This allows direct initialization like `let topLevel: Media.TopLevelType = "text"`.
|
||||
/// Allows direct initialization like `let topLevel: Media.TopLevelType = "text"`.
|
||||
/// The string literal is automatically lowercased.
|
||||
///
|
||||
/// - parameter stringLiteral: The type name as a string literal (e.g., `"text"`, `"image"`).
|
||||
/// - parameter stringLiteral: The type name as a string literal (for example, `"text"` or `"image"`).
|
||||
public init(stringLiteral: String) {
|
||||
self.init(stringLiteral)
|
||||
}
|
||||
@@ -173,7 +173,7 @@ extension String {
|
||||
extension Media {
|
||||
/// The subtype component of a MIME media type.
|
||||
///
|
||||
/// The subtype is the second component of a media type (e.g., `plain` in `text/plain`).
|
||||
/// The subtype is the second component of a media type (for example, `plain` in `text/plain`).
|
||||
/// Subtypes are case-insensitive, normalized to lowercase, and are specific to their top-level type.
|
||||
///
|
||||
/// Defined in [RFC 2045](https://datatracker.ietf.org/doc/html/rfc2045) with subtypes registered at
|
||||
@@ -186,20 +186,20 @@ extension Media {
|
||||
/// Clients should display the most appropriate alternative according to user preferences.
|
||||
public static let alternative = Self("alternative")
|
||||
|
||||
/// The `multipart/related` subtype, specifying related body parts (e.g., HTML with embedded images).
|
||||
/// The `multipart/related` subtype, specifying related body parts (for example, HTML with embedded images).
|
||||
///
|
||||
/// Parts in a multipart/related message are typically related to one another (e.g., an HTML
|
||||
/// Parts in a multipart/related message are typically related to one another (for example, an HTML
|
||||
/// document with embedded images or stylesheets).
|
||||
public static let related = Self("related")
|
||||
|
||||
/// The `multipart/mixed` subtype, specifying a generic set of mixed data types.
|
||||
///
|
||||
/// This is the default multipart subtype for messages with multiple unrelated parts.
|
||||
/// The default multipart subtype for messages with multiple unrelated parts.
|
||||
public static let mixed = Self("mixed")
|
||||
|
||||
/// The `message/rfc822` subtype for encapsulated email messages.
|
||||
///
|
||||
/// This subtype indicates the message part contains a complete RFC 822 (email) message,
|
||||
/// Indicates the message part contains a complete RFC 822 (email) message,
|
||||
/// which may have its own headers, body structure, and attachments.
|
||||
public static let rfc822 = Self("rfc822")
|
||||
|
||||
@@ -208,7 +208,7 @@ extension Media {
|
||||
|
||||
/// The subtype as a lowercase string.
|
||||
///
|
||||
/// - Returns: The subtype name in lowercase (e.g., `"plain"`, `"html"`, `"mixed"`).
|
||||
/// - Returns: The subtype name in lowercase (for example, `"plain"`, `"html"`, or `"mixed"`).
|
||||
public var debugDescription: String { self.stringValue }
|
||||
|
||||
/// Creates a subtype from a string.
|
||||
@@ -216,7 +216,7 @@ extension Media {
|
||||
/// The provided string is automatically lowercased to normalize the subtype value. This allows
|
||||
/// case-insensitive comparison between subtype values.
|
||||
///
|
||||
/// - parameter stringValue: The subtype name as a string (e.g., `"PLAIN"`, `"Html"`, `"plain"`). Will be lowercased.
|
||||
/// - parameter stringValue: The subtype name as a string (for example, `"PLAIN"`, `"Html"`, or `"plain"`). Will be lowercased.
|
||||
public init(_ stringValue: String) {
|
||||
self.stringValue = stringValue.lowercased()
|
||||
}
|
||||
@@ -226,10 +226,10 @@ extension Media {
|
||||
extension Media.Subtype: ExpressibleByStringLiteral {
|
||||
/// Creates a subtype from a string literal.
|
||||
///
|
||||
/// This allows direct initialization like `let subtype: Media.Subtype = "plain"`.
|
||||
/// Allows direct initialization like `let subtype: Media.Subtype = "plain"`.
|
||||
/// The string literal is automatically lowercased.
|
||||
///
|
||||
/// - parameter stringLiteral: The subtype name as a string literal (e.g., `"plain"`, `"html"`).
|
||||
/// - parameter stringLiteral: The subtype name as a string literal (for example, `"plain"` or `"html"`).
|
||||
public init(stringLiteral: String) {
|
||||
self.init(stringLiteral)
|
||||
}
|
||||
|
||||
@@ -37,7 +37,7 @@
|
||||
/// for this message. If copied to another mailbox, the copied message will receive the same
|
||||
/// `EMAILID`, allowing clients to recognize the messages as identical content.
|
||||
///
|
||||
/// ## Related Proprietary Identifiers
|
||||
/// ## Related proprietary identifiers
|
||||
///
|
||||
/// Gmail servers provide a similar but proprietary identifier via the `X-GM-MSGID` field (see
|
||||
/// ``FetchAttribute/gmailMessageID``). While both serve similar purposes, `EMAILID` is
|
||||
|
||||
@@ -19,7 +19,7 @@ import struct NIO.ByteBuffer
|
||||
/// in the X-GM-LABELS attribute of a FETCH response. Labels are stored as byte buffers and may be
|
||||
/// encoded in modified UTF-7 format (the same encoding used for mailbox names).
|
||||
///
|
||||
/// This is a Gmail-specific extension not part of the standard IMAP protocol. It is available when
|
||||
/// A Gmail-specific extension not part of the standard IMAP protocol. It is available when
|
||||
/// the server advertises the X-GM-EXT-1 capability.
|
||||
///
|
||||
/// ### Example
|
||||
@@ -29,7 +29,7 @@ import struct NIO.ByteBuffer
|
||||
/// S: * 1 FETCH (X-GM-LABELS ("Important" "Work"))
|
||||
/// ```
|
||||
///
|
||||
/// This response indicates message 1 has two labels: "Important" and "Work".
|
||||
/// The response indicates message 1 has two labels: "Important" and "Work".
|
||||
///
|
||||
/// - SeeAlso: [Gmail IMAP Extensions](https://developers.google.com/gmail/imap/imap-extensions)
|
||||
/// - SeeAlso: ``MessageAttribute/gmailLabels(_:)``
|
||||
|
||||
@@ -30,13 +30,13 @@ import struct NIO.ByteBuffer
|
||||
/// The response line contains three attributes: ``flags(_:)`` wrapping `\Seen`, ``envelope(_:)`` containing the message envelope,
|
||||
/// and ``uid(_:)`` with UID `123`.
|
||||
///
|
||||
/// ## Request vs Response
|
||||
/// ## Request versus response
|
||||
///
|
||||
/// Use ``FetchAttribute`` to request specific message attributes in a `FETCH` command. The server responds with ``MessageAttribute``
|
||||
/// values containing the requested data. Not all ``FetchAttribute`` cases have corresponding ``MessageAttribute`` cases — for example,
|
||||
/// ``FetchAttribute/bodyStructure(extensions:)`` (a request) produces ``body(_:hasExtensionData:)`` (response).
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - ``FetchAttribute`` — Request side (what the client asks for)
|
||||
/// - ``FetchModifier`` — Modifiers for `FETCH` commands (RFC 7162)
|
||||
@@ -56,7 +56,7 @@ public enum MessageAttribute: Hashable, Sendable {
|
||||
/// S: * 1 FETCH (FLAGS (\Seen \Flagged))
|
||||
/// ```
|
||||
///
|
||||
/// This response contains the ``flags(_:)`` case with two system flags.
|
||||
/// The response contains the ``flags(_:)`` case with two system flags.
|
||||
///
|
||||
/// - SeeAlso: [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2)
|
||||
case flags([Flag])
|
||||
@@ -149,7 +149,7 @@ public enum MessageAttribute: Hashable, Sendable {
|
||||
/// S: * 1 FETCH (BINARY.SIZE[2] 5000)
|
||||
/// ```
|
||||
///
|
||||
/// This indicates body part 2 has 5000 octets when decoded.
|
||||
/// Indicates body part 2 has 5000 octets when decoded.
|
||||
///
|
||||
/// - SeeAlso: [RFC 3516 IMAP4 Binary Content Extension](https://datatracker.ietf.org/doc/html/rfc3516)
|
||||
case binarySize(section: SectionSpecifier.Part, size: Int)
|
||||
@@ -166,7 +166,7 @@ public enum MessageAttribute: Hashable, Sendable {
|
||||
/// S: * 1 FETCH (BODY[4.TEXT] NIL)
|
||||
/// ```
|
||||
///
|
||||
/// This indicates that body part 4 has no TEXT section (it doesn’t exist).
|
||||
/// Indicates that body part 4 has no TEXT section (it doesn’t exist).
|
||||
///
|
||||
/// - SeeAlso: [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2)
|
||||
case nilBody(StreamingKind)
|
||||
@@ -174,7 +174,7 @@ public enum MessageAttribute: Hashable, Sendable {
|
||||
/// The modification sequence number for the message.
|
||||
///
|
||||
/// The `MODSEQ` attribute contains a modification sequence number indicating when the message or its flags last changed.
|
||||
/// This is used with the `CONDSTORE` extension for efficient synchronization.
|
||||
/// Used with the `CONDSTORE` extension for efficient synchronization.
|
||||
///
|
||||
/// - SeeAlso: [RFC 7162 IMAP4 Extensions: CONDSTORE and QRESYNC](https://datatracker.ietf.org/doc/html/rfc7162)
|
||||
case fetchModificationSequence(ModificationSequenceValue)
|
||||
@@ -182,7 +182,7 @@ public enum MessageAttribute: Hashable, Sendable {
|
||||
/// Gmail-specific message unique identifier (vendor extension).
|
||||
///
|
||||
/// The `X-GM-MSGID` attribute contains a Gmail-specific unique message ID that remains stable across mailboxes.
|
||||
/// This is a 64-bit unsigned integer. This is a Gmail-only extension, not part of the standard IMAP protocol.
|
||||
/// A 64-bit unsigned integer and Gmail-only extension, not part of the standard IMAP protocol.
|
||||
///
|
||||
/// For standard IMAP object identifiers, see ``emailID(_:)`` which uses RFC 8474.
|
||||
///
|
||||
@@ -192,7 +192,7 @@ public enum MessageAttribute: Hashable, Sendable {
|
||||
/// Gmail-specific thread identifier (vendor extension).
|
||||
///
|
||||
/// The `X-GM-THRID` attribute contains a Gmail-specific thread ID that associates messages belonging to the same thread.
|
||||
/// This is a 64-bit unsigned integer. This is a Gmail-only extension, not part of the standard IMAP protocol.
|
||||
/// A 64-bit unsigned integer and Gmail-only extension, not part of the standard IMAP protocol.
|
||||
///
|
||||
/// For standard IMAP object identifiers, see ``threadID(_:)`` which uses RFC 8474.
|
||||
///
|
||||
@@ -202,7 +202,7 @@ public enum MessageAttribute: Hashable, Sendable {
|
||||
/// Gmail-specific message labels (vendor extension).
|
||||
///
|
||||
/// The `X-GM-LABELS` attribute contains a list of labels (tags) applied to the message in Gmail. Each label is a ``GmailLabel``.
|
||||
/// This is a Gmail-only extension, not part of the standard IMAP protocol.
|
||||
/// A Gmail-only extension, not part of the standard IMAP protocol.
|
||||
///
|
||||
/// - SeeAlso: [Gmail IMAP Extensions](https://developers.google.com/gmail/imap/imap-extensions)
|
||||
case gmailLabels([GmailLabel])
|
||||
@@ -219,7 +219,7 @@ public enum MessageAttribute: Hashable, Sendable {
|
||||
/// An object identifier for the message content.
|
||||
///
|
||||
/// The `EMAILID` attribute contains an object identifier that uniquely identifies the message’s content.
|
||||
/// This is stable across servers and can be used to detect when a message with the same content exists
|
||||
/// Stable across servers and can be used to detect when a message with the same content exists
|
||||
/// in different mailboxes or on different servers.
|
||||
///
|
||||
/// For Gmail-specific message identifiers, see ``gmailMessageID(_:)`` which uses the `X-GM-MSGID` extension.
|
||||
@@ -230,7 +230,7 @@ public enum MessageAttribute: Hashable, Sendable {
|
||||
/// An object identifier for the message thread.
|
||||
///
|
||||
/// The `THREADID` attribute contains an object identifier for the thread the message belongs to.
|
||||
/// This is `nil` if the message is not part of a thread or if the server does not support threading.
|
||||
/// `nil` if the message is not part of a thread or if the server does not support threading.
|
||||
///
|
||||
/// For Gmail-specific thread identifiers, see ``gmailThreadID(_:)`` which uses the `X-GM-THRID` extension.
|
||||
///
|
||||
|
||||
@@ -40,7 +40,7 @@ public enum MessageData: Hashable, Sendable {
|
||||
///
|
||||
/// The EXPUNGE response indicates that the message at the specified sequence number
|
||||
/// no longer exists. Clients must renumber remaining messages accordingly.
|
||||
/// This response is not sent for UID-based commands.
|
||||
/// Not sent for UID-based commands.
|
||||
///
|
||||
/// - SeeAlso: [RFC 3501 Section 7.4.1 EXPUNGE](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.1)
|
||||
case expunge(SequenceNumber)
|
||||
|
||||
@@ -42,7 +42,7 @@
|
||||
/// Messages 1 and 2 have the same `THREADID (abc123def456)`, indicating they are related.
|
||||
/// Message 3 has a different `THREADID (xyz789abc123)`, indicating it belongs to a different thread.
|
||||
///
|
||||
/// ## Related Proprietary Identifiers
|
||||
/// ## Related proprietary identifiers
|
||||
///
|
||||
/// Gmail servers provide a similar but proprietary identifier via the `X-GM-THRID` field (see
|
||||
/// ``FetchAttribute/gmailThreadID``). While both serve similar purposes, `THREADID` is
|
||||
|
||||
@@ -18,7 +18,7 @@
|
||||
/// formatted as angle-bracketed text, for example <B27397-0100000@cac.washington.edu>. The Message-ID
|
||||
/// appears in the In-Reply-To header and is used to correlate related messages in threads.
|
||||
///
|
||||
/// This type wraps the raw string value including angle brackets as sent by the server.
|
||||
/// Wraps the raw string value including angle brackets as sent by the server.
|
||||
///
|
||||
/// ### Example
|
||||
///
|
||||
|
||||
@@ -23,7 +23,7 @@
|
||||
/// - **URLAUTH URLs**: `imap://server/mailbox/;uidvalidity=V/;uid=N;urlauth=...`
|
||||
/// - **CATENATE operations**: Reference existing messages when composing new messages (RFC 4469)
|
||||
///
|
||||
/// ### Message Path Components
|
||||
/// ### Message path components
|
||||
///
|
||||
/// 1. **Mailbox Reference** (``MailboxUIDValidity``): Identifies the mailbox with optional UID validity
|
||||
/// 2. **Message UID** (``IUID``): The message unique identifier
|
||||
@@ -53,7 +53,7 @@
|
||||
/// S: * GENURLAUTH "imap://user@example.com/INBOX/;uidvalidity=4294967295/;uid=20;urlauth=anonymous:internal:..."
|
||||
/// ```
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - ``MailboxUIDValidity`` provides the mailbox reference
|
||||
/// - ``IUID`` wraps the message unique identifier
|
||||
@@ -74,7 +74,7 @@ public struct MessagePath: Hashable, Sendable {
|
||||
/// The unique identifier of the message within the mailbox.
|
||||
public var iUID: IUID
|
||||
|
||||
/// Optional section of the message (e.g., "1", "2.MIME", "TEXT").
|
||||
/// Optional section of the message (for example, "1", "2.MIME", or "TEXT").
|
||||
///
|
||||
/// When `nil`, refers to the entire message. When specified, refers to a specific
|
||||
/// part or substructure of the message.
|
||||
|
||||
@@ -35,7 +35,7 @@ import NIO
|
||||
/// in the ``MetadataResponse/values(values:mailbox:)`` response. They appear in ``Response/untagged(_:)``
|
||||
/// containing ``ResponsePayload/metadata(_:)``.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - See ``MetadataValue`` for metadata entry values
|
||||
/// - See ``MetadataResponse`` for complete metadata responses
|
||||
@@ -54,7 +54,7 @@ public struct MetadataEntryName: Hashable, Sendable {
|
||||
|
||||
/// Creates a `MetadataEntryName` from a `String`.
|
||||
///
|
||||
/// - parameter string: The entry name as a string (e.g., `"/shared/comment"`, `"/private/notes"`).
|
||||
/// - parameter string: The entry name as a string (for example, `"/shared/comment"` or `"/private/notes"`).
|
||||
public init(_ string: String) {
|
||||
self.backing = ByteBuffer(string: string)
|
||||
}
|
||||
|
||||
@@ -31,7 +31,7 @@
|
||||
/// The options `(MAXSIZE 1024 DEPTH 1)` are ``MetadataOption`` values that limit results to entries
|
||||
/// with a maximum size of 1024 bytes and restrict the search to a depth of 1 level.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - See ``MetadataEntryName`` for metadata entry names
|
||||
/// - See ``MetadataValue`` for metadata entry values
|
||||
|
||||
@@ -35,7 +35,7 @@ import struct OrderedCollections.OrderedDictionary
|
||||
/// ``ResponsePayload/metadata(_:)`` with a ``MetadataResponse/values(values:mailbox:)`` case.
|
||||
/// Each entry name maps to a ``MetadataValue`` (which may be `nil` if not found).
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - See ``MetadataEntryName`` for entry name representation
|
||||
/// - See ``MetadataValue`` for entry values
|
||||
|
||||
@@ -35,7 +35,7 @@ import struct NIO.ByteBuffer
|
||||
/// - `MetadataValue(ByteBuffer("Team folder"))` for `/shared/comment`
|
||||
/// - `MetadataValue(nil)` for `/private/notes` (not set or deleted)
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - See ``MetadataEntryName`` for entry names
|
||||
/// - See ``MetadataResponse`` for complete metadata responses
|
||||
|
||||
@@ -17,7 +17,7 @@ import struct OrderedCollections.OrderedDictionary
|
||||
|
||||
/// A description of a single namespace, including its prefix and hierarchy delimiter.
|
||||
///
|
||||
/// This type represents one namespace descriptor in the server's namespace configuration (RFC 2342).
|
||||
/// Represents one namespace descriptor in the server's namespace configuration (RFC 2342).
|
||||
/// It consists of a prefix string that specifies the mailbox path hierarchy and an optional hierarchy
|
||||
/// delimiter that separates mailbox name components. For namespaces that do not use a hierarchy delimiter,
|
||||
/// the delimiter is `nil`.
|
||||
@@ -30,7 +30,7 @@ import struct OrderedCollections.OrderedDictionary
|
||||
/// S: * NAMESPACE (("" "/") ("INBOX." ".")) NIL NIL
|
||||
/// ```
|
||||
///
|
||||
/// This response contains two personal namespace descriptors:
|
||||
/// The response contains two personal namespace descriptors:
|
||||
/// - The first is ``NamespaceDescription`` with prefix `""` (empty string) and delimiter `/`
|
||||
/// - The second is ``NamespaceDescription`` with prefix `INBOX.` and delimiter `.`
|
||||
///
|
||||
@@ -38,7 +38,7 @@ import struct OrderedCollections.OrderedDictionary
|
||||
public struct NamespaceDescription: Hashable, Sendable {
|
||||
/// The namespace prefix string.
|
||||
///
|
||||
/// This prefix specifies the root of the namespace. Mailboxes within this namespace
|
||||
/// Specifies the root of the namespace. Mailboxes within this namespace
|
||||
/// are accessed by appending the mailbox name to this prefix, separated by the delimiter.
|
||||
/// An empty string indicates the namespace has no prefix (mailboxes are accessed directly).
|
||||
public var string: ByteBuffer
|
||||
@@ -52,7 +52,7 @@ public struct NamespaceDescription: Hashable, Sendable {
|
||||
|
||||
/// Response extensions for this namespace, supporting future protocol enhancements.
|
||||
///
|
||||
/// This dictionary contains arbitrary key-value pairs that may be included by servers
|
||||
/// Contains arbitrary key-value pairs that may be included by servers
|
||||
/// to provide additional namespace information. Keys are extension names, and values are
|
||||
/// arrays of strings containing the extension parameters.
|
||||
/// Non-standard extensions should be prefixed with `X-` as per RFC 2342.
|
||||
|
||||
@@ -16,7 +16,7 @@ import struct NIO.ByteBuffer
|
||||
|
||||
/// A response containing the server's namespace configuration for personal, other users', and shared mailboxes.
|
||||
///
|
||||
/// This type represents the response to a `NAMESPACE` command (RFC 2342), which allows clients to discover
|
||||
/// Represents the response to a `NAMESPACE` command (RFC 2342), which allows clients to discover
|
||||
/// the mailbox namespace structure used by the server. The response contains three namespace categories,
|
||||
/// each consisting of zero or more ``NamespaceDescription`` objects. Any category that is not available
|
||||
/// on the server will contain an empty array.
|
||||
@@ -32,7 +32,7 @@ import struct NIO.ByteBuffer
|
||||
/// S: A001 OK NAMESPACE command completed
|
||||
/// ```
|
||||
///
|
||||
/// This response is wrapped as ``NamespaceResponse`` where:
|
||||
/// The response is wrapped as ``NamespaceResponse`` where:
|
||||
/// - `userNamespace` is `[NamespaceDescription(string: "", delimiter: "/")]`
|
||||
/// - `otherUserNamespace` is `[NamespaceDescription(string: "~", delimiter: "/")]`
|
||||
/// - `sharedNamespace` is `[]` (NIL indicates no shared namespace available)
|
||||
|
||||
@@ -25,7 +25,7 @@ import struct NIO.ByteBuffer
|
||||
///
|
||||
/// ### Usage in IMAP URLs
|
||||
///
|
||||
/// This type represents the base URL before any URLAUTH authorization is added:
|
||||
/// Represents the base URL before any URLAUTH authorization is added:
|
||||
/// ```
|
||||
/// imap://user@example.com/INBOX/;uidvalidity=100/;uid=20
|
||||
/// ```
|
||||
@@ -52,7 +52,7 @@ import struct NIO.ByteBuffer
|
||||
///
|
||||
/// The `imap://owner@example.com/INBOX/;uid=20` portion would be a ``NetworkMessagePath``.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - ``MessagePath`` provides the message location (mailbox, UID, section, range)
|
||||
/// - ``IMAPServer`` provides the server connection details
|
||||
|
||||
@@ -46,7 +46,7 @@
|
||||
/// Result: imap://other.com/
|
||||
/// ```
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - ``RelativeIMAPURL`` uses network paths as one variant of relative URLs
|
||||
/// - ``IMAPServer`` provides the server connection specification
|
||||
|
||||
@@ -18,7 +18,7 @@ import struct NIO.ByteBuffer
|
||||
///
|
||||
/// **Requires server capability:** ``Capability/multiSearch``
|
||||
///
|
||||
/// This type represents a non-empty list of mailbox names used with mailbox filters in RFC 7377 MULTIMAILBOX SEARCH.
|
||||
/// Represents a non-empty list of mailbox names used with mailbox filters in RFC 7377 MULTIMAILBOX SEARCH.
|
||||
/// The filter types are defined in RFC 5465 NOTIFY but are re-used by RFC 7377. Certain filters like
|
||||
/// ``MailboxFilter/subtree(_:)`` and ``MailboxFilter/mailboxes(_:)`` require one or more specific mailbox names.
|
||||
/// See [RFC 7377 Section 3](https://datatracker.ietf.org/doc/html/rfc7377#section-3).
|
||||
@@ -34,7 +34,7 @@ import struct NIO.ByteBuffer
|
||||
/// The mailbox names `"Archive"` and `"Sent Mail"` form a ``Mailboxes`` collection that specifies
|
||||
/// which mailboxes (via ``MailboxFilter``) are included in a multi-mailbox search operation.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - See ``MailboxFilter`` for different ways to select mailboxes
|
||||
/// - See ``MailboxName`` for individual mailbox name representation
|
||||
@@ -43,7 +43,7 @@ import struct NIO.ByteBuffer
|
||||
public struct Mailboxes: Hashable, Sendable {
|
||||
/// Array of one or more mailbox names.
|
||||
///
|
||||
/// This collection must contain at least one mailbox. The mailboxes are represented as
|
||||
/// Must contain at least one mailbox. The mailboxes are represented as
|
||||
/// ``MailboxName`` values, which can include standard or UTF-7-modified mailbox names.
|
||||
public let content: [MailboxName]
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ import struct NIO.ByteBuffer
|
||||
|
||||
/// An option value, which can be a single string or a nested array of values.
|
||||
///
|
||||
/// This recursive enum allows option values to be nested arbitrarily deep, enabling representation
|
||||
/// Allows option values to be nested arbitrarily deep, enabling representation
|
||||
/// of complex structured data in the RFC 4466 extension mechanism. Values can be simple strings
|
||||
/// or arrays of other option values, supporting flexible data representation.
|
||||
///
|
||||
|
||||
@@ -16,7 +16,7 @@
|
||||
///
|
||||
/// The `PARTIAL` extension (RFC 9394) allows clients to request `SEARCH` and `FETCH` results
|
||||
/// in fixed-size pages, either from the beginning (`.first`) or end (`.last`) of the result set.
|
||||
/// This enables efficient pagination of large result sets without retrieving the entire list.
|
||||
/// Enables efficient pagination of large result sets without retrieving the entire list.
|
||||
///
|
||||
/// The two forms are:
|
||||
/// - `.first`: Requests N results starting from the lowest UID (beginning)
|
||||
@@ -30,7 +30,7 @@ public enum PartialRange: Hashable, Sendable {
|
||||
case first(SequenceRange)
|
||||
/// A range relative to the newest (highest UID) message.
|
||||
///
|
||||
/// This is encoded as negative number.
|
||||
/// Encoded as a negative number.
|
||||
///
|
||||
/// Aka. `partial-range-last`.
|
||||
case last(SequenceRange)
|
||||
|
||||
@@ -17,7 +17,7 @@ import struct NIO.ByteBuffer
|
||||
extension SearchReturnData {
|
||||
/// Partial search results with a specified range.
|
||||
///
|
||||
/// This type contains the range that was requested via the `PARTIAL` modifier and the
|
||||
/// Contains the range that was requested via the `PARTIAL` modifier and the
|
||||
/// message numbers matching the search within that range. The `PARTIAL` extension (RFC 9394)
|
||||
/// enables efficient pagination of large search results.
|
||||
///
|
||||
|
||||
@@ -37,7 +37,7 @@ import struct NIO.ByteBuffer
|
||||
///
|
||||
/// These appear as part of the ``ResponsePayload/quota(_:_:)`` response.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - See ``QuotaResource`` for current usage along with limits
|
||||
/// - See ``QuotaRoot`` for quota root names
|
||||
@@ -59,7 +59,7 @@ public struct QuotaLimit: Hashable, Sendable {
|
||||
|
||||
/// Creates a new `QuotaLimit` with a resource name and maximum limit.
|
||||
///
|
||||
/// - parameter resourceName: The resource name (e.g., `"STORAGE"`, `"MESSAGE"`).
|
||||
/// - parameter resourceName: The resource name (for example, `"STORAGE"` or `"MESSAGE"`).
|
||||
/// - parameter limit: The maximum allowed value for the resource.
|
||||
public init(resourceName: String, limit: Int) {
|
||||
self.resourceName = resourceName
|
||||
|
||||
@@ -37,7 +37,7 @@ import struct NIO.ByteBuffer
|
||||
///
|
||||
/// These appear as part of the ``ResponsePayload/quota(_:_:)`` response.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - See ``QuotaLimit`` for just the maximum limit without usage
|
||||
/// - See ``QuotaRoot`` for quota root names
|
||||
@@ -65,7 +65,7 @@ public struct QuotaResource: Hashable, Sendable {
|
||||
|
||||
/// Creates a new `QuotaResource` with current usage and maximum limit.
|
||||
///
|
||||
/// - parameter resourceName: The resource name (e.g., `"STORAGE"`, `"MESSAGE"`).
|
||||
/// - parameter resourceName: The resource name (for example, `"STORAGE"` or `"MESSAGE"`).
|
||||
/// - parameter usage: The current usage of the resource.
|
||||
/// - parameter limit: The maximum allowed value for the resource.
|
||||
public init(resourceName: String, usage: Int, limit: Int) {
|
||||
|
||||
@@ -35,7 +35,7 @@ import struct NIO.ByteBufferView
|
||||
/// along with an array of ``QuotaResource`` values. This response is wrapped as
|
||||
/// ``Response/untagged(_:)`` containing ``ResponsePayload/quota(_:_:)``.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - See ``QuotaResource`` for resource usage and limits
|
||||
/// - See ``ResponsePayload/quotaRoot(_:_:)`` for mailbox-to-quota-root associations
|
||||
|
||||
@@ -55,7 +55,7 @@
|
||||
/// imap://user@example.com/INBOX/
|
||||
/// ```
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// - ``IMAPURL`` provides absolute URL specification
|
||||
/// - ``NetworkPath`` represents network-accessible paths
|
||||
|
||||
@@ -35,7 +35,7 @@ import struct NIO.ByteBuffer
|
||||
/// indicates the search matched 42 messages (COUNT 42) and provides the UIDs of all matches
|
||||
/// (ALL 1,3,5,7,9,...) because UID was specified and RETURN (COUNT ALL) was requested.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// Link to related types using DocC symbol links: ``SearchReturnOption``, ``SearchReturnData``,
|
||||
/// ``SearchCorrelator``.
|
||||
@@ -115,7 +115,7 @@ extension ExtendedSearchResponse {
|
||||
/// Returns `nil` if this is not a UID response or if the response does not contain matched UIDs.
|
||||
/// When no matching UIDs exist, this property returns an empty set rather than `nil`.
|
||||
///
|
||||
/// This property extracts UIDs from ``SearchReturnData/all(_:)`` if present, or falls back to
|
||||
/// Extracts UIDs from ``SearchReturnData/all(_:)`` if present, or falls back to
|
||||
/// ``SearchReturnData/partial(_:_:)`` if only partial results are available. Per RFC 9394, a
|
||||
/// single SEARCH response should contain either ALL or PARTIAL, but not both; if both are
|
||||
/// present, ALL takes precedence.
|
||||
@@ -132,7 +132,7 @@ extension ExtendedSearchResponse {
|
||||
/// Returns `nil` if this is not a sequence number response or if the response does not contain matched sequence numbers.
|
||||
/// When no matching sequence numbers exist, this property returns an empty set rather than `nil`.
|
||||
///
|
||||
/// This property extracts sequence numbers from ``SearchReturnData/all(_:)`` if present, or falls back to
|
||||
/// Extracts sequence numbers from ``SearchReturnData/all(_:)`` if present, or falls back to
|
||||
/// ``SearchReturnData/partial(_:_:)`` if only partial results are available. Per RFC 9394, a
|
||||
/// single SEARCH response should contain either ALL or PARTIAL, but not both; if both are
|
||||
/// present, ALL takes precedence.
|
||||
|
||||
@@ -27,7 +27,7 @@ public enum ResponseOrContinuationRequest: Hashable, Sendable {
|
||||
/// and command continuation requests (prefixed with `+`). This enum wraps all response variants.
|
||||
/// See [RFC 3501 Section 7](https://datatracker.ietf.org/doc/html/rfc3501#section-7) for details.
|
||||
///
|
||||
/// ## Response Types
|
||||
/// ## Response types
|
||||
///
|
||||
/// **Untagged responses** (``untagged(_:)``) convey server data or status information that does not
|
||||
/// indicate command completion. Examples include capabilities, mailbox status, and message data.
|
||||
@@ -123,7 +123,7 @@ public enum Response: Hashable, Sendable {
|
||||
/// S: * BYE Server shutting down
|
||||
/// ```
|
||||
///
|
||||
/// This line is wrapped as ``Response/fatal(_:)`` containing a ``ResponseText`` with the
|
||||
/// The line is wrapped as ``Response/fatal(_:)`` containing a ``ResponseText`` with the
|
||||
/// server's message.
|
||||
///
|
||||
/// - SeeAlso: ``ResponseText``, [RFC 3501 Section 7.1.3](https://datatracker.ietf.org/doc/html/rfc3501#section-7.1.3)
|
||||
@@ -195,7 +195,7 @@ extension Response: CustomDebugStringConvertible {
|
||||
|
||||
/// Creates a string from the array of `Response` with all _personally identifiable information_ redacted.
|
||||
///
|
||||
/// This is equivalent to joining `debugDescription` of all elements.
|
||||
/// Equivalent to joining `debugDescription` of all elements.
|
||||
public static func descriptionWithoutPII(_ responses: some Sequence<Response>) -> String {
|
||||
ResponseEncodeBuffer.makeDescription(loggingMode: true) {
|
||||
for response in responses {
|
||||
@@ -228,7 +228,7 @@ extension Response: CustomDebugStringConvertible {
|
||||
/// S: )
|
||||
/// ```
|
||||
///
|
||||
/// This represents a fetch for message 1. The first line contains the simple attributes
|
||||
/// The above represents a fetch for message 1. The first line contains the simple attributes
|
||||
/// (UID and FLAGS), wrapped in separate ``FetchResponse/simpleAttribute(_:)`` events. The
|
||||
/// second part begins a streaming section with ``FetchResponse/streamingBegin(kind:byteCount:)``
|
||||
/// for the message body, followed by ``FetchResponse/streamingBytes(_:)`` events, and
|
||||
@@ -238,7 +238,7 @@ extension Response: CustomDebugStringConvertible {
|
||||
public enum FetchResponse: Hashable, Sendable {
|
||||
/// The beginning of a fetch response for the message at the given sequence number.
|
||||
///
|
||||
/// This is the first event in a fetch response sequence. The sequence number can be used to
|
||||
/// The first event in a fetch response sequence. The sequence number can be used to
|
||||
/// correlate this fetch with the original FETCH command.
|
||||
///
|
||||
/// - SeeAlso: ``SequenceNumber``, [RFC 3501 Section 2.3.1.2](https://datatracker.ietf.org/doc/html/rfc3501#section-2.3.1.2)
|
||||
@@ -248,7 +248,7 @@ public enum FetchResponse: Hashable, Sendable {
|
||||
///
|
||||
/// When a client uses “UID Only” mode (see [RFC 9586](https://datatracker.ietf.org/doc/html/rfc9586)),
|
||||
/// the server returns only the UID in the FETCH response rather than the sequence number.
|
||||
/// This is more efficient for pipelined commands.
|
||||
/// More efficient for pipelined commands.
|
||||
///
|
||||
/// - SeeAlso: ``UID``, [RFC 9586](https://datatracker.ietf.org/doc/html/rfc9586) - IMAP Extension: SUBMIT
|
||||
case startUID(UID)
|
||||
@@ -264,7 +264,7 @@ public enum FetchResponse: Hashable, Sendable {
|
||||
|
||||
/// The start of a streaming section containing potentially large data.
|
||||
///
|
||||
/// This event indicates that a large message part (body, RFC 822 header, etc.) is about to be
|
||||
/// Indicates that a large message part (body, RFC 822 header, etc.) is about to be
|
||||
/// streamed to the client. The ``StreamingKind`` specifies which part is being streamed,
|
||||
/// and the `byteCount` parameter indicates the total bytes that will follow.
|
||||
///
|
||||
@@ -288,7 +288,7 @@ public enum FetchResponse: Hashable, Sendable {
|
||||
|
||||
/// The end of the currently streaming section.
|
||||
///
|
||||
/// This marks the completion of a streaming section started by ``streamingBegin(kind:byteCount:)``.
|
||||
/// Marks the completion of a streaming section started by ``streamingBegin(kind:byteCount:)``.
|
||||
/// More streaming sections may immediately follow, or the fetch may complete with ``finish``.
|
||||
///
|
||||
/// - SeeAlso: ``streamingBegin(kind:byteCount:)``
|
||||
@@ -296,7 +296,7 @@ public enum FetchResponse: Hashable, Sendable {
|
||||
|
||||
/// The end of all fetch data for this message.
|
||||
///
|
||||
/// This is the final event in a fetch response sequence. After this, processing of the message
|
||||
/// The final event in a fetch response sequence. After this, processing of the message
|
||||
/// is complete, and a new fetch (or other response) may begin.
|
||||
case finish
|
||||
}
|
||||
@@ -328,7 +328,7 @@ public enum StreamingKind: Hashable, Sendable {
|
||||
/// The `BINARY[1] {512}` indicates that 512 bytes of binary data from message part 1 will be
|
||||
/// streamed. This corresponds to ``StreamingKind/binary(section:offset:)`` with an empty offset.
|
||||
///
|
||||
/// - parameter section: The part of the message to fetch (e.g., 1, 2.1)
|
||||
/// - parameter section: The part of the message to fetch (for example, 1 or 2.1)
|
||||
/// - parameter offset: Optional byte offset for partial fetch (requires RFC 9394 PARTIAL extension)
|
||||
///
|
||||
/// - SeeAlso: ``SectionSpecifier/Part``, [RFC 3516](https://datatracker.ietf.org/doc/html/rfc3516)
|
||||
@@ -337,7 +337,7 @@ public enum StreamingKind: Hashable, Sendable {
|
||||
/// A body section being streamed.
|
||||
///
|
||||
/// The `BODY` fetch item returns message structure and content according to [RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501).
|
||||
/// The `section` specifies which part of the message is being returned (e.g., TEXT for the message body,
|
||||
/// The `section` specifies which part of the message is being returned (for example, TEXT for the message body,
|
||||
/// HEADER for headers, or 1.2.3 for nested MIME parts). The `offset` specifies a byte offset for
|
||||
/// partial fetches.
|
||||
///
|
||||
@@ -350,7 +350,7 @@ public enum StreamingKind: Hashable, Sendable {
|
||||
/// ```
|
||||
///
|
||||
/// The `BODY[TEXT] {1024}` indicates that 1024 bytes of the message body text will be streamed.
|
||||
/// This corresponds to ``StreamingKind/body(section:offset:)`` with the TEXT section specifier.
|
||||
/// Corresponds to ``StreamingKind/body(section:offset:)`` with the TEXT section specifier.
|
||||
///
|
||||
/// - parameter section: The section specifier (part and section type)
|
||||
/// - parameter offset: Optional byte offset for partial fetch (requires RFC 9394 PARTIAL extension)
|
||||
@@ -372,7 +372,7 @@ public enum StreamingKind: Hashable, Sendable {
|
||||
/// ```
|
||||
///
|
||||
/// The `RFC822 {2048}` indicates that 2048 bytes of the complete message will be streamed.
|
||||
/// This corresponds to ``StreamingKind/rfc822``.
|
||||
/// Corresponds to ``StreamingKind/rfc822``.
|
||||
///
|
||||
/// - SeeAlso: [RFC 3501 Section 6.4.5](https://datatracker.ietf.org/doc/html/rfc3501#section-6.4.5)
|
||||
case rfc822
|
||||
@@ -391,7 +391,7 @@ public enum StreamingKind: Hashable, Sendable {
|
||||
/// ```
|
||||
///
|
||||
/// The `RFC822.TEXT {1024}` indicates that 1024 bytes of the message body will be streamed.
|
||||
/// This corresponds to ``StreamingKind/rfc822Text``.
|
||||
/// Corresponds to ``StreamingKind/rfc822Text``.
|
||||
///
|
||||
/// - SeeAlso: [RFC 3501 Section 6.4.5](https://datatracker.ietf.org/doc/html/rfc3501#section-6.4.5)
|
||||
case rfc822Text
|
||||
@@ -410,7 +410,7 @@ public enum StreamingKind: Hashable, Sendable {
|
||||
/// ```
|
||||
///
|
||||
/// The `RFC822.HEADER {512}` indicates that 512 bytes of the message headers will be streamed.
|
||||
/// This corresponds to ``StreamingKind/rfc822Header``.
|
||||
/// Corresponds to ``StreamingKind/rfc822Header``.
|
||||
///
|
||||
/// - SeeAlso: [RFC 3501 Section 6.4.5](https://datatracker.ietf.org/doc/html/rfc3501#section-6.4.5)
|
||||
case rfc822Header
|
||||
|
||||
@@ -35,7 +35,7 @@
|
||||
public struct ResponseCodeAppend: Hashable, Sendable {
|
||||
/// The UID validity value of the destination mailbox.
|
||||
///
|
||||
/// This value allows clients to validate that the UIDs returned in this response are still
|
||||
/// Allows clients to validate that the UIDs returned in this response are still
|
||||
/// correct if they are later referenced. If the UID validity changes, all cached UIDs are invalid.
|
||||
///
|
||||
/// - SeeAlso: ``UIDValidity``
|
||||
@@ -43,7 +43,7 @@ public struct ResponseCodeAppend: Hashable, Sendable {
|
||||
|
||||
/// The UIDs of the messages after they have been appended.
|
||||
///
|
||||
/// This set contains the UID or UIDs assigned by the server to the messages that were just
|
||||
/// Contains the UID or UIDs assigned by the server to the messages that were just
|
||||
/// appended. The sequence and count of UIDs corresponds to the number of messages appended by
|
||||
/// the APPEND command.
|
||||
///
|
||||
|
||||
@@ -39,7 +39,7 @@
|
||||
public struct ResponseCodeCopy: Hashable, Sendable {
|
||||
/// The UID validity value of the destination mailbox.
|
||||
///
|
||||
/// This value allows clients to validate that the destination UIDs are still correct if
|
||||
/// Allows clients to validate that the destination UIDs are still correct if
|
||||
/// referenced later. If the UID validity of the destination mailbox changes, the cached
|
||||
/// destination UIDs become invalid.
|
||||
///
|
||||
|
||||
@@ -44,7 +44,7 @@ import struct OrderedCollections.OrderedDictionary
|
||||
/// The third line corresponds to ``capabilityData(_:)``, while the fourth corresponds
|
||||
/// to ``id(_:)``.
|
||||
///
|
||||
/// ## Related Types
|
||||
/// ## Related types
|
||||
///
|
||||
/// See ``Response`` for the main response wrapper, ``UntaggedStatus`` for conditional status responses,
|
||||
/// and ``ResponsePayload`` cases for detailed information types.
|
||||
@@ -53,7 +53,7 @@ import struct OrderedCollections.OrderedDictionary
|
||||
public enum ResponsePayload: Hashable, Sendable {
|
||||
/// Indicates if a command executed successfully or encountered an error.
|
||||
///
|
||||
/// This case wraps an ``UntaggedStatus`` which can be `OK` (success), `NO` (warning/rejection),
|
||||
/// Wraps an ``UntaggedStatus`` which can be `OK` (success), `NO` (warning/rejection),
|
||||
/// `BAD` (protocol error), `PREAUTH` (pre-authenticated), or `BYE` (server closing connection).
|
||||
/// See [RFC 3501 Section 7.1](https://datatracker.ietf.org/doc/html/rfc3501#section-7.1) for
|
||||
/// details on status responses.
|
||||
@@ -61,33 +61,33 @@ public enum ResponsePayload: Hashable, Sendable {
|
||||
|
||||
/// Contains information on a single mailbox.
|
||||
///
|
||||
/// This case wraps mailbox-specific data such as flags, existence counts, recent count,
|
||||
/// Wraps mailbox-specific data such as flags, existence counts, recent count,
|
||||
/// and search results. See ``MailboxData`` for the various mailbox information types.
|
||||
case mailboxData(MailboxData)
|
||||
|
||||
/// Contains information on a single message.
|
||||
///
|
||||
/// This case wraps message-specific data returned during FETCH operations or other
|
||||
/// Wraps message-specific data returned during FETCH operations or other
|
||||
/// message queries. See ``MessageData`` for the various message attribute types.
|
||||
case messageData(MessageData)
|
||||
|
||||
/// An array of capabilities supported by the server.
|
||||
///
|
||||
/// This case is returned in response to `CAPABILITY` commands or as part of the initial
|
||||
/// Returned in response to `CAPABILITY` commands or as part of the initial
|
||||
/// server greeting. It indicates which IMAP extensions and features the server supports.
|
||||
/// See [RFC 3501 Section 7.1](https://datatracker.ietf.org/doc/html/rfc3501#section-7.1) and ``Capability``.
|
||||
case capabilityData([Capability])
|
||||
|
||||
/// An array of capabilities that have been enabled on the server by the client.
|
||||
///
|
||||
/// This case is returned in response to an `ENABLE` command and lists the capabilities
|
||||
/// Returned in response to an `ENABLE` command and lists the capabilities
|
||||
/// that were successfully enabled. See [RFC 5161](https://datatracker.ietf.org/doc/html/rfc5161)
|
||||
/// (ENABLE Extension) for details.
|
||||
case enableData([Capability])
|
||||
|
||||
/// The server's implementation details used for identification.
|
||||
///
|
||||
/// This case contains an ordered dictionary of key-value pairs providing server identification
|
||||
/// Contains an ordered dictionary of key-value pairs providing server identification
|
||||
/// information. Common keys include "name", "version", and "os". Returned in response to
|
||||
/// the ID command. See [RFC 2971](https://datatracker.ietf.org/doc/html/rfc2971) (ID Extension)
|
||||
/// for details.
|
||||
@@ -95,26 +95,26 @@ public enum ResponsePayload: Hashable, Sendable {
|
||||
|
||||
/// Matches a quota root with a mailbox.
|
||||
///
|
||||
/// This case associates a mailbox with its quota root. Multiple mailboxes may share the same
|
||||
/// Associates a mailbox with its quota root. Multiple mailboxes may share the same
|
||||
/// quota root. See [RFC 2087](https://datatracker.ietf.org/doc/html/rfc2087) (QUOTA Extension)
|
||||
/// for details and ``QuotaRoot``.
|
||||
case quotaRoot(MailboxName, QuotaRoot)
|
||||
|
||||
/// Contains quotas and resource limits for the specified quota root.
|
||||
///
|
||||
/// This case provides the usage and limit information for a quota root. See [RFC 2087](https://datatracker.ietf.org/doc/html/rfc2087)
|
||||
/// Provides the usage and limit information for a quota root. See [RFC 2087](https://datatracker.ietf.org/doc/html/rfc2087)
|
||||
/// for details on quota resources and ``QuotaResource``.
|
||||
case quota(QuotaRoot, [QuotaResource])
|
||||
|
||||
/// Metadata for a mailbox.
|
||||
///
|
||||
/// This case provides metadata entries for a mailbox, as requested by a `GETMETADATA` command.
|
||||
/// Provides metadata entries for a mailbox, as requested by a `GETMETADATA` command.
|
||||
/// See [RFC 5464](https://datatracker.ietf.org/doc/html/rfc5464) (METADATA Extension) for details.
|
||||
case metadata(MetadataResponse)
|
||||
|
||||
/// JMAP Access URL for the mailbox.
|
||||
///
|
||||
/// This case provides a URL that allows clients to access mailbox data via JMAP (JSON Mail
|
||||
/// Provides a URL that allows clients to access mailbox data via JMAP (JSON Mail
|
||||
/// Access Protocol). See [RFC 9698](https://datatracker.ietf.org/doc/html/rfc9698) (JMAPACCESS Extension)
|
||||
/// for details.
|
||||
case jmapAccess(URL)
|
||||
|
||||
@@ -37,7 +37,7 @@ import struct NIO.ByteBuffer
|
||||
public struct ResponseText: Hashable, Sendable {
|
||||
/// The optional structured status code providing additional semantic information.
|
||||
///
|
||||
/// Status codes are brief tokens that communicate specific server conditions (e.g., `[ALERT]`,
|
||||
/// Status codes are brief tokens that communicate specific server conditions (for example, `[ALERT]`,
|
||||
/// `[CANNOT]`, `[PERMANENT]`). They provide machine-readable information to clients that extends
|
||||
/// the human-readable text. Not all responses include a code; `nil` indicates no code is present.
|
||||
///
|
||||
|
||||
Loaded 100 of 151 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user