42.3 Опции конфигурации для “local_scan()”

   Возможно использовать установку опции, которая устанавливает значения в статических переменных, в модуле “local_scan()”. Если вы этого хотите, вы должны иметь строку


LOCAL_SCAN_HAS_OPTIONS=yes

в файле “Local/Makefile”Local/Makefile когда вы  собираете Exim. (Эта строка находится в “OS/Makefile-Default”, закомментированная). Затем в исходном файле “local_scan()” вы должны определить статические переменные, для хранения значений и таблицу, определяющую их.
   Таблица должна быть вектором называемым “local_scan_options”, типа “optionlist”. Каждая точка входа – тройное значение состоящее из имени, типа опции, и указателя на переменную содержащую значение. Точки входа должны следовать в алфавитном порядке. Следуя за “local_scan_options”, вы должны так же определить значение переменной называемой “local_scan_options_count” содержащую количество входов в таблицу. Вот краткий пример, демонстрирующий две опции:


static int my_integer_option = 42; static uschar *my_string_option = US"a default string"; optionlist local_scan_options[] = { { "my_integer", opt_int, &my_integer_option }, { "my_string", opt_stringptr, &my_string_option } }; int local_scan_options_count = sizeof(local_scan_options)/sizeof(optionlist);

   Значения переменных могут быть изменены Exim'ом из файла конфигурации включением секции local scan, так, как в этом примере:


begin local_scan my_integer = 99 my_string = some string of text...

   Доступные типы данных следующие:


42.4 Доступные переменные Exim

   Заголовок “local_scan.h” дает вам доступ к некоторым С переменным. Тут перечислены только те, которые, гарантировано, будут поддерживаться от релиза к релизу. Заметьте, как бы то ни было, вы можете получить любое значение переменной Exim, включая “$recipients” вызывая функцию “expand_string()”. Экспортируемые переменные “C” следующие:


42.5 Структура “header_line”

Структура “header_line”, содержит элементы упомянутые ниже. Вы можете добавить дополнительные строки заголовка, вызывая функцию “header_add()”(см. ниже). Вы можете комментировать (удалять) линии заголовка, устанавливая их тип в “*”.


42.6 Структура “recipient_item”

Структура “recipient_item” содержит следующие элементы:


42.7 Доступные функции Exim

   Заголовок “local_scan.h” дает вам доступ к некоторому числу функций Exim. Здесь представлены только те, которые гарантированно будут поддерживаться от релиза к релизу.
“pid_t child_open(uschar **argv, uschar **envp, int newumask, int *infdptr, int *outfdptr,   BOOL make_leader)”
   Эта функция создает дочерний процесс, который запускает команду определенную в “argv”. Окружение этого процесса определено в “envp”, который может быть NULL, если не передаются переменные окружения. Новое unmask служит для процесса в newumask.
   Пайпы стандартного ввода и вывода нового процесса уже настроены и возвращаются вызвавшему через аргументы “infdptr” и “outfdptr”. Стандартная ошибка клонируется в стандартный вывод. Если есть дескрипторы для файла «в пути» в новом процессе, то они закрываются. Если последний аргумент TRUE, новый процесс возглавляет группу процессов.
   Функция возвращает pid нового процесса, или -1 если что то пошло не так.

“int child_close(pid_t pid, int timeout)”
   Функция ждет, когда дочерний процесс завершится, или таймаут (в секундах). Значение таймаута установленное в 0, означает ждать столько, сколько потребуется. Возвращаемые значения следующие:


exim -t -oem -oi -f <>

и возвращает (через аргумент int *) файловый дескриптор для пайпа который подключен к стандартному вводу. Конечный результат фукции - PID подпроцесса. Затем вы можете написать сообщение файловому дескриптору, с получателями в поле “To”, “Cc:” и/или “Bcc:” строками в заголовке.
   Когда вы закончите, вызовите “child_close()”, подождите пока процесс завершится и получите его статус окончания. Таймаут со значением ноль обычно неплохо в этих обстоятельствах. До тех пор пока вы не сделаете ошибку в адресе получателя, вы должны получать код возврата 0.

“pid_t child_open_exim2(int *fd, uschar *sender, uschar *sender_authentication)”
   Эта функция более сложная версия “child_open()”. Команда которая загружает ее:


exim -t -oem -oi -f sender -oMas sender_authentication

   Третий аргумент может быть NULL, в этом случае опция -oMas опущена.

“void debug_printf(char *, ...)”
   Это отладочная функция Exim'а, с аргументами как для “printf()”. Вывод производится в поток стандартных ошибок. Если отладка не выбрана вызов “debug_printf()” не будет иметь эффекта. Обычно вы должны делать вызовы по состоянию селекторов local_scan написав это так:


if ((debug_selector & D_local_scan) != 0) debug_printf("xxx", ...);

“uschar *expand_string(uschar *string)”
   Интерфейс для расширения строки Exim'а. Возвращаемое значение - расширяемая строка, или NULL, если расширение не произошло. Переменная C “expand_string_message” содержит сообщение об ошибке, после невозможности расширения. Если расширение не меняет строку, возвращаемое значение является указателем на строку ввода. В другом случае, возвращаемое значение указывает на новый блок памяти, который был получен вызовом “store_get()”. (см. раздел 42.8 ниже, где обсуждается выделение памяти).

“void header_add(int type, char *format, ...)”
   Эта функция позволяет добавить дополнительную строку заголовка в конец уже существующей. Первый аргумент – тип, который обычно начинается пробелом. Второй аргумент форматированная строка, и любой номер заменяемых аргументов как для “sprintf()”. Вы можете включать внутренний символ новой строки и вы должны убедится, что строка заканчивается символом новой строки.

“void header_add_at_position(BOOL after, uschar *name, BOOL topnot, int type, char *format,   ...)”
   Функция добавляет новую строку заголовка в определенную точку в цепочке заголовков.  Сам заголовок определен как для “header_add()”.
   Если “name” NULL, новый заголовок добавляется в конец цепочки, при условии что “after” TRUE, или в начало, если “after” FALSE. Если “name” не NULL, строки заголовка ищутся до первого неудаленного заголовка, который совпадает с именем. Если что то найдено, новый заголовок добавляется до него, если значение “after” FALSE. Если “after” TRUE, добавляется новый заголовок после найденного заголовка и любых найденных последующих с таким же именем (даже если они отмечены как “deleted”). Если нет совпадений с non-deleted заголовком, то опция “topnot” проверяет где был добавлен заголовок. Если он добавлялся – дополнение на верху, если нет то – внизу. Таким образом, что бы добавить заголовок после всех заголовков с полем “Received:” или в начало, если нет заголовков “Received:”, вы должны использовать:


header_add_at_position(TRUE, US"Received", TRUE, ' ', "X-xxx: ...");

   Обычно присутствует хотя бы один не удаленный заголовок “Received:”, но его может не оказаться если “received_header_text” расширяется пустой строкой.

“void header_remove(int occurrence, uschar *name)”
   Функция удаляет строки заголовка. Если “occurrence” равно нулю или отрицательное - заголовок удаляется.  Если “occurrence” больше нуля, удаляется часть заголовка. Если никаких совпадений не найдено, функция не делает ничего.

“BOOL header_testname(header_line *hdr, uschar *name, int length, BOOL notdel)”
   Функция проверяет имеет ли данный заголовок данное имя. Это не просто сравнение строк, потому что непоказываемый пробел допускается между именем и двоеточием. Если аргумент “notdel” TRUE, тогда возвращаемое FALSE применяется для всех “deleted” заголовков, иначе они не рассматриваются. Например:


if (header_testname(h, US"X-Spam", 6, TRUE)) ...

“uschar *lss_b64encode(uschar *cleartext, int length)”
   Эта функция кодирует (base64) строку, которая передаётся по адресу и длине. Текст может содержать байты любого значения включая ноль. Результат возвращается в динамическую память которая динамически получается вызовом “store_get()”. Заканчивается нулем.

“int lss_b64decode(uschar *codetext, uschar **cleartext)”
   Функция декодирования  base64 строки. Если аргумент заканчивающаяся нулем base64 строка, и адрес переменной который указывает на результат, находящийся в динамической памяти. Длина декодируемой строки получается после выполнения функции. Если вводимые данные неправильные, то результат -1. Нулевой байт добавляется в конце выводимой строки, для более простого ее определения, как С строки (предполагается что она не содержит собственных нулей). Добавляемый нулевой байт не считается.

“int lss_match_domain(uschar *domain, uschar *list)”
   Функция проверяет совпадения в доменном списке. Домены всегда выбираются бессистемно. Возвращемое значение одно из следующих:


OK match succeeded FAIL match failed DEFER match deferred

   Deffer обычно вызван каким либо поиском, таким как невозможность связаться с базой данных.

“int lss_match_local_part(uschar *localpart, uschar *list, BOOL caseless)”
   Функция проверяет совпадения в локальном списке. Третий аргумент контролирует чувствительность к регистру. Возвращаемое значение такое же как и для “lss_match_domain()”.

“int lss_match_address(uschar *address, uschar *list, BOOL caseless)”
   Эта функция проверяет совпадения для списка адресов. Третий аргумент контролирует чувствительность к регистру. Домены всегда выбираются бессистемно. Возвращаемое значение такое же как и для “lss_match_domain()”.

“int lss_match_host(uschar *host_name, uschar *host_address, uschar *list)”
   Функция проверяет совпадения в списке хостов. Самое распространенное использование:


lss_match_host(sender_host_name, sender_host_address, ...)

   Пустое поле адреса, совпадает с пустым записью в списке хостов. Если имя хоста  NULL, соответствие названия “$sender_host_address” ищется автоматически, если название хоста должно совпадать с именем в списке. Возвращаемые значения такие же как и в “lss_match_domain()”, но в дополнении “lss_match_domain()” возвращает ERROR в случае, когда имя искалось и не нашлось.

“void log_write(unsigned int selector, int which, char *format, ...)”
   Эта функция записывает лог файлы Exim'а. Первый аргумент должен быть 0 (это связано с “log_selector”). Следующий аргумент должен быть LOG_MAIN или LOG_REJECT, или LOG_PANIC или любую их комбинацию (лог. “ИЛИ” (“OR”)). Это определяет в какой лог или логи будет записано сообщение. Оставшиеся аргументы – это формат и вставка. Строка не должна включать символов новой строки, даже в конце.

“void receive_add_recipient(uschar *address, int pno)”
   Эта функция добавляет дополнительного получателя к сообщению. Первый аргумент – это адрес получателя. Если адрес не квалифицирован (не имеет домена) он квалифицируется с “qualify_recipient” доменом. Второй аргумент должен быть всегда -1.
   Функция не позволяет вам определить частный “errors_to” адрес (как описано в структуре “recipient_item” выше) потому что это предшествует дополнению поля к структуре. Однако, в последствии легко добавить это значение. Например:


receive_add_recipient(US"monitor@mydom.example", -1); recipients_list[recipients_count-1].errors_to = US"postmaster@mydom.example";

“BOOL receive_remove_recipient(uschar *recipient)”
   Эта удобная функция для удаления названного получателя из списка получателей. Если возвращаемое значение TRUE получатель удален и FALSE если совпадающий получатель не найден. Аргумент должен быть полным e-mail адресом.

“uschar rfc2047_decode(uschar *string, BOOL lencheck, uschar *target, int zeroval, int *lenptr,   uschar **error)”
   Эта функция декодирует строку которая закодирована согласно RFC 2047. Обычно это содержимое файлов заголовка. Сперва, каждое “закодированное слово”  декодируется от Q или B кодировки в байтовую строку.  Затем, если представлено имя таблицы кодировки, и если “iconv()” функция доступна, предпринимается попытка перевести результаты к данной кодовой таблице. Если это сделать не удается, бинарная строка возвращает сообщение об ошибке.
   Первый аргумент – строка которая должна быть дешифрована. Если “lencheck” TRUE, устанавливается максимальная длина MIME слова. Третий агрумент – перекодированое слово, или NULL если перекодировка не удалась.
   Если бинарный ноль попадается в строке, то он заменяется в соответствии с содержимым аргумента “zeroval”. Для использования с заголовками Exim, значение должно быть не ноль, поскольку строки заголовков заканчиваются нулем.
   Функция возвращает результат обработки строки, заканчивающийся нулем; если “lenptr” не NULL, то длина обработки устанавливается в переменную на которую она указывает. Когда “zeroval” равен 0, “lenptr” не должен быть NULL.
   Если возникла ошибка функция возвращает NULL и использует “error” аргумент для возврата сообщения об ошибке. Переменная указывающая на error устанавливается в NULL если небыло ошибки; она может быть установлена в не NULL даже когда функция возвращает не NULL значение при удачной расшифровке, но есть проблемы с перекодировкой.

“int smtp_fflush(void) ”
   Функция используется совместно с “smtp_printf()”, как описано ниже.

“void smtp_printf(char *, ...)”
   Аргументы такие же как и у “printf()”; она записывает в выходной поток SMTP. Вы должны использовать эту функцию только когда есть выходной SMTP поток, то есть тогда когда получается через SMTP входящее сообщение, в этом случае “smtp_input” TRUE, а “smtp_batched_input” FALSE. Если вам нужно протестировать  сообщение с другого хоста (в противоположность локальному процессу, который использует “-bs” опцию командной строки) вы можете проверить значение “sender_host_address” который не NULL если применяется удаленный хост.
   Если SMTP TLS соединение установлено “smtp_printf()” использует функцию вывода TLS, таким образом это может использоваться для всех SMTP соединений.
   Строки которые написаны “smtp_printf()”, внутри “local_scan()” должны начинаться с правильного кода ответа: 550 если вы собираетесь возвратить LOCAL_SCAN_REJECT, 451 если вы собираетесь возвратить LOCAL_SCAN_TEMPREJECT и 250 в остальных случаях. Поскольку вы пишите начальные строки многострочного сообщения, код может сопровождаться дефисом, что бы показать что это не последняя строчка в коде отклика. Вы должны так же убедиться что строки, которые вы пишите заканчиваются CRLF. Например:


smtp_printf("550-this is some extra info\r\n"); return LOCAL_SCAN_REJECT;

   Учтите, что вы можете создать многострочный отклик включая символы новой строки в данные возвращаемые через аргумент “return_text”.
   Добавляемое значение использует “smtp_printf()” для того, что бы вы могли ввести задержки между многократным выводом.
   Функция “smtp_printf()” не использует никакого возвращаемого сообщения об ошибке, потому что она не стирает автоматически идущий вывод и поэтому не проверяет состояние потока. (в главном коде Exim стирание и проверка ошибок отрабатываются когда Exim готов для следующего SMTP соединения). Если вы хотите удалить вывод и проверить ошибки (например, сбрасывая TCP/IP соединение) вы все еще сможете вызвать “smtp_fflush()”, у которой нет аргументов. Она стирает вывод и возвращает ненулевое значение, при возникновении ошибки.

“void *store_get(int)”
   Эта функция получает доступ к управлению внутренней памятью Exim. Она получает новую область памяти, чей размер задан аргументом. Exim завершается, если память исчерпана. Смотрите следующий раздел, где обсуждается выделение памяти.

“void *store_get_perm(int)”
   Функция наподобии “store_get()”, но всегда получает память из постоянного пула. Смотрите следующий раздел, где обсуждается выделение памяти.

“uschar *string_copy(uschar *string)”
   смотрите ниже

“uschar *string_copyn(uschar *string, int length)”
   смотрите ниже

“uschar *string_sprintf(char *format, ...)”
   Эти три функции создают строки используя средства динамической памяти Exim'а. Первая делает копию всей строки. Вторая копирует максимальное число символов, переданных во втором аргументе. Третья использует формат и вставку новой строки. В каждом случае результатом является указатель на новую строку в данном пуле памяти. Смотрите следующий раздел, где обсуждается выделение памяти.



42.8 Больше об обработке памяти Exim'ом

   Нет никакой функции для освобождения памяти, поскольку она не нужна. Динамическая память, которую использует Exim автоматически передается другому сообщению полученному этим же процессом (распространяется только на SMTP подключения – другие методы могут только доставить одно сообщение за раз). После получения последнего сообщения, процесс получения завершается.
   Поскольку память повторно используется, нормальная динамическая память не может быть использована для хранения данных, которые должны быть сохранены более чем число входящих сообщений на том же SMTP соединении. Однако, Exim на самом деле использует два пула динамической памяти, второй не передается и может использоваться для этих целей.
   Если вы хотите выделить память, которая останется доступной для последующих сообщений в том же SMTP соединении, вы должны установить


store_pool = POOL_PERM

прежде, чем вызовите функцию выделения памяти. Не нужно восстанавливать значение без необходимости; однако если вы хотите вернуться к нормальному пулу, вы можете восстановить прежнее значение “store_pool” или установить явным образом POOL_MAIN.
   Установка пула, применяется ко всем функциям, которые получают динамическую память, включая “expand_string()”, “store_get()”, и “string_xxx()” функции. Есть так же, удобная функция называемая “store_get_perm()” которая получает блоки памяти из постоянного пула, сохраняя значения “store_pool”.

=============
translated by Andy
verifying by lissyara
verifying by Gerk