Описание API EDIMail

Описание API EDIMail
Функции инициализации и работы с контекстом
EDIMailContext* InitContext(char* filepath)
Функция инициализации библиотеки. Предназначена для создания контекста, с
помощью которого определяются умолчания для не заданных аргументов
функций и параметров. Конструктор каждого создаваемого объекта позволяет
указать имя прототипа объекта. Имя прототипа ищется в контексте, и методы,
атрибуты найденного прототипа используются при инициализации объекта. При
окончании работы с библиотекой контекст должен быть освобожден функцией
FreeContext
void FreeContext(EDIMailContext *ctx)
Функция освобождает память и другие ресурсы, связанные с контекстом
библиотеки. После этого вызова использование функций библиотеки будет
завершаться с ошибкой.
void AddPrototype(EDIMailContext *ctx, v8:String name, v8:Object
prototype)
Добавляет указанный объект в качестве прототипа к контексту. Создав объект с
требуемыми методами и атрибутами, можно добавить его к контексту с тем, чтобы
в дальнейшем использовать его в качестве шаблона в конструкторах объектов.
Аналогично использованию шаблонов документов в MS Word.
int GetMessageStatus(EDIMailContext *ctx, v8:String messageId)
Функция возвращает статус отправленного сообщения или код ошибки, если о
таком сообщении ничего не известно.
Основные функции библиотеки
Адресация
Цель работы библиотеки – доставить сообщение в хранилище сообщений, откуда
его получит (заберет) адресат. Под адресатом понимается бизнес-сущность,
имеющая наименование, ИНН и несколько хранилищ сообщений для разных
целей (сервисов). Хранилищем сообщений в данной реализации библиотеки
может выступать папка в файловой системе, папка на FTP сервере или папка на
IMAP сервере. Каждому хранилищу соответствует свой URL, например,
file://C:/doc, ftp://ftp.micex.com/common, imap://sbrf@ex.micex.com/inbox. Некоторые
хранилища сообщений могут иметь прокси-url для входящих сообщений,
например, url хранилища imap://sbrf@ex.micex.com/inbox может соответствовать
url для входящих сообщений mailto:sbrf@ex.micex.com. Еще пример прокси-url: на
компьютере abc.local c локальной папкой C:\Inetpub\common можно настроить FTP
сервер с корнем C:\Inetpub. Получим хранилище с url
file://abc.local/C:/Inetpub/common и прокси-url ftp://abc.local/common.
Объекты типа EDIMailAddress
Для адресации исходящих сообщений используется объект типа EDIMailAddress.
Этот объект инкапсулирует связь между атрибутами бизнес-сущности и url ее
хранилища сообщений.
Атрибуты EDIMailAddress
Этот объект имеет 4 атрибута:




email – строка или список строк с url для входящих сообщеий; как правило,
это url mailto; в соответствии со стандартом данный url может содержать не
только собственно RFC822 адрес электронной почты, но и заголовки,
предмет письма.
rtsmail – строка с адресом в «старой» системе вида
EMAIL@TROYM.REPORT;
DName – строка в формате запроса к LDAP серверу, например
«DN=Московская биржа, OU=Клиентский отдел» или «INN=7707083893»
service – строка, обозначающая сервис, использующий систему EDIMail для
доставки своих сообщений адресату, например «REPORT».
При создании объекта в конструкторе может быть задано любое допустимое
сочетание из этих четырех атрибутов. При работе с объектом обращение к не
определенному в конструкторе атрибуту вызовет обращение к функции контекста
библиотеки, которая выполнит поиск значения в справочнике или выбор значения
по умолчанию. Недопустимое сочетание атрибутов в конструкторе вызовет
ошибку-исключение и объект EDIMailAddress создан не будет. Примером
недопустимого сочетания атрибутов является, например, задание строки service
не совпадающей с соответствующим заголовком в параметре email, содержащим
url mailto:.
Конструктор EDIMailAddress(EDIMailContext *ctx, v8::String rtsmail, v8::string DName, v8::String
service, v8::Value email, v8::String prototype = v8::Null)
Создает объект адрес, связанный с контекстом ctx.
Объект будет автоматически удален при освобождении контекста, если он не был
удален ранее.
Объекты типа EDIMailURL
Объекты этого типа используются для получения доступа к хранилищам
сообщений. Некоторые url предоставляют отграниченный доступ, например, url
mailto предоставляют только доступ «на запись», доступ по другим url, например,
ftp, зависит от настроек сервера, к которому идет обращение.
Некоторые атрибуты объекта могут как инициализироваться из строки url,
например, имя пользователя и пароль, так и задаваться непосредственным
присваиванием значения атрибуту.
Конструктор EDIMailURL(EDIMailContext *ctx, v8::String url, v8::String prototype = v8::Null)
Создает объект, который можно использовать в дальнейшем для доступа к
хранилищу сообщений. Все атрибуты, которые можно заполнить с помощью
информации, содержащейся в строке URL, будут заполнены. Конструктор не
проводит никаких проверок, кроме синтаксических. Создание объекта не означает,
что к описываемому хранилищу можно будет получить доступ в дальнейшем. При
обнаружении синтаксических ошибок в строке URL объект не создается, возникает
исключение. Объект будет автоматически удален при освобождении контекста,
если он не был удален ранее.
Атрибуты EDIMailURL
user – v8::String – имя пользователя, строка, используемая для авторизации
доступа к хранилищу.
password – v8::String – пароль, строка, используемая для авторизации доступа к
хранилищу.
usetls – v8::Number. Использование TLS для IMAP и SMTP:



0 – не использовать, если сервер требует TLS/SSL, соединения с
сервером не происходит;
1 – использовать по возможности, если сервер допускает использование
TLS/SSL, то оно используется;
2 – обязательно использовать, если сервер не поддерживает TLS/SSL,
соединения с сервером не происходит.
tlsfirst – v8::Number. Порядок запуска протоколов для IMAP и SMTP:


0 – сначала запускается почтовый протокол, потом по команде протокола
STARTTLS запускается TLS;
1 – сначала запускается TLS/SSL, а затем поверх запускается почтовый
протокол.
Этот параметр может задаваться в строке url путем добавления “s” к схеме url,
например imaps://… вместо imap://…
tlscheck – v8::Number. Проверка сертификата SMTP и IMAP сервера:



0 – не производится;
1 – проверяется соответствие имени сервера, с которым было
установлено соединение и имени сервера в сертификате;
2 – проверка совпадения имени сервера и проверка валидности самого
сертификата, самоподписанные сертификаты эту проверку не проходят.
url – v8::String – строка, указанная в конструкторе. Атрибут только для чтения.
proxy_url – URL, который надо использовать для доступа к данному URL. Этот
атрибут может заполняться контекстом при создании объекта. Например, при
создании url со схемой mailto: proxy_url должен содержать url smtp сервера,
используемого для посылки сообщений.
Преобразование формата сообщений
Для унификации работы с областями памяти и файлами используется базовый
класс EDIStream. Его потомки – EDIMemoryStream представляет поток,
инициализированный буфером в памяти, EDIFileStream – поток,
инициализированный файлом. Для преобразования формата сообщений к потоку
могут прикрепляться фильтры. С помощью фильтров осуществляется
шифрование, подписывание, проверка подписи, расшифровывание.
Потоки
Базовый класс EDIStream
Атрибуты класса
Date – v8::Date дата, ассоциированая с потоком, в случае если это файловый
поток – дата последнего изменения файла
Length – v8::Number размер потока или -1, если длина неизвестна
Name – v8::String имя потока, в случае файлового потока – имя файла
Методы класса
AddFilter(EDIFilter *filter) – добавляет фильтр к потоку, фильтры применяются в
порядке добавления при выполнении записи в другой поток.
RemoveFilter(EDIFilter *filter) – удаляет ранее добавленный фильтр.
Write(const char *buf, size_t len) – запись в поток.
Read(const char *buf, size_t len) – чтение из потока.
size_t Tell() – текущая позиция потока.
Seek(size_t offset, int whence) – изменение текущей позиции потока
Write2Stream(EDIStream* stream) – запись в другой поток, может использоваться,
например, для записи содержимого памяти в файл с криптопреобразованием,
заданным фильтрами.
Класс EDIMemoryStream - поток, инициализируемый буфером памяти
Класс инициализируется буфером памяти, если происходит запись за пределами
буфера, размер буфера увеличивается по аналогии с функцией realloc.
EDIMemoryStream(EDIMailContext *ctx, char* buffer, size_t length, v8::String prototype
= v8::Null) – конструктор создает поток и инициализирует его буфером заданного
размера
EDIMemoryStream(EDIMailContext *ctx) – конструктор создает пустой поток в
памяти, размер потока будет зависеть от выполненных в него операций записи.
Класс EDIFileStream – поток, инициализированный файлом
EDIFileStream(EDIMailContext *ctx, v8::String file_name, const char * mode, v8::String
prototype = v8::Null) – конструктор создает поток, открывая файл по аналогии с
функций fopen.
EDIFileStream(EDIMailContext *ctx, v8::String prototype = v8::Null) – конструктор
создает пустой файловый поток, предназначенный для записи. Имя файла может
определяться с помощью прототипа, например, можно сделать прототип, который
будет определять имя файла по имени файла аттачмента, которым будет в
дальнейшем инициализирован поток.
Фильтры
Фильтры используются для зашифровывания, расшифровывания, подписывания
и проверок подписей, преобразования файла в аттачмент к электронному письму,
отделение аттачментов от электронного письма. Фильтры применяются при
записи из одного потока в другой. Порядок применения фильтров совпадает с
порядком их добавления.
Класс EDISignFilter(EDIMailContext *ctx, EDIMailAddress *address, v8::String
prototype = v8::Null) – обеспечивает подписывание сообщение присоединенной
подписью от имени бизнес-сущности, соответствующей указанному экземпляру
класса EDIMailAddress. Запрос сертификата бизнес-сущности происходит с
помощью указанного в вызове контекста, если данный контекст возвратит
сертификат, не содержащий бита KEYUSAGE_DIGITAL_SIGNATURE, применение
фильтра вызовет исключение.
Класс EDISenderEncryptFilter(EDIMailContext *ctx, EDIMailAddress *address,
v8::String prototype = v8::Null) – обеспечивает шифрование файла приватным
ключом бизнес-сущности, соответствующей указанному экземпляру класса
EDIMailAddress. Запрос сертификата бизнес-сущности происходит с помощью
указанного в вызове контекста, если данный контекст возвратит сертификат, не
содержащий приватного ключа, применение фильтра вызовет исключение.
Класс EDIReceiverEncryptFilter(EDIMailContext *ctx, EDIMailAddress *address,
v8::String prototype = v8::Null) – обеспечивает шифрование файла публичным
ключом бизнес-сущности, соответствующей указанному экземпляру класса
EDIMailAddress (анонимное шифрование). Запрос сертификата бизнес-сущности
происходит с помощью указанного в вызове контекста, если данный контекст
возвратит сертификат, не содержащий публичного ключа, применение фильтра
вызовет исключение.
Класс EDICheckSignatureFilter(EDIMailContext *ctx, EDISignStatusList* status,
v8::String prototype = v8::Null) – обеспечивает проверку электронных подписей,
возвращает список объектов содержащих результаты проверки и экземпляры
EDIMailAddress идентифицирующие подписавших сообщение.
Класс EDIDecryptFilter(EDIMailContext *ctx, EDIMailAddress *sender, v8::String
prototype = v8::Null) – обеспечивает расшифрование и возвращает экземпляр
EDIMailAddress, соответствующий отправителю, если использовалось не
анонимное шифрование. Если расшифрование невозможно, происходит
исключение.
Класс EDIAttachFilter(EDIMailContext *ctx, EDIStream *stream, v8::String prototype =
v8::Null) – фильтр преобразует указанный поток в формат аттачмента.
Класс EDIMessageFilter(EDIMailContext *ctx, EDIStream *stream, v8::String prototype
= v8::Null) – фильтр преобразует указанный поток в формат сообщения. Данный
фильтр имеет те же атрибуты, что и класс EDIMessage. Которые используются
для задания атрибутов результирующего сообщения.
Класс EDIDetachFilter(EDIMailContext *ctx, EDIStreamList *list, v8::String prototype =
v8::Null) – фильтр преобразует сообщение в список инициализированных потоков
в памяти, каждый из которых не является ни сообщением, ни аттачментом к
сообщению. Используется для распаковки полученных сообщений. Потоки
получают атрибуты сообщений и/или аттачментов, к которым они принадлежали
– from, to и т.д.
Отправка и получение сообщений.
Класс EDIMessage
Данный класс предназначен для представления сообщений в формате,
используемом для непосредственной обработки на MTA и MDA, другими словами,
сообщения в этом формате принимаются SMTP серверами и получаются с IMAP
серверов. Данный класс используется при необходимости обработки атрибутов
сообщения перед отправкой или анализа структуры полученного сообщения.
Конструктор EDIMessage
Конструктор EDIMessage(EDIMailContext* ctx, EDIStream* stream, v8::String
prototype = v8::Null) создает сообщение из указанного потока. Если синтаксический
анализ закачивается ошибкой, объект не создается и генерируется исключение.
Атрибуты EDIMessage
From – v8::String адрес отправителя, определяется контекстом по сертификату
неанонимного шифрования или цифровой подписи
To – адрес получателя, определяется контекстом по сертификатам анонимного
шифрования, может определяться при посылке с помощью url mailto:.
MessageId – определяется контекстом
Mailbox – сервис получателя, которому адресуется сообщение, может
определяться при посылке с помощью url mailto:.
Date – дата сообщения, контекст определяет ее дате цифровой подписи если она
присутствует или по текущей дате
Subject – тема сообщения, определяется по атрибуту Mailbox, может
определяться при посылке с помощью url mailto:.
Part – v8::Object – корневая MIME-часть сообщения
Методы EDIMessage
WriteToStream(EDIStream *stream) – инициализирует указанный поток сообщением
в MIME формате
V8::string PostTo(EDIMailURL *url) – асинхронно отправляет сообщение по
указанному url. Статус доставки сообщения можно запросить у контекста, в
котором создавалось сообщение с помощью MessageId, которое вернул метод. В
случае использования url mailto: указанные в url атрибуты (адрес доставки,
mailbox, subject и др.) заменяют соответствующие атрибуты письма. Если url есть
NULL, то для отправки используется smtp сервер по умолчанию, указанный в
контексте письма.
Функция Post
Данная функция предназначена для асинхронной отправки сообщений. Функция
возвращает строку с идентификатором отправленного сообщения.
v8::String Post(EDIMailContext* ctx , EDIStream *stream, EDIMailURL *url, v8::String
prototype = v8::Null)
Функция выполняет построение объекта EDIMessage из указанного потока и его
отправку по указанному url. Если для выполнения функции не хватает данных,
генерируется исключение.
Функция Collect
Данная функция предназначена для опроса указанного с помощью URL
хранилища сообщений и получения «новых» сообщений. «Новыми» считаются
сообщения, у которых отметка времени хранилища сообщений больше или равна
отметки времени последнего обработанного сообщения из этого хранилища.
Отметка времени последнего обработанного сообщения сохраняется в контексте
и обновляется в результате выполнения каждого вызова, закончившегося
получением сообщения.
int Collect(EDIMailContext* ctx , EDIStream *stream, EDIMailURL *url, v8::String
prototype = v8::Null)
При наличии сообщения функция возвращает количество «новых» сообщений в
хранилище, считая уже принятое, т.е. если в хранилище было 2 сообщения,
функция вернет 2 и инициализирует поток первым новым сообщением. Если в
хранилище нет новых сообщений, функция вернет 0.