Дата и время публикации:
Назначение и использование
Библиотеки libESMTP Library for Posting Electronic Mail
1. Назначение
Библиотека libESMTP является клиентом SMTP, который управляет отправкой электронных писем через сконфигурированный ранее транспортного агента почтовых отправлений (Mail Transport Agent, MTA) . Это может быть использовано как часть почтового клиента пользователя (Mail User Agent, MUA) или других программ, которые должны быть доступны для отправки электронных писем, где в реализуемой функциональности поддержка ими такого обмена не является главной.
2. Использование
2.1 Установка библиотеки
В Debian/GNU Linux необходимо установить следующий набор пакетов, который перечислен в дампе 2.1
Дамп 2.1
sudo apt search libesmtp6 libesmtp-dev openssl-dev build-essential
2.2 Удовлетворение зависимостей в процессе линковки
В Makefile.am проекта прописать в переменной _LDADD линковщика программы myesmtp, как показано в листинге 2.2
Дамп 2.2
. . .
myesmtp_LDADD = \
-lm \
-lssl \
-lcrypto \
-ldl \
-lpthread \
${libdir}/libesmtp.a
. . .
Для использования libESMTP API подключаются заголовочный файл <libesmtp.h>.
2.3 Установка соединения
Функции указываются в порядке их вызова.
2.3.1 Функция smtp_create_session()
СИНОПСИС
smtp_session_t smtp_create_session(void);
ОПИСАНИЕ
Производит открытие сессии . При этом, возвращаемое значение smtp_session_t является по сути указателем, которое необходимо проверять на нулевое значение, как показано в листинге 2.4
Листинг 2.4
smtp_session_t session = smtp_create_session();
if( session )
{
smtp_message_t message = smtp_add_message (session);
/* success */
}
else
{
/* failure */
}
После нормального завершения создания сессии функция возвратит ненулевой указатель session , как показано в листинге 2.4, далее, если сессия была успешно создана, к ней добавляется сообщение с помощью функции smtp_add_message() .
2.3.2 Функция smtp_add_message()
СИНОПСИС
smtp_message_t smtp_add_message(smtp_session_t session);
ОПИСАНИЕ
Добавляет в инкапсулирует сообщение во внутрь сессии.
Возвращает ненулевое значение в случае нормального завершения и нулевое – в случае отказа, как показано в листинге 2.4
2.3.3 Функция smtp_set_server()
СИНОПСИС
int smtp_set_server (smtp_session_t session, const char *hostport);
Устанавливает имя узла в передаваемом сообщении на удаленный сервер в формате доменного имени без пробелов и указания порта через двоеточие. В случае отсутствие берется порт 587
Листинг 2.5. Пример значений порта 2525 для узла "mail.localhost"
if ( smtp_set_server (session, "mail.localhost:2525" ) )
{
/* success */
}
else
{
/* failure */
}
Возвращает ненулевое значение в случае нормального завершения и нулевое – в случае отказа, как показано в дампе выше.
2.3.4 Функция smtp_set_reverse_path()
СИНОПСИС
int smtp_set_reverse_path (smtp_session_t session, const char *mailbox);
ОПИСАНИЕ
Устанавливает путь возрата почтового ящика (обратный адрес) согласно представления адреса в RFC 5321. В случае, если обратный адрес отсутствует, требуется указать во втром аргументе mailbox значение NULL или "". При этом строго рекомендуется, чтобы сообщение содержало в заголовке "From:" как минимум один обратный адрес.
2.3.5 Функция smtp_set_header()
СИНОПСИС
int smtp_set_header (smtp_message_t message, const char *header, ... );
ОПИСАНИЕ
Устанавливает заголовок сообщение согласно RFC 5322. При этом, если значение подставляется с использованием smtp_set_header() заголовок будет представлен в сообщении. Так же, если при вставке значения не установлена опция Hdr_OVERRIDE, оно будет использоваться неизменяемым. Иначе, значение в сообщении будет замещено.
Заголовок в сообщении не соответствуют действиями с заголовками, определенными по умолчанию, или передаются неизменными с устанавкой через smtp_set_header()
Ниже показан пример установки в заголовке поля адреса назначения "To" и "Subject", как показано в листинге 2.6
Листинг 2.6
const char * subject = "My first message sending on e-mail";
...
If ( smtp_set_header (message, "To", NULL, NULL) )
{
if( smtp_set_header (message, "Subject", subject) )
{
if( smtp_set_header_option (message, "Subject", Hdr_OVERRIDE, 1) )
{
/* Написание текста письма и отправка сообщения */
}
}
}
...
Как уже упоминалось выше, по умолчанию запрещены какие либо изменения введеных значений. В данном случае, поле "Subject" будет изменяемым, потому что ему устанавливается опция Hdr_OVERRIDE после добавления в заголовок сообщения.
2.3.6 Функция smtp_set_message_str()
СИНОПСИС
int smtp_set_message_str ( smtp_message_t message, const char *string );
ОПИСАНИЕ
Устанавливает текстовое сообщение согласно формату, представленным в RFC 5322, как показано в примере установки (передачи) текстового сообщения, в листинге 2.7
Листинг 2.7
(void)smtp_set_message_str ( message, " Some message text ... ");
2.3.7 Функция smtp_add_recipient()
СИНОПСИС
smtp_recipient_t smtp_add_recipient ( smtp_message_t message,
const char* mailbox );
ОПИСАНИЕ
Добавляет адрес отправителя в заголовок сообщения согласно синтаксису адреса, принятого в RFC5321
При этом, строго рекомендуется добавлять в сообщение (заголовок) поля "To:", "Bcc:" или "Сс:", как это уже делали ранее с использованием функции smtp_set_header()
В случае отказа возвращает нулевое значение, как показано в листинге 2.8
Листинг 2.8
const char* mailbox = "mailbox@mail.server";
if( smtp_add_recipient ( message, mailbox ) )
{
/* failure */
}
else
{
/* success */
}
2.3.8 Функция smtp_start_session ()
СИНОПСИС
int smtp_start_session(smtp_session_t session );
ОПИСАНИЕ
Инициирует передачу сообщения по протоколу SMTP, которая заключается в соединении с сервером SMTP и передачи ему сообщения в виде пакета, который конструируется из сообщения и параметров отправления, установленных ранее.
В случае, успешного завершения отправки статус можно получить с использованием функции smtp_message_transfer_status(). В обратном случае, с использованием smtp_strerror() и smtp_errno() выяснить причину ошибки.
Библиография
3.1 libESMTP - A Library for Posting Electronic Mail
3.3 SMTPSettings