На этом шаге мы рассмотрим компонент TNMPOP3.
Компонент TNMPOP3 применяется для получения электронных писем (e-mail) от РОРЗ сервера. Перед тем, как получать электронную почту при помощи компонента TNMPOP3, нужно установить соединение с сервером РОРЗ, на котором находится почтовый ящик. Для этого нужно задать значение для свойства Host, в котором нужно указать имя почтового сервера или его IP-адрес. Необходимо задать также имя пользователя и пароль в свойствах UserID и Password соответственно, открывающие доступ к почтовому ящику. После этого нужно вызвать метод Connect, который и установит соединение.
Чтобы получить почту, необходимо вызвать метод GetMailMessage. Полученное сообщение будет попадать в свойство MailMessage.
Это был краткий обзор назначения компонента. Далее рассмотрим детали по мере ознакомления со свойствами, методами и событиями этого компонента.
В свойстве MailCount компонента TNMPOP3 указывается число сообщений, находящихся в почтовом ящике пользователя на сервере. Это свойство получает значение после установления соединения с сервером. Свойству MailMessage присваивается значение после вызова метода GetMailMessage. В нем находятся все элементы полученного электронного сообщения. Эти элементы включают в себя свойства Attachments, Body, From, Head, MessagelD и Subject. В первом помещаются имена вложенных файлов, во втором - текст сообщения, в третьем - адрес отправителя, в четвертом - заголовок письма. В свойстве MessageID помещается уникальный идентификатор письма, а в свойстве Subject - тема письма.
Свойство Summary содержит краткую информацию об электронном сообщении. Это свойство изменяется после вызова метода GetSummary. В состав этого сложного свойства входят свойства Bytes, From, Header, MessageID и Subject. Свойства этого составного свойства повторяют свойства из MailMessage, но в отличие от свойства MailMessage здесь не хватает свойств Attachments и Body и добавлено новое свойство Bytes - размер сообщения. Содержимое свойств MailMessage и Summary изменяется после каждого вызова методов GetMailMessage и GetSummary соответственно. Поэтому, если считывается несколько писем, необходимо сначала обрабатывать полученные сообщения и только после этого переходить к следующему вызову метода GetMailMessage или GetSummary.
В свойстве AttachFilePath можно задать каталог для размещения присоединенных к сообщениям файлов. Если этого не сделать, то по умолчанию эти файлы будут сохраняться в том же каталоге, из которого запускалось приложение. Если каталог, указанный в свойстве AttachFilePath не существует, то присоединенные файлы будут сохраняться в текущем каталоге. Добавлять в конце пути символ слэш ("/") не обязательно; если его не указали, то он добавляется автоматически.
В зависимости от значения свойства DeleteOnRead прочитанные сообщения могут удаляться по прочтении или оставаться в почтовом ящике на сервере. Сообщения удаляются после выполнения метода GetMailMessage, если свойство DeleteOnRead установлено в True. Если значение DeleteOnRead равно False, то сообщения остаются на сервере. По умолчанию сообщения не удаляются. Удаление сообщений происходит после завершения сеанса работы с сервером. Метод Reset позволяет снять отметку на удаление, поэтому, пока сессия не окончена, все удаленные методами DeleteOnRead и DeleteMailMessage сообщения можно "вернуть".
Для регистрации на сервере нужно задать значения свойству Password и UserID. В свойстве Password указывается пароль, используемый для получения доступа к почтовому серверу. Пароль должен соответствовать имени пользователя, указанному в свойстве UserID.
Если указан неверный пароль, то в этом случае будет вызвано событие OnAuthenticationFailed. Если пароль не указан, вызывается событие OnAuthenticationNeeded. Если указанное в свойстве UserID имя не известно почтовому серверу, то происходит генерация события OnAuthenticationFailed. Если указанные в свойствах UserID и Password значения не соответствуют друг другу, то в этом случае также происходит вызов события OnAuthenticationFailed. Если в UserID не указано имя пользователя, то генерируется событие OnAuthenticationNeeded.
Метод UniqueID возвращает идентификатор сообщения, указанного в параметре метода по номеру. Идентификатор представляет собой строковое, уникальное значение, присваиваемое каждому письму почтовым сервером. Это значение помещается в свойство MessageID, являющееся частью составного свойства Summary типа TSummary. Параметр MailNumber изменяется от 1 до максимального значения, определяемого свойством MailCount.
Метод DeleteMailMessage удаляет указанное по номеру сообщение из почтового ящика на почтовом сервере. В случае возникновения ошибки происходит событие OnFailure и возбуждается исключительная ситуация. Если сообщение успешно помечается как удаленное, происходит событие OnSuccess. Удаленные этим методом сообщения только помечаются как удаленные, реально они удаляются только тогда, когда вы заканчиваете работу с почтовым сервером. А пока вы этого не сделали, вы можете вызвать метод Reset, и все "удаленные" в данном сеансе связи сообщения опять станут доступны. Метод GetMailMessage извлекает указанное по своему номеру сообщение и помещает его в свойство MailMessage. Если при выполнении метода возникает ошибка, возбуждается исключительная ситуация. Когда начинается процесс загрузки сообщения, наступает событие OnRetrieveStart. По окончании загрузки генерируется событие ОnRetrieveEnd.
Если сообщение благополучно получено, происходит событие OnSuccess. Если свойство DeleteOnRead имеет значение True, то метод GetMailMessage, кроме того, пометит на сервере полученное сообщение на удаление.
Метод GetSummary извлекает краткую информацию о письме и сохраняет ее в свойстве Summary. Если при выполнении метода возникает ошибка, то возбуждается исключительная ситуация. Перед вызовом двух последних методов следует подключиться к почтовому серверу. Если вызывать метод, а соединение с сервером неустановленно, то в этом случае произойдет событие OnConnectionRequired.
Когда начинается процесс загрузки резюме сообщения, генерируется событие OnRetrieveStart. По окончании загрузки происходит событие OnRetrieveEnd. Если резюме сообщения благополучно получено, происходит событие OnSuccess. Метод List получает список номеров и размеры сообщений. Для каждого сообщения в списке генерируется событие OnList, которому через параметры передаются номер сообщения и размер сообщения. Если возникают ошибки выполнения метода, то возбуждается исключительная ситуация. До вызова этого метода необходимо подключиться к почтовому серверу. Если этого не сделано, то произойдет событие OnConnectionRequired.
Метод Reset снимает отметку "удаленное" с сообщений, помеченных в текущем сеансе работы на удаление. Эту отметку выставляет метод DeleteMailMessage или метод GetMailMessage в случае, если свойство DeleteOnRead установлено в True. Если происходит ошибка выполнения метода, то возбуждается исключительная ситуация. Перед вызовом метода следует подключиться к почтовому серверу. Если вызывается данный метод, а соединения нет, то в этом случае будет генерироваться событие OnConnectionRequired. Если метод выполняется успешно, происходит событие OnReset.
Далее рассмотрим события данного компонента.
Событие OnAuthenticationFailed происходит в случае, когда для работы с почтовым сервером требуется идентификация, а одно из свойств UserID или Password не задано или заданные значения не верны. Если свойство Handled имеет значение True, то попытка регистрации повторяется. Если в Handled прописано False (что является значением по умолчанию), то возбуждается исключительная ситуация, и соединение обрывается.
Событие OnAuthenticationNeeded генерируется, когда не заданы значения для одного из свойств UserID или Password или не заданы оба. Если свойство Handled имеет значение True, то попытка регистрации повторяется. Если в Handled прописано False (что является значением по умолчанию), то возбуждается исключительная ситуация и соединение обрывается.
Событие OnDecodeStart происходит тогда, когда необходимо декодировать и записать на диск присоединенный к письму файл. У обработчика этого события имеется параметр FileName, определяющий имя присоединенного файла. Это имя можно изменить, если необходимо сохранить файл под другим именем. Если в письме нет вложенных файлов, то событие не наступает. Добавлять путь к имени файла не следует, потому что путь указывается в свойстве AttachFilePath.
Событие OnFailure генерируется, когда выполнение метода заканчивается с ошибкой. Это может произойти, например, при удалении сообщения.
Событие OnList происходит в процессе работы метода List после получения номера и размера текущего сообщения в списке.
Событие OnReset генерируется в случае успешного вызова метода Reset и означает тот факт, что со всех сообщений, помеченных в текущем сеансе на удаление, снята отметка на удаление.
Событие OnRetrieveEnd происходит, когда завершается загрузка письма или его резюме.
Событие OnRetrieveStart генерируется, когда начинается процесс загрузки сообщения. Эти события заменяют свои предыдущие версии, названные ошибочно OnRetriveEnd и OnRetriveStart. Эти предыдущие версии, тем не менее, доступны как Public, так что приложения, использующие их, будут работать.
Событие OnSuccess происходит после того, как сообщение успешно помечается методом DeleteMailMessage как удаленное.
На следующем шаге мы рассмотрим пример использования компонента TNMPOP3.
