[virt-tools-list] Libosinfo + GObject

[Arjun Roy]

Proposed GObject based libosinfo API.

See also:

https://www.redhat.com/archives/virt-tools-list/2010-February/msg00000.html
https://www.redhat.com/archives/virt-tools-list/2010-February/msg00013.html

Quick summary:
1. A few main object types, one abstract, the rest usable by interface users
2. Each object has a collection of public methods that are listed below and
   are the only interface with the library.
3. Each method listed below is grouped with the object for which the functionality
   makes the most sense.

Current Status:
1. All objects except lists and filters are specified fully, though a couple of
   methods need to be filled in.
2. Remaining tasks include implementing lists and filters, and filling in some
   methods on the other objects.

Request:

1. If possible, go over the API real quick if you have the time, and see if
anything else needs to be changed.

2. Observe the email at
https://www.redhat.com/archives/virt-tools-list/2009-October/msg00162.html
that specifies the data format, and verify that it matches the desired
functionality. (I'm pretty certain that it does).


-Arjun

________________________________________________________________________________

Main objects

OsinfoDb : Main interface to libosinfo
OsinfoEntity : Base class for all objects tracked by libosinfo
OsinfoDevice : descends from OsinfoEntity
OsinfoHypervisor : descends from OsinfoEntity
OsinfoOs : descends from OsinfoEntity
OsinfoFilter : used for list filtering
OsinfoOsList, OsinfoDeviceList, OsinfoHypervisorList : Lists of objects

_________________________________________________
OsinfoEntity: Implemented as a GObject
Properties:
ID
Backpointer to OsinfoDb object

gchar *osinfoGetId(OsinfoEntity *self, GError **err);
GPtrArray *osinfoGetParams(OsinfoEntity *self, GError **err);
gchar *osinfoGetParamValue(OsinfoEntity *self, gchar *key, GError **err);
GPtrArray *osinfoGetParamAllValues(OsinfoEntity *self, gchar *key, GError **err);

_________________________________________________

OsinfoDb: Main interface to libosinfo

// Get handle to single object by ID
OsinfoHypervisor *osinfoGetHypervisorById(OsinfoDb *self, gchar *hvId, GError **err);
OsinfoDevice *osinfoGetDeviceById(OsinfoDb *self, gchar *devId, GError **err);
OsinfoOs *osinfoGetOsById(OsinfoDb *self, gchar *osId, GError **err);

// Get list of devices, can supply initial filter
OsinfoOsList *osinfoGetOsList(OsinfoDb *self, OsinfoFilter *filter, GError **err);
OsinfoHypervisorList *osinfoGetHypervisorList(OsinfoDb *self, OsinfoFilter *filter, GError **err);
OsinfoDeviceList *osinfoGetDeviceList(OsinfoDb *self, OsinfoFilter *filter, GError **err);

// Get me all unique values for property "vendor" among operating systems
GPtrArray *osinfoUniqueValuesForPropertyInOs(OsinfoDb *self, gchar *propName, GError **err);

// Get me all unique values for property "vendor" among hypervisors
GPtrArray *osinfoUniqueValuesForPropertyInHv(OsinfoDb *self, gchar *propName, GError **err);

// Get me all unique values for property "vendor" among devices
GPtrArray *osinfoUniqueValuesForPropertyInDev(OsinfoDb *self, gchar *propName, GError **err);

// Get me all OSes that 'upgrade' another OS (or whatever relationship is specified)
OsinfoOsList *osinfoUniqueValuesForOsRelationship(OsinfoDb *self, osinfoRelation relshp, GError **err);

_________________________________________________

Hypervisor: All methods in OsinfoEntity, plus

// Return a list of all device types handled by hypervisor on some OS
GPtrArray *osinfoGetHypervisorDeviceTypes(OsinfoHypervisor *self, GError **err);

// Get all devices of type. Note these are not OS specific, all we know is that the hypervisor
// supports the device on some OS
OsinfoDeviceList *osinfoGetHypervisorDevicesByType(OsinfoHypervisor *self, gchar *devType, OsinfoFilter *filter, GError **err);

_________________________________________________

Devices: All methods in OsinfoEntity, plus

// Get device driver for OS and HV combination. If HV is null, assume we want
// driver used by OS when running on bare metal. Note we specify devType in case
// we have a franken-device which does more than one task (eg. a video card that
// can also handle...networking, I guess?)
gchar *osinfoGetDeviceDriver(OsinfoDevice *self, gchar *devType, OsinfoOs *os, OsinfoHypervisor *hv, GError **err);

_________________________________________________

Operating Systems: All methods in OsinfoEntity, plus

// Get me the OS that 'clones' this one, for example
OsinfoOs *osinfoGetRelatedOs(OsinfoOs *self, osinfoRelation relshp, GError **err);

// Get me the best audio device for this OS on this hypervisor that isn't made by Realtek
OsinfoDevice *osinfoGetPreferredDeviceForOs(OsinfoOs *self, OsinfoHypervisor *hv, gchar *devType, OsinfoFilter *filter, GError **err);

// Get me all audio devices for this OS on this hypervisor that isn't made by Realtek, sorted by how 'preferable' they are
OsinfoDeviceList *osinfoGetDevicesForOs(OsinfoOs *self, OsinfoHypervisor *hv, gchar *devType, OsinfoFilter *filter, GError **err);

_________________________________________________

All lists will have the following methods:

ie. Analogous methods for OsList, HypervisorList

void osinfoFreeDeviceList(OsinfoDeviceList *self);
gint osinfoDeviceListLength(OsinfoDeviceList *self);
OsinfoDevice *osinfoGetDeviceAtIndex(OsinfoDeviceList *self, gint idx);
OsinfoDeviceList *osinfoDeviceListIntersect(OsinfoDeviceList *self, OsinfoDeviceList *otherList, GError **err);
OsinfoDeviceList *osinfoDeviceListUnion(OsinfoDeviceList *self, OsinfoDeviceList *otherList, GError **err);
OsinfoDeviceList *osinfoDeviceListFilter(OsinfoDeviceList *self, OsinfoFilter *filter, GError **err);

_________________________________________________

Filter:

OsinfoFilter *osinfoGetFilter(OsinfoDb *db, GError **err);
OsinfoFilter *osinfoFreeFilter(OsinfoFilter *self);

gboolean osinfoAddFilterContstraint(OsinfoFilter *self, gchar *propName, gchar *propVal);

// Only applicable to OSes, ignored by other types of objects
gboolean osinfoAddRelationConstraint(OsinfoFilter *self, osinfoRelationship relshp, OsinfoOs *os);

gboolean osinfoClearFilterConstraint(OsinfoFilter *self, gchar *propName);
gboolean osinfoClearRelationshipConstraint(OsinfoFilter *self, osinfoRelationship relshp);
gboolean osinfoClearAllFilterConstraints(OsinfoFilter *self);

GPtrArray *osinfoGetFilterConstraintKeys(OsinfoFilter *self, GError **err);
gchar *osinfoGetFilterConstraintValue(OsinfoFilter *self, GError **err);
OsinfoOs *osinfoGetRelationshipConstraintValue(OsinfoFilter *self, osinfoRelationship relshp, GError **err);