|
From: Chris F. <cd...@fo...> - 2011-07-18 21:40:55
|
Hi, I've made a number of changes and fixed some memory leaks in the capabilities API. You can see the last change here: http://repo.or.cz/w/opensync/opensync-cdf.git/commitdiff/a826a3ce69bd1e84beca7344c18e2a0047306960 I've updated the evolution2, vformat, and xmlformat plugins as well, with the small API change required, since I'm tracking them. For plugin authors, the change is pretty simple: Change: osync_capability_new() To: osync_capabilities_add_new_capability() and Change: osync_capabilities_objtype_new() To: osync_capabilieis_add_new_objtype() The reason for this change was because the capabilities API behaved differently than the rest of opensync. The _new() calls would add the new object to an internal list, and return an unref'd pointer. This is inconsistent with what the user will expect from every other _new() call in the library. Also, due to this oddity, some of the internal implementations were very difficult to get right. While building the capabiities hierarchy, there could be errors after an object was created, but before it could be returned successfully. I have changed the internal API so that all calls to _new(), _ref(), and _unref(), in the capabilities API behave as expected. I have also hidden a number of calls, in favour of promoting just the top level OSyncCapabilities objects. This is all that the user should need to worry about, when it comes to memory management, and the normal _new(), _ref(), and _unref() calls are available for it only. API Changes: ============ Removed (moved to internal) osync_capabilities_objtype_new osync_capabilities_objtype_ref osync_capabilities_objtype_unref osync_capability_new osync_capability_ref osync_capability_unref Added osync_capabilities_add_new_objtype osync_capabilities_add_new_capability Background: =========== For those who don't know what the "capabilities hierarchy" is, here's the docs that I added to opensync_capabilities_private.h. /** * @brief Represent a Capabilities object * * This is the top level Capabilities object, which contains a list of * lists of capability objects for each objtype. * * For example, if your device has a set of capabilities, you could call the * set "foodevice-caps". This would be the Capabilities format name. * This format name could contain different capability lists for each * objtype supported, for example "contact" or "event" or both. * * The names of the capabilities do not have to match anything else, but * if they do not match something opensync knows about, it will need a * caps-converter (capabilities converter) to translate your list of * capability objects for, say, "contact" into something it knows, say, * "xmlformat-contact". * * foodevice-caps * contact * name * address1 * phonenumber * event * date * location * * I don't know if multiple objtypes are ever useful, but they are possible, * given the 3 structures: OSyncCapabilities, OSyncCapabilitiesObjType, * and finally OSyncCapability. * * Note that OSyncCapability is a hierarchical list, having its own children. * It also has a list of OSyncCapabilityParameter objects. * */ The Capabilities API could use some feedback and thought. Currently there is no way to properly manage the OSyncCapabilityParameters programmatically. Enjoy, - Chris |