[Opensync-devel] API change: capabilities API reworked

[Chris F. <cd...@fo...>]

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