git.m6w6.name Git - m6w6/ext-propro/blob - php_propro.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_H
  14 #define PHP_PROPRO_H
  15
  16 #ifndef DOXYGEN
  17
  18 extern zend_module_entry propro_module_entry;
  19 #define phpext_propro_ptr &propro_module_entry
  20
  21 #define PHP_PROPRO_VERSION "1.0.1"
  22
  23 #ifdef PHP_WIN32
  24 #       define PHP_PROPRO_API __declspec(dllexport)
  25 #elif defined(__GNUC__) && __GNUC__ >= 4
  26 #       define PHP_PROPRO_API extern __attribute__ ((visibility("default")))
  27 #else
  28 #       define PHP_PROPRO_API extern
  29 #endif
  30
  31 #ifdef ZTS
  32 #       include <TSRM/TSRM.h>
  33 #endif
  34
  35 #ifdef IS_UNDEF /* TODO: replace with version check */
  36 #define PHPNG
  37 #define zend_object_value zend_object
  38 #endif
  39
  40 #endif
  41
  42 /**
  43  * The internal property proxy.
  44  *
  45  * Container for the object/array holding the proxied property.
  46  */
  47 struct php_property_proxy {
  48         /** The container holding the property */
  49         zval *container;
  50         /** The name of the proxied property */
  51         char *member_str;
  52         /** The length of the name */
  53         size_t member_len;
  54 };
  55 typedef struct php_property_proxy php_property_proxy_t;
  56
  57 /**
  58  * The userland object.
  59  *
  60  * Return an object instance of php\\PropertyProxy to make your C-struct
  61  * member accessible by reference from PHP userland.
  62  *
  63  * Example:
  64  * ~~~~~~~~~~{.c}
  65  * static zval *my_read_prop(zval *object, zval *member, int type, zend_literal *key TSRMLS_DC)
  66  * {
  67  *     my_object_t *obj = zend_object_store_get_object(object TSRMLS_CC);
  68  *     my_prophandler_t *handler;
  69  *     zval *return_value, *copy = my_cast(IS_STRING, member);
  70  *
  71  *     if (SUCCESS == my_get_prophandler(Z_STRVAL_P(copy), Z_STRLEN_P(copy), &handler)) {
  72  *         ALLOC_ZVAL(return_value);
  73  *         Z_SET_REFCOUNT_P(return_value, 0);
  74  *         Z_UNSET_ISREF_P(return_value);
  75  *
  76  *         if (type == BP_VAR_R) {
  77  *             handler->read(obj, return_value TSRMLS_CC);
  78  *         } else {
  79  *             //
  80  *             // This is the interesting part
  81  *             //
  82  *             php_property_proxy_t *proxy;
  83  *             zend_object_value proxy_ov;
  84  *             zend_class_entry *proxy_ce;
  85  *
  86  *             proxy = php_property_proxy_init(object, Z_STRVAL_P(copy), Z_STRLEN_P(copy) TSRMLS_CC);
  87  *             proxy_ce = php_property_proxy_get_class_entry();
  88  *             proxy_ov = php_property_proxy_object_new_ex(proxy_ce, proxy, NULL TSRMLS_CC);
  89  *             RETVAL_OBJVAL(proxy_ov, 0);
  90  *         }
  91  *     } else {
  92  *         zend_object_handlers *oh = zend_get_std_object_handlers();
  93  *         return_value = oh->read_property(object, member, type, key TSRMLS_CC);
  94  *     }
  95  *
  96  *     zval_ptr_dtor(&copy);
  97  *
  98  *     return return_value;
  99  * }
 100  * ~~~~~~~~~~
 101  */
 102 struct php_property_proxy_object {
 103 #ifndef PHPNG
 104         /** The std zend_object */
 105         zend_object zo;
 106 #endif
 107         /** The object value for easy zval creation */
 108         zend_object_value zv;
 109         /** The actual property proxy */
 110         php_property_proxy_t *proxy;
 111         /** A reference to any parent property proxy object */
 112         struct php_property_proxy_object *parent;
 113 };
 114 typedef struct php_property_proxy_object php_property_proxy_object_t;
 115
 116 /**
 117  * Create a property proxy
 118  *
 119  * The property proxy will forward reads and writes to itself to the
 120  * proxied property with name \a member_str of \a container.
 121  *
 122  * @param container the container holding the property
 123  * @param member_str the name of the proxied property
 124  * @param member_len the length of the name
 125  * @return a new property proxy
 126  */
 127 PHP_PROPRO_API php_property_proxy_t *php_property_proxy_init(zval *container,
 128                 const char *member_str, size_t member_len TSRMLS_DC);
 129
 130 /**
 131  * Destroy and free a property proxy.
 132  *
 133  * The destruction of the property proxy object calls this.
 134  *
 135  * @param proxy a pointer to the allocated property proxy
 136  */
 137 PHP_PROPRO_API void php_property_proxy_free(php_property_proxy_t **proxy);
 138
 139 /**
 140  * Get the zend_class_entry of php\\PropertyProxy
 141  * @return the class entry pointer
 142  */
 143 PHP_PROPRO_API zend_class_entry *php_property_proxy_get_class_entry(void);
 144
 145 /**
 146  * Instantiate a new php\\PropertyProxy
 147  * @param ce the property proxy or derived class entry
 148  * @return the zval object value
 149  */
 150 PHP_PROPRO_API zend_object_value php_property_proxy_object_new(
 151                 zend_class_entry *ce TSRMLS_DC);
 152
 153 /**
 154  * Instantiate a new php\\PropertyProxy with \a proxy
 155  * @param ce the property proxy or derived class entry
 156  * @param proxy the internal property proxy
 157  * @param ptr a pointer to store the resulting property proxy object
 158  * @return the zval object value
 159  */
 160 PHP_PROPRO_API zend_object_value php_property_proxy_object_new_ex(
 161                 zend_class_entry *ce, php_property_proxy_t *proxy,
 162                 php_property_proxy_object_t **ptr TSRMLS_DC);
 163
 164 #endif  /* PHP_PROPRO_H */
 165
 166
 167 /*
 168  * Local variables:
 169  * tab-width: 4
 170  * c-basic-offset: 4
 171  * End:
 172  * vim600: noet sw=4 ts=4 fdm=marker
 173  * vim<600: noet sw=4 ts=4
 174  */