[Libosinfo] osinfo_entity param vs gobject property

[Daniel P. Berrangé]

On Fri, Mar 08, 2019 at 01:43:45PM -0500, Cole Robinson wrote:
> I'm a bit confused about the suggested way to extend bits of the
> libosinfo API. Here's my current understanding:
> 
> We have osinfo_entity*param* functions. This is used internally to store
> basically all XML string field data. To get a string field the API user
> can do:
> 
> osinfo_entity_get_param_value(OSINFO_ENTITY(foo), KEY)
> 
> KEY will be a public C macro pointing to a string. A few examples:
> 
> #define OSINFO_PRODUCT_PROP_EOL_DATE     "eol-date"
> #define OSINFO_TREE_PROP_TREEINFO_FAMILY  "treeinfo-family"
> #define OSINFO_OS_PROP_FAMILY              "family"
> 
> These macros are also used for passing to filter add_constraint
> functions. This param data is what the filter APIs will actually filter on.
> 
> We also have gobject properties. This is all the internal PROP_FOO
> macros, GParamSpec usage. All properties seem to just map to an entity
> param value internally, so it's just an alternate access method. Many
> entity params are not exposed as properties, like eol-date and family above.
> 
> We also have accessor functions. These are public API that return the
> entity param values, possibly with some tweaks. eol-date above has
> osinfo_product_get_eol_date_string which converts the string to a glib
> date, treeinfo-family has osinfo_tree_get_treeinfo_family, but 'family'
> doesn't have one.
> 
> 
> So, when adding a new osinfo entity param, my questions are:
> 
> - What's the criteria for adding a gobject property to match?
> - What's the criteria for adding an accessor function?
> - What's the benefit of using osinfo_entity params instead of the
> gobject property system which seems much more flexible and well
> established? (besides the fact that I assume we are stuck with this for
> back compat reasons)

The key difference between an entity parameters vs a gobject property
is that entity parameters are always arrays of strings. By convention
for some of the entity parametrs we'll only honour a single value, and
in such cases might expose them as GObject parameters.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|