/ Содержание. \
---------------
1. Введение
2. Функции Simple MAPI.
2.1. MAPIAddress
2.2. MAPIDeleteMail
2.3. MAPIDetails
2.4. MAPIFindNext
2.5. MAPIFreeBuffer
2.6. MAPILogoff
2.7. MAPILogon
2.8. MAPIReadMail
2.9. MAPIResolvName
2.10. MAPISaveMail
2.11. MAPISendDocumets
2.12. MAPISendMail
3. Основные структуры данных в Simple MAPI.
3.1. MapiRecipDesc
3.2. MapiMessage
3.3. MapiFileDesc
4. Использование Simple MAPI.
4.1. Пример отправки сообщения.
4.2. Пример получения сообщения.
5. Источники.
6. История редакций.
Я не несу никакой ответственности за использование/неправильное употребление
информации в этом документе. Я не несу ответственности за неправильность
материала, короче говоря я не несу никакой ответственности за этот материал. Я
даю полное разрешение на копирование любой части этого документа, и на изменение
этого файла любым способом, который Вы найдете удобным. Я надеюсь, что в
будущем члены андерграунда улучшат этот документ, или используют его как основу
для создания своих собственных статей, в помощь другим исследователям.
Для ссылок используйте:
Sergeev Alex, "Введение в Simple MAPI", Coders Engines #1,
rook.evilenigma.org, 2000.
/ 1. Введение. \
----------------
Очень часто, когда пишешь программу, нужно чтобы она работала с почтой, но
навороченный интерфейс даром не нужен, а следовательно и нет смысла использовать
компоненты VCL (TNMPop3, TNMSmtp), вот тут то и приходит на ум использовать
Simple MAPI.
Simple MAPI (SMAPI) предоставляет набор функций для использования начального
уровня работы с сообщениями в приложениях для Microsoft Windows. SMAPI совместим
с Windows 9x, Windows NT и Windows for Workgroups 3.1. В составе этого
интерфейса
содержится 12 функций (рассмотренных ниже), позволяющих послать (send),
принять (receive), ответить (reply) и адресовать сообщение. Посылаемые сообщения
могут содержать вложенные файлы и OLE-объекты.
/ 2.Функции Simple MAPI. \
--------------------------
/ 2.1. MAPIAddress (LPMAPIADDRESS) \
------------------------------------
Эта функция создает или модифицирует записи в адресной книге.
Синтаксис:
ULONG FAR PASCAL MAPIAddress (LHANDLE lhSession,
ULONG ulUIParam,
LPTSTR lpszCaption,
ULONG nEditFields,
LPTSTR lpszLabels,
ULONG nRecips,
lpMapiRecipDesc lpRecips,
FLAGS flFlags,
ULONG ulReserved,
LPULONG lpnNewRecips,
lpMapiRecipDesc FAR * lppNewRecips)
Параметры:
lhSession - handle сессии или 0, если handle равен нулю создается временная
книга и сессия, по истечении которой книга уничтожается.
ulUIParam - handle диалогового окна или 0. Если 0 , то этот параметр
игнорируется.
lpszCaption - указывает название книги. Если строка пустая, используется
стандартное название "Address Book".
nEditFields - параметр указывающий количество полей редактирования,
представленных в адресной книге. Может принимать значения
от 0 до 4.
lpszLabels - указатель на строку, используемую в диалоге списка адресов. Если
nEditFields не единица, тогда этот параметр игнорируется.
nRecips - параметр, показывающий какое число элементов берется из массива
lpRecips. Если параметр равен нулю, то он игнорируется.
lpRecips - указатель на структуру MapiRecipDesc.
flFlags - устанавливает флаги опций:
MAPI_LOGON_UI - показывает диалог для идентификации, если это потребуется.
MAPI_NEW_SESSION - если флаг установлен, функция попытается создать новую
сессию перед тем как использовать существующую.
ulReserved - зарезервировано, пока не используется
lpnNewRecips-указатель на положение в массиве lppNewRecips. Eсли 0,игнорируется.
lppNewRecips - указатель на структуру MapiRecipDesc.
Возвращаемые значения:
+----------------------------+-----------+-------------------------------------+
| Значение | Тип | Описание |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_FAILURE | Ошибка(*) | Одна (или более) неизвестная ошибка |
| | | произошла во время выполнения. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INSUFFICIENT_MEMORY | Ошибка | Недостаточно памяти для процесса. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INVALID_EDITFIELDS | Ошибка | Значение nEditFields вне диапазона |
| | | от 0 до 4. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INVALID_RECIPS | Ошибка | По одному (или более) получателю нет|
| | | информации в адресной книге. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INVALID_SESSION | Ошибка | Неправильный handle сессии был |
| | | использован в lhSession. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_LOGIN_FAILURE | Ошибка | Был исользованр не верное имя |
| | | пользователя при входе в систему. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_NOT_SUPPORTED | Ошибка | Эта операция не поддерживается |
| | | используемой системой сообщений. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_USER_ABORT |Прерывание | Пользователь завершил работу с |
| | | одним из диалоговых окон (cancel). |
+----------------------------+-----------+-------------------------------------+
| SUCCESS_SUCCESS | Ответ | Операция была успешно завершена. |
+----------------------------+-----------+-------------------------------------+
Примечание:
(*) При ошибке работа функции заканчивается и переменные не изменяются.
/ 2.2. MAPIDeleteMail (LPMAPIDELETEMAIL) \
------------------------------------------
Функция удаления сообщения.
Синтаксис:
ULONG FAR PASCAL MAPIDeleteMail (LHANDLE lhSession,
ULONG ulUIParam,
LPTSTR lpszMessageID,
FLAGS flFlags,
ULONG ulReserved)
Параметры:
lhSession - handle сессии или 0, если handle равен нулю создается временная
книга и сессия, по истечении которой книга уничтожается.
ulUIParam- handle диалогового окна или 0. Если 0, то этот параметр игнорируется.
lpszMessageID - идентификатор сообщения которое надо удалить.
flFlags, ulReserved - зарезервировано, пока не используется.
Возвращаемые значения:
+----------------------------+-----------+-------------------------------------+
| Значение | Тип | Описание |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_FAILURE | Ошибка | Одна (или более) неизвестная ошибка |
| | | произошла во время выполнения. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INSUFFICIENT_MEMORY | Ошибка | Недостаточно памяти для процесса. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INVALID_MESSAGE | Ошибка | Неверный идентификатор сообщения был|
| | | передан в параметр lpszMessageID. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INVALID_SESSION | Ошибка | Неправильный handle сессии был |
| | | использован в lhSession. |
+----------------------------+-----------+-------------------------------------+
| SUCCESS_SUCCESS | Ответ | Операция была успешно завершена. |
+----------------------------+-----------+-------------------------------------+
/ 2.3. MAPIDetails (LPMAPIDETAILS) \
------------------------------------
Эта функция выводит диалоговое окно, показывающее подробности по выбранной
записи в адресной книге.
Синтаксис:
ULONG FAR PASCAL MAPIDetails (LHANDLE lhSession,
ULONG ulUIParam,
lpMapiRecipDesc lpRecip,
FLAGS flFlags,
ULONG ulReserved)
Параметры:
lhSession - handle сессии или 0, если handle равен нулю создается временная
книга и сессия, по истечении которой книга уничтожается.
ulUIParam- handle диалогового окна или 0. Если 0, то этот параметр игнорируется.
lpRecip - указатель на адресата, для которого надо показать подробности.
flFlags - устанавливает флаги опций:
MAPI_AB_NOMODIFY - если этот флаг установлен, полученные сведения будут
обладать атрибутом read-only.
MAPI_LOGON_UI - показывает диалог для идентификации, если это потребуется.
MAPI_NEW_SESSION - если флаг установлен, функция попытается создать новую
сессию перед тем как использовать существующую.
ulReserved - зарезервировано, пока не спользуется.
Возвращаемые значения:
+----------------------------+-----------+-------------------------------------+
| Значение | Тип | Описание |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_AMBIGUOUS_RECIPIENT | warning | Диалоговое окно не может быть |
| | | показано т.к. lpRecips->ulEIDSize=0 |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_FAILURE | Ошибка | Одна (или более) неизвестная ошибка |
| | | произошла во время выполнения. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INSUFFICIENT_MEMORY | Ошибка | Недостаточно памяти для процесса. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INVALID_RECIPS | Ошибка | По одному (или более) получателю нет|
| | | информации в адресной книге. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_LOGIN_FAILURE | Ошибка | Был исользованр не верное имя |
| | | пользователя при входе в систему. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_NOT_SUPPORTED | Ошибка | Эта операция не поддерживается |
| | | используемой системой сообщений. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_USER_ABORT |Прерывание | Пользователь завершил работу с |
| | | одним из диалоговых окон (cancel). |
+----------------------------+-----------+-------------------------------------+
| SUCCESS_SUCCESS | Ответ | Операция была успешно завершена. |
+----------------------------+-----------+-------------------------------------+
/ 2.4. MAPIFindNext (LPFINDNEXT) \
----------------------------------
Забирает сообщение, следующее за текущим.
Синтаксис:
ULONG FAR PASCAL MAPIFindNext (LHANDLE lhSession,
ULONG ulUIParam,
LPTSTR lpszMessageType,
LPTSTR lpszSeedMessageID,
FLAGS flFlags,
ULONG ulReserved,
LPTSTR lpszMessageID)
Параметры:
lhSession - handle сессии или 0, если handle равен нулю создается временная
книга и сессия, по истечении которой книга уничтожается.
ulUIParam- handle диалогового окна или 0. Если 0, то этот параметр игнорируется.
lpszMessageType - указатель на строку-идентификатор класса для поиска.
lpszSeedMessageID
flFlags - флаги опций:
MAPI_GUARANTEE_FIFO - если флаг установлен идентификаторы полученных сообщений
выводятся в порядке получения (по времени).
MAPI_LONG_MSGID - этот флаг указывает что идентификатор сообщения будет больше
чем 512 символов, lpszMessageID должен быть больше
этого числа.
MAPI_UNREAD_ONLY - этот флаг указывает на то, то будут выведены только не
прочитанные сообщения
ulReserved - зарезервировано, пока не используется.
lpszMessageID - указатель на идентификатор сообщения.
Возвращаемые значения:
+----------------------------+-----------+-------------------------------------+
| Значение | Тип | Описание |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_FAILURE | Ошибка | Одна (или более) неизвестная ошибка |
| | | произошла во время выполнения. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INSUFFICIENT_MEMORY | Ошибка | Недостаточно памяти для процесса. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INVALID_MESSAGE | Ошибка | Неверный идентификатор сообщения был|
| | | передан в параметр lpszMessageID. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INVALID_SESSION | Ошибка | Неправильный handle сессии был |
| | | использован в lhSession. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_NO_MESSAGES | Ошибка | Сообщений не найдено. |
+----------------------------+-----------+-------------------------------------+
| SUCCESS_SUCCESS | Ответ | Операция была успешно завершена. |
+----------------------------+-----------+-------------------------------------+
/ 2.5. MAPIFreeBuffer (LPMAPIFREEBUFFER) \
------------------------------------------
Освобождает память, занятую системой сообщений.
Синтаксис:
ULONG MAPIFreeBuffer(LPVOID lpBuffer)
Параметры:
lpBuffer - указатель на буффер. Если NULL функция не выполняется.
Возвращаемые значения:
+----------------------------+-----------+-------------------------------------+
| Значение | Тип | Описание |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_FAILURE | Ошибка | Одна (или более) неизвестная ошибка |
| | | произошла во время выполнения. |
+----------------------------+-----------+-------------------------------------+
| SUCCESS_SUCCESS | Ответ | Операция была успешно завершена. |
+----------------------------+-----------+-------------------------------------+
/ 2.6. MAPILogoff (LPMAPILOGOFF) \
----------------------------------
Завершает сессию с почтовой системой, когда она больше не нужна.
Синтаксис:
ULONG FAR PASCAL MAPILogoff (LHANDLE lhSession,
ULONG ulUIParam,
FLAGS flFlags,
ULONG ulReserved)
Параметры:
lhSession - handle сессии, которую нужно завершить. Этот параметр не может быть
нулевым.
ulParam - handle диалогового окна созданного MAPILogon или 0. Если 0 ,то этот
параметр игнорируется.
flFlags, ulReserved - зарезервированы, пока не используются.
Возвращаемые значения:
+----------------------------+-----------+-------------------------------------+
| Значение | Тип | Описание |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_FAILURE | Ошибка | Одна (или более) неизвестная ошибка |
| | | произошла во время выполнения. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INSUFFICIENT_MEMORY | Ошибка | Недостаточно памяти для процесса. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INVALID_SESSION | Ошибка | Неправильный handle сессии был |
| | | использован в lhSession. |
+----------------------------+-----------+-------------------------------------+
| SUCCESS_SUCCESS | Ответ | Операция была успешно завершена. |
+----------------------------+-----------+-------------------------------------+
/ 2.7. MAPILogon (LPMAPILOGON) \
--------------------------------
Эта функция начинает новую сессию, загружает адресную книгу и список сообщений.
Синтаксис:
ULONG FAR PASCAL MAPILogon (ULONG ulUIParam,
LPTSTR lpszProfileName,
LPTSTR lpszPassword,
FLAGS flFlags,
ULONG ulReserved,
LPLHANDLE lplhSession)
Параметры:
ulParam - handle диалогового окна созданного MAPILogon или 0. Если 0 ,то этот
параметр игнорируется.
lpszProfileName - указатель на строку, содержащую путь к файлу настроек.
lpszPassword - указатель на строку, содержащую пароль для доступа.
flFlags - флаги опций:
MAPI_FORCE_DOWNLOAD - если флаг установлен, то функция пытается загрузить все
сообщения, перед ее завершением. Если флаг не
установлен, тогда сообщения будут загружены, после
завершения функции.
MAPI_LOGON_UI - показывает диалог для идентификации, если это потребуется.
MAPI_NEW_SESSION - если флаг установлен, функция попытается создать новую
сессию перед тем как использовать существующую.
ulReserved - зарезервировано, пока не используется.
lplhSession - указатель на сессию Simple MAPI.
Возвращаемые значения:
+----------------------------+-----------+-------------------------------------+
| Значение | Тип | Описание |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_FAILURE | Ошибка | Одна (или более) неизвестная ошибка |
| | | произошла во время выполнения. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INSUFFICIENT_MEMORY | Ошибка | Недостаточно памяти для процесса. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_LOGIN_FAILURE | Ошибка | Был исользованр не верное имя |
| | | пользователя при входе в систему. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_TOO_MANY_SESSIONS | Ошибка | Слишком много сессий было запущенно |
| | | одновременно. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_USER_ABORT |Прерывание | Пользователь завершил работу с |
| | | одним из диалоговых окон (cancel). |
+----------------------------+-----------+-------------------------------------+
| SUCCESS_SUCCESS | Ответ | Операция была успешно завершена. |
+----------------------------+-----------+-------------------------------------+
/ 2.8. MAPIReadMail (LPMAPIREADMAIL) \
--------------------------------------
Чтение сообщений из почтового ящика.
Синтаксис:
ULONG FAR PASCAL MAPIReadMail (LHANDLE lhSession,
ULONG ulUIParam,
LPTSTR lpszMessageID,
FLAGS flFlags,
ULONG ulReserved,
lpMapiMessage FAR *lppMessage)
Параметры:
lhSession - handle сессии, которую нужно завершить. Этот параметр не может быть
нулевым.
ulUIParam - handle диалогового окна созданного MAPILogon или 0. Если 0 ,то этот
параметр игнорируется.
lpszMessageID - указатель на идентификатор сообщения, которое должно быть
прочитано.
flFlags - флаги опций:
MAPI_BODY_AS_FILE - показывает, что сообщение будет сохранено в файл, и
добавлено первым номером в список приложений.
MAPI_ENVELOPE_ONLY - показывает, что будет прочитан только заголовок письма.
MAPI_PEEK - если флаг установлен, прочитанные сообщения не будут отмечаться
как прочитанные.
MAPI_SUPPRESS_ATTACH - показывает, что приложения не будут загружены, но
сообщние будет записано в структуру MapiMessage.
ulReserved - зарезервировано, пока не используется.
lppMessage - указатель на место куда было сохранено сообщение.
Возвращаемые значения:
+----------------------------+-----------+-------------------------------------+
| Значение | Тип | Описание |
+----------------------------+-----------+-------------------------------------+
| (MAPI_E_ATTACHMENT_ | Ошибка | Приложение не может быть записано во|
| WRITE_FAILURE)| | временный файл. Проверте путь. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_DISK_FULL | Ошибка | Приложение не может быть записано на|
| | | диск, т.к. места там нет совсем. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_FAILURE | Ошибка | Одна (или более) неизвестная ошибка |
| | | произошла во время выполнения. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INSUFFICIENT_MEMORY | Ошибка | Недостаточно памяти для процесса. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INVALID_MESSAGE | Ошибка | Неверный идентификатор сообщения был|
| | | передан в параметр lpszMessageID. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_TOO_MANY_FILES | Ошибка | Слишком много приложений, сообщение |
| | | не может быть прочитано. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_TOO_MANY_RECIPIENTS | Ощибка | Слишком много получателей, сообщение|
| | | не может быть прочитано. |
+----------------------------+-----------+-------------------------------------+
| SUCCESS_SUCCESS | Ответ | Операция была успешно завершена. |
+----------------------------+-----------+-------------------------------------+
/ 2.9. MAPIResolveName (LPMAPIRESOLVENAME) \
--------------------------------------------
Сопоставление адреса с именем адресата.
Синтаксис:
ULONG FAR PASCAL MAPIResolveName (LHANDLE lhSession,
ULONG ulUIParam,
LPTSTR lpszName,
FLAGS flFlags,
ULONG ulReserved,
lpMapiRecipDesc FAR * lppRecip)
Параметры:
lhSession - handle сессии, которую нужно завершить. Этот параметр не может быть
нулевым.
ulUIParam - handle диалогового окна созданного MAPILogon или 0. Если 0 ,то этот
параметр игнорируется.
lpszName - указатель на имя для сопоставления.
flFlags - флаги опции:
MAPI_AB_NOMODIFY - если этот флаг установлен, полученные сведения будут
обладать атрибутом read-only.
MAPI_DIALOG - показывает, что будет выведено окно диалога, для выбора имени.
MAPI_LOGON_UI - показывает диалог для идентификации, если это потребуется.
MAPI_NEW_SESSION - если флаг установлен, функция попытается создать новую
сессию перед тем как использовать существующую.
ulReserved - зарезервировано, пока не используется.
lppRecip - указатель на структуру с результатом поиска.
Возвращаемые значения:
+----------------------------+-----------+-------------------------------------+
| Значение | Тип | Описание |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_AMBIGUOUS_RECIPIENT | warning | Диалоговое окно не может быть |
| | | показано т.к. lpRecips->ulEIDSize=0 |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_FAILURE | Ошибка | Одна (или более) неизвестная ошибка |
| | | произошла во время выполнения. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INSUFFICIENT_MEMORY | Ошибка | Недостаточно памяти для процесса. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_LOGIN_FAILURE | Ошибка | Был исользованр не верное имя |
| | | пользователя при входе в систему. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_NOT_SUPPORTED | Ошибка | Эта операция не поддерживается |
| | | используемой системой сообщений. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_USER_ABORT |Прерывание | Пользователь завершил работу с |
| | | одним из диалоговых окон (cancel). |
+----------------------------+-----------+-------------------------------------+
| SUCCESS_SUCCESS | Ответ | Операция была успешно завершена. |
+----------------------------+-----------+-------------------------------------+
/ 2.10. MAPISaveMail (LPMAPISAVEMAIL) \
---------------------------------------
Сохранение сообщения в хранилище сообщений (messages store).
Синтаксис:
ULONG FAR PASCAL MAPISaveMail (LHANDLE lhSession,
ULONG ulUIParam,
lpMapiMessage lpMessage,
FLAGS flFlags,
ULONG ulReserved,
LPTSTR lpszMessageID)
Параметры:
lhSession - handle сессии, которую нужно завершить. Этот параметр не может быть
нулевым.
ulUIParam - handle диалогового окна созданного MAPILogon или 0. Если 0 ,то этот
параметр игнорируется.
lpMessage
flFlags
MAPI_LOGON_UI - показывает диалог для идентификации, если это потребуется.
MAPI_LONG_MSGID - этот флаг указывает что идентификатор сообщения будет больше
чем 512 символов, lpszMessageID должен быть больше
этого числа.
MAPI_NEW_SESSION - если флаг установлен, функция попытается создать новую
сессию перед тем как использовать существующую.
ulReserved - зарезервировано, пока не используется.
lpszMessageID - указатель на идентификатор сообщения, который должен быть
заменен операцией сохранения или на пустую строку, показывающий,
что новое сообщение было создано.
Возвращаемые значения:
+----------------------------+-----------+-------------------------------------+
| Значение | Тип | Описание |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_FAILURE | Ошибка | Одна (или более) неизвестная ошибка |
| | | произошла во время выполнения. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INSUFFICIENT_MEMORY | Ошибка | Недостаточно памяти для процесса. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INVALID_MESSAGE | Ошибка | Неверный идентификатор сообщения был|
| | | передан в параметр lpszMessageID. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INVALID_SESSION | Ошибка | Неправильный handle сессии был |
| | | использован в lhSession. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_LOGIN_FAILURE | Ошибка | Был исользованр не верное имя |
| | | пользователя при входе в систему. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_NOT_SUPPORTED | Ошибка | Эта операция не поддерживается |
| | | используемой системой сообщений. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_USER_ABORT |Прерывание | Пользователь завершил работу с |
| | | одним из диалоговых окон (cancel). |
+----------------------------+-----------+-------------------------------------+
| SUCCESS_SUCCESS | Ответ | Операция была успешно завершена. |
+----------------------------+-----------+-------------------------------------+
/ 2.11. MAPISendDocuments (LPMAPISENDDOCUMENTS) \
-------------------------------------------------
Отправка сообщение с приложенными файлами.
Синтаксис:
ULONG FAR PASCAL MAPISendDocuments (ULONG ulUIParam,
LPTSTR lpszDelimChar,
LPTSTR lpszFullPaths,
LPTSTR lpszFileNames,
ULONG ulReserved)
Параметры:
ulUIParam - handle диалогового окна созданного MAPILogon или 0. Если 0,то этот
параметр игнорируется.
lpszFullPaths - указатель на строку, содержащую полные пути до файлов
приложений, разделенных точкой с запятой. Например:
c:\path\to\file\to.attach;c:\path\to\file\to.attach2
lpszFileNames - указатель на строку, содержащую оригинальные названия файлов,
под которыми они будут видны в сообщении.
ulReserved - зарезервировано, пока не используется.
Возвращаемые значения:
+----------------------------+-----------+-------------------------------------+
| Значение | Тип | Описание |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_FAILURE | Ошибка | Одна (или более) неизвестная ошибка |
| | | произошла во время выполнения. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INSUFFICIENT_MEMORY | Ошибка | Недостаточно памяти для процесса. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INVALID_MESSAGE | Ошибка | Неверный идентификатор сообщения был|
| | | передан в параметр lpszMessageID. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INVALID_SESSION | Ошибка | Неправильный handle сессии был |
| | | использован в lhSession. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_LOGIN_FAILURE | Ошибка | Был исользованр не верное имя |
| | | пользователя при входе в систему. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_NOT_SUPPORTED | Ошибка | Эта операция не поддерживается |
| | | используемой системой сообщений. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_USER_ABORT |Прерывание | Пользователь завершил работу с |
| | | одним из диалоговых окон (cancel). |
+----------------------------+-----------+-------------------------------------+
| SUCCESS_SUCCESS | Ответ | Операция была успешно завершена. |
+----------------------------+-----------+-------------------------------------+
/ 2.12. MAPISendMail (LPMAPISENDMAIL) \
---------------------------------------
Отправка сообщения с/без приложений. Является более гибким вариантом
MAPISendDocuments.
Синтаксис:
ULONG FAR PASCAL MAPISendMail (LHANDLE lhSession,
ULONG ulUIParam,
lpMapiMessage lpMessage,
FLAGS flFlags,
ULONG ulReserved)
Параметры:
lhSession - handle сессии, которую нужно завершить. Этот параметр не может быть
нулевым.
ulUIParam - handle диалогового окна созданного MAPILogon или 0. Если 0 ,то этот
параметр игнорируется.
lpMessage - указатель на строку, содержащую сообщение для посылки.
flFlags - флаги опций:
MAPI_DIALOG - показывает, что будет выведено окно диалога, для выбора имени.
MAPI_LOGON_UI - показывает диалог для идентификации, если это потребуется.
MAPI_NEW_SESSION - если флаг установлен, функция попытается создать новую
сессию перед тем как использовать существующую.
ulReserved - зарезервировано, пока не используется.
Возвращаемые значения:
+----------------------------+-----------+-------------------------------------+
| Значение | Тип | Описание |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_ATTACHMENT_ | Ошибка | Один или более приложенных файлов в |
| OPEN_FAILURE) | | lpszFilePaths не удается обнаружить |
+----------------------------+-----------+-------------------------------------+
| (MAPI_E_ATTACHMENT_ | Ошибка | Приложение не может быть записано во|
| WRITE_FAILURE)| | временный файл. Проверте путь. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_FAILURE | Ошибка | Одна (или более) неизвестная ошибка |
| | | произошла во время выполнения. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_INSUFFICIENT_MEMORY | Ошибка | Недостаточно памяти для процесса. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_LOGIN_FAILURE | Ошибка | Был исользованр не верное имя |
| | | пользователя при входе в систему. |
+----------------------------+-----------+-------------------------------------+
| MAPI_E_USER_ABORT |Прерывание | Пользователь завершил работу с |
| | | одним из диалоговых окон (cancel). |
+----------------------------+-----------+-------------------------------------+
| SUCCESS_SUCCESS | Ответ | Операция была успешно завершена. |
+----------------------------+-----------+-------------------------------------+
/ 3. Основные структуры данных в Simple MAPI. \
--------------------------------------
/ 3.1. MapiRecipDesc \
----------------------
Эта структура содержит информацию о получателе или отправителе сообщения.
Члены класса:
ULONG ulReserved - зарезервировано, всегда 0.
ULONG ulRecipClass; - Численное значение, устанавливающее тип получателя:
0 MAPI_ORIG Основной получатель сообщения.
1 MAPI_TO Первый получатель сообщения.
2 MAPI_CC Получатель копии сообщения.
3 MAPI_BCC Получатель копии blind copy.
LPTSTR lpszName; - указатель на имя получателя или отправителя.
LPTSTR lpszAddress; - указатель на адресс получателя или отправителя. Вообще,
это используется для приходящих сообщений. Для исходящих
этот адрес может быть введен юзером. Формат адреса
следующий:
[тип адреса][электронный адрес]
Например:
SMTP: E@MAIL.COM
ULONG ulEIDSize; - размер в байтах указателя lpEntryID.
LPVOID lpEntryID; - указатель на идентификатор, используемый системой
сообщений, чтобы установить получателя сообщения.
/ 3.2. MapiMessage \
--------------------
Структура содержит информацию о посылаемом/принимаемом сообщении.
ULONG ulReserved; - зарезервировано, всегда 0.
LPTSTR lpszSubject; - указатель на строку с темой сообщения.
LPTSTR lpszNoteText; - указатель на строку с текстом сообщения.
LPTSTR lpszMessageType; - указатель на строку, показывающую
тип сообщения (например IPM - Interpersonal
Message).
LPTSTR lpszDateReceived; - указатель на дату получения в формате
YYYY/MM/DD HH(0-24):MM
LPTSTR lpszConversationID; - указатель на строку, содержащую идентификатор
потока в который поступило сообщение.
Некоторые системы не возвращают это значение.
FLAGS flFlags; - маска флагов сообщений:
MAPI_RECEIPT_REQUESTED - необходимо
подтверждение получения.
MAPI_SENT - сообщение было послано
MAPI_UNREAD - сообщение не было прочитано.
lpMapiRecipDesc lpOriginator; - информация об отправителе сообщения.
ULONG nRecipCount; - количество получателей, записанных в
массиве lpRecips.
lpMapiRecipDesc lpRecips; - указатель на структуры MapiRecipDesc,
содержащие информацию о получателях
сообщения.
ULONG nFileCount; - количество файлов-приложений в массиве
lpFiles.
lpMapiFileDesc lpFiles; - указатель на структуру, содержащую информацию
о всех файлах, приложенных к сообщению.
/ 3.3. MapiFileDesc \
---------------------
ULONG ulReserved; - зарезервировано, всегда 0.
ULONG flFlags; - маска флагов приложения:
MAPI_OLE - показывает, что приложение - OLE-объект.
MAPI_OLE_STATIC - статичный OLE-объект.
Если не установлен ни один флаг, то приложение
простой файл данных.
ULONG nPosition; - целое число, показывающее положение файлов-приложений
в сообщении, используется в MapiMessage->lpszNoteText
LPTSTR lpszPathName; - указатель на строку, содержащую путь к файлу. Включает
в себя имя диска и директории.
LPTSTR lpszFileName; - имя файла приложения (под таким именем его увидит
получатель). Может отличаться от имени в lpszPathName,
если используется временный файл. Если значение не
заданно или установленно как NULL, то используется имя
из lpszPathName.
LPVOID lpFileType; - указывает тип файла. Например ".DOC". Если значение
установлено NULL, файл будет воспринят как не
распознанный ОС.
/ 4. Использование Simple MAPI. \
---------------------------
/ 4.1. Пример отправки сообщения. \
-----------------------------------
LHANDLE pSession;
MapiRecipDesc *pRecipient;
//Структура получателей.
MapiMessage pMessage;
//Структура сообщения.
LPMAPILOGON(0,"profile", NULL, MAPI_NEW_SESSION, 0, &pSession);
//Установка новой сессии.
LPMAPIRESOLVENAME(pSession, 0, "Suicide", 0, 0, &pRecipient);
//Получение сведений о Suicide из адресной книги.
ZeroMemory(&pMessage, sizeof(pMessage));
pMessage.lpszSubject = " Subject";
pMessage.lpszNoteText = "Message Text";
pMessage.nRecipCount = 1;
pMessage.lpRecips = pRecipient;
LPMAPISENDMAIL(pSession, 0, &pMessage, 0, 0);
//Отправка сообщения
LPMAPILOGOFF(pSession, 0, 0, 0);
//Завершение сессии.
/ 4.2. Пример получения сообщения. \
-----------------------------------
Пример целиком взят с сайта Microsoft, и публикуется без изменений.
ULONG err;
LHANDLE lhSession;
CHAR rgchMsgID[513];
// Идентификатор сообщения 512 байт + NULL
MapiMessage *lpMessage;
// Используется для получения сообщения
int i,
err = MAPILogon(0L,
"c:\\pst\\myprofil.pro",
NULL, // Пароль не нужен
0L, // Использование открытой сессии
0L,
&lhSession);
if (err != SUCCESS_SUCCESS) // Проверка на ошибку
{
printf("Error: could not log on\r\n");
return(err);
}
// Поиск первого сообщения
err = MAPIFindNext(lhSession,
0L,
NULL,
NULL, // Идентификатор сообщения; NULL= первому сообщению
MAPI_LONG_MSGID |
MAPI_UNREAD_ONLY,
0L,
rgchMsgID);
if (err == MAPI_E_NO_MESSAGES) // Проверка на существование сообщения.
{
printf("No unread messages.\r\n");
return(err);
}
if (err != SUCCESS_SUCCESS) // Проверка на ошибку
{
printf("Error while searching for messages\r\n");
return(err);
}
// Пересылка сообщения
err = MAPIReadMail(lhSession,
0L,
rgchMsgID,
MAPI_SUPPRESS_ATTACH,
0L,
&lpMessage);
if(err != SUCCESS_SUCCESS) // Проверка на ошибку
{
printf("Error retrieving message %s\r\n",rgchMsgID);
return(err);
}
// Вывод на экран имена и адреса отправителей.
if((lpMessage->lpOriginator->lpszName != NULL) &&
lpMessage->lpOriginator->lpszName[0] != '\0')
printf("From: %s\r\n",lpMessage->lpOriginator->lpszName);
else
printf("From: %s\r\n",lpMessage->lpOriginator->lpszAddress);
// Вывод на экран имен получателей.
if(lpMessage->nRecipCount == 0)
printf("Warning: no recipients present for this message\r\n");
else
for(i = 0; i < lpMessage->nRecipCount; i++)
{
LPSTR lpszT = lpMessage->lpRecips[i]->lpszName;
int length = lstrlen(lpszT);
if(i == 0) // Первый получатель.
{
printf("Recipients:");
totalLength = 11;
}
if(length == 0)
length = lstrlen(lpszT=lpMessage->lpRecips[i]->lpszAddress);
if(totalLength + length + 1 > LINE_WIDTH)
{
printf("\r\n");
totalLength = 0;
}
printf(" %s",lpszT); // Окончательный вывод на экран имен.
totalLength += length + 1;
// Если адресов много, они будут разделены.
if(i < (lpMessage->nRecipCount - 1))
{
printf(";");
totalLength++;
}
}
// Вывод на экран заголовка и тела сообщения.
if(lpMessage->lpszSubject != NULL &&
lpMessage->lpszSubject[0] != '\0')
printf("Subject: %s\r\n",lpMessage->lpszSubject);
if(lpMessage->lpszNoteText != NULL &&
lpMessage->lpszNoteText[0] != '\0')
printf("Message Text:\r\n%s",lpMessage->lpszNoteText;
else
printf("No message text.\r\n");
MAPIFreeBuffer(lpMessage);
MAPILogoff(lhSession,
0L,
0L, // Без флагов
0L);
return SUCCESS_SUCCESS;
}
/ 5. Источники: \
-----------------
[1] http://msdn.microsoft.com/
[2] Borland Delphi 3 CSS MAPI Help.
[3] Miracle Dispatch [Deployment], Вирусы с обратной связью, 1999.
[4] Михаил Плакунов,"MAPI.Добавь почту в свое приложение", www.softerra.ru, 2001.
/ 6. История: \
---------------
02.12.2000 - Начало статьи. Описания функций и их параметров.
15.12.2000 - Добавлен пример отправки почты. [4]
02.03.2001 - Добавлен пример получения почты. [1]
25.03.2001 - Добавлены описания значений, возвращаемых функциями.
27.03.2001 - Добавлены описания основных структур, используемых в Simple MAPI.
Sergeev Alex aka Rook[@bsurd]
rook@evilenigma.org, rook@aanet.ru
uinC Member
[c]uinC
Все документы и программы на этом сайте собраны ТОЛЬКО для образовательных целей, мы
не отвечаем ни за какие последствия, которые имели место как следствие использования
этих материалов\программ. Вы используете все вышеперечисленное на свой страх и риск.
Любые материалы с этого сайта не могут быть скопированы без разрешения автора или
администрации.
|