Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 128 lines (105 sloc) 3.887 kb
27d63c5 Adding some docs for new parameter parsing API. They really should be mo...
Andrei Zmievski authored
1 New parameter parsing functions
2 ===============================
3
4 It should be easier to parse input parameters to an extension function.
5 Hence, borrowing from Python's example, there are now a set of functions
6 that given the string of type specifiers, can parse the input parameters
7 and store the results in the user specified variables. This avoids most
8 of the IS_* checks and convert_to_* conversions. The functions also
9 check for the appropriate number of parameters, and try to output
10 meaningful error messages.
11
12
13 Prototypes
14 ----------
15 /* Implemented. */
b31c3e0 Fix-up.
Andrei Zmievski authored
16 int zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, ...);
17 int zend_parse_parameters_ex(int flags, int num_args TSRMLS_DC, char *type_spec, ...);
27d63c5 Adding some docs for new parameter parsing API. They really should be mo...
Andrei Zmievski authored
18
19 The zend_parse_parameters() function takes the number of parameters
20 passed to the extension function, the type specifier string, and the
21 list of pointers to variables to store the results in. The _ex() version
22 also takes 'flags' argument -- current only ZEND_PARSE_PARAMS_QUIET can
23 be used as 'flags' to specify that the function should operate quietly
24 and not output any error messages.
25
b31c3e0 Fix-up.
Andrei Zmievski authored
26 Both functions return SUCCESS or FAILURE depending on the result.
27
27d63c5 Adding some docs for new parameter parsing API. They really should be mo...
Andrei Zmievski authored
28 The auto-conversions are performed as necessary. Arrays, objects, and
fd4d1f2 Jon Parise Formatting nit: "autoconverted" to "auto-converted"
jparise authored
29 resources cannot be auto-converted.
27d63c5 Adding some docs for new parameter parsing API. They really should be mo...
Andrei Zmievski authored
30
31
32 Type specifiers
33 ---------------
34 l - long
35 d - double
36 s - string (with possible null bytes) and its length
37 b - boolean, stored in zend_bool
38 r - resource (stored in zval)
39 a - array
40 o - object (of any type)
41 O - object (of specific type, specified by class entry)
42 z - the actual zval
43
44 The following characters also have a meaning in the specifier string:
45 | - indicates that the remaining parameters are optional, they
46 should be initialized to default values by the extension since they
47 will not be touched by the parsing function if they are not
48 passed to it.
49 / - use SEPARATE_ZVAL_IF_NOT_REF() on the parameter it follows
50 ! - the parameter it follows can be of specified type or NULL (only applies
51 to 'a', 'o', 'O', 'r', and 'z'). If NULL is passed, the results
52 pointer is set to NULL as well.
53
54 Examples
55 --------
56 /* Gets a long, a string and its length, and a zval */
57 long l;
58 char *s;
59 int s_len;
60 zval *param;
b31c3e0 Fix-up.
Andrei Zmievski authored
61 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "lsz",
62 &l, &s, &s_len, &param) == FAILURE) {
63 return;
64 }
27d63c5 Adding some docs for new parameter parsing API. They really should be mo...
Andrei Zmievski authored
65
66
67 /* Gets an object of class specified by my_ce, and an optional double. */
68 zval *obj;
69 double d = 0.5;
550550f Rasmus Lerdorf Minor tweaks
rlerdorf authored
70 zend_class_entry my_ce;
b31c3e0 Fix-up.
Andrei Zmievski authored
71 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O|d",
72 &obj, my_ce, &d) == FAILURE) {
73 return;
74 }
27d63c5 Adding some docs for new parameter parsing API. They really should be mo...
Andrei Zmievski authored
75
76
77 /* Gets an object or null, and an array.
78 If null is passed for object, obj will be set to NULL. */
79 zval *obj;
80 zval *arr;
550550f Rasmus Lerdorf Minor tweaks
rlerdorf authored
81 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "o!a",
b31c3e0 Fix-up.
Andrei Zmievski authored
82 &obj, &arr) == FAILURE) {
83 return;
84 }
27d63c5 Adding some docs for new parameter parsing API. They really should be mo...
Andrei Zmievski authored
85
86
550550f Rasmus Lerdorf Minor tweaks
rlerdorf authored
87 /* Gets a separated array which can also be null. */
27d63c5 Adding some docs for new parameter parsing API. They really should be mo...
Andrei Zmievski authored
88 zval *arr;
550550f Rasmus Lerdorf Minor tweaks
rlerdorf authored
89 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a/!",
b31c3e0 Fix-up.
Andrei Zmievski authored
90 &arr) == FAILURE) {
91 return;
92 }
27d63c5 Adding some docs for new parameter parsing API. They really should be mo...
Andrei Zmievski authored
93
94
95 /* Get only the first three parameters (useful for varargs functions). */
96 zval *z;
97 zend_bool b;
98 zval *r;
b31c3e0 Fix-up.
Andrei Zmievski authored
99 if (zend_parse_parameters(3 TSRMLS_CC, "zbr!",
100 &z, &b, &r) == FAILURE) {
101 return;
102 }
27d63c5 Adding some docs for new parameter parsing API. They really should be mo...
Andrei Zmievski authored
103
104
105 /* Get either a set of 3 longs or a string. */
106 long l1, l2, l3;
107 char *s;
ad8b425 Please note that you need to use 'int' as a length type when
Sascha Schumann authored
108 /*
109 * The function expects a pointer to a integer in this case, not a long
110 * or any other type. If you specify a type which is larger
111 * than a 'int', the upper bits might not be initialized
112 * properly, leading to random crashes on platforms like
113 * Tru64 or Linux/Alpha.
114 */
115 int length;
dfd8ea7 - Fix README
Derick Rethans authored
116
b31c3e0 Fix-up.
Andrei Zmievski authored
117 if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC,
118 "lll", &l1, &l2, &l3) == SUCCESS) {
27d63c5 Adding some docs for new parameter parsing API. They really should be mo...
Andrei Zmievski authored
119 /* manipulate longs */
b31c3e0 Fix-up.
Andrei Zmievski authored
120 } else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC,
dfd8ea7 - Fix README
Derick Rethans authored
121 "s", &s, &length) == SUCCESS) {
27d63c5 Adding some docs for new parameter parsing API. They really should be mo...
Andrei Zmievski authored
122 /* manipulate string */
123 } else {
124 /* output error */
b31c3e0 Fix-up.
Andrei Zmievski authored
125
126 return;
27d63c5 Adding some docs for new parameter parsing API. They really should be mo...
Andrei Zmievski authored
127 }
Something went wrong with that request. Please try again.