libetpan

To support RFC 2231 without breaking the public API, libetpan implements an internal normalization process.

1. Parsing: The raw parser treats RFC 2231 names (like name*0*) as generic attributes.
2. Normalization: An internal helper (proposed as mailmime_parameters_rfc2231_normalize) scans the parsed parameter list. It identifies fragments such as:
   • name* (single extended parameter)
   • name*0, name*1 (continuations)
   • name*0*, name*1* (encoded continuations)
3. Decoding:
   • Percent-decodes valid %HH triples.
   • Converts from the declared charset to UTF-8 using existing libetpan charset conversion helpers.
   • Falls back to percent-decoded bytes if charset conversion fails.
4. Joining: For continuations, segment 0 is required. Segments are appended in numeric order. If segment 0 is extended, the charset/language is parsed from it.
5. Replacement: The normalized, single struct mailmime_parameter replaces the fragments in the public list, so callers using mailmime_content_param_get() see the final decoded value (e.g., filename) instead of the fragments.

The ActiveSync implementation uses a transport abstraction to decouple the command logic from the HTTP backend (libcurl). This allows for easy testing via fake transports.

Core Data Structures:

• struct mailactivesync_http_header: Represents a single HTTP header with name and value.
• struct mailactivesync_http_request: Contains the method, url, headers (a clist of headers), body, body_len, and timeout.
• struct mailactivesync_http_response: Contains the status_code, headers, body, and body_len.
• struct mailactivesync_http_transport: An interface containing a context pointer and function pointers for perform (to execute the request) and free (to clean up the transport).

struct mailactivesync_http_header {
  char * name;
  char * value;
};

struct mailactivesync_http_request {
  char * method;
  char * url;
  clist * headers; /* struct mailactivesync_http_header * */
  unsigned char * body;
  size_t body_len;
  time_t timeout;
};

struct mailactivesync_http_response {
  int status_code;
  clist * headers; /* struct mailactivesync_http_header * */
  unsigned char * body;
  size_t body_len;
};

struct mailactivesync_http_transport {
  void * context;
  int (*perform)(struct mailactivesync_http_transport * transport,
      struct mailactivesync_http_request * request,
      struct mailactivesync_http_response ** response);
  void (*free)(struct mailactivesync_http_transport * transport);
};

The ActiveSync HTTP implementation in libEtPan follows a phased approach to build up from core transport to high-level mail operations.

Core Transport & Setup

• Phase 1 & 2: Establishes the HTTP request/response core using libcurl. This provides HTTPS, redirects, proxies, TLS verification, and timeouts. If built without HAVE_CURL, the library returns MAILACTIVESYNC_ERROR_HTTP_UNAVAILABLE.
• Phase 3: Implements mailactivesync_options() to negotiate protocol versions (defaulting to 16.1) and commands.
• Phase 3.5: Handles Provisioning Policy. If a server requires it, mailactivesync_provision() is used to store a policy key, which is then sent via the X-MS-PolicyKey header in subsequent requests.

Mail Operations

• Phase 4 (FolderSync): Uses a sync key to fetch folder changes (adds, updates, deletes) into a mailactivesync_folder_sync_result.
• Phase 5 (Sync): Performs the main synchronization of collections (e.g., Inbox) using a SyncKey. It parses message changes, read/flag states, and MIME bodies into a mailactivesync_sync_result.
• Phase 6 (ItemOperations Fetch): Retrieves specific items using CollectionId and ServerId.
• Phase 7 (SendMail): Sends mail via POST, supporting ClientId and SaveInSentItems.
• Phase 8 (MoveItems): Moves items between collections.
• Phase 9 (SmartReply/SmartForward): Specialized reply/forward operations.
• Phase 10 (Ping): A heartbeat mechanism with longer timeouts to detect changes in watched collections.

The plain text rendering in this project follows a specific pipeline to ensure consistency with HTML-first rendering strategies. Instead of a direct MIME-to-text conversion, the process follows these steps:

1. MIME Parsing: The message is parsed into a MIME/message tree using mailmime_parse().
2. HTML Rendering: The full message is rendered as HTML using the default message HTML renderer.
   • text/plain parts are converted into escaped HTML with line breaks (<br/>) and quote block handling (<blockquote type="cite">).
   • text/html parts are cleaned and inserted as HTML.
   • Part Selection Logic:
     • For multipart/alternative: The last part containing text/html is chosen; if none, the last part containing text/plain; otherwise, the first child.
     • For multipart/related: The first child is the root body; remaining children are related attachments.
     • For multipart/mixed: Children are rendered in order.
     • For message/rfc822: The nested body is wrapped with an embedded-message header template.
3. HTML Flattening: The final HTML document is flattened into plain text (using logic similar to String::flattenHTML()).
4. Normalization: Lines beginning with Date: are normalized by replacing " at " with " " to ensure deterministic comparison.