Партнерка на США и Канаду по недвижимости, выплаты в крипто
- 30% recurring commission
- Выплаты в USDT
- Вывод каждую неделю
- Комиссия до 5 лет за каждого referral
ОписаниеAPIEDIMail
Table of Contents
Описание API EDIMail 1
Назначение системы.. 3
Архитектура системы.. 3
Функция получения сообщения об ошибке. 3
const char* GetLastEDIMailError(void). 3
Функции инициализации и работы с контекстом.. 3
EDIMailContext* InitContext(const char* szFilepath, mallocfun pAllocFun). 3
voidFreeContext(EDIMailContext *ctx). 3
int GetMessageStatus(EDIMailContext *ctx, const char* szMessageId, int* pStatus). 3
Работа со скриптами. 3
Выполнитьскрипт int Execute(EDIMailContext *pCtx, const char* szScript, char** pResult). 3
Добавить примесь к контексту int AddMixin(EDIMailContext* ctx, const char* szName, const char* szMixin) 3
Удалить примесь из контекста int RemoveMixin(EDIMailContext* ctx, const char* szName). 3
Адресация. 3
Объекты типа EDIMailAddress. 3
Атрибуты EDIMailAddress. 3
Конструктор int InitEDIMailAddress(EDIMailAddress* pAddress, EDIMailContext *ctx, const char* szTicker, const char* szService, const char* szEmail, const char* szKey, const char* szMixin). 3
Конструкторповнутреннемуномеруобъекта int InitEDIMailAddressByHandle(EDIMailAddress* pAddress, EDIMailContext *ctx, unsigned int uiHandle). 3
Деструктор int FreeEDIMailAddress(EDIMailAddress* pAddress). 3
Получениеатрибутовобъекта int GetEDIMailAddressProperty(const EDIMailAddress* pAddress, const char* szProperty, char** pValue). 3
Получениевнутреннегономераобъекта int GetEDIMailAddressHandle(const EDIMailAddress* pAddress) 3
Работа с потоками. 3
Атрибуты потоков. 3
Конструкторпотокаизфайла InitEDIMailStreamFromFile(EDIMailStream* pStream, EDIMailContext* ctx, const char* szFilename, const char* szFilemode, const char* szMixin). 3
Конструктор потока из буфера памяти int InitEDIMailStreamFromBuffer(EDIMailStream* pStream, EDIMailContext* ctx, const void* pBuffer, size_tsize, constchar* szMixin). 3
Конструктор потока по внутреннему номеру объекта int InitEDIMailStreamByHandle(EDIMailStream* pStream, EDIMailContext *ctx, unsigned int uiHandle). 3
Конструкторподпотокаизпотока int GetEDIMailSubstream(EDIMailStream* pSrcStream, EDIMailStream* pSubstream, size_t start, size_t end). 3
Деструкторобъекта int FreeEDIMailStream(EDIMailStream* pStream). 3
Получениеатрибутовобъекта int GetEDIMailStreamProperty(const EDIMailStream* pStream, const char* szProperty, char** pValue). 3
Получение внутреннего номера объекта intGetEDIMailStreamHandle(constEDIMailStream* pStream) 3
Запись в поток size_tStreamWrite(EDIMailStream* pStream, constvoid* pBuffer, size_tlen). 3
size_t StreamRead(EDIMailStream* pStream, void* pBuffer, size_t len). 3
size_t StreamTell(const EDIMailStream* pStream). 3
size_t StreamLength(const EDIMailStream* pStream). 3
size_t StreamSeek(EDIMailStream* pStream, size_t offset, int whence). 3
size_t StreamWriteToStream(EDIMailStream* pSrcStream, EDIMailStream* pDestStream). 3
Объекты типа EDIMailURL. 3
Атрибуты EDIMailURL. 3
Конструктор int InitEDIMailURL(EDIMailURL* pURL, EDIMailContext* ctx, const char* szURL, const char* szMixin) 3
Конструктор URL по внутреннему номеру объекта intInitEDIMailURLByHandle(EDIMailURL* pURL, EDIMailContext *ctx, unsignedintuiHandle). 3
Деструктор int FreeEDIMailURL(EDIMailURL* pURL). 3
Получениеатрибутовобъекта int GetEDIMailURLProperty(const EDIMailURL* pURL, const char* szProperty, char** pV.. 3
Получение внутреннего номера объекта intGetEDIMailURLHandle(constEDIMailURL* pURL). 3
Задать поток для приема данных от сервера int EDIMailURLSetWriteStream(EDIMailURL* pURL, EDIMailStream* pStream). 3
Задать поток для отправки данных на сервер int EDIMailURLSetReadStream(EDIMailURL* pURL, EDIMailStream* pStream). 3
Выполнить запрос к серверу int EDIMailURLPerform(EDIMailURL* pURL). 3
Получениесообщений int EDIMailCollect(EDIMailURL* pURL, const char* szMixin, unsigned int* pMessageCounter, EDIMailMessage** pMessage). 3
Подтверждение получения сообщений int ConfirmMessage(EDIMailURL* pCollectURL, const char* szMessageId, EDIMailURL* pSmtpURL). 3
Работа с сообщениями. 3
Атрибуты EDIMailMessage. 3
Конструктор int InitEDIMailMessage(EDIMailMessage* pMessage, EDIMailContext *ctx, EDIMailAddress* pAddress, const char* szMixin). 3
Конструкторсообщенияизпотока InitEDIMailMessageFromStream(EDIMailMessage* pMessage, EDIMailContext *ctx, EDIMailStream* pStream, const char* szMixin). 3
Конструктор сообщения по внутреннему номеру объекта intInitEDIMailMessageByHandle (EDIMailMessage* pMessage, EDIMailContext *ctx, unsignedintuiHandle). 3
Деструктор int FreeEDIMailMessage(EDIMailMessage* pMessage). 3
Получениеатрибутовобъекта int GetEDIMailMessageProperty(const EDIMailMessage* pMessage, const char* szProperty, char** pValue). 3
Получениевнутреннегономераобъекта int GetEDIMailMessageHandle(const EDIMailMessage* pMessage) 3
Прикрепление потока к сообщению для его пересылки intEDIMailAttachStreamToMessage(EDIMailMessage* pMessage, EDIMailStream* pStream, ProtectionLevellevel). 3
Сохранениесообщениявпоток int EDIMailMessageToStream(const EDIMailMessage* pMessage, EDIMailStream* pStream). 3
Получить адрес отправителя intGetEDIMailMessageSender(constEDIMailMessage* pMessage, EDIMailAddress* pAddress). 3
Получить количество прикрепленных к сообщению потоков int GetNumOfEDIMailMessageAttachments(const EDIMailMessage* pMessage, int* pNum). 3
Сохранить прикрепленный к сообщению поток в указанный поток size_t SaveEDIMailMessageAttachment(const EDIMailMessage* pMessage, int number, EDIMailStream* pStream). 3
Получитьдатуивремясозданиясообщения int GetEDIMailMessageDate(const EDIMailMessage* pMessage, time_t* pTime). 3
Получитьимяфайлаприкрепленногопотока int GetEDIMailMessageAttachmentFilename(const EDIMailMessage* pMessage, int number, char** pValue). 3
Установить пользовательский заголовок сообщения int SetEDIMailMessageCustomHeader(EDIMailMessage* pMessage, const char* szHeader, const char* szValue). 3
Получить установленный пользователем заголовок сообщения int GetEDIMailMessageCustomHeader(const EDIMailMessage* pMessage, const char* szHeader, char** pValue). 3
Удалить установленный пользователем заголовок int RemoveEDIMailMessageCustomHeader(EDIMailMessage* pMessage, const char* szHeader). 3
Отправкасообщения int PostMessageTo(const EDIMailMessage* pMessage, EDIMailURL* pSmtpURL, char** pMsgId). 3
Приложение – заголовочный файл библиотеки. 3
Назначение системы
EDIMailпредназначен для обмена сообщениями с прикрепленными к ним файламис гарантированной доставкой, причем EDIMailобеспечивает конфиденциальность и целостность прикрепленных файлов и аутентификацию отправителя при условии использования криптографического провайдера. В качестве провайдера возможно использование криптопровайдера ВалидатаCSP для резидентов и PGPдля нерезидентов. Необходимо отметить, что выбор криптопровайдера происходит не на уровне настройки библиотеки. Выбор криптопровайдера на уровне библиотеки должен быть обеспечен развертыванием соотвествующей инфраструктуры.
Архитектура системы
Система состоит из сервиса MoscowExchangeEDIMailServiceи DLLбиблиотеки, которая используется в пользовательском приложении. Сервис EDIMailService запускается при загрузке системы и отслеживает изменения состояний отправленных сообщений, непосредственно взаимодействует с почтовыми 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.
voidFreeContext(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.
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 – почтовый адрес вида *****@***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_tsize, constchar* 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 резервируется библиотекой и должна быть освобождена пользователем.
ПолучениевнутреннегономераобъектаintGetEDIMailStreamHandle(constEDIMailStream* pStream)
Возвращает внутренний номер объекта, для использования этого объекта в Javascript. Объект в Javascriptполучается как EDIMailStream[номер_объекта].
Записьвпотокsize_tStreamWrite(EDIMailStream* pStream, constvoid* pBuffer, size_tlen)
Возвращает количество записанных в поток байт.
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повнутреннемуномеруобъектаintInitEDIMailURLByHandle(EDIMailURL* pURL, EDIMailContext *ctx, unsignedintuiHandle)
Создает объект по внутреннему номеру существующего объекта. Может использоваться для продолжения работы в С-интерфейсе с объектом, созданным в Javascript-интерфейсе библиотеки.
Деструктор int FreeEDIMailURL(EDIMailURL* pURL)
Уничтожает существующий объект. В JavaScriptинтерфейсе для этих целей используется метод dispose()
Получениеатрибутовобъекта int GetEDIMailURLProperty(const EDIMailURL* pURL, const char* szProperty, char** pV
szPrioperty – имя атрибута или метода без параметров. Встроенные имена атрибутов были перечислены выше, дополнительные атрибуты и методы могут быть созданы с помощью Javascriptили унаследованы от примеси szMixin, указанной в конструкторе. Память для возвращаемого значения pValue резервируется библиотекой и должна быть освобождена пользователем.
ПолучениевнутреннегономераобъектаintGetEDIMailURLHandle(constEDIMailURL* 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)
Выполняет опрос указанного pURLIMAPсервера для получения новых (неподтвержденных) сообщений. Примесь 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, т. е. он может включать имя отправителя и его e-mail в угловых скобках.
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. Из потока может быть восстановлено только одно сообщение.
Конструкторсообщения повнутреннемуномеруобъектаintInitEDIMailMessageByHandle (EDIMailMessage* pMessage, EDIMailContext *ctx, unsignedintuiHandle)
Создает объект по внутреннему номеру существующего объекта. Может использоваться для продолжения работы в С-интерфейсе с объектом, созданным в 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[номер_объекта]
ПрикреплениепотокаксообщениюдляегопересылкиintEDIMailAttachStreamToMessage(EDIMailMessage* pMessage, EDIMailStream* pStream, ProtectionLevellevel)
Прикрепляет поток к сообщению и применяет к нему указанную степень криптографической защиты:
Cleartext – никакой защиты, сообщение может быть прочтено любым почтовым клиентом;
Signed – прикрепляемый файл подписывается отправителем, подпись и файл прикрепляются по отдельности, сообщение может быть получено любым почтовым клиентом, почтовый клиент, поддерживающий S/MIME, может проверить подпись;
SignedEncrypted – прикрепляемый файл подписывается присоединенной цифровой подписью и зашифровывается, почтовые клиенты просто видят прикрепленный файл;
MIMESignedEncrypted - прикрепляемый файл подписывается отсоединенной цифровой подписью, подпись и файл прикрепляются по отдельности и вместе зашифровывается, почтовые клиенты, не поддерживающие S/MIME, просто видят прикрепленный файл со стандартным названием, почтовые клиенты, поддерживающие S/MIME, могут расшифровать приложение и проверить подпись.
Все защиты, кроме Cleartext, обеспечивают защиту целостности передаваемого потока и аутентификацию отправителя, защиты SignedEncrypted и MIMESignedEncrypted обеспечивают дополнительно защиту конфиденциальности передаваемого потока.
Сохранениесообщениявпотокint EDIMailMessageToStream(const EDIMailMessage* pMessage, EDIMailStream* pStream)
Сохраняет указанное сообщение со всеми прикрепленными потоками в указанный поток в MIMEформате. Может использоваться для сохранения шаблонов типовых сообщений.
ПолучитьадресотправителяintGetEDIMailMessageSender(constEDIMailMessage* 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сервер, адресуемый URLpSmtpURLи возвращает уникальный идентификатор отправленного сообщения. Пользователь должен освободить память, выделенную для хранения идентификатора сообщения в pMsgId.
Используемый для отправки pSmtpURL должен иметь все необходимые атрибуты для установления содинения с SMTPсервером – логин, пароль, настройки TLS(transportlayersecurity) и т. п.
Возврат из вызова происходит после завершения сеанса связи с SMTPсервером, в зависимости от скорости соединения с сервером для завершения вызова может потребоваться некоторое время.
JavaScriptинтерфейс к функциям сервиса
Практически все, что можно сделать с помощью описанного выше С-интерфейса, можно сделать с помощью объектов и методов встроенного JavaScript. Объекты, созданные с помощью вызовов С-интерфейса можно обрабатывать с помощью JavaScript, и наоборот, созданные в JavaScriptобъекты (не любые, конечно, а описанных выше типов) можно получить в С-интерфейсе и продолжить обработку там.
Создание объектов в JavaScript
Аргументы конструкторов в JavaScriptтакие же и идут в том же порядке, что и в Init… вызовах С-интерфейса, за исключением того, что все JavaScriptобъекты существуют только в рамках одного контекста, того, который выполняет данный скрипт, и, поэтому, указание контекста в конструкторах отсутствует. Приведемпример:
varaddr = EDIMailAddress(“TROIM”, “REPORT“); /*создаем адрес для участника с тикером TROIMдля сервиса REPORT */
varmessage = EDIMailMessage(addr); /* СоздаемсообщениедляадресатаTROIM */
varstream = EDIMailStream(“C:\myreport. txt”, “rt”); /* файл для отсылки */
message. attachStream(stream, 3); /* Прикрепить файл для отсылки к сообщению по правилам
S/MIMEс подписью и шифрованием */
varurl = EDIMailURL(“smtp://aspmx. ”); /* создаем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 */
