EDIMAILDLL_API int AddMixin(EDIMailContext* ctx, const char

Описание API EDIMail
Table of Contents
Описание API EDIMail .................................................................................................................................. 1
Назначение системы ............................................................................................................................... 4
Архитектура системы .............................................................................................................................. 4
Функция получения сообщения об ошибке .......................................................................................... 5
const char* GetLastEDIMailError(void) ............................................................................................. 5
Функции инициализации и работы с контекстом................................................................................. 5
EDIMailContext* InitContext(const char* szFilepath, mallocfun pAllocFun) ..................... 5
void FreeContext(EDIMailContext *ctx) ................................................................................................ 5
int GetMessageStatus(EDIMailContext *ctx, const char* szMessageId, int* pStatus) ......................... 5
Работа со скриптами ............................................................................................................................... 6
Выполнить скрипт int Execute(EDIMailContext *pCtx, const char* szScript, char** pResult) ........... 6
Добавить примесь к контексту int AddMixin(EDIMailContext* ctx, const char* szName, const
char* szMixin) ....................................................................................................................................... 6
Удалить примесь из контекста int RemoveMixin(EDIMailContext* ctx, const char* szName) ......... 6
Адресация ................................................................................................................................................ 6
Объекты типа EDIMailAddress ............................................................................................................. 7
Атрибуты EDIMailAddress ................................................................................................................ 7
Конструктор int InitEDIMailAddress(EDIMailAddress* pAddress, EDIMailContext *ctx, const char*
szTicker, const char* szService, const char* szEmail, const char* szKey, const char* szMixin)........... 7
Конструктор по внутреннему номеру объекта int InitEDIMailAddressByHandle(EDIMailAddress*
pAddress, EDIMailContext *ctx, unsigned int uiHandle) ...................................................................... 7
Деструктор int FreeEDIMailAddress(EDIMailAddress* pAddress) ....................................................... 8
Получение атрибутов объекта int GetEDIMailAddressProperty(const EDIMailAddress* pAddress,
const char* szProperty, char** pValue) ............................................................................................... 8
Получение внутреннего номера объекта int GetEDIMailAddressHandle(const EDIMailAddress*
pAddress) .............................................................................................................................................. 8
Работа с потоками ................................................................................................................................... 8
Атрибуты потоков ................................................................................................................................ 8
Конструктор потока из файла InitEDIMailStreamFromFile(EDIMailStream* pStream,
EDIMailContext* ctx, const char* szFilename, const char* szFilemode, const char* szMixin) ............ 8
Конструктор потока из буфера памяти int InitEDIMailStreamFromBuffer(EDIMailStream*
pStream, EDIMailContext* ctx, const void* pBuffer, size_t size, const char* szMixin)........................ 8
Конструктор потока по внутреннему номеру объекта int
InitEDIMailStreamByHandle(EDIMailStream* pStream, EDIMailContext *ctx, unsigned int uiHandle)
............................................................................................................................................................... 9
Конструктор подпотока из потока int GetEDIMailSubstream(EDIMailStream* pSrcStream,
EDIMailStream* pSubstream, size_t start, size_t end) ......................................................................... 9
Деструктор объекта int FreeEDIMailStream(EDIMailStream* pStream) ............................................ 9
Получение атрибутов объекта int GetEDIMailStreamProperty(const EDIMailStream* pStream,
const char* szProperty, char** pValue) ............................................................................................... 9
Получение внутреннего номера объекта int GetEDIMailStreamHandle(const EDIMailStream*
pStream) ................................................................................................................................................ 9
Запись в поток size_t StreamWrite(EDIMailStream* pStream, const void* pBuffer, size_t len) ........ 9
size_t StreamRead(EDIMailStream* pStream, void* pBuffer, size_t len) ............................................ 9
size_t StreamTell(const EDIMailStream* pStream) .............................................................................. 9
size_t StreamLength(const EDIMailStream* pStream) ......................................................................... 9
size_t StreamSeek(EDIMailStream* pStream, size_t offset, int whence) ............................................. 9
size_t StreamWriteToStream(EDIMailStream* pSrcStream, EDIMailStream* pDestStream) .............. 9
Объекты типа EDIMailURL .....................................................................................................................10
Атрибуты EDIMailURL.........................................................................................................................10
Конструктор int InitEDIMailURL(EDIMailURL* pURL, EDIMailContext* ctx, const char* szURL, const
char* szMixin) .....................................................................................................................................11
Конструктор URL по внутреннему номеру объекта int InitEDIMailURLByHandle(EDIMailURL*
pURL, EDIMailContext *ctx, unsigned int uiHandle) ...........................................................................11
Деструктор int FreeEDIMailURL(EDIMailURL* pURL) ........................................................................11
Получение атрибутов объекта int GetEDIMailURLProperty(const EDIMailURL* pURL, const char*
szProperty, char** pV .........................................................................................................................11
Получение внутреннего номера объекта int GetEDIMailURLHandle(const EDIMailURL* pURL) ...11
Задать поток для приема данных от сервера int EDIMailURLSetWriteStream(EDIMailURL* pURL,
EDIMailStream* pStream) ...................................................................................................................11
Задать поток для отправки данных на сервер int EDIMailURLSetReadStream(EDIMailURL* pURL,
EDIMailStream* pStream) ...................................................................................................................11
Выполнить запрос к серверу int EDIMailURLPerform(EDIMailURL* pURL) ....................................11
Получение сообщений int EDIMailCollect(EDIMailURL* pURL, const char* szMixin, unsigned int*
pMessageCounter, EDIMailMessage** pMessage) ............................................................................12
Подтверждение получения сообщений int ConfirmMessage(EDIMailURL* pCollectURL, const
char* szMessageId, EDIMailURL* pSmtpURL) ....................................................................................12
Работа с сообщениями..........................................................................................................................12
Атрибуты EDIMailMessage .................................................................................................................12
Конструктор int InitEDIMailMessage(EDIMailMessage* pMessage, EDIMailContext *ctx,
EDIMailAddress* pAddress, const char* szMixin) ..............................................................................13
Конструктор сообщения из потока InitEDIMailMessageFromStream(EDIMailMessage* pMessage,
EDIMailContext *ctx, EDIMailStream* pStream, const char* szMixin) ..............................................13
Конструктор сообщения по внутреннему номеру объекта int InitEDIMailMessageByHandle
(EDIMailMessage* pMessage, EDIMailContext *ctx, unsigned int uiHandle) ....................................13
Деструктор int FreeEDIMailMessage(EDIMailMessage* pMessage) .................................................13
Получение атрибутов объекта int GetEDIMailMessageProperty(const EDIMailMessage*
pMessage, const char* szProperty, char** pValue) ...........................................................................13
Получение внутреннего номера объекта int GetEDIMailMessageHandle(const EDIMailMessage*
pMessage) ...........................................................................................................................................13
Прикрепление потока к сообщению для его пересылки int
EDIMailAttachStreamToMessage(EDIMailMessage* pMessage, EDIMailStream* pStream,
ProtectionLevel level) ..........................................................................................................................14
Сохранение сообщения в поток int EDIMailMessageToStream(const EDIMailMessage* pMessage,
EDIMailStream* pStream) ...................................................................................................................14
Получить адрес отправителя int GetEDIMailMessageSender(const EDIMailMessage* pMessage,
EDIMailAddress* pAddress) ................................................................................................................14
Получить количество прикрепленных к сообщению потоков int
GetNumOfEDIMailMessageAttachments(const EDIMailMessage* pMessage, int* pNum) ..............14
Сохранить прикрепленный к сообщению поток в указанный поток size_t
SaveEDIMailMessageAttachment(const EDIMailMessage* pMessage, int number, EDIMailStream*
pStream) ..............................................................................................................................................14
Получить дату и время создания сообщения int GetEDIMailMessageDate(const
EDIMailMessage* pMessage, time_t* pTime) ....................................................................................14
Получить имя файла прикрепленного потока int GetEDIMailMessageAttachmentFilename(const
EDIMailMessage* pMessage, int number, char** pValue) ................................................................15
Установить пользовательский заголовок сообщения int
SetEDIMailMessageCustomHeader(EDIMailMessage* pMessage, const char* szHeader, const char*
szValue) ...............................................................................................................................................15
Получить установленный пользователем заголовок сообщения int
GetEDIMailMessageCustomHeader(const EDIMailMessage* pMessage, const char* szHeader,
char** pValue) ....................................................................................................................................15
Удалить установленный пользователем заголовок int
RemoveEDIMailMessageCustomHeader(EDIMailMessage* pMessage, const char* szHeader) .......15
Отправка сообщения int PostMessageTo(const EDIMailMessage* pMessage, EDIMailURL*
pSmtpURL, char** pMsgId) .................................................................................................................15
Приложение – заголовочный файл библиотеки ....................................................................................15
Назначение системы
EDIMail предназначен для обмена сообщениями с прикрепленными к ним файлами с
гарантированной доставкой, причем EDIMail обеспечивает конфиденциальность и целостность
прикрепленных файлов и аутентификацию отправителя при условии использования
криптографического провайдера. В качестве провайдера возможно использование
криптопровайдера Валидата CSP для резидентов и PGP для нерезидентов. Необходимо отметить,
что выбор криптопровайдера происходит не на уровне настройки библиотеки. Выбор
криптопровайдера на уровне библиотеки должен быть обеспечен развертыванием
соотвествующей инфраструктуры.
Архитектура системы
Система состоит из сервиса Moscow Exchange EDIMail Service и DLL библиотеки, которая
используется в пользовательском приложении. Сервис EDIMail Service запускается при загрузке
системы и отслеживает изменения состояний отправленных сообщений, непосредственно
взаимодействует с почтовыми SMTP и IMAP серверами, выполняет криптографические операции.
DLL библиотека предоставляет доступ к функциям сервиса с помощью механизмов RPC
(удаленного вызова процедур). Данная архитектура выбрана из соображений безопасности.
Пользовательский процесс не имеет непосредственного доступа в адресное пространство сервиса
и не может скомпрометировать криптографическую информацию или вмешаться в работу
алгоритмов криптографии.
Система имеет в своем составе интерпретатор скриптового языка на основе стандарта ECMA-262
ECMAScript, известного также как JavaScript. Система создает по одному интерпретатору на
каждый инициализированный контекст библиотеки. Интерпретаторы изолированы друг от друга объекты одного интерпретатора недоступны из другого. Сервис допускает многопоточную работу,
но каждый контекст должен использоваться в пределах одного потока (thread).
Наличие скриптового языка расширяет возможности использования в пользовательском
приложении имеющихся в описании библиотеки объектов. Кроме указанного в описании
фиксированного набора атрибутов объекты могут иметь любое разумное количество
дополнительных атрибутов, непосредственно доступных из скриптового языка и с помощью API,
указанного в разделе «Доступ к дополнительным атрибутам объектов» из других языков.
DLL библиотека предоставляет С-интерфейс к объектам и функциям сервиса, и, если не оговорено
противное, функции возвращают код ошибки. Коды ошибок:
EDIMAIL_OK = 0 кода ошибки означает успешное завершение;
EDIMAIL_INVALID_PTR – один или несколько параметров- указателей являются недопустимыми;
EDIMAIL_SERVICE_ERR – выполнение функции завершилось ошибкой, подробное сообщение об
ошибке можно получить с помощью вызова GetLastEDIMailError;
EDIMAIL_RPC_FAIL – невозможно связаться с сервисом EDIMail, причиной может быть остановка
сервиса или неверные параметры настройки связи с сервисом;
EDIMAIL_NO_MEMORY – указанная при инициализации контекста функция выделения памяти не
смогла выделить память.
Как правило, в вызовах библиотеки используются указатели на структуры, память для которых
резервируется пользователем до вызова. Если в результате вызова библиотеки происходит
выделение памяти, это каждый раз оговаривается особо.
Функция получения сообщения об ошибке
const char* GetLastEDIMailError(void)
Функция возвращает текст сообщения о последней ошибке в данном потоке (thread).
Возвращаемый указатель показывает на внутренний буфер библиотеки, поэтому не нужно
освобождать память по этому указателю.
Функции инициализации и работы с контекстом
EDIMailContext* InitContext(const char* szFilepath, mallocfun pAllocFun)
Функция инициализации библиотеки. В качестве параметров ей передается имя файла с
параметрами и функция выделения памяти аналогичная malloc
Файл с параметрами должен иметь формат
[секция]
параметр=значение
параметр=значение
[секция]
параметр=значение
и т.д.
Функция предназначена для создания контекста, в котором хранятся все пользовательские
объекты. Контекст связан с создавшим его потоком (thread). При завершении потока контекст
будет уничтожен вместе со всеми созданными объектами. Контекст может определять
дополнительные атрибуты и методы для создаваемых объектов. Конструктор каждого
создаваемого объекта позволяет указать имя примеси (mixin) для создаваемого объекта. Имя
примеси ищется в контексте, и методы, атрибуты найденной примеси используются при
инициализации объекта. Для создания примесей в контексте можно использовать вызовы API и
секцию [global] в ini файле. Например, такая секция
[global]
myUrl=({login:’test01’, password:’123’})
создаст объект myUrl с атрибутами login и password.
При окончании работы с библиотекой контекст должен быть освобожден функцией FreeContext.
void FreeContext(EDIMailContext *ctx)
Функция освобождает память и другие ресурсы, связанные с контекстом библиотеки. После этого
вызова использование функций библиотеки будет завершаться с ошибкой.
int GetMessageStatus(EDIMailContext *ctx, const char* szMessageId, int* pStatus)
Функция возвращает статус отправленного сообщения по его идентификатору, полученному при
отправке. Если сообщение было отправлено в несколько адресов или сервисов, возвращается
«худший» статус, т.е. если сообщение, например, послано в два адреса, по одному доставлено, по
другому – нет, статус будет «не доставлено».
int GetExactMessageStatus(EDIMailContext *ctx, const char* szMessageId, EDIMailAddress*
pAddress, * pStatus, char** pValue)
Функция возвращает статус отправленного сообщения по его идентификатору и адресу доставки.
Если адрес доставки является групповым, функция работает как предыдущая, возвращая
«худший» статус и соответствующее ему сообщение об ошибке. Если адрес уникальный,
возвращается результат доставки именно по этому адресу.
Работа со скриптами
Все функции С-интерфейса библиотеки имеют свои аналоги в Javascript. Через Javascript
организован доступ к параметрам .ini файла, использованного при инициализации контекста.
.ini файлу соответствует объект iniFile, секциям .ini файла – атрибуты iniFile, параметрам секций –
атрибуты атрибутов. Например, такой .ini файл
[myIMAP]
url = imap://ex.micex.com
login = myCompany
password = 123
будет доступен как iniFile.myIMAP.url, iniFile.myIMAP.login, iniFile.myIMAP.password
Секция [global] .ini файла используется для создания функций и объектов, доступных для всех
скриптов в данном контексте.
Выполнить скрипт int Execute(EDIMailContext *pCtx, const char* szScript, char** pResult)
Память для возвращаемого значения pResult резервируется библиотекой и должна быть
освобождена пользователем. Если скрипт выполнился с ошибкой, pResult будет равно NULL, а
диагностика ошибок доступна через вызов GetLastEDIMailError.
Добавить примесь к контексту int AddMixin(EDIMailContext* ctx, const char* szName,
const char* szMixin)
Вычисляет скрипт szMixin и добавляет его к контексту под именем szName. Это имя можно
использовать в конструкторах объектов для ссылок на этот объект в качестве примеси. При
добавлении примесей с одинаковым именем ранее добавленная замещается на вновь
добавляемую. Эта ситуация не является ошибкой.
Удалить примесь из контекста int RemoveMixin(EDIMailContext* ctx, const char* szName)
Из контекста удаляется примесь с указанным именем. Объекты, созданные с использованием
удаленной примеси, никак не изменяются.
Адресация
Цель работы библиотеки – доставить сообщение в хранилище сообщений, откуда его получит
(заберет) адресат. Под адресатом понимается клиент ЭДО, имеющий наименование, ИНН,
биржевой тикер, криптографический сертификат и несколько хранилищ сообщений для разных
целей (сервисов). Хранилищем сообщений в данной реализации библиотеки выступает папка на
IMAP сервере. Все клиенты системы EDIMail зарегистрированы в базе данных клиентов ЭДО,
которая используется для поиска почтовых адресов клиентов по их реквизитам – ИНН,
наименованию, биржевому тикеру и DN сертификата.
Объекты типа EDIMailAddress
Для адресации исходящих сообщений используется объект типа EDIMailAddress. Этот объект
инкапсулирует связь между атрибутами клиента ЭДО и его адресом электронной почты.
Атрибуты EDIMailAddress
Этот объект имеет следующие атрибуты, доступные с помощью вызова GetEDIMailAddressProperty:
dn – идентификатор сертификата в LDAP
email – почтовый адрес вида who@compary.com
key – наименование организации в старом LDAP, как правило, латиницей
ticker – биржевой код организации, часть старого почтового адреса
service – сервис ЭДО, часть старого почтового адреса
handle – внутренний номер объекта для работы с объектами созданными в JavaScript через Синтерфейс и наоборот.
access – тип доступа к почте
issuer_dn – идентификатор издателя сертификата организации в LDAP
is_default – почта используется по умолчанию
inn – ИНН организации
fullname – полное наименование организации из LDAP, как правило, кириллицей.
Конструктор int InitEDIMailAddress(EDIMailAddress* pAddress, EDIMailContext *ctx, const
char* szTicker, const char* szService, const char* szEmail, const char* szKey, const char*
szMixin)
В конструктор передается адрес уже существующей структуры EDIMailAddress, конструктор только
инициализирует ее необходимыми данными.
Создает объект адрес, связанный с контекстом ctx.
Объект будет автоматически удален при освобождении контекста, если он не был удален ранее.
При создании объекта в конструкторе может быть задано любое допустимое сочетание из
четырех атрибутов – биржевой тикер, сервис ЭДО, электронная почта, наименование или ИНН
организации. При работе с объектом обращение к не определенному в конструкторе атрибуту
вызовет обращение к функции контекста библиотеки, которая выполнит поиск значения в
справочнике или выбор значения по умолчанию. Недопустимое сочетание атрибутов в
конструкторе вызовет ошибку-исключение и объект EDIMailAddress создан не будет. Примером
недопустимого сочетания атрибутов является, например, указание в szKey несуществующего ИНН.
Конструктор по внутреннему номеру объекта int
InitEDIMailAddressByHandle(EDIMailAddress* pAddress, EDIMailContext *ctx, unsigned int
uiHandle)
Создает объект по внутреннему номеру существующего объекта. Может использоваться для
продолжения работы в С-интерфейсе с объектом, созданным в Javascript-интерфейсе библиотеки.
Деструктор int FreeEDIMailAddress(EDIMailAddress* pAddress)
Уничтожает существующий объект. В JavaScript интерфейсе для этих целей используется метод
dispose()
Получение атрибутов объекта int GetEDIMailAddressProperty(const EDIMailAddress*
pAddress, const char* szProperty, char** pValue)
szPrioperty – имя атрибута или метода без параметров. Встроенные имена атрибутов были
перечислены выше, дополнительные атрибуты и методы могут быть созданы с помощью
Javascript или унаследованы от примеси szMixin, указанной в конструкторе. Память для
возвращаемого значения pValue резервируется библиотекой и должна быть освобождена
пользователем.
Получение внутреннего номера объекта int GetEDIMailAddressHandle(const
EDIMailAddress* pAddress)
Возвращает внутренний номер объекта, для использования этого объекта в Javascript. Объект в
Javascript получается как EDIMailAddress[номер_объекта].
Работа с потоками
Потоки используются для обеспечения единообразной работы с буферами в памяти и файлами на
диске. Операции с потоками повторяют обычный набор операций с файлами. При записи в поток,
находящийся в буферах памяти, его размер увеличивается «прозрачным» для пользователя
способом. Потоки используются для «прикрепления» информации к пересылаемому сообщению.
Обратите внимание, что прикрепляется не все содержимое потока, а начиная от текущей позиции
до конца потока, т.е. можно прочитать начало потока и переслать его остаток.
Атрибуты потоков
Поток имеет следующие встроенные атрибуты:
tell – текущая позиция потока;
length – длина потока в байтах;
fileName – имя потока, при создании потока из файла устанавливается равным имени файла в
каталоге, например, файл C:\Temp\example.txt будет иметь атрибут fileName равным example.txt.
При пересылке потока сообщением атрибут fileName сохраняется (длина, конечно же, тоже);
handle – внутренний номер объекта, используется для продолжения работы с объектом,
созданным в Javascript-интерфейсе библиотеки в С-интерфейсе и наоборот.
Конструктор потока из файла InitEDIMailStreamFromFile(EDIMailStream* pStream,
EDIMailContext* ctx, const char* szFilename, const char* szFilemode, const char* szMixin)
Создает поток из файла по аналогии с вызовом fopen стандартной библиотеки. В отличие от
стандартной библиотеки можно указать szFilemode равным “tmpfile” для создания временного
файла, удаляемого при вызове деструктора потока и szFilemode равным “crnx” для создания
файла только в случае, если указанного имени нет в каталоге.
Конструктор потока из буфера памяти int InitEDIMailStreamFromBuffer(EDIMailStream*
pStream, EDIMailContext* ctx, const void* pBuffer, size_t size, const char* szMixin)
Создает поток в памяти и инициализирует его содержимым указанного буфера. Указанный буфер
после создания потока никак не используется и может быть освобожден. Созданный поток имеет
указанный в конструкторе размер, при записи в поток его размер будет увеличиваться. Атрибут
fileName потока можно задать с помощью примеси, например, установив szMixin равным
“({fileName: ‘myfile.txt’})”.
Конструктор потока по внутреннему номеру объекта int
InitEDIMailStreamByHandle(EDIMailStream* pStream, EDIMailContext *ctx, unsigned int
uiHandle)
Создает объект по внутреннему номеру существующего объекта. Может использоваться для
продолжения работы в С-интерфейсе с объектом, созданным в Javascript-интерфейсе библиотеки.
Конструктор подпотока из потока int GetEDIMailSubstream(EDIMailStream* pSrcStream,
EDIMailStream* pSubstream, size_t start, size_t end)
Создает подпоток – новый поток, являющийся частью существующего потока и разделяющий с
существующим потоком свои данные. Примером применения подпотока может быть случай,
когда надо прикрепить к сообщению не весь файл, а его часть.
Деструктор объекта int FreeEDIMailStream(EDIMailStream* pStream)
Удаляет объект, закрывает файл, если поток был связан с файлом или освобождает память, если
поток был связан с памятью.
Получение атрибутов объекта int GetEDIMailStreamProperty(const EDIMailStream*
pStream, const char* szProperty, char** pValue)
szPrioperty – имя атрибута или метода без параметров. Встроенные имена атрибутов были
перечислены выше, дополнительные атрибуты и методы могут быть созданы с помощью
Javascript или унаследованы от примеси szMixin, указанной в конструкторе. Память для
возвращаемого значения pValue резервируется библиотекой и должна быть освобождена
пользователем.
Получение внутреннего номера объекта int GetEDIMailStreamHandle(const
EDIMailStream* pStream)
Возвращает внутренний номер объекта, для использования этого объекта в Javascript. Объект в
Javascript получается как EDIMailStream[номер_объекта].
Запись в поток size_t StreamWrite(EDIMailStream* pStream, const void* pBuffer, size_t len)
Возвращает количество записанных в поток байт.
size_t StreamRead(EDIMailStream* pStream, void* pBuffer, size_t len)
Возвращает количество считанных байт
size_t StreamTell(const EDIMailStream* pStream)
Возвращает текущую позицию в потоке
size_t StreamLength(const EDIMailStream* pStream)
Возвращает длину потока в байтах
size_t StreamSeek(EDIMailStream* pStream, size_t offset, int whence)
Устанавливает текущую позицию потока, параметры аналогичны стандартному seek.
size_t StreamWriteToStream(EDIMailStream* pSrcStream, EDIMailStream* pDestStream)
Копирует содержимое одного потока в другой начиная с текущей позиции до конца потока.
Возвращает число скопированных байт.
Объекты типа EDIMailURL
Объекты этого типа используются для получения доступа к хранилищам сообщений – IMAP
серверам и SMTP серверам для отправки сообщений.
Некоторые атрибуты EDIMailURL объектов используются для авторизации доступа к
соответствующим серверам, например атрибуты login и password. Эти атрибуты могут указываться
в строке url или передаваться из примеси. В примерах показано, как задавать эти атрибуты с
помощью секций в .ini файлах. Это не является рекомендуемой практикой, а только самым
лаконичным способом иллюстрирует работу библиотеки. Способ хранения логинов и паролей
целиком определяется пользователем библиотеки, а в конструкторы объектов EDIMailURL они
передаются или в строке url или с помощью механизма примесей. Указание атрибута в примеси
имеет приоритет.
Атрибуты EDIMailURL
login – имя пользователя, строка, используемая для авторизации доступа к серверу;
password – пароль, строка, используемая для авторизации доступа к серверу;
useTls – Использование TLS для IMAP и SMTP:



0 – не использовать, если сервер требует TLS/SSL, соединения с сервером не происходит;
1 – использовать по возможности, если сервер допускает использование TLS/SSL, то оно
используется;
2 – обязательно использовать, если сервер не поддерживает TLS/SSL, соединения с
сервером не происходит.
tlsFirst – Порядок запуска протоколов для IMAP и SMTP:


0 – сначала запускается почтовый протокол, потом по команде протокола STARTTLS
запускается TLS;
1 – сначала запускается TLS/SSL, а затем поверх запускается почтовый протокол.
Этот параметр может задаваться в строке url путем добавления “s” к схеме url, например
imaps://… вместо imap://…
tlsCheck – Проверка сертификата SMTP и IMAP сервера:



0 – не производится;
1 – проверяется соответствие имени сервера, с которым было установлено соединение и
имени сервера в сертификате;
2 – проверка совпадения имени сервера и проверка валидности самого сертификата,
самоподписанные сертификаты эту проверку не проходят;
url – строка, указанная в конструкторе. Атрибут только для чтения;
handle – внутренний номер объекта для работы с объектами созданными в JavaScript через Синтерфейс и наоборот.
Конструктор int InitEDIMailURL(EDIMailURL* pURL, EDIMailContext* ctx, const char*
szURL, const char* szMixin)
Создает объект, который можно использовать в дальнейшем для доступа к IMAP, SMTP а также
HTTP и FTP серверам. Все атрибуты, которые можно заполнить с помощью информации,
содержащейся в строке URL, будут заполнены. Конструктор не проводит никаких проверок, типа
существования и/или доступности сервера, кроме синтаксических. Создание объекта не означает,
что к адресуемому серверу можно будет получить доступ в дальнейшем. При обнаружении
синтаксических ошибок в строке URL объект не создается, возникает ошибка. Объект будет
автоматически удален при освобождении контекста, если он не был удален ранее. Необходимые
для авторизации атрибуты можно установить с помощью szMixin. В простейшем случае из .ini
файла. Используя ранее приведенный пример .ini файла szMixin надо задать как “iniFile.myIMAP”.
Конструктор URL по внутреннему номеру объекта int
InitEDIMailURLByHandle(EDIMailURL* pURL, EDIMailContext *ctx, unsigned int uiHandle)
Создает объект по внутреннему номеру существующего объекта. Может использоваться для
продолжения работы в С-интерфейсе с объектом, созданным в Javascript-интерфейсе библиотеки.
Деструктор int FreeEDIMailURL(EDIMailURL* pURL)
Уничтожает существующий объект. В JavaScript интерфейсе для этих целей используется метод
dispose()
Получение атрибутов объекта int GetEDIMailURLProperty(const EDIMailURL* pURL, const
char* szProperty, char** pV
szPrioperty – имя атрибута или метода без параметров. Встроенные имена атрибутов были
перечислены выше, дополнительные атрибуты и методы могут быть созданы с помощью
Javascript или унаследованы от примеси szMixin, указанной в конструкторе. Память для
возвращаемого значения pValue резервируется библиотекой и должна быть освобождена
пользователем.
Получение внутреннего номера объекта int GetEDIMailURLHandle(const EDIMailURL*
pURL)
Возвращает внутренний номер объекта, для использования этого объекта в Javascript. Объект в
Javascript получается как EDIMailURL[номер_объекта].
Задать поток для приема данных от сервера int
EDIMailURLSetWriteStream(EDIMailURL* pURL, EDIMailStream* pStream)
Задает поток, в который будут записаны данные, полученные от адресуемого URL сервера при
выполнении вызова EDIMailURLPerform. Может использоваться для получения данных от HTTP,
FTP серверов.
Задать поток для отправки данных на сервер int
EDIMailURLSetReadStream(EDIMailURL* pURL, EDIMailStream* pStream)
Задает поток, данные из которого будут отправлены на сервер при выполнении вызова
EDIMailURLPerform. Может использоваться для обмена данными с HTTP, FTP серверами.
Выполнить запрос к серверу int EDIMailURLPerform(EDIMailURL* pURL)
Выполняет обмен данными с адресуемым URL сервером.
Получение сообщений int EDIMailCollect(EDIMailURL* pURL, const char* szMixin,
unsigned int* pMessageCounter, EDIMailMessage** pMessage)
Выполняет опрос указанного pURL IMAP сервера для получения новых (неподтвержденных)
сообщений. Примесь szMixin используется для придания получаемым сообщениям нестандартных
атрибутов и методов, pMessageCounter указывает на целую переменную, которая до вызова
задает максимальное ожидаемое количество сообщений, а после вызова – фактически принятое
количество сообщений. pMessage после вызова указывает на последовательность (массив)
принятых сообщений. pMessage[0] – первое сообщение, pMessage[1] – второе и т.д. Память,
выделенная под массив сообщений, должна быть освобождена пользователем библиотеки
самостоятельно.
Возврат из вызова происходит после завершения сеанса связи с IMAP сервером, в зависимости от
скорости соединения с сервером и количества принимаемых сообщений для завершения вызова
может потребоваться некоторое время.
Подтверждение получения сообщений int ConfirmMessage(EDIMailURL* pCollectURL,
const char* szMessageId, int status, const char* szReason, EDIMailURL* pSmtpURL)
Выполняет подтверждение получения сообщений для механизма гарантированной доставки. URL
pSmtpURL используется для отправки подтверждающего получение сообщения и должен
указывать на SMTP сервер. URL pCollectURL должен быть тем же самым, который использовался в
вызове EDIMailCollect для получения подтверждаемого сообщения. Подтверждаемое сообщение
идентифицируется своим messageId, которое является одним из атрибутов сообщения и доступно
после его получения.
Подтвержденное сообщение не будет более передаваться при вызове EDIMailCollect.
Неподтвержденные сообщения будут передаваться вызовом EDIMailCollect вплоть до получения
подтверждения.
Параметры status и szReason используются для указания было ли сообщение обработано
получателем правильно (нулевой status) или нет, и позволяют передать отправителю текст с
причиной отказа.
Работа с сообщениями
Пересылаемые по электронной почте сообщения имеют MIME или S/MIME формат. Для создания
новых или анализа принятых сообщений в этом формате используется класс EDIMailMessage.
Атрибуты EDIMailMessage
messageId – уникальный идентификатор сообщения, определяется отправителем. Так как одно и
тоже сообщение можно послать нескольким адресатам, нельзя использовать messageId в качестве
уникального ключа без учета адресата сообщения. Посылаемым сообщениям messageId
присваивается библиотекой автоматически.
sender – адрес отправителя в формате RFC822, т.е. он может включать имя отправителя и его email в угловых скобках.
date – строка - UTC время отправки сообщения в формате RFC822.
senderService – сервис ЭДО, от имени которого послано сообщение, задается отправителем и
может быть пустой строкой.
ediMailSender – объект EDIMailAddress, соответствующий отправителю. С помощью его свойств
можно узнать полное наименование отправителя его ИНН и т.д. см. описание EDIMailAddress.
recepients – адреса получателей в формате RFC822 через запятую, если их несколько.
subject – тема письма.
Date – дата сообщения, контекст определяет ее дате цифровой подписи если она присутствует или
по текущей дате
subject – тема сообщения;
numStreams – количество присоединенных к сообщению потоков.
handle – внутренний номер объекта для работы с объектами созданными в JavaScript через Синтерфейс и наоборот.
Конструктор int InitEDIMailMessage(EDIMailMessage* pMessage, EDIMailContext *ctx,
EDIMailAddress* pAddress, const char* szMixin)
Создает сообщение указанному адресату. С помощью примеси можно задать тему и текстовую
часть сообщения. Атрибуты примеси header, caption, title будут использованы в качестве subject
создаваемого сообщения, атрибут text примеси – в качестве содержимого текстовой части.
Пример szMixin: “({caption: ‘Отчеты о продажах’, text: ‘Отчеты за август, см. приложения’})”.
Конструктор сообщения из потока InitEDIMailMessageFromStream(EDIMailMessage*
pMessage, EDIMailContext *ctx, EDIMailStream* pStream, const char* szMixin)
Создает сообщение из потока, куда ранее сообщение было сохранено вызовом
EDIMailMessageToStream. Из потока может быть восстановлено только одно сообщение.
Конструктор сообщения по внутреннему номеру объекта int
InitEDIMailMessageByHandle (EDIMailMessage* pMessage, EDIMailContext *ctx, unsigned
int uiHandle)
Создает объект по внутреннему номеру существующего объекта. Может использоваться для
продолжения работы в С-интерфейсе с объектом, созданным в Javascript-интерфейсе библиотеки.
Деструктор int FreeEDIMailMessage(EDIMailMessage* pMessage)
Уничтожает существующий объект. В JavaScript интерфейсе для этих целей используется метод
dispose().
Получение атрибутов объекта int GetEDIMailMessageProperty(const EDIMailMessage*
pMessage, const char* szProperty, char** pValue)
szPrioperty – имя атрибута или метода без параметров. Встроенные имена атрибутов были
перечислены выше, дополнительные атрибуты и методы могут быть созданы с помощью
Javascript или унаследованы от примеси szMixin, указанной в конструкторе. Память для
возвращаемого значения pValue резервируется библиотекой и должна быть освобождена
пользователем.
Получение внутреннего номера объекта int GetEDIMailMessageHandle(const
EDIMailMessage* pMessage)
Возвращает внутренний номер объекта, для использования этого объекта в Javascript. Объект в
Javascript получается как EDIMailMessage[номер_объекта]
Прикрепление потока к сообщению для его пересылки int
EDIMailAttachStreamToMessage(EDIMailMessage* pMessage, EDIMailStream* pStream,
ProtectionLevel level)
Прикрепляет поток к сообщению и применяет к нему указанную степень криптографической
защиты:
Cleartext – никакой защиты, сообщение может быть прочтено любым почтовым клиентом;
Signed – прикрепляемый файл подписывается отправителем, подпись и файл прикрепляются по
отдельности, сообщение может быть получено любым почтовым клиентом, почтовый клиент,
поддерживающий S/MIME, может проверить подпись;
SignedEncrypted – прикрепляемый файл подписывается присоединенной цифровой подписью и
зашифровывается, почтовые клиенты просто видят прикрепленный файл;
MIMESignedEncrypted - прикрепляемый файл подписывается отсоединенной цифровой подписью,
подпись и файл прикрепляются по отдельности и вместе зашифровывается, почтовые клиенты,
не поддерживающие S/MIME, просто видят прикрепленный файл со стандартным названием,
почтовые клиенты, поддерживающие S/MIME, могут расшифровать приложение и проверить
подпись.
Все защиты, кроме Cleartext, обеспечивают защиту целостности передаваемого потока и
аутентификацию отправителя, защиты SignedEncrypted и MIMESignedEncrypted обеспечивают
дополнительно защиту конфиденциальности передаваемого потока.
Сохранение сообщения в поток int EDIMailMessageToStream(const EDIMailMessage*
pMessage, EDIMailStream* pStream)
Сохраняет указанное сообщение со всеми прикрепленными потоками в указанный поток в MIME
формате. Может использоваться для сохранения шаблонов типовых сообщений.
Получить адрес отправителя int GetEDIMailMessageSender(const EDIMailMessage*
pMessage, EDIMailAddress* pAddress)
Инициализирует pAddress данными отправителя сообщения. С помощью pAddress и вызова
GetEDIMailAddressProperty можно узнать полное наименование отправителя, его ИНН, данные
сертификата и т.п.
Получить количество прикрепленных к сообщению потоков int
GetNumOfEDIMailMessageAttachments(const EDIMailMessage* pMessage, int* pNum)
Возвращает в указываемой pNum целой переменной количество прикрепленных к сообщению
потоков.
Сохранить прикрепленный к сообщению поток в указанный поток size_t
SaveEDIMailMessageAttachment(const EDIMailMessage* pMessage, int number,
EDIMailStream* pStream)
Прикрепленные потоки всегда нумеруются, начиная с 1. Поток номер 0 – текстовая часть
сообщения, но она может отсутствовать.
Возвращается число сохраненных байт. Если при отправке применялась криптография,
сохраняемый поток предварительно дешифруется и проверяется на целостность, проверяется
соответствие сертификата цифровой подписи адресу отправителя. Непрошедший проверки поток
не сохраняется, возвращается размер 0 и устанавливается сообщение об ошибке.
Получить дату и время создания сообщения int GetEDIMailMessageDate(const
EDIMailMessage* pMessage, time_t* pTime)
Дата и время берутся из заголовков сообщения не защищенных криптографией.
Получить имя файла прикрепленного потока int
GetEDIMailMessageAttachmentFilename(const EDIMailMessage* pMessage, int number,
char** pValue)
Возвращается значение атрибута fileName прикрепленного потока. Если прикреплялся поток,
созданный из файла, то этот атрибут содержал имя и расширение имени прикрепленного файла.
Прикрепленные потоки нумеруются, начиная с 1.
Пользователь библиотеки должен освободить память, выделенную для хранения имени файла в
pValue.
Установить пользовательский заголовок сообщения int
SetEDIMailMessageCustomHeader(EDIMailMessage* pMessage, const char* szHeader, const
char* szValue)
Пользователь может передавать вместе с сообщением произвольное количество пар имя
атрибута – значение. Имя атрибута передается в szHeader и должно содержать только латинские
буквы и цифры, значение szValue может содержать любые ненулевые байты и кончаться 0.
Получить установленный пользователем заголовок сообщения int
GetEDIMailMessageCustomHeader(const EDIMailMessage* pMessage, const char* szHeader,
char** pValue)
Пользователь может передать вместе с сообщением пары имя атрибута – значение. Для
получения надо задать имя атрибута в szHeader, оно должно содержать только латинские буквы и
цифры. Возвращаемое значение pValue может содержать любые ненулевые байты и кончается 0.
Пользователь должен освободить память, выделенную для хранения полученного в pValue
заголовка.
Удалить установленный пользователем заголовок int
RemoveEDIMailMessageCustomHeader(EDIMailMessage* pMessage, const char* szHeader)
Удаляет ранее установленный пользователем заголовок из сообщения.
Отправка сообщения int PostMessageTo(const EDIMailMessage* pMessage, EDIMailURL*
pSmtpURL, char** pMsgId)
Отправляет указанное сообщение на SMTP сервер, адресуемый URL pSmtpURL и возвращает
уникальный идентификатор отправленного сообщения. Пользователь должен освободить память,
выделенную для хранения идентификатора сообщения в pMsgId.
Используемый для отправки pSmtpURL должен иметь все необходимые атрибуты для
установления содинения с SMTP сервером – логин, пароль, настройки TLS (transport layer security)
и т.п.
Возврат из вызова происходит после завершения сеанса связи с SMTP сервером, в зависимости от
скорости соединения с сервером для завершения вызова может потребоваться некоторое время.
JavaScript интерфейс к функциям сервиса
Практически все, что можно сделать с помощью описанного выше С-интерфейса, можно сделать с
помощью объектов и методов встроенного JavaScript. Объекты, созданные с помощью вызовов Синтерфейса можно обрабатывать с помощью JavaScript, и наоборот, созданные в JavaScript
объекты (не любые, конечно, а описанных выше типов) можно получить в С-интерфейсе и
продолжить обработку там.
Создание объектов в JavaScript
Аргументы конструкторов в JavaScript такие же и идут в том же порядке, что и в Init… вызовах Синтерфейса, за исключением того, что все JavaScript объекты существуют только в рамках одного
контекста, того, который выполняет данный скрипт, и, поэтому, указание контекста в
конструкторах отсутствует. Приведем пример:
var addr = EDIMailAddress(“TROIM”, “REPORT“); /* создаем адрес для участника с тикером TROIM
для сервиса REPORT */
var message = EDIMailMessage(addr); /* Создаем сообщение для адресата TROIM */
var stream = EDIMailStream(“C:\myreport.txt”, “rt”); /* файл для отсылки */
message.attachStream(stream, 3); /* Прикрепить файл для отсылки к сообщению по правилам
S/MIME с подписью и шифрованием */
var url = EDIMailURL(“smtp://aspmx.l.google.com”); /* создаем url для отсылки письма */
url.login = “mylogin”; url.password = “mypassword”; /* настраиваем url */
message.postTo(url); /* отсылаем сообщение через почту google*/
JavaScript обладает свойством интроспекции, т.е. с помощью языка можно узнавать свойства
объектов у самих объектов:
for (var prop in message)
{
print(“message property ”, prop, “ have value “, message[prop], “\n”);
}
Приложение – заголовочный файл библиотеки
/****************************** Module Header ******************************\
* Module Name: EDIMail.dll
* Project:
EDIMailService
* Copyright (c) 2013, Moscow Exchange
*
* The EDIMail library API description
*
\***************************************************************************/
#ifndef __MIMICRY__EDIMAIL_H
#define __MIMICRY__EDIMAIL_H
#pragma once
// The following ifdef block is the standard way of creating macros which make exporting
// from a DLL simpler. All files within this DLL are compiled with the EDIMAILDLL_EXPORTS
// symbol defined on the command line. This symbol should not be defined on any project
// that uses this DLL. This way any other project whose source files include this file see
// EDIMAILDLL_API functions as being imported from a DLL, whereas this DLL sees symbols
// defined with this macro as being exported.
#ifdef EDIMAILDLL_EXPORTS
#define EDIMAILDLL_API __declspec(dllexport)
#else
#define EDIMAILDLL_API __declspec(dllimport)
#endif
#ifdef __cplusplus
extern "C" {
#endif
namespace MIMICry {
#pragma region Error handling
// Error codes
enum error_codes {
// 0 - function completed successfully
EDIMAIL_OK = 0,
// One or more function input parameters is a NULL pointer
EDIMAIL_INVALID_PTR,
// Service return error
EDIMAIL_SERVICE_ERR,
// Service unaccessible
EDIMAIL_RPC_FAIL,
// Callback function for memory allocation return NULL pointer
EDIMAIL_NO_MEMORY
};
// Do not deallocate pointer to error message
EDIMAILDLL_API const char* GetLastEDIMailError(void);
#pragma endregion
#pragma region Context initialization and handling
typedef void* (*mallocfun)(size_t);
typedef struct EDIMailContext_s {} EDIMailContext;
typedef struct EDIMailAddress_s {
int handle;
EDIMailContext *pCtx;
} EDIMailAddress;
// Description:
// Library initialization function. Must be called first before any other call.
// Every thread must initialize and use it's own context, context must not be shared between different
threads.
//
// Parameres:
// filepath - C-string, path of Windows-style .ini file with parameters for context initialization
//
EDIMAILDLL_API EDIMailContext* InitContext(const char* szFilepath, mallocfun pAllocFun);
// Description:
// Free resources used by library context
//
// Parameres:
// ctx - previously initialized context
//
EDIMAILDLL_API void FreeContext(EDIMailContext* ctx);
// Description:
// Get message status from local message database.
// If message is addressed to several destinations returns the worst status.
//
// Parameres:
// ctx - previously initialized context
// pMessageId - pointer to unique message id string. Message id may be obtained by call
//
GetEDIMailMessageProperty(const EDIMailMessage* pMessage, "messageId", char**
pValue);
// pStatus - pointer to preallocated int receiving message status after the call
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int GetMessageStatus(EDIMailContext *ctx, const char* szMessageId, int* pStatus);
// Description:
// Get message status from local message database.
//
// Parameres:
// ctx - previously initialized context
// pMessageId - pointer to unique message id string. Message id may be obtained by call
//
GetEDIMailMessageProperty(const EDIMailMessage* pMessage, "messageId", char**
pValue);
// pAddress - pointer to initialized EDIMailAddress message was sent to
// pStatus - pointer to preallocated int receiving message status after the call
// pValue - preallocated pointer to be initialised by returned C-string error message in case of failed
//
message delivery or processing. C-string is allocated by callback function provided during
context initialisation.
//
Caller must free allocated memory.
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int GetExactMessageStatus(EDIMailContext *ctx, const char* szMessageId,
EDIMailAddress* pAddress,
int* pStatus, char** pValue);
// Description:
// Get EDIMailAdress object initialized to self address. This address to be used as sender address in all
outgoing messages.
//
// Parameres:
// ctx - previously initialized context
// pAddress - pointer to preallocated EDIMailAddress structure
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int GetEDIMailSenderAddress(EDIMailContext *ctx, EDIMailAddress* pAddress);
#pragma endregion
#pragma region Addressing
// Description:
// Create address object for at least one or more business enities from any not empty valid
combination of excange ticker,
// EDI service used, business entity e-mail, LDAP business entity key.
// LDAP key may be INN for new qualified certificates or business entity LDAP name.
// Created object may borrow properties from optional mixin, mixin may be created with AddMixin
call.
//
// Parameres:
// pAddress - pointer to preallocated EDIMailAddress structure to be initialised.
// ctx - previously initialized context
// szTicker - exchange ticker like GAZP for AO Gazprom
// szService - EDI service used, for example REPORTS
// szEmail - e-mail address
// szKey - business entity LDAP key like INN or LDAP name
// szMixin - mixin object name created by AddMixin call
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int InitEDIMailAddress(EDIMailAddress* pAddress, EDIMailContext *ctx, const char*
szTicker, const char* szService,
const char* szEmail, const char* szKey, const char* szMixin);
// Description:
// Create address object from handle obtained from EDIMailAddress object created by script.
//
// Parameres:
// pAddress - pointer to preallocated EDIMailAddress structure to be initialised.
// ctx - previously initialized context
// uiHandle - handle obtained from handle property of EDIMailAddress created by script.
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int InitEDIMailAddressByHandle(EDIMailAddress* pAddress, EDIMailContext *ctx,
unsigned int uiHandle);
// Destroy address object
//
// Parameres:
// pAddress - pointer to initialised EDIMailAddress structure
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int FreeEDIMailAddress(EDIMailAddress* pAddress);
// Description:
// Get object property. If address match several business entities property contain
// values for every entity separated by newline character.
//
// Parameres:
// pAddress - pointer to initialised EDIMailAddress structure
// szProperty - property name
// pValue - preallocated pointer to be initialised by returned C-string property value. Memory for
returned C-string
//
is allocated by callback function provided during context initialisation. Caller must free
//
allocated memory.
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int GetEDIMailAddressProperty(const EDIMailAddress* pAddress, const char*
szProperty, char** pValue);
// Description:
// Get object handle. Hadle value may be used in script to reference previously initialised object
// as EDIMailAddress[handle value].
//
// Parameres:
// pAddress - pointer to initialised EDIMailAddress structure
//
// Returns:
// Address handle. Valid handle can't be 0.
//
EDIMAILDLL_API int GetEDIMailAddressHandle(const EDIMailAddress* pAddress);
#pragma endregion
#pragma region Scripting
// Description:
// Execute string as a script, returning result of script evaluation and script compiling diagnostics.
// Compiling and run-time diagnostics may be obtained by GetLastEDIMailError call.
//
// Parameres:
// ctx - previously initialized context
// szScript - C-string, script to be executed
// pResult - preallocated pointer to be initialised by returned C-string result of script evaluation.
Memory for returned C-string
//
is allocated by callback function provided during context initialisation. Caller must free
//
allocated memory.
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int Execute(EDIMailContext *pCtx, const char* szScript, char** pResult);
// Description:
// Add object to library context as mixin. Mixin can be used as patterns later in object constructors
//
// Parameres:
// ctx - previously initialized context
// name - C-string, mixin name, must be unique
// szMixin - JavaScript string with mixin object
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int AddMixin(EDIMailContext* ctx, const char* szName, const char* szMixin);
// Description:
// Remove mixin from library context.
//
// Parameres:
// ctx - previously initialized context
// name - C-string, mixin name
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int RemoveMixin(EDIMailContext* ctx, const char* szName);
#pragma endregion
#pragma region Streams
typedef struct EDIMailFilter_s {
int handle;
EDIMailContext *pCtx;
} EDIMailFilter;
typedef struct EDIMailStream_s {
int handle;
EDIMailContext *pCtx;
} EDIMailStream;
typedef struct EDIMailMessage_s {
int handle;
EDIMailContext *pCtx;
} EDIMailMessage;
// Description:
// Create stream object for given file path and file mode like fopen call.
// Created object may borrow properties from optional mixin, mixin may be created with AddMixin
call.
//
// Parameres:
// pStream - pointer to preallocated EDIMailStream structure to be initialised.
// ctx - previously initialized context
// szFilename - full file path
// szFilemode - file mode like fopen call
// szMixin - mixin object name created by AddMixin call
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int InitEDIMailStreamFromFile(EDIMailStream* pStream, EDIMailContext* ctx, const
char* szFilename,
const char* szFilemode, const char* szMixin);
// Description:
// Create stream object for given buffer.
// Created object may borrow properties from optional mixin, mixin may be created with AddMixin
call.
//
// Parameres:
// pStream - pointer to preallocated EDIMailStream structure to be initialised.
// ctx - previously initialized context
// pBuffer - pointer to pre-allocated buffer initialised with data
// size - pre-allocated buffer size
// szMixin - mixin object name created by AddMixin call
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int InitEDIMailStreamFromBuffer(EDIMailStream* pStream, EDIMailContext* ctx, const
void* pBuffer,
size_t size, const char* szMixin);
// Description:
// Create stream object from handle obtained from EDIMailStream object created by script.
//
// Parameres:
// pStream - pointer to preallocated EDIMailStream structure to be initialised.
// ctx - previously initialized context
// uiHandle - handle obtained from handle property of EDIMailStream created by script.
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int InitEDIMailStreamByHandle(EDIMailStream* pStream, EDIMailContext *ctx,
unsigned int uiHandle);
// Destroy stream object
//
// Parameres:
// pStream - pointer to initialised EDIMailStream structure
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int FreeEDIMailStream(EDIMailStream* pStream);
// Description:
// Get object property. If address match several business entities property contain
// values for every entity separated by newline character.
//
// Parameres:
// pStream - pointer to initialised EDIMailStream structure
// szProperty - property name
// pValue - preallocated pointer to be initialised by returned C-string property value. Memory for
returned C-string
//
is allocated by callback function provided during context initialisation. Caller must free
//
allocated memory.
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int GetEDIMailStreamProperty(const EDIMailStream* pStream, const char* szProperty,
char** pValue);
// Description:
// Get object handle. Hadle value may be used in script to reference previously initialised object
// as EDIMailStream[handle value].
//
// Parameres:
// pStream - pointer to initialised EDIMailStream structure
//
// Returns:
// Address handle. Valid handle can't be 0.
//
EDIMAILDLL_API int GetEDIMailStreamHandle(const EDIMailStream* pStream);
EDIMAILDLL_API int AddStreamFilter(EDIMailStream* pStream, EDIMailFilter* pFilter);
EDIMAILDLL_API int RemoveStreamFilter(EDIMailStream* pStream, EDIMailFilter* pFilter);
EDIMAILDLL_API size_t StreamWrite(EDIMailStream* pStream, const void* pBuffer, size_t len);
EDIMAILDLL_API size_t StreamRead(EDIMailStream* pStream, void* pBuffer, size_t len);
EDIMAILDLL_API size_t StreamTell(const EDIMailStream* pStream);
EDIMAILDLL_API size_t StreamLength(const EDIMailStream* pStream);
EDIMAILDLL_API size_t StreamSeek(EDIMailStream* pStream, size_t offset, int whence);
EDIMAILDLL_API size_t StreamWriteToStream(EDIMailStream* pSrcStream, EDIMailStream*
pDestStream);
// Description:
// Get substream from current stream. Substream is part of original stream, not new stream.
// When you write to substream the original stream also have been changed.
//
// Parameres:
// pSrcStream - pointer to initialised EDIMailStream structure, original stream
// pSubstream - pointer to preallocated EDIMailStream structure, will be initialised to subctream of
original stream
// start - where to start substream (0 - from the beginning)
// end - where to end substream (-1 - no end limit)
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int GetEDIMailSubstream(EDIMailStream* pSrcStream, EDIMailStream* pSubstream,
size_t start, size_t end);
// Description:
// Parse stream contence and get array of EDIMail messages contained in it.
// You should deallocate the array you get.
//
// Parameres:
// pStream - pointer to initialised EDIMailStream structure
// szMixin - mixin object name created by AddMixin call
// pMessageCounter - pointer to int varaiable getting number of messages in array
// pMessage - pointer to EDIMailMessage getting array of messages from *pMessage[0] to
*pMessage[*pMessageCounter - 1]
// On error *pMessage will get NULL value, *pMessageCounter will be zero.
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
//EDIMAILDLL_API int GetEDIMailMessages(EDIMailStream* pStream, const char* szMixin, int*
pMessageCounter, EDIMailMessage** pMessage);
#pragma endregion
#pragma region URLs
typedef struct {
int handle;
EDIMailContext *pCtx;
} EDIMailURL;
// Description:
// Create url object.
// Created object may borrow properties from optional mixin, mixin may be created with AddMixin
call.
//
// Parameres:
// pURL - pointer to preallocated EDIMailURL structure to be initialised.
// ctx - previously initialized context
// szURL - url string
// szMixin - mixin object name created by AddMixin call
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int InitEDIMailURL(EDIMailURL* pURL, EDIMailContext* ctx, const char* szURL, const
char* szMixin);
// Description:
// Create url object from handle obtained from EDIMailURL object created by script.
//
// Parameres:
// pURL - pointer to preallocated EDIMailURL structure to be initialised.
// ctx - previously initialized context
// uiHandle - handle obtained from handle property of EDIMailURL created by script.
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int InitEDIMailURLByHandle(EDIMailURL* pURL, EDIMailContext *ctx, unsigned int
uiHandle);
// Destroy url object
//
// Parameres:
// pURL - pointer to initialised EDIMailURL structure
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int FreeEDIMailURL(EDIMailURL* pURL);
// Description:
// Get object property. If address match several business entities property contain
// values for every entity separated by newline character.
//
// Parameres:
// pURL - pointer to initialised EDIMailURL structure
// szProperty - property name
// pValue - preallocated pointer to be initialised by returned C-string property value. Memory for
returned C-string
//
is allocated by callback function provided during context initialisation. Caller must free
//
allocated memory.
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int GetEDIMailURLProperty(const EDIMailURL* pURL, const char* szProperty, char**
pValue);
// Description:
// Get object handle. Hadle value may be used in script to reference previously initialised object
// as EDIMailURL[handle value].
//
// Parameres:
// pURL - pointer to initialised EDIMailURL structure
//
// Returns:
// Address handle. Valid handle can't be 0.
//
EDIMAILDLL_API int GetEDIMailURLHandle(const EDIMailURL* pURL);
// Description:
// Set stream for data retrived from URL.
//
// Parameres:
// pURL - pointer to initialised EDIMailURL structure
// pStream - pointer to initialised stream
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int EDIMailURLSetWriteStream(EDIMailURL* pURL, EDIMailStream* pStream);
// Description:
// Set stream for data to be sent to URL.
//
// Parameres:
// pURL - pointer to initialised EDIMailURL structure
// pStream - pointer to initialised stream
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int EDIMailURLSetReadStream(EDIMailURL* pURL, EDIMailStream* pStream);
// Description:
// Actually execute data excange to/from URL
//
// Parameres:
// pURL - pointer to initialised EDIMailURL structure
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int EDIMailURLPerform(EDIMailURL* pURL);
// Description:
// Get array of new EDIMail messages stored in location pointed to by url.
// You should deallocate the array you get.
//
// Parameres:
// pURL - pointer to initialised EDIMailURL structure pointed to IMAP server
// szMixin - mixin object used as pattern for received messages. Mixins may be created by AddMixin
call.
// pMessageCounter - pointer to int varaiable initialized to maximum expected number of messages to
retrive and getting
// real number of messages received in array. Initialize to 0 to get all new messages.
// pMessage - pointer to EDIMailMessage getting array of messages from *pMessage[0] to
*pMessage[*pMessageCounter - 1]
// On error *pMessage will get NULL value, *pMessageCounter will be zero.
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int EDIMailCollect(EDIMailURL* pURL, const char* szMixin, unsigned int*
pMessageCounter, EDIMailMessage** pMessage);
// Description:
// Mark message as recived and processed. Sender will be informed via sending MDN.
//
// Parameres:
// ctx - previously initialized context
// pCollectURL - pointer to initialised EDIMailURL structure pointed to IMAP server and used to collect
message to confirm
// pMessageId - pointer to unique message id string. Message id may be obtained by call
//
GetEDIMailMessageProperty(const EDIMailMessage* pMessage, "messageId", char**
pValue);
// status - confirmed message processing status, 0 - Ok positive confirmation,
//
<> 0 - negative confirmation, message can't be processed.
// szReason - pointer to C-string with human readable explanation of message processing error. Can be
NULL if no error occur.
// pSendURL - pointer to initialised EDIMailURL structure pointed to SMTP server and used in
PostMessageTo calls
//
// Returns:
// Nothing.
//
EDIMAILDLL_API int ConfirmMessage(EDIMailURL* pCollectURL, const char* szMessageId, int status,
const char* szReason, EDIMailURL* pSmtpURL);
#pragma endregion
#pragma region Messages
// Description:
// Create message object for given address.
// Created object may borrow properties from optional mixin, mixin may be created with AddMixin
call.
//
// Parameres:
// pMessage - pointer to preallocated EDIMailMessage structure to be initialised.
// ctx - previously initialized context
// pAddress - pointer to initialised EDIMailAddress structure
// szMixin - mixin object name created by AddMixin call
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int InitEDIMailMessage(EDIMailMessage* pMessage, EDIMailContext *ctx,
EDIMailAddress* pAddress, const char* szMixin);
// Description:
// Create message object from stream by parsing stream data.
// Created object may borrow properties from optional mixin, mixin may be created with AddMixin
call.
//
// Parameres:
// pMessage - pointer to preallocated EDIMailMessage structure to be initialised.
// ctx - previously initialized context
// pStream - pointer to initialised EDIMailStream structure
// szMixin - mixin object name created by AddMixin call
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int InitEDIMailMessageFromStream(EDIMailMessage* pMessage, EDIMailContext *ctx,
EDIMailStream* pStream, const char* szMixin);
EDIMAILDLL_API int InitEDIMailMessageByHandle(EDIMailMessage* pMessage, EDIMailContext *ctx,
unsigned int uiHandle);
// Destroy message object
//
// Parameres:
// pMessage - pointer to initialised EDIMailMessage structure
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int FreeEDIMailMessage(EDIMailMessage* pMessage);
// Description:
// Get object property.
//
// Parameres:
// pMessage - pointer to initialised EDIMailMessage structure
// szProperty - property name
// pValue - preallocated pointer to be initialised by returned C-string property value. Memory for
returned C-string
//
is allocated by callback function provided during context initialisation. Caller must free
//
allocated memory.
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int GetEDIMailMessageProperty(const EDIMailMessage* pMessage, const char*
szProperty, char** pValue);
// Description:
// Get object handle. Hadle value may be used in script to reference previously initialised object
// as EDIMailMessage[handle value].
//
// Parameres:
// pMessage - pointer to initialised EDIMailMessage structure
//
// Returns:
// Message handle. Valid handle can't be 0.
//
EDIMAILDLL_API int GetEDIMailMessageHandle(const EDIMailMessage* pMessage);
typedef enum ProtectionLevel_t {
Cleartext = 0,
Signed,
SignedEncrypted,
MIMESignedEncrypted
} ProtectionLevel;
// Description:
// Attaches stream content to message starting from current stream position. Attachment may be sent
as is
// (level == Cleartext) or protected by digital signature and encryption.
//
// Parameres:
// pMessage - pointer to initialised EDIMailMessage structure to which stream content will be attached
// pStream - pointer to initialised EDIMailStream structure. Stream content will be taken from current
//
stream position till stream end.
// level - stream content protection level. Cleartext - unprotected, Signed - protect integrity,
//
SignedEncrypted - protect integrity and privacy
//
// Returns:
// Message handle. Valid handle can't be 0.
//
EDIMAILDLL_API int EDIMailAttachStreamToMessage(EDIMailMessage* pMessage, EDIMailStream*
pStream, ProtectionLevel level);
EDIMAILDLL_API size_t EDIMailMessageToStream(const EDIMailMessage* pMessage, EDIMailStream*
pStream);
// Description:
// Get EDIMailAddress object matching message sender.
//
// Parameres:
// pMessage - pointer to initialised EDIMailMessage structure
// pAddress - pointer to preallocated EDIMailAddress structure to be filled with message sender data.
//
You don't need to free EDIMailAddress received it will be freed when the message will be
deallocated.
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int GetEDIMailMessageSender(const EDIMailMessage* pMessage, EDIMailAddress*
pAddress);
EDIMAILDLL_API int GetNumOfEDIMailMessageAttachments(const EDIMailMessage* pMessage, int*
pNum);
// Atachments are numbered starting from 1
EDIMAILDLL_API size_t SaveEDIMailMessageAttachment(const EDIMailMessage* pMessage, int
number, EDIMailStream* pStream);
// Description:
// Get message creation time as C style time_t value (UTC time).
//
// Parameres:
// pMessage - pointer to initialised EDIMailMessage structure
// pTime - pointer to preallocated time_t.
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int GetEDIMailMessageDate(const EDIMailMessage* pMessage, time_t* pTime);
// Description:
// Get object property.
//
// Parameres:
// pMessage - pointer to initialised EDIMailMessage structure
// number - attachment number, attachments are numbered starting from 1.
// pValue - preallocated pointer to be initialised by returned C-string attachment file name. If
attachment was
//
created from memory buffer stream without name filename will be NULL. Memory for returned
C-string
//
is allocated by callback function provided during context initialisation. Caller must free allocated
memory.
//
// Returns:
// 0 - Ok,
// <>0 - error code
//
EDIMAILDLL_API int GetEDIMailMessageAttachmentFilename(const EDIMailMessage* pMessage, int
number, char** pValue);
EDIMAILDLL_API int GetEDIMailMessageCustomHeader(const EDIMailMessage* pMessage, const char*
szHeader, char** pValue);
EDIMAILDLL_API int SetEDIMailMessageCustomHeader(EDIMailMessage* pMessage, const char*
szHeader, const char* szValue);
EDIMAILDLL_API int RemoveEDIMailMessageCustomHeader(EDIMailMessage* pMessage, const char*
szHeader);
EDIMAILDLL_API int PostMessageTo(const EDIMailMessage* pMessage, EDIMailURL* pSmtpURL, char**
pMsgId);
#pragma endregion
};
#ifdef __cplusplus
}
#endif
#endif /* __MIMICRY__EDIMAIL_H */