blah

1 files changed, 97 insertions, 0 deletions

diff --git a/ext/rpc/RPC_HOWTO b/ext/rpc/RPC_HOWTO
new file mode 100644
index 0000000000..9b6e92b7c6
--- /dev/null
+++ b/ext/rpc/RPC_HOWTO
@@ -0,0 +1,97 @@
+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.