Учебник РНР
Назад Глава 32. Исходные Ресурсы. Обсуждение. Вперёд

Объявление экспортируемых функций

Для объявления функций, которые экспортируются (т.е. делаются доступными в PHP как новые внешние функции), Zend предоставляет набор макросов. Сэмпл объявления выглядит примерно так:

ZEND_FUNCTION(my_function);

ZEND_FUNCTION объявляет новую C-функцию, которая работает с внутренним API Zend'а. Это означает, что функция имеет тип void и принимает в качестве параметров INTERNAL_FUNCTION_PARAMETERS (другой макрос). В дополнение к этому, к имени функции делается префикс zif. Расширенная версия ранее сделанного определения будет выглядеть так:

void zif_my_function(INTERNAL_FUNCTION_PARAMETERS);

Расширение INTERNAL_FUNCTION_PARAMETERS даст:

void zif_my_function(int ht, zval *return_value, zval *this_ptr, int return_value_used, zend_executor_globals *executor_globals);

Поскольку интерпретатор и ядро исполнителя отделены от главного пакета PHP, привлекается второй API, определяющий наборы макросов и функций: Zend API. Поскольку Zend API сейчас выполняет сравнительно мало работы, которую раньше делал PHP, многие функции PHP были уменьшены до псевдонимов для вызова в Zend API. Рекомендуем использовать Zend API везде, где это возможно, так как старый API сохранён только для обеспечения обратной совместимости. Например, типы zval и pval идентичны. zval это определение Zend'а; pval это определение PHP (в действительности pval это, в настоящее время, псевдоним zval). Так как макрос INTERNAL_FUNCTION_PARAMETERS это Zend-макрос, вышеприведённое определение содержит zval. При написании кода вы всегда должны использовать zval для обеспечения соответствия новому Zend API.

Список параметров этого объявления очень важен; вы должны их запомнить (см. Таблицу 9.1).

Рисунок 32-1. Таблица 9.1. Zend-параметры функций, вызываемых из PHP
Параметр Описание
ht Количество параметров, передаваемых в Zend-функцию. Вы не должны напрямую воздействовать на этот параметр; используйте ZEND_NUM_ARGS() для получения этого значения.
return_value Эта переменная используется для передачи и возвращения значений вашей функции обратно в PHP. Доступ к этой переменной лучше выполнять с помощью предопределённых макросов. См. далее их описание.
this_ptr Используя эту переменную, вы можете получить доступ к объекту, в котором содержится ваша функция, если она используется внутри объекта. Используйте функцию getThis() для получения этого указателя.
return_value_used Этот флаг указывает, будет ли return-значение этой функции действительно использоваться вызывающим скриптом. 0 указывает, что return-значение не используется; 1 указывает, что вызывающий ожидает return-значение. Вычисление этого флага может быть сделано для проверки корректности использования функции и для оптимизации скорости, если возвращение значения требует затратных операций (например, см., как array.c использует это).
executor_globals Эта переменная указывает на глобальные установки Zend-машины. Вам это может потребоваться, например, при создании новых переменных (подробнее об это чуть дальше). Глобалы исполнителя также могут вводиться в вашу функцию путём использования макроса ELS_FETCH().

Назад Оглавление Вперёд
Включения Header-файлов Вверх Объявление блока Zend-функции