[翻译][php扩展和嵌入式]第6章-返回值

本书目前在github上由laruence(http://www.laruence.com)和walu(http://www.walu.cc)两位大牛组织翻译. 该翻译项目地址为: https://github.com/walu/phpbook

本书在github上的地址: https://github.com/goosman-lei/php-eae

未来本书将可能部分合并到phpbook项目中, 同时保留一份独立版本.

原书名: <Extending and Embedding PHP>

原作者: Sara Golemon

译者: goosman.lei(雷果国)

译者Email: lgg860911@yahoo.com.cn

译者Blog: http://blog.csdn.net/lgg201

返回值

用户空间函数利用return关键字向它的调用空间回传信息, 这一点和C语言的语法相同.

例如:

普通的ZVAL宏
return_value专用宏
ZVAL_NULL(return_value)
RETVAL_NULL()
ZVAL_BOOL(return_value, bval)
RETVAL_BOOL(bval)
ZVAL_TRUE(return_value)
RETVAL_TRUE
ZVAL_FALSE(return_value)
RETVAL_FALSE
ZVAL_LONG(return_value, lval)
RETVAL_LONG(lval)
ZVAL_DOUBLE(return_value, dval)
RETVAL_DOUBLE(dval)
ZVAL_STRING(return_value, str, dup)
RETVAL_STRING(str, dup)
ZVAL_STRINGL(return_value, str, len, dup)
RETVAL_STRINGL(str, len, dup)
ZVAL_RESOURCE(return_value, rval)
RETVAL_RESOURCE(rval)

要注意到, TRUE和FALSE宏没有括号. 这是考虑到了Zend/PHP代码标准的偏差, 保留了主要的一种以保持向后兼容. 如果你构建扩展失败, 收到了错误消息undefined macro RETVAL_TRUE(), 请确认你是否在代码中写这两个宏时误写了括号.
通常, 在你的函数处理返回值的时候, 它已经准备好退出并将控制返回给调用作用域了. 由于这个原因, 为内部函数设计了另外一些宏用于返回: RETURN_*()族宏.
标记类型
含义
BYREF_NONE
这个参数永远都不允许引用传值.尝试使用调用时引用传值将被忽略,参数仍然会被拷贝.
BYREF_FORCE
参数永远都是引用传值,无论怎样调用.这等价于在用户空间函数定义时使用取地址符(&)
BYREF_ALLOW
参数是否引用传值取决于调用时的语义.这等价于普通的用户空间函数定义.
BYREF_FORCE_REST
当前参数以及后面所有参数都将应用BYREF_FORCE.这个标记只能作为列表的最后一个标记.在BYREF_FORCE_REST后面放置其他标记可能导致未定义行为.

在Zend引擎2(php 5+)中, 你将使用一种更加可扩展的结构, 它包含类更多的信息, 比如最小和最大参数要求, 类型暗示, 是否强制引用等.
首先, 参数信息结构使用两个宏中的一个定义. 较简单的一个是ZEND_BEGIN_ARG_INFO(), 它需要两个参数:
宏
用途
ZEND_ARG_PASS_INFO(by_ref)
by_ref和所有后面的宏一样是一个二选一的选项,它用来标识是否对应的参数应该被强制为引用传值.设置这个选项为1等同于在Zend引擎1中使用BYREF_FORCE.
ZEND_ARG_INFO(by_ref, name)
这个宏提供了一个附加的name属性,用于内部生成的错误消息和反射API.它应该被设置成一些非加密的帮助信息.
ZEND_ARG_ARRAY_INFO(by_ref, name, allow_null)
这两个宏提供了内部函数的参数类型暗示,用来描述参数只能是数组或某个特定类型的实例.将allow_null设置为非0值将允许调用时在放置array/object的地方传递NULL值.
ZEND_ARG_OBJ_INFO(by_ref, name, classname, allow_null)

最后, 所有使用Zend引擎2的宏设置的参数信息结构必须使用ZEND_END_ARG_INFO()结束. 对于你的sample函数, 你需要选择一个如下的结构:
PHP_FALIAS(sample_byref_compiletime, sample_byref_calltime,    php_sample_byref_arginfo)
回顾第5章, 这将创建一个名为sample_byref_compiletime()的用户空间函数, 它对应的内部实现是sample_byref_calltime()的代码. php_sample_byref_arginfo是这个版本的特殊之处.
小结
本章你看到了怎样从一个内部函数返回值, 包括直接返回值和引用方式返回, 以及通过参数栈引用返回. 此外还简单了解了Zend引擎2的参数类型暗示结构zend_arg_info.
下一章你将会继续探究接受基本的zval参数以及使用zend_parse_parameters()强大的类型戏法.

目录上一章: 您的第一个扩展
下一章: 待续