1 /* 2 +----------------------------------------------------------------------+ 3 | Zend Engine | 4 +----------------------------------------------------------------------+ 5 | Copyright (c) Zend Technologies Ltd. (http://www.zend.com) | 6 +----------------------------------------------------------------------+ 7 | This source file is subject to version 2.00 of the Zend license, | 8 | that is bundled with this package in the file LICENSE, and is | 9 | available through the world-wide-web at the following url: | 10 | http://www.zend.com/license/2_00.txt. | 11 | If you did not receive a copy of the Zend license and are unable to | 12 | obtain it through the world-wide-web, please send a note to | 13 | license@zend.com so we can mail you a copy immediately. | 14 +----------------------------------------------------------------------+ 15 | Authors: Andi Gutmans <andi@php.net> | 16 | Zeev Suraski <zeev@php.net> | 17 +----------------------------------------------------------------------+ 18 */ 19 20 #ifndef ZEND_OBJECT_HANDLERS_H 21 #define ZEND_OBJECT_HANDLERS_H 22 23 #include <stdint.h> 24 25 struct _zend_property_info; 26 27 #define ZEND_WRONG_PROPERTY_INFO \ 28 ((struct _zend_property_info*)((intptr_t)-1)) 29 30 #define ZEND_DYNAMIC_PROPERTY_OFFSET ((uintptr_t)(intptr_t)(-1)) 31 32 #define IS_VALID_PROPERTY_OFFSET(offset) ((intptr_t)(offset) > 0) 33 #define IS_WRONG_PROPERTY_OFFSET(offset) ((intptr_t)(offset) == 0) 34 #define IS_DYNAMIC_PROPERTY_OFFSET(offset) ((intptr_t)(offset) < 0) 35 36 #define IS_UNKNOWN_DYNAMIC_PROPERTY_OFFSET(offset) (offset == ZEND_DYNAMIC_PROPERTY_OFFSET) 37 #define ZEND_DECODE_DYN_PROP_OFFSET(offset) ((uintptr_t)(-(intptr_t)(offset) - 2)) 38 #define ZEND_ENCODE_DYN_PROP_OFFSET(offset) ((uintptr_t)(-((intptr_t)(offset) + 2))) 39 40 41 /* Used to fetch property from the object, read-only */ 42 typedef zval *(*zend_object_read_property_t)(zend_object *object, zend_string *member, int type, void **cache_slot, zval *rv); 43 44 /* Used to fetch dimension from the object, read-only */ 45 typedef zval *(*zend_object_read_dimension_t)(zend_object *object, zval *offset, int type, zval *rv); 46 47 48 /* Used to set property of the object 49 You must return the final value of the assigned property. 50 */ 51 typedef zval *(*zend_object_write_property_t)(zend_object *object, zend_string *member, zval *value, void **cache_slot); 52 53 /* Used to set dimension of the object */ 54 typedef void (*zend_object_write_dimension_t)(zend_object *object, zval *offset, zval *value); 55 56 57 /* Used to create pointer to the property of the object, for future direct r/w access. 58 * May return one of: 59 * * A zval pointer, without incrementing the reference count. 60 * * &EG(error_zval), if an exception has been thrown. 61 * * NULL, if acquiring a direct pointer is not possible. 62 * In this case, the VM will fall back to using read_property and write_property. 63 */ 64 typedef zval *(*zend_object_get_property_ptr_ptr_t)(zend_object *object, zend_string *member, int type, void **cache_slot); 65 66 /* Used to check if a property of the object exists */ 67 /* param has_set_exists: 68 * 0 (has) whether property exists and is not NULL 69 * 1 (set) whether property exists and is true 70 * 2 (exists) whether property exists 71 */ 72 typedef int (*zend_object_has_property_t)(zend_object *object, zend_string *member, int has_set_exists, void **cache_slot); 73 74 /* Used to check if a dimension of the object exists */ 75 typedef int (*zend_object_has_dimension_t)(zend_object *object, zval *member, int check_empty); 76 77 /* Used to remove a property of the object */ 78 typedef void (*zend_object_unset_property_t)(zend_object *object, zend_string *member, void **cache_slot); 79 80 /* Used to remove a dimension of the object */ 81 typedef void (*zend_object_unset_dimension_t)(zend_object *object, zval *offset); 82 83 /* Used to get hash of the properties of the object, as hash of zval's */ 84 typedef HashTable *(*zend_object_get_properties_t)(zend_object *object); 85 86 typedef HashTable *(*zend_object_get_debug_info_t)(zend_object *object, int *is_temp); 87 88 typedef enum _zend_prop_purpose { 89 /* Used for debugging. Supersedes get_debug_info handler. */ 90 ZEND_PROP_PURPOSE_DEBUG, 91 /* Used for (array) casts. */ 92 ZEND_PROP_PURPOSE_ARRAY_CAST, 93 /* Used for serialization using the "O" scheme. 94 * Unserialization will use __wakeup(). */ 95 ZEND_PROP_PURPOSE_SERIALIZE, 96 /* Used for var_export(). 97 * The data will be passed to __set_state() when evaluated. */ 98 ZEND_PROP_PURPOSE_VAR_EXPORT, 99 /* Used for json_encode(). */ 100 ZEND_PROP_PURPOSE_JSON, 101 /* Dummy member to ensure that "default" is specified. */ 102 _ZEND_PROP_PURPOSE_NON_EXHAUSTIVE_ENUM 103 } zend_prop_purpose; 104 105 /* The return value must be released using zend_release_properties(). */ 106 typedef zend_array *(*zend_object_get_properties_for_t)(zend_object *object, zend_prop_purpose purpose); 107 108 /* Used to call methods */ 109 /* args on stack! */ 110 /* Andi - EX(fbc) (function being called) needs to be initialized already in the INIT fcall opcode so that the parameters can be parsed the right way. We need to add another callback for this. 111 */ 112 typedef zend_function *(*zend_object_get_method_t)(zend_object **object, zend_string *method, const zval *key); 113 typedef zend_function *(*zend_object_get_constructor_t)(zend_object *object); 114 115 /* free_obj should release any resources the object holds, without freeing the 116 * object structure itself. The object does not need to be in a valid state after 117 * free_obj finishes running. 118 * 119 * free_obj will always be invoked, even if the object leaks or a fatal error 120 * occurs. However, during shutdown it may be called once the executor is no 121 * longer active, in which case execution of user code may be skipped. 122 */ 123 typedef void (*zend_object_free_obj_t)(zend_object *object); 124 125 /* dtor_obj is called before free_obj. The object must remain in a valid state 126 * after dtor_obj finishes running. Unlike free_obj, it is run prior to 127 * deactivation of the executor during shutdown, which allows user code to run. 128 * 129 * This handler is not guaranteed to be called (e.g. on fatal error), and as 130 * such should not be used to release resources or deallocate memory. Furthermore, 131 * releasing resources in this handler can break detection of memory leaks, as 132 * cycles may be broken early. 133 * 134 * dtor_obj should be used *only* to call user destruction hooks, such as __destruct. 135 */ 136 typedef void (*zend_object_dtor_obj_t)(zend_object *object); 137 138 typedef zend_object* (*zend_object_clone_obj_t)(zend_object *object); 139 140 /* Get class name for display in var_dump and other debugging functions. 141 * Must be defined and must return a non-NULL value. */ 142 typedef zend_string *(*zend_object_get_class_name_t)(const zend_object *object); 143 144 typedef int (*zend_object_compare_t)(zval *object1, zval *object2); 145 146 /* Cast an object to some other type. 147 * readobj and retval must point to distinct zvals. 148 */ 149 typedef zend_result (*zend_object_cast_t)(zend_object *readobj, zval *retval, int type); 150 151 /* updates *count to hold the number of elements present and returns SUCCESS. 152 * Returns FAILURE if the object does not have any sense of overloaded dimensions */ 153 typedef zend_result (*zend_object_count_elements_t)(zend_object *object, zend_long *count); 154 155 typedef zend_result (*zend_object_get_closure_t)(zend_object *obj, zend_class_entry **ce_ptr, zend_function **fptr_ptr, zend_object **obj_ptr, bool check_only); 156 157 typedef HashTable *(*zend_object_get_gc_t)(zend_object *object, zval **table, int *n); 158 159 typedef zend_result (*zend_object_do_operation_t)(uint8_t opcode, zval *result, zval *op1, zval *op2); 160 161 struct _zend_object_handlers { 162 /* offset of real object header (usually zero) */ 163 int offset; 164 /* object handlers */ 165 zend_object_free_obj_t free_obj; /* required */ 166 zend_object_dtor_obj_t dtor_obj; /* required */ 167 zend_object_clone_obj_t clone_obj; /* optional */ 168 zend_object_read_property_t read_property; /* required */ 169 zend_object_write_property_t write_property; /* required */ 170 zend_object_read_dimension_t read_dimension; /* required */ 171 zend_object_write_dimension_t write_dimension; /* required */ 172 zend_object_get_property_ptr_ptr_t get_property_ptr_ptr; /* required */ 173 zend_object_has_property_t has_property; /* required */ 174 zend_object_unset_property_t unset_property; /* required */ 175 zend_object_has_dimension_t has_dimension; /* required */ 176 zend_object_unset_dimension_t unset_dimension; /* required */ 177 zend_object_get_properties_t get_properties; /* required */ 178 zend_object_get_method_t get_method; /* required */ 179 zend_object_get_constructor_t get_constructor; /* required */ 180 zend_object_get_class_name_t get_class_name; /* required */ 181 zend_object_cast_t cast_object; /* required */ 182 zend_object_count_elements_t count_elements; /* optional */ 183 zend_object_get_debug_info_t get_debug_info; /* optional */ 184 zend_object_get_closure_t get_closure; /* optional */ 185 zend_object_get_gc_t get_gc; /* required */ 186 zend_object_do_operation_t do_operation; /* optional */ 187 zend_object_compare_t compare; /* required */ 188 zend_object_get_properties_for_t get_properties_for; /* optional */ 189 }; 190 191 BEGIN_EXTERN_C() 192 extern const ZEND_API zend_object_handlers std_object_handlers; 193 194 #define zend_get_std_object_handlers() \ 195 (&std_object_handlers) 196 197 #define zend_get_function_root_class(fbc) \ 198 ((fbc)->common.prototype ? (fbc)->common.prototype->common.scope : (fbc)->common.scope) 199 200 #define ZEND_PROPERTY_ISSET 0x0 /* Property exists and is not NULL */ 201 #define ZEND_PROPERTY_NOT_EMPTY ZEND_ISEMPTY /* Property is not empty */ 202 #define ZEND_PROPERTY_EXISTS 0x2 /* Property exists */ 203 204 ZEND_API void zend_class_init_statics(zend_class_entry *ce); 205 ZEND_API zend_function *zend_std_get_static_method(zend_class_entry *ce, zend_string *function_name_strval, const zval *key); 206 ZEND_API zval *zend_std_get_static_property_with_info(zend_class_entry *ce, zend_string *property_name, int type, struct _zend_property_info **prop_info); 207 ZEND_API zval *zend_std_get_static_property(zend_class_entry *ce, zend_string *property_name, int type); 208 ZEND_API ZEND_COLD bool zend_std_unset_static_property(zend_class_entry *ce, zend_string *property_name); 209 ZEND_API zend_function *zend_std_get_constructor(zend_object *object); 210 ZEND_API struct _zend_property_info *zend_get_property_info(const zend_class_entry *ce, zend_string *member, int silent); 211 ZEND_API HashTable *zend_std_get_properties(zend_object *object); 212 ZEND_API HashTable *zend_std_get_gc(zend_object *object, zval **table, int *n); 213 ZEND_API HashTable *zend_std_get_debug_info(zend_object *object, int *is_temp); 214 ZEND_API zend_result zend_std_cast_object_tostring(zend_object *object, zval *writeobj, int type); 215 ZEND_API zval *zend_std_get_property_ptr_ptr(zend_object *object, zend_string *member, int type, void **cache_slot); 216 ZEND_API zval *zend_std_read_property(zend_object *object, zend_string *member, int type, void **cache_slot, zval *rv); 217 ZEND_API zval *zend_std_write_property(zend_object *object, zend_string *member, zval *value, void **cache_slot); 218 ZEND_API int zend_std_has_property(zend_object *object, zend_string *member, int has_set_exists, void **cache_slot); 219 ZEND_API void zend_std_unset_property(zend_object *object, zend_string *member, void **cache_slot); 220 ZEND_API zval *zend_std_read_dimension(zend_object *object, zval *offset, int type, zval *rv); 221 ZEND_API void zend_std_write_dimension(zend_object *object, zval *offset, zval *value); 222 ZEND_API int zend_std_has_dimension(zend_object *object, zval *offset, int check_empty); 223 ZEND_API void zend_std_unset_dimension(zend_object *object, zval *offset); 224 ZEND_API zend_function *zend_std_get_method(zend_object **obj_ptr, zend_string *method_name, const zval *key); 225 ZEND_API zend_string *zend_std_get_class_name(const zend_object *zobj); 226 ZEND_API int zend_std_compare_objects(zval *o1, zval *o2); 227 ZEND_API zend_result zend_std_get_closure(zend_object *obj, zend_class_entry **ce_ptr, zend_function **fptr_ptr, zend_object **obj_ptr, bool check_only); 228 ZEND_API void rebuild_object_properties(zend_object *zobj); 229 230 ZEND_API HashTable *zend_std_build_object_properties_array(zend_object *zobj); 231 232 /* Handler for objects that cannot be meaningfully compared. 233 * Only objects with the same identity will be considered equal. */ 234 ZEND_API int zend_objects_not_comparable(zval *o1, zval *o2); 235 236 ZEND_API bool zend_check_protected(const zend_class_entry *ce, const zend_class_entry *scope); 237 238 ZEND_API zend_result zend_check_property_access(const zend_object *zobj, zend_string *prop_info_name, bool is_dynamic); 239 240 ZEND_API zend_function *zend_get_call_trampoline_func(const zend_class_entry *ce, zend_string *method_name, bool is_static); 241 242 ZEND_API uint32_t *zend_get_property_guard(zend_object *zobj, zend_string *member); 243 244 ZEND_API uint32_t *zend_get_property_guard(zend_object *zobj, zend_string *member); 245 246 ZEND_API uint32_t *zend_get_recursion_guard(zend_object *zobj); 247 248 /* Default behavior for get_properties_for. For use as a fallback in custom 249 * get_properties_for implementations. */ 250 ZEND_API HashTable *zend_std_get_properties_for(zend_object *obj, zend_prop_purpose purpose); 251 252 /* Will call get_properties_for handler or use default behavior. For use by 253 * consumers of the get_properties_for API. */ 254 ZEND_API HashTable *zend_get_properties_for(zval *obj, zend_prop_purpose purpose); 255 256 #define zend_release_properties(ht) do { \ 257 if ((ht) && !(GC_FLAGS(ht) & GC_IMMUTABLE) && !GC_DELREF(ht)) { \ 258 zend_array_destroy(ht); \ 259 } \ 260 } while (0) 261 262 #define zend_free_trampoline(func) do { \ 263 if ((func) == &EG(trampoline)) { \ 264 EG(trampoline).common.function_name = NULL; \ 265 } else { \ 266 efree(func); \ 267 } \ 268 } while (0) 269 270 /* Fallback to default comparison implementation if the arguments aren't both objects 271 * and have the same compare() handler. You'll likely want to use this unless you 272 * explicitly wish to support comparisons between objects and non-objects. */ 273 #define ZEND_COMPARE_OBJECTS_FALLBACK(op1, op2) \ 274 if (Z_TYPE_P(op1) != IS_OBJECT || \ 275 Z_TYPE_P(op2) != IS_OBJECT || \ 276 Z_OBJ_HT_P(op1)->compare != Z_OBJ_HT_P(op2)->compare) { \ 277 return zend_std_compare_objects(op1, op2); \ 278 } 279 280 END_EXTERN_C() 281 282 #endif 283