what's this ?
=============

This is an abstraction layer that eases the task of writing rpc
extensions (e.g. java, com, corba, soap, srm, .net, xml-rpc, ..).
it maps the quite complex ZendEngine2 oo api to a few simpler to
handle callback functions declared in the 'rpc_object_handlers'
struct.

so what happens behind my back ?
================================

- the abstraction layer takes care of your underlaying data structure
and passes it to you each time you have to handle an operation.
- it does reference counting and tells you when you have to destruct
your underlaying data structure.
- it registers a class and four functions (xxx_load, xxx_call, xxx_get,
xxx_set) for your rpc layer and checks if the parameters are valid (beside
the ones that are optional for your rpc layer).
- it silently creates proxies for references to members of your rpc
objects.
- it optionally does object pooling for objects that support it (has to
be defined in the constructor)
- it optionally requests hash values for method and property names and
caches them. call / get and set requests will then receive the hash value
instead of the original function- / propertyname.

how can i make use of it ?
==========================

take ext/rpc/com/com.c as a starting point. you'll have to set up the following struct:

typedef struct _rpc_object_handlers {
	int (*rpc_hash)(char *name, zend_uint name_len, char **hash, zend_uint *hash_len, int type);
	int hash_type;
	int (*rpc_ctor)(char *class_name, zend_uint class_name_len, void **data, INTERNAL_FUNCTION_PARAMETERS);
	int (*rpc_dtor)(void **data);
	int (*rpc_call)(char *method_name, zend_uint method_name_len, void **data, INTERNAL_FUNCTION_PARAMETERS);
	int (*rpc_get)(char *property_name, zend_uint property_name_len, zval *return_value, void **data);
	int (*rpc_set)(char *property_name, zend_uint property_name_len, zval *value, zval *return_value, void **data);
	int (*rpc_compare)(void **data1, void **data2);
	int (*rpc_get_classname)(char **class_name, zend_uint *class_name_length, void **data);
	int (*rpc_has_property)(char *property_name, zend_uint property_name_length, void **data);
	int (*rpc_unset_property)(char *property_name, zend_uint property_name_length, void **data);
	int (*rpc_get_properties)(HashTable **properties, void **data);
} rpc_object_handlers;


rpc_hash:
the hashing function for method and property names. returns a hash value
for the string passed in 'name'. 'type' is either METHOD or PROPERTY.
if you set 'hash_type' to HASH_AS_INT you can set '*hash' to NULL and pass
the hash value as 'hash_len'.
rpc_hash can be set to NULL if hashing of method and property names is not
appreciated.

hash_type:
either HASH_AS_INT, HASH_AS_STRING or DONT_HASH

rpc_ctor:
the constructor

rpc_dtor:
the destructor

rpc_call:
the call handler

rpc_get:
the get handler

rpc_set:
the set handler

rpc_compare:
the compare handler.
rpc_compare can be set to NULL then objects will be treated the same if they
belong to the same rpc layer.

rpc_get_classname:
returns the classname.
rpc_get_classname can be set to NULL then the name of the rpc layer will be
used as classname.

rpc_has_property:
check if a property exists.
rpc_has_property can be set to NULL then true will be returned for every request.

rpc_unset_property:
unset a property.
rpc_unset_property can be set to NULL, a 'not supported' warning will then be
issued.

rpc_get_properties:
returns a HashTable with all the properties.
rpc_get_properties can be set to NULL, then a list of the explicit declared
properties will be returned.