Главная/Учебник/Справочник почтовых функций
283 функции · четыре библиотеки · версия общая с бинарником

Справочник почтовых функций

Вкомпилируется вариантом build.bat xmail (или любым протокольным — xmail подтянется автоматически). Скрипт пишет #include <xsmtp.h> (или xpop3/ximap) — и разрешаются объявления всего семейства.

Слой MIME (xmail, 89 функций)

Общий фундамент отправки и приёма: #include <xmail.h> подтягивает все объявления (модульные заголовки разрешаются через поддерево xrt/ в VFS).

xrtMailTreeParse / TreeLimitsInit разбор

Исходное письмо → дерево сообщения с лимитами (глубина/количество/размер — защита от враждебной вложенности).

bool xrtMailTreeParse(xstrview Message, const xrtMailTreeLimits* pLimits, xrtMailNode** ppTree);

xrtMailBuilderInit / Header / Body / Multipart / Finish сборка

Потоковое конструирование: заголовки (с кодированными словами и нормализацией адресов), тела (авто-выбор QP/Base64), границы multipart, финиш одним шагом. Ноль промежуточных копий.

void xrtMailBuilderInit(xrtMailBuilder* pBuilder, xbuffer* pBuffer); bool xrtMailBuilderBody(xrtMailBuilder* pBuilder, xbytesview Body, xrtMailCodec Codec);

xrtMailQp / Base64 семейства кодеки

Кодирование/декодирование QP и Base64, у каждого два вида: Write (в ваш буфер) и возвращающий (освобождение xrtFree).

xrtMailAddress / Word / Date / Param / MessageId поля

Курсоры списков адресов, декодирование кодированных слов (RFC 2047), даты (RFC 5322), параметры Content-Type/Disposition и Message-ID — всё заимствованные представления с курсорной итерацией.

Клиент SMTP (44 функции)

xrtSmtpClientOpen / Capabilities / Auth / Close сеанс

Соединение (открытый текст/STARTTLS/SSL по конфигурации), согласование возможностей, SASL-аутентификация, корректное закрытие.

xsmtpclient* xrtSmtpClientOpen(const xsmtpclientconfig* pConfig, xnetengine* pEngine, xerror* pError);

xrtSmtpClientMail / Rcpt / Data / Bdat доставка

Двухфазная доставка: конверт (MAIL FROM/RCPT TO), затем содержимое (DATA или блоки BDAT); SizeLimit заранее проверяет ёмкость.

xrtSmtpSubmit один шаг

Доставка целого письма за один шаг (сборка → конверт → содержимое → закрытие), внутри переиспользует сеансовый API.

bool xrtSmtpSubmit(const xsmtpsubmitconfig* pConfig, xnetengine* pEngine, xerror* pError);

xrtSmtpReplyLineParse / CapabilityParse разборщики

Разбор строк ответа и возможностей, без сети — тестируется офлайн.

Клиент POP3 (48 функций)

xrtPop3ClientOpen / Stat / List / Uidl инвентарь

Установка сеанса и три инвентарных вызова (количество/размер, список, уникальные ID).

xrtPop3ClientRetr / Top / RetrTree выборка

Выборка целого письма, заголовков с N строками и прямое получение дерева сообщения (через слой MIME).

bool xrtPop3ClientRetrTree(xpop3client* pClient, uint64 uMessage, const xrtMailTreeLimits* pLimits, xrtMailNode** ppTree);

xrtPop3ClientDelete / Reset / Noop / Quit управление

Пометки удаления (применяются на QUIT), сброс, поддержание жизни и выход.

Клиент IMAP (102 функции)

xrtImapClientOpen / Select / Examine сеанс

Сеанс и выбор ящика (чтение-запись/только чтение), возвращает метаданные ящика (exists/recent/UIDNEXT).

xrtImapClientBeginSearch / BeginFetch / BeginStore операции

Поиск (наборы последовательностей/условия), выборка (заголовки/тела/флаги по требованию), правка флагов — Begin* запускает, далее результаты потоково потребляются через Next/Refresh.

xrtImapClientAppend / BeginIdle / EndIdle продвинутый

Архивация писем, ожидание пуша IDLE (сервер сам сообщает о новых), сеансы COMPRESS.

xrtImapResponseParse / DataCursor семейства разборщики

Разбор ответов и элементов данных (flag/status/search/fetch/body), независимо тестируемый.

Общий SASL и транспорт

Три протокола делят одну SASL-машину (PLAIN / XOAUTH2 / OAUTHBEARER) и один транспорт (TCP + опциональные TLS и сжатие); учётные данные приходят через собственный AuthConfig каждого протокола. Секреты — через окружение или Custom (см. справочник конфигурации); проверка TLS включена по умолчанию.

Конструирование и соглашения

Владение: дескрипторы клиентов выделяет библиотека (Close рвёт связь / Destroy освобождает); результаты разбора и ответы — заимствованные представления, копируйте семействами Write/Bytes до выхода из функции. Композиция вариантов: xsmtp/xpop3/ximap несут xmail через requires; рантайм-проверка — xsExtensionEnabled("xsmtp"). Учебник — глава 36.

Полные сигнатуры по каждой функции — в каталогах lib/{xmail,xsmtp,xpop3,ximap}/include репозитория (зеркало на Gitee); эта страница даёт главные маршруты и частые комбинации по семействам.