git.m6w6.name Git - m6w6/ext-propro/blob - php_propro_api.h

   1 /*
   2     +--------------------------------------------------------------------+
   3     | PECL :: propro                                                     |
   4     +--------------------------------------------------------------------+
   5     | Redistribution and use in source and binary forms, with or without |
   6     | modification, are permitted provided that the conditions mentioned |
   7     | in the accompanying LICENSE file are met.                          |
   8     +--------------------------------------------------------------------+
   9     | Copyright (c) 2013 Michael Wallner <mike@php.net>                  |
  10     +--------------------------------------------------------------------+
  11 */
  12
  13 #ifndef PHP_PROPRO_API_H
  14 #define PHP_PROPRO_API_H
  15
  16 #include "php_propro.h"
  17
  18 /**
  19  * The internal property proxy.
  20  *
  21  * Container for the object/array holding the proxied property.
  22  */
  23 struct php_property_proxy {
  24         /** The container holding the property */
  25         zval *container;
  26         /** The name of the proxied property */
  27         char *member_str;
  28         /** The length of the name */
  29         size_t member_len;
  30 };
  31 typedef struct php_property_proxy php_property_proxy_t;
  32
  33 /**
  34  * The userland object.
  35  *
  36  * Return an object instance of php\\PropertyProxy to make your C-struct
  37  * member accessible by reference from PHP userland.
  38  *
  39  * Example:
  40  * ~~~~~~~~~~{.c}
  41  * static zval *my_read_prop(zval *object, zval *member, int type, zend_literal *key TSRMLS_DC)
  42  * {
  43  *     my_object_t *obj = zend_object_store_get_object(object TSRMLS_CC);
  44  *     my_prophandler_t *handler;
  45  *     zval *return_value, *copy = my_cast(IS_STRING, member);
  46  *
  47  *     if (SUCCESS == my_get_prophandler(Z_STRVAL_P(copy), Z_STRLEN_P(copy), &handler)) {
  48  *         ALLOC_ZVAL(return_value);
  49  *         Z_SET_REFCOUNT_P(return_value, 0);
  50  *         Z_UNSET_ISREF_P(return_value);
  51  *
  52  *         if (type == BP_VAR_R) {
  53  *             handler->read(obj, return_value TSRMLS_CC);
  54  *         } else {
  55  *             //
  56  *             // This is the interesting part
  57  *             //
  58  *             php_property_proxy_t *proxy;
  59  *             zend_object_value proxy_ov;
  60  *             zend_class_entry *proxy_ce;
  61  *
  62  *             proxy = php_property_proxy_init(object, Z_STRVAL_P(copy), Z_STRLEN_P(copy) TSRMLS_CC);
  63  *             proxy_ce = php_property_proxy_get_class_entry();
  64  *             proxy_ov = php_property_proxy_object_new_ex(proxy_ce, proxy, NULL TSRMLS_CC);
  65  *             RETVAL_OBJVAL(proxy_ov, 0);
  66  *         }
  67  *     } else {
  68  *         zend_object_handlers *oh = zend_get_std_object_handlers();
  69  *         return_value = oh->read_property(object, member, type, key TSRMLS_CC);
  70  *     }
  71  *
  72  *     zval_ptr_dtor(&copy);
  73  *
  74  *     return return_value;
  75  * }
  76  * ~~~~~~~~~~
  77  */
  78 struct php_property_proxy_object {
  79         /** The std zend_object */
  80         zend_object zo;
  81         /** The object value for easy zval creation */
  82         zend_object_value zv;
  83         /** The actual property proxy */
  84         php_property_proxy_t *proxy;
  85         /** A reference to any parent property proxy object */
  86         struct php_property_proxy_object *parent;
  87 };
  88 typedef struct php_property_proxy_object php_property_proxy_object_t;
  89
  90 /**
  91  * Create a property proxy
  92  *
  93  * The property proxy will forward reads and writes to itself to the
  94  * proxied property with name \a member_str of \a container.
  95  *
  96  * @param container the container holding the property
  97  * @param member_str the name of the proxied property
  98  * @param member_len the length of the name
  99  * @return a new property proxy
 100  */
 101 PHP_PROPRO_API php_property_proxy_t *php_property_proxy_init(zval *container,
 102                 const char *member_str, size_t member_len TSRMLS_DC);
 103
 104 /**
 105  * Destroy and free a property proxy.
 106  *
 107  * The destruction of the property proxy object calls this.
 108  *
 109  * @param proxy a pointer to the allocated property proxy
 110  */
 111 PHP_PROPRO_API void php_property_proxy_free(php_property_proxy_t **proxy);
 112
 113 /**
 114  * Get the zend_class_entry of php\\PropertyProxy
 115  * @return the class entry pointer
 116  */
 117 PHP_PROPRO_API zend_class_entry *php_property_proxy_get_class_entry(void);
 118
 119 /**
 120  * Instantiate a new php\\PropertyProxy
 121  * @param ce the property proxy or derived class entry
 122  * @return the zval object value
 123  */
 124 PHP_PROPRO_API zend_object_value php_property_proxy_object_new(
 125                 zend_class_entry *ce TSRMLS_DC);
 126
 127 /**
 128  * Instantiate a new php\\PropertyProxy with \a proxy
 129  * @param ce the property proxy or derived class entry
 130  * @param proxy the internal property proxy
 131  * @param ptr a pointer to store the resulting property proxy object
 132  * @return the zval object value
 133  */
 134 PHP_PROPRO_API zend_object_value php_property_proxy_object_new_ex(
 135                 zend_class_entry *ce, php_property_proxy_t *proxy,
 136                 php_property_proxy_object_t **ptr TSRMLS_DC);
 137
 138 #endif  /* PHP_PROPRO_API_H */
 139
 140
 141 /*
 142  * Local variables:
 143  * tab-width: 4
 144  * c-basic-offset: 4
 145  * End:
 146  * vim600: noet sw=4 ts=4 fdm=marker
 147  * vim<600: noet sw=4 ts=4
 148  */