libvirt.h: avoid regression, and document preferred name

Commit 824dcaff was a regression (thankfully unreleased) for any
client code that used 'struct _virSchedParameter' directly rather
than the preferred virSchedParameter typedef.  Adding a #define
avoids even that API change, while rearranging the file makes it
clear what the old vs. new API is.

* include/libvirt/libvirt.h.in: Rearrange older names to the
bottom and improve documentation on preferred names.
(virDomainGetSchedulerParameters, virDomainSetSchedulerParameters)
(virDomainSetSchedulerParametersFlags)
(virDomainSetBlkioParameters, virDomainGetBlkioParameters)
(virDomainSetMemoryParameters, virDomainGetMemoryParameters):
Use newer type names.
* python/libvirt-override.c: Adjust code generation to cope.
Suggested by Daniel P. Berrange.

include/libvirt/libvirt.h.in

@@ -308,6 +308,10 @@ typedef enum {
  * virTypedParameter:
  *
  * A named parameter, including a type and value.
+ *
+ * The types virSchedParameter, virBlkioParameter, and
+ * virMemoryParameter are aliases of this type, for use when
+ * targetting libvirt earlier than 0.9.2.
  */
 typedef struct _virTypedParameter virTypedParameter;
 
@@ -331,21 +335,8 @@ struct _virTypedParameter {
  */
 typedef virTypedParameter *virTypedParameterPtr;
 
-/* Management of scheduler parameters */
 
-/**
- * virDomainSchedParameterType:
- *
- * A scheduler parameter field type
- */
-typedef enum {
-    VIR_DOMAIN_SCHED_FIELD_INT     = VIR_TYPED_PARAM_INT,
-    VIR_DOMAIN_SCHED_FIELD_UINT    = VIR_TYPED_PARAM_UINT,
-    VIR_DOMAIN_SCHED_FIELD_LLONG   = VIR_TYPED_PARAM_LLONG,
-    VIR_DOMAIN_SCHED_FIELD_ULLONG  = VIR_TYPED_PARAM_ULLONG,
-    VIR_DOMAIN_SCHED_FIELD_DOUBLE  = VIR_TYPED_PARAM_DOUBLE,
-    VIR_DOMAIN_SCHED_FIELD_BOOLEAN = VIR_TYPED_PARAM_BOOLEAN,
-} virSchedParameterType;
+/* Management of scheduler parameters */
 
 typedef enum {
     VIR_DOMAIN_SCHEDPARAM_CURRENT = 0,        /* affect current domain state */
@@ -353,49 +344,25 @@ typedef enum {
     VIR_DOMAIN_SCHEDPARAM_CONFIG  = (1 << 1), /* Affect next boot */
 } virDomainSchedParameterFlags;
 
-/**
- * VIR_DOMAIN_SCHED_FIELD_LENGTH:
- *
- * Macro providing the field length of virSchedParameter
- */
-
-#define VIR_DOMAIN_SCHED_FIELD_LENGTH VIR_TYPED_PARAM_FIELD_LENGTH
-
-/**
- * virDomainSchedParameter:
- *
- * a virDomainSchedParameter is the set of scheduler parameters
- */
-
-typedef struct _virTypedParameter virSchedParameter;
-
-/**
- * virSchedParameterPtr:
- *
- * a virSchedParameterPtr is a pointer to a virSchedParameter structure.
- */
-
-typedef virSchedParameter *virSchedParameterPtr;
-
 /*
  * Fetch scheduler parameters, caller allocates 'params' field of size 'nparams'
  */
 int     virDomainGetSchedulerParameters (virDomainPtr domain,
-                                         virSchedParameterPtr params,
+                                         virTypedParameterPtr params,
                                          int *nparams);
 
 /*
  * Change scheduler parameters
  */
 int     virDomainSetSchedulerParameters (virDomainPtr domain,
-                                         virSchedParameterPtr params,
+                                         virTypedParameterPtr params,
                                          int nparams);
 
 /*
  * Change scheduler parameters
  */
 int     virDomainSetSchedulerParametersFlags (virDomainPtr domain,
-                                              virSchedParameterPtr params,
+                                              virTypedParameterPtr params,
                                               int nparams,
                                               unsigned int flags);
 
@@ -810,29 +777,8 @@ int                     virDomainGetState       (virDomainPtr domain,
 char *                  virDomainGetSchedulerType(virDomainPtr domain,
                                                  int *nparams);
 
-/* Manage blkio parameters.  */
-
-/**
- * virDomainBlkioParameterType:
- *
- * A blkio parameter field type
- */
-typedef enum {
-    VIR_DOMAIN_BLKIO_PARAM_INT     = VIR_TYPED_PARAM_INT,
-    VIR_DOMAIN_BLKIO_PARAM_UINT    = VIR_TYPED_PARAM_UINT,
-    VIR_DOMAIN_BLKIO_PARAM_LLONG   = VIR_TYPED_PARAM_LLONG,
-    VIR_DOMAIN_BLKIO_PARAM_ULLONG  = VIR_TYPED_PARAM_ULLONG,
-    VIR_DOMAIN_BLKIO_PARAM_DOUBLE  = VIR_TYPED_PARAM_DOUBLE,
-    VIR_DOMAIN_BLKIO_PARAM_BOOLEAN = VIR_TYPED_PARAM_BOOLEAN,
-} virBlkioParameterType;
-
-/**
- * VIR_DOMAIN_BLKIO_FIELD_LENGTH:
- *
- * Macro providing the field length of virBlkioParameter
- */
 
-#define VIR_DOMAIN_BLKIO_FIELD_LENGTH VIR_TYPED_PARAM_FIELD_LENGTH
+/* Manage blkio parameters.  */
 
 /**
  * VIR_DOMAIN_BLKIO_WEIGHT:
@@ -843,46 +789,16 @@ typedef enum {
 
 #define VIR_DOMAIN_BLKIO_WEIGHT "weight"
 
-/**
- * virDomainBlkioParameter:
- *
- * a virDomainBlkioParameter is the set of blkio parameters
- */
-
-typedef struct _virTypedParameter virBlkioParameter;
-
-/**
- * virBlkioParameterPtr:
- *
- * a virBlkioParameterPtr is a pointer to a virBlkioParameter structure.
- */
-
-typedef virBlkioParameter *virBlkioParameterPtr;
-
 /* Set Blkio tunables for the domain*/
 int     virDomainSetBlkioParameters(virDomainPtr domain,
-                                     virBlkioParameterPtr params,
-                                     int nparams, unsigned int flags);
+                                    virTypedParameterPtr params,
+                                    int nparams, unsigned int flags);
 int     virDomainGetBlkioParameters(virDomainPtr domain,
-                                     virBlkioParameterPtr params,
-                                     int *nparams, unsigned int flags);
+                                    virTypedParameterPtr params,
+                                    int *nparams, unsigned int flags);
 
 /* Manage memory parameters.  */
 
-/**
- * virDomainMemoryParameterType:
- *
- * A memory parameter field type
- */
-typedef enum {
-    VIR_DOMAIN_MEMORY_PARAM_INT     = VIR_TYPED_PARAM_INT,
-    VIR_DOMAIN_MEMORY_PARAM_UINT    = VIR_TYPED_PARAM_UINT,
-    VIR_DOMAIN_MEMORY_PARAM_LLONG   = VIR_TYPED_PARAM_LLONG,
-    VIR_DOMAIN_MEMORY_PARAM_ULLONG  = VIR_TYPED_PARAM_ULLONG,
-    VIR_DOMAIN_MEMORY_PARAM_DOUBLE  = VIR_TYPED_PARAM_DOUBLE,
-    VIR_DOMAIN_MEMORY_PARAM_BOOLEAN = VIR_TYPED_PARAM_BOOLEAN,
-} virMemoryParameterType;
-
 /* flags for setting memory parameters */
 typedef enum {
     VIR_DOMAIN_MEMORY_PARAM_CURRENT = 0,        /* affect current domain state */
@@ -890,14 +806,6 @@ typedef enum {
     VIR_DOMAIN_MEMORY_PARAM_CONFIG  = (1 << 1)  /* affect next boot */
 } virMemoryParamFlags;
 
-/**
- * VIR_DOMAIN_MEMORY_FIELD_LENGTH:
- *
- * Macro providing the field length of virMemoryParameter
- */
-
-#define VIR_DOMAIN_MEMORY_FIELD_LENGTH VIR_TYPED_PARAM_FIELD_LENGTH
-
 /**
  * VIR_DOMAIN_MEMORY_PARAM_UNLIMITED:
  *
@@ -943,28 +851,12 @@ typedef enum {
 
 #define VIR_DOMAIN_MEMORY_SWAP_HARD_LIMIT "swap_hard_limit"
 
-/**
- * virDomainMemoryParameter:
- *
- * a virDomainMemoryParameter is the set of scheduler parameters
- */
-
-typedef struct _virTypedParameter virMemoryParameter;
-
-/**
- * virMemoryParameterPtr:
- *
- * a virMemoryParameterPtr is a pointer to a virMemoryParameter structure.
- */
-
-typedef virMemoryParameter *virMemoryParameterPtr;
-
 /* Set memory tunables for the domain*/
 int     virDomainSetMemoryParameters(virDomainPtr domain,
-                                     virMemoryParameterPtr params,
+                                     virTypedParameterPtr params,
                                      int nparams, unsigned int flags);
 int     virDomainGetMemoryParameters(virDomainPtr domain,
-                                     virMemoryParameterPtr params,
+                                     virTypedParameterPtr params,
                                      int *nparams, unsigned int flags);
 
 /* Memory size modification flags. */
@@ -2643,6 +2535,139 @@ int virDomainOpenConsole(virDomainPtr dom,
 
 int virDomainInjectNMI(virDomainPtr domain, unsigned int flags);
 
+
+/**
+ * virDomainSchedParameterType:
+ *
+ * A scheduler parameter field type.  Provided for backwards
+ * compatibility; virTypedParameterType is the preferred enum since
+ * 0.9.2.
+ */
+typedef enum {
+    VIR_DOMAIN_SCHED_FIELD_INT     = VIR_TYPED_PARAM_INT,
+    VIR_DOMAIN_SCHED_FIELD_UINT    = VIR_TYPED_PARAM_UINT,
+    VIR_DOMAIN_SCHED_FIELD_LLONG   = VIR_TYPED_PARAM_LLONG,
+    VIR_DOMAIN_SCHED_FIELD_ULLONG  = VIR_TYPED_PARAM_ULLONG,
+    VIR_DOMAIN_SCHED_FIELD_DOUBLE  = VIR_TYPED_PARAM_DOUBLE,
+    VIR_DOMAIN_SCHED_FIELD_BOOLEAN = VIR_TYPED_PARAM_BOOLEAN,
+} virSchedParameterType;
+
+/**
+ * VIR_DOMAIN_SCHED_FIELD_LENGTH:
+ *
+ * Macro providing the field length of virSchedParameter.  Provided
+ * for backwards compatibility; VIR_TYPED_PARAM_FIELD_LENGTH is the
+ * preferred value since 0.9.2.
+ */
+#define VIR_DOMAIN_SCHED_FIELD_LENGTH VIR_TYPED_PARAM_FIELD_LENGTH
+
+/**
+ * virDomainSchedParameter:
+ *
+ * a virDomainSchedParameter is the set of scheduler parameters.
+ * Provided for backwards compatibility; virTypedParameter is the
+ * preferred alias since 0.9.2.
+ */
+#define _virSchedParameter _virTypedParameter
+typedef struct _virTypedParameter virSchedParameter;
+
+/**
+ * virSchedParameterPtr:
+ *
+ * a virSchedParameterPtr is a pointer to a virSchedParameter structure.
+ * Provided for backwards compatibility; virTypedParameterPtr is the
+ * preferred alias since 0.9.2.
+ */
+typedef virSchedParameter *virSchedParameterPtr;
+
+/**
+ * virDomainBlkioParameterType:
+ *
+ * A blkio parameter field type.  Provided for backwards
+ * compatibility; virTypedParameterType is the preferred enum since
+ * 0.9.2.
+ */
+typedef enum {
+    VIR_DOMAIN_BLKIO_PARAM_INT     = VIR_TYPED_PARAM_INT,
+    VIR_DOMAIN_BLKIO_PARAM_UINT    = VIR_TYPED_PARAM_UINT,
+    VIR_DOMAIN_BLKIO_PARAM_LLONG   = VIR_TYPED_PARAM_LLONG,
+    VIR_DOMAIN_BLKIO_PARAM_ULLONG  = VIR_TYPED_PARAM_ULLONG,
+    VIR_DOMAIN_BLKIO_PARAM_DOUBLE  = VIR_TYPED_PARAM_DOUBLE,
+    VIR_DOMAIN_BLKIO_PARAM_BOOLEAN = VIR_TYPED_PARAM_BOOLEAN,
+} virBlkioParameterType;
+
+/**
+ * VIR_DOMAIN_BLKIO_FIELD_LENGTH:
+ *
+ * Macro providing the field length of virBlkioParameter.  Provided
+ * for backwards compatibility; VIR_TYPED_PARAM_FIELD_LENGTH is the
+ * preferred value since 0.9.2.
+ */
+#define VIR_DOMAIN_BLKIO_FIELD_LENGTH VIR_TYPED_PARAM_FIELD_LENGTH
+
+/**
+ * virDomainBlkioParameter:
+ *
+ * a virDomainBlkioParameter is the set of blkio parameters.
+ * Provided for backwards compatibility; virTypedParameter is the
+ * preferred alias since 0.9.2.
+ */
+#define _virBlkioParameter _virTypedParameter
+typedef struct _virTypedParameter virBlkioParameter;
+
+/**
+ * virBlkioParameterPtr:
+ *
+ * a virBlkioParameterPtr is a pointer to a virBlkioParameter structure.
+ * Provided for backwards compatibility; virTypedParameterPtr is the
+ * preferred alias since 0.9.2.
+ */
+typedef virBlkioParameter *virBlkioParameterPtr;
+
+/**
+ * virDomainMemoryParameterType:
+ *
+ * A memory parameter field type.  Provided for backwards
+ * compatibility; virTypedParameterType is the preferred enum since
+ * 0.9.2.
+ */
+typedef enum {
+    VIR_DOMAIN_MEMORY_PARAM_INT     = VIR_TYPED_PARAM_INT,
+    VIR_DOMAIN_MEMORY_PARAM_UINT    = VIR_TYPED_PARAM_UINT,
+    VIR_DOMAIN_MEMORY_PARAM_LLONG   = VIR_TYPED_PARAM_LLONG,
+    VIR_DOMAIN_MEMORY_PARAM_ULLONG  = VIR_TYPED_PARAM_ULLONG,
+    VIR_DOMAIN_MEMORY_PARAM_DOUBLE  = VIR_TYPED_PARAM_DOUBLE,
+    VIR_DOMAIN_MEMORY_PARAM_BOOLEAN = VIR_TYPED_PARAM_BOOLEAN,
+} virMemoryParameterType;
+
+/**
+ * VIR_DOMAIN_MEMORY_FIELD_LENGTH:
+ *
+ * Macro providing the field length of virMemoryParameter.  Provided
+ * for backwards compatibility; VIR_TYPED_PARAM_FIELD_LENGTH is the
+ * preferred value since 0.9.2.
+ */
+#define VIR_DOMAIN_MEMORY_FIELD_LENGTH VIR_TYPED_PARAM_FIELD_LENGTH
+
+/**
+ * virDomainMemoryParameter:
+ *
+ * a virDomainMemoryParameter is the set of scheduler parameters.
+ * Provided for backwards compatibility; virTypedParameter is the
+ * preferred alias since 0.9.2.
+ */
+#define _virMemoryParameter _virTypedParameter
+typedef struct _virTypedParameter virMemoryParameter;
+
+/**
+ * virMemoryParameterPtr:
+ *
+ * a virMemoryParameterPtr is a pointer to a virMemoryParameter structure.
+ * Provided for backwards compatibility; virTypedParameterPtr is the
+ * preferred alias since 0.9.2.
+ */
+typedef virMemoryParameter *virMemoryParameterPtr;
+
 #ifdef __cplusplus
 }
 #endif

python/libvirt-override.c

@@ -206,7 +206,7 @@ libvirt_virDomainGetSchedulerParameters(PyObject *self ATTRIBUTE_UNUSED,
     char *c_retval;
     int i_retval;
     int nparams, i;
-    virSchedParameterPtr params;
+    virTypedParameterPtr params;
 
     if (!PyArg_ParseTuple(args, (char *)"O:virDomainGetScedulerParameters",
                           &pyobj_domain))
@@ -242,27 +242,27 @@ libvirt_virDomainGetSchedulerParameters(PyObject *self ATTRIBUTE_UNUSED,
         PyObject *key, *val;
 
         switch (params[i].type) {
-        case VIR_DOMAIN_SCHED_FIELD_INT:
+        case VIR_TYPED_PARAM_INT:
             val = PyInt_FromLong((long)params[i].value.i);
             break;
 
-        case VIR_DOMAIN_SCHED_FIELD_UINT:
+        case VIR_TYPED_PARAM_UINT:
             val = PyInt_FromLong((long)params[i].value.ui);
             break;
 
-        case VIR_DOMAIN_SCHED_FIELD_LLONG:
+        case VIR_TYPED_PARAM_LLONG:
             val = PyLong_FromLongLong((long long)params[i].value.l);
             break;
 
-        case VIR_DOMAIN_SCHED_FIELD_ULLONG:
+        case VIR_TYPED_PARAM_ULLONG:
             val = PyLong_FromLongLong((long long)params[i].value.ul);
             break;
 
-        case VIR_DOMAIN_SCHED_FIELD_DOUBLE:
+        case VIR_TYPED_PARAM_DOUBLE:
             val = PyFloat_FromDouble((double)params[i].value.d);
             break;
 
-        case VIR_DOMAIN_SCHED_FIELD_BOOLEAN:
+        case VIR_TYPED_PARAM_BOOLEAN:
             val = PyBool_FromLong((long)params[i].value.b);
             break;
 
@@ -287,7 +287,7 @@ libvirt_virDomainSetSchedulerParameters(PyObject *self ATTRIBUTE_UNUSED,
     char *c_retval;
     int i_retval;
     int nparams, i;
-    virSchedParameterPtr params;
+    virTypedParameterPtr params;
 
     if (!PyArg_ParseTuple(args, (char *)"OO:virDomainSetScedulerParameters",
                           &pyobj_domain, &info))
@@ -325,27 +325,27 @@ libvirt_virDomainSetSchedulerParameters(PyObject *self ATTRIBUTE_UNUSED,
             continue;
 
         switch (params[i].type) {
-        case VIR_DOMAIN_SCHED_FIELD_INT:
+        case VIR_TYPED_PARAM_INT:
             params[i].value.i = (int)PyInt_AS_LONG(val);
             break;
 
-        case VIR_DOMAIN_SCHED_FIELD_UINT:
+        case VIR_TYPED_PARAM_UINT:
             params[i].value.ui = (unsigned int)PyInt_AS_LONG(val);
             break;
 
-        case VIR_DOMAIN_SCHED_FIELD_LLONG:
+        case VIR_TYPED_PARAM_LLONG:
             params[i].value.l = (long long)PyLong_AsLongLong(val);
             break;
 
-        case VIR_DOMAIN_SCHED_FIELD_ULLONG:
+        case VIR_TYPED_PARAM_ULLONG:
             params[i].value.ul = (unsigned long long)PyLong_AsLongLong(val);
             break;
 
-        case VIR_DOMAIN_SCHED_FIELD_DOUBLE:
+        case VIR_TYPED_PARAM_DOUBLE:
             params[i].value.d = (double)PyFloat_AsDouble(val);
             break;
 
-        case VIR_DOMAIN_SCHED_FIELD_BOOLEAN:
+        case VIR_TYPED_PARAM_BOOLEAN:
             {
                 /* Hack - Python's definition of Py_True breaks strict
                  * aliasing rules, so can't directly compare :-(