[翻译][php扩展和嵌入式]第7章-接受参数
全部翻译内容pdf文档下载地址: http://download.csdn.net/detail/lgg201/5107012
本书目前在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项目中, 同时保留一份独立版本.
原书名:
原作者: sara golemon
译者: goosman.lei(雷果国)
译者email: lgg860911@yahoo.com.cn
译者blog: http://blog.csdn.net/lgg201
权利声明
此译本在不获利的情况下, 可以无限制自由传播.
除了几个预览的例外, 你迄今处理的扩展函数都很简单, 只有返回. 然而, 多数函数并非只有一个目的. 你通常会传递一些参数, 并希望接收到基于值和其他附加处理的有用的响应.
zend_parse_parameters()的自动类型转换
和上一章你看到的返回值一样, 参数的值也是围绕着对zval引用的间访展开的. 获取这些zval*的值最简单的方法就是使用zend_parse_parameters()函数.
调用zend_parse_parameters()几乎总是以zend_num_args()宏接着是无所不在的tsrmls_cc. zend_num_args()从名字上可以猜到, 它返回int型的实际传递的参数个数. 由于zend_parse_parameters()内部工作的方法, 你可能不需要直接了解这个值, 因此现在只需要传递它.
zend_parse_parameters()的下一个参数是格式串参数, 它是由zend引擎支持的基础类型描述字符组成的字符序列, 用来描述要接受的函数参数. 下表是基础的类型字符:
类型字符
用户空间数据类型
b
boolean
l
integer
d
floating point
s
string
r
resource
a
array
o
object instance
o
object instance of a specified type
z
non-specific zval
z
dereferenced non-specific zval
zend_parse_parameters()剩下的参数依赖于你的格式串中所指定的类型描述. 对于简单类型, 直接解引用为c语言的基础类型. 例如, long数据类型如下解出:
php_function(sample_getlong){ long foo; if (zend_parse_parameters(zend_num_args() tsrmls_cc, l, &foo) == failure) { return_null(); } php_printf(the integer value of the parameter you passed is: %ld\n, foo); return_true;}
尽管integer和long的存储空间通常是一样大的, 但它们并不完全一致. 尝试将一个int类型的数据解引用到long *参数可能会带来不期望的结果, 尤其是在64位平台上更加容易出错. 因此, 请严格使用下表中列出的数据类型.
类型
c语言中的对应数据类型
b
zend_bool
l
long
d
double
s
char *, int
r
zval *
a
zval *
o
zval *
o
zval *, zend_class_entry *
z
zval *
z
zval *
注意, 所有其他的复杂类型实际上都解析为简单的zval. 这样做的原因和不使用return_*()宏返回复杂数据类型一样, 都是受限于无法真正的模拟c空间中的这些结构. zend_parse_parameters()能为你的函数所做的, 是确保你接收到的zval *是正确的类型. 如果需要, 它甚至会执行隐式的类型转换, 比如将数组转换为stdclass的对象.
s和o类型需要单独说明, 因为它们一次调用需要两个参数. 在第10章php4对象和第11章php5对象中你将更进一部的了解o. 对于s这个类型, 我们对第5章你的第一个扩展的sample_hello_world()函数进行一次扩展, 让它可以跟指定的人名打招呼.
function sample_hello_world($name) { echo hello $name!\n;}/* 在c中, 你将使用zend_parse_parameters()函数接受一个字符串 */php_function(sample_hello_world){ char *name; int name_len; if (zend_parse_parameters(zend_num_args() tsrmls_cc, s, &name, &name_len) == failure) { return_null(); } php_printf(hello ); phpwrite(name, name_len); php_printf(!\n);}
zend_parse_parameters()函数可能由于函数传递的参数太少不能满足格式串, 或者因为其中某个参数不能转换为请求的类型而失败. 这种情况下, 它将自动的输出错误消息, 因此你的扩展不需要这样做.
要请求超过1个参数, 就需要扩充格式串, 包括其他字符, 并将zend_parse_parameters()调用的后面其他参数压栈. 参数和它们在用户空间函数定义的行为一致, 从左向右解析.
function sample_hello_world($name, $greeting) { echo hello $greeting $name!\n;}sample_hello_world('john smith', 'mr.');or:php_function(sample_hello_world){ char *name; int name_len; char *greeting; int greeting_len; if (zend_parse_parameters(zend_num_args() tsrmls_cc, ss, &name, &name_len, &greeting, &greeting_len) == failure) { return_null(); } php_printf(hello ); phpwrite(greeting, greeting_len); php_printf( ); phpwrite(name, name_len); php_printf(!\n);}
除了基础类型, 还有3个元字符用于修改参数处理方式. 如下表所示:
类型修改符
含义
|
接下来是可选参数了.当指定它时,所有之前的参数都被认为是必须的,所有后续的参数都被认为是可选的.
!
!之前的一个修饰符对应的参数如果是null,提供的内部变量将被设置为真实的null指针.
/
/之前的一个修饰符对应的参数指定为写时拷贝,它将自动的隔离到新的zval(is_ref = 0, refcount = 1)
可选参数
我们再来看一看修订版的sample_hello_world()示例, 下一步是增加一个可选的$greeting参数:
function sample_hello_world($name, $greeting='mr./ms.') { echo hello $greeting $name!\n;}
sample_hello_world()现在可以只用$name参数调用, 也可以同时使用两个参数调用.
sample_hello_world('ginger rogers','ms.');sample_hello_world('fred astaire');
当不传递第二个参数时, 使用默认值. 在c语言实现中, 可选参数也是以类似的方式指定.
要完成这个功能, 我们需要使用zend_parse_parameters()格式串中的管道符(|). 管道符左侧的参数从调用栈解析, 所有管道符右边的参数如果在调用栈中没有提供, 则不会被修改(zend_parse_parameters()格式串后面对应的参数). 例如:
php_function(sample_hello_world){ char *name; int name_len; char *greeting = mr./mrs.; int greeting_len = sizeof(mr./mrs.) - 1; /* 如果调用时没有传递第二个参数, 则greeting和greeting_len保持不变. */ if (zend_parse_parameters(zend_num_args() tsrmls_cc, s|s, &name, &name_len, &greeting, &greeting_len) == failure) { return_null(); } php_printf(hello ); phpwrite(greeting, greeting_len); php_printf( ); phpwrite(name, name_len); php_printf(!\n);}
除非调用时提供了可选参数的值, 否则不会修改它的初始值, 因此, 为可选参数设置初始的默认值非常重要. 多数情况下, 它的初始默认值是null/0, 不过有时候, 比如上面的例子, 默认的是有意义的其他值.
is_null vs. null
每个zval, 即便是非常简单的is_null类型, 都会占用一块很小的内存空间. 从而, 它就需要一些(cpu)时钟周期去分配内存空间, 初始化值, 最后认为不再需要它的时候释放它.
对于很多函数, 在调用空间使用null参数只是标记参数不重要, 因此这个处理就没有意义. 幸运的是zend_parse_parameters()允许参数被标记为允许null, 如果在一个格式描述字符后加上感叹号(!), 则表示对应参数如果传递了null, 则将zend_parse_parameters()调用时对应的参数设置为真正的null指针. 考虑下面两段代码, 一个有这个修饰符, 一个没有:
php_function(sample_arg_fullnull){ zval *val; if (zend_parse_parameters(zend_num_args() tsrmls_cc, z, &val) == failure) { return_null(); } if (z_type_p(val) == is_null) { val = php_sample_make_defaultval(tsrmls_c); }...php_function(sample_arg_nullok){ zval *val; if (zend_parse_parameters(zend_num_args() tsrmls_cc, z!, &val) == failure) { return_null(); } if (!val) { val = php_sample_make_defaultval(tsrmls_c); }...
这两个版本的代码其实没什么不同, 前者表面上看起来需要更多的处理时间. 通常, 这个特性并不是很有用, 但最好还是知道有这么回事.
强制隔离
当一个变量传递到一个函数中后, 无论是否是引用传值, 它的refcount至少是2; 一个是变量自身, 另外一个是传递给函数的拷贝. 因此在修改zval之前(如果直接在参数传递进来的zval上), 将它从它所属的非引用集合中分离出来非常重要.
如果没有/格式修饰符, 这将是一个单调重复的工作. 这个格式修饰符自动的隔离所有写时拷贝的引用传值参数, 这样, 你的函数中就可以为所欲为了. 和null标记一样, 这个修饰符放在它要修饰的格式描述字符后面. 同样和null标记一样, 直到你真的有使用它的地方, 你可能才知道你需要这个特性.
zend_get_arguments()
如果你正在设计的代码计划在非常旧的php版本上工作, 或者你有一个函数, 它只需要zval *, 就可以考虑使用zend_get_parameters()的api调用.
zend_get_parameters()调用与它对应的新版本有一点不同. 首先, 它不会自动执行类型转换; 而是所有期望的参数都是zval *数据类型. 下面是zend_get_parameters()的最简单用法:
php_function(sample_onearg){ zval *firstarg; if (zend_get_parameters(zend_num_args(), 1, &firstarg) == failure) { php_error_docref(null tsrmls_cc, e_warning, expected at least 1 parameter.); return_null(); } /* do something with firstarg... */}
其次, 你可能已经注意到, 它需要手动处理错误消息, zend_get_parameters()并不会在失败的时候输出错误文本. 它对可选参数的处理也很落后. 如果你让它抓取4个参数, 最好至少给它提供4个参数, 否则可能返回failure.
最后, 它不像parse, 这个get变种会自动的隔离所有写时复制的引用集合. 如果你想要跳过自动隔离, 就要使用它的兄弟接口: zend_get_parameters_ex().
除了不隔离写时复制集合, zend_get_parameters_ex()还有一个不同点是返回zval **指针而不是直接的zval *. 它们的差别同样可能直到你使用的时候才知道需要它们, 不过它们最终的使用非常相似:
php_function(sample_onearg){ zval **firstarg; if (zend_get_parameters_ex(1, &firstarg) == failure) { wrong_param_count; } /* do something with firstarg... */}
要注意的是_ex版本不需要zend_num_args()参数. 这是因为增加_ex的版本时已经比较晚了, 当时zend引擎已经不需要这个参数了.
在这个例子中, 你还使用了wrong_param_count宏, 它用来处理e_warning错误消息的显示已经自动的离开函数.
处理任意数目的参数
还有两个zend_get_parameters()族的函数, 用于解出zval *和zval **指针集合, 它们适用于有很多参数或运行时才知道参数个数的引用场景.
考虑var_dump()函数, 它用来展示传递给它的任意数量的变量的内容:
php_function(var_dump){ int i, argc = zend_num_args(); zval ***args; args = (zval ***)safe_emalloc(argc, sizeof(zval **), 0); if (zend_num_args() == 0 || zend_get_parameters_array_ex(argc, args) == failure) { efree(args); wrong_param_count; } for (i=0; i这里, var_dump()预分配了一个传给函数的参数个数大小的zval **指针向量. 接着使用zend_get_parameters_array_ex()一次性将参数摊入到该向量中. 你可能会猜到, 存在这个函数的另外一个版本: zend_get_parameters_array(), 它们仅有一点不同: 自动隔离, 返回zval *而不是zval **, 在第一个参数上要求传递zend_num_args().
参数信息和类型暗示
在上一章已经简短的向你介绍了使用zend引擎2的 参数信息结构进行类型暗示的概念. 我们应该记得, 这个特性是针对ze2(zend引擎2)的, 对于php4的ze1(zend引擎1)不可用.
我们重新从ze2的参数信息结构开始. 每个参数信息都使用zend_begin_arg_info()或zend_begin_arg_info_ex()宏开始, 接着是0个或多个zend_arg_*info()行, 最后以zend_end_arg_info()调用结束.
这些宏的定义和基本使用可以在刚刚结束的第6章返回值的编译期引用传值一节中找到.
假设你想要重新实现count()函数, 你可能需要创建下面这样一个函数:
php_function(sample_count_array){ zval *arr; if (zend_parse_parameters(zend_num_args() tsrmls_cc, a, &arr) == failure) { return_null(); } return_long(zend_hash_num_elements(z_arrval_p(arr)));}
zend_parse_parameters()会做很多工作, 以保证传递给你的函数是一个真实的数组. 但是, 如果你使用zend_get_parameters()函数或某个它的兄弟函数, 你就需要自己在函数中做类型检查. 当然, 你也可以使用类型暗示! 通过定义下面这样一个arg_info结构:
static zend_begin_arg_info(php_sample_array_arginfo, 0) zend_arg_array_info(0, arr, 0) zend_end_arg_info()
并在你的php_sample_function结构中声明该函数时使用它:
php_fe(sample_count_array, php_sample_array_arginfo)
这样就将类型检查的工作交给了zend引擎. 同时你给了你的参数一个名字(arr), 它可以在产生错误消息时被使用, 这样在使用你api的脚本发生错误时, 更加容易跟踪问题.
在第6章第一次介绍参数信息结构时, 你可能注意到了对象, 也可以使用arg_info宏进行类型暗示. 只需要在参数名后增加一个额外的参数来说明类型名(类名)
static zend_begin_arg_info(php_sample_class_arginfo, 0) zend_arg_object_info(1, obj, stdclass, 0) zend_end_arg_info()
要注意到这里的第一个参数(by_ref)被设置为1. 通常来说这个参数对对象来说并不是很重要, 因为ze2中所有的对象默认都是引用方式的, 对它们的拷贝必须显式的通过clone来实现. 在函数调用内部强制clone可以做到, 但是它和强制引用完全不同.
因为当设置了zend.ze1_compatiblity_mode标记时, 你可能关心zend_arg_object_info一行的by_ref设置. 这种特殊情况下, 对象可能仍然传递的是一个拷贝而不是引用. 因为你在处理对象的时候, 可能需要的是一个真正的引用, 因此设置这个标记你就不用担心这一方面的影响.
不要忘记了数组和对象的参数信息宏中有一个allow_null选项. 关于允许null的细节请参考前一章的编译期引用传值一节.
当然, 使用使用参数信息进行类型暗示只在ze2中支持, 如果你想让你看的扩展兼容php4, 需要使用zend_get_parameters(), 这样就只能将类型验证放到函数内部, 手动的通过测试z_type_p(value)或使用第2章看到的convert_to_type()方法进行自动类型转换来完成.
小结
现在你的手头可能已经有点脏乱了, 和用户空间通信的功能代码通过简单的输入/输出函数实现. 已经比较深入的了解了zval的引用计数系统, 并学习了控制变量传递到你的内部函数方法和时机.
下一章将开始学习数组数据类型, 并了解用户空间的数组表示怎样映射到内部的hashtable实现. 此外还将看到一大批可选的zend以及php api函数, 它们用于操纵这些复杂的结构体.
目录上一章: 返回值
下一章: 在数组和哈希表上工作