network: add public APIs for network port object

Introduce a new virNetworPort object that will present an attachment to
a virtual network from a VM.

Reviewed-by: Laine Stump <laine@laine.org>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

include/libvirt/libvirt-network.h

@@ -46,6 +46,22 @@ typedef struct _virNetwork virNetwork;
  */
 typedef virNetwork *virNetworkPtr;
 
+/**
+ * virNetworkPort:
+ *
+ * a virNetworkPort is a private structure representing a virtual network
+ * port
+ */
+typedef struct _virNetworkPort virNetworkPort;
+
+/**
+ * virNetworkPortPtr:
+ *
+ * a virNetworkPortPtr is pointer to a virNetworkPort private structure,
+ * this is the type used to reference a virtual network port in the API.
+ */
+typedef virNetworkPort *virNetworkPortPtr;
+
 /*
  * Get connection from network.
  */
@@ -333,4 +349,110 @@ int virConnectNetworkEventRegisterAny(virConnectPtr conn,
 int virConnectNetworkEventDeregisterAny(virConnectPtr conn,
                                         int callbackID);
 
+
+virNetworkPortPtr
+virNetworkPortLookupByUUID(virNetworkPtr net,
+                           const unsigned char *uuid);
+
+virNetworkPortPtr
+virNetworkPortLookupByUUIDString(virNetworkPtr net,
+                                 const char *uuidstr);
+
+typedef enum {
+    VIR_NETWORK_PORT_CREATE_RECLAIM = (1 << 0), /* reclaim existing used resources */
+} virNetworkPortCreateFlags;
+
+virNetworkPortPtr
+virNetworkPortCreateXML(virNetworkPtr net,
+                        const char *xmldesc,
+                        unsigned int flags);
+
+virNetworkPtr
+virNetworkPortGetNetwork(virNetworkPortPtr port);
+
+char *
+virNetworkPortGetXMLDesc(virNetworkPortPtr port,
+                         unsigned int flags);
+
+int
+virNetworkPortGetUUID(virNetworkPortPtr port,
+                      unsigned char *uuid);
+int
+virNetworkPortGetUUIDString(virNetworkPortPtr port,
+                            char *buf);
+
+/* Management of interface parameters */
+
+/**
+ * VIR_NETWORK_PORT_BANDWIDTH_IN_AVERAGE:
+ *
+ * Macro represents the inbound average of NIC bandwidth, as a uint.
+ */
+# define VIR_NETWORK_PORT_BANDWIDTH_IN_AVERAGE "inbound.average"
+
+/**
+ * VIR_NETWORK_PORT_BANDWIDTH_IN_PEAK:
+ *
+ * Macro represents the inbound peak of NIC bandwidth, as a uint.
+ */
+# define VIR_NETWORK_PORT_BANDWIDTH_IN_PEAK "inbound.peak"
+
+/**
+ * VIR_NETWORK_PORT_BANDWIDTH_IN_BURST:
+ *
+ * Macro represents the inbound burst of NIC bandwidth, as a uint.
+ */
+# define VIR_NETWORK_PORT_BANDWIDTH_IN_BURST "inbound.burst"
+
+/**
+ * VIR_NETWORK_PORT_BANDWIDTH_IN_FLOOR:
+ *
+ * Macro represents the inbound floor of NIC bandwidth, as a uint.
+ */
+# define VIR_NETWORK_PORT_BANDWIDTH_IN_FLOOR "inbound.floor"
+
+/**
+ * VIR_NETWORK_PORT_BANDWIDTH_OUT_AVERAGE:
+ *
+ * Macro represents the outbound average of NIC bandwidth, as a uint.
+ */
+# define VIR_NETWORK_PORT_BANDWIDTH_OUT_AVERAGE "outbound.average"
+
+/**
+ * VIR_NETWORK_PORT_BANDWIDTH_OUT_PEAK:
+ *
+ * Macro represents the outbound peak of NIC bandwidth, as a uint.
+ */
+# define VIR_NETWORK_PORT_BANDWIDTH_OUT_PEAK "outbound.peak"
+
+/**
+ * VIR_NETWORK_PORT_BANDWIDTH_OUT_BURST:
+ *
+ * Macro represents the outbound burst of NIC bandwidth, as a uint.
+ */
+# define VIR_NETWORK_PORT_BANDWIDTH_OUT_BURST "outbound.burst"
+
+int
+virNetworkPortSetParameters(virNetworkPortPtr port,
+                            virTypedParameterPtr params,
+                            int nparams,
+                            unsigned int flags);
+int
+virNetworkPortGetParameters(virNetworkPortPtr port,
+                            virTypedParameterPtr *params,
+                            int *nparams,
+                            unsigned int flags);
+
+int
+virNetworkPortDelete(virNetworkPortPtr port,
+                     unsigned int flags);
+
+int
+virNetworkListAllPorts(virNetworkPtr network,
+                       virNetworkPortPtr **ports,
+                       unsigned int flags);
+
+int
+virNetworkPortFree(virNetworkPortPtr port);
+
 #endif /* LIBVIRT_NETWORK_H */

include/libvirt/virterror.h

@@ -326,6 +326,9 @@ typedef enum {
     VIR_ERR_INVALID_DOMAIN_CHECKPOINT = 102, /* invalid domain checkpoint */
     VIR_ERR_NO_DOMAIN_CHECKPOINT = 103, /* domain checkpoint not found */
     VIR_ERR_NO_DOMAIN_BACKUP = 104,     /* domain backup job id not found */
+    VIR_ERR_INVALID_NETWORK_PORT = 105, /* invalid network port object */
+    VIR_ERR_NETWORK_PORT_EXIST = 106,   /* the network port already exist */
+    VIR_ERR_NO_NETWORK_PORT = 107,      /* network port not found */
 
 # ifdef VIR_ENUM_SENTINELS
     VIR_ERR_NUMBER_LAST

src/datatypes.c

@@ -40,6 +40,7 @@ virClassPtr virDomainCheckpointClass;
 virClassPtr virDomainSnapshotClass;
 virClassPtr virInterfaceClass;
 virClassPtr virNetworkClass;
+virClassPtr virNetworkPortClass;
 virClassPtr virNodeDeviceClass;
 virClassPtr virNWFilterClass;
 virClassPtr virNWFilterBindingClass;
@@ -55,6 +56,7 @@ static void virDomainCheckpointDispose(void *obj);
 static void virDomainSnapshotDispose(void *obj);
 static void virInterfaceDispose(void *obj);
 static void virNetworkDispose(void *obj);
+static void virNetworkPortDispose(void *obj);
 static void virNodeDeviceDispose(void *obj);
 static void virNWFilterDispose(void *obj);
 static void virNWFilterBindingDispose(void *obj);
@@ -92,6 +94,7 @@ virDataTypesOnceInit(void)
     DECLARE_CLASS(virDomainSnapshot);
     DECLARE_CLASS(virInterface);
     DECLARE_CLASS(virNetwork);
+    DECLARE_CLASS(virNetworkPort);
     DECLARE_CLASS(virNodeDevice);
     DECLARE_CLASS(virNWFilter);
     DECLARE_CLASS(virNWFilterBinding);
@@ -388,6 +391,63 @@ virNetworkDispose(void *obj)
 }
 
 
+/**
+ * virGetNetworkPort:
+ * @net: the network object
+ * @uuid: pointer to the uuid
+ *
+ * Allocates a new network port object. When the object is no longer needed,
+ * virObjectUnref() must be called in order to not leak data.
+ *
+ * Returns a pointer to the network port object, or NULL on error.
+ */
+virNetworkPortPtr
+virGetNetworkPort(virNetworkPtr net, const unsigned char *uuid)
+{
+    virNetworkPortPtr ret = NULL;
+
+    if (virDataTypesInitialize() < 0)
+        return NULL;
+
+    virCheckNetworkGoto(net, error);
+    virCheckNonNullArgGoto(uuid, error);
+
+    if (!(ret = virObjectNew(virNetworkPortClass)))
+        goto error;
+
+    ret->net = virObjectRef(net);
+    memcpy(&(ret->uuid[0]), uuid, VIR_UUID_BUFLEN);
+
+    return ret;
+
+ error:
+    virObjectUnref(ret);
+    return NULL;
+}
+
+/**
+ * virNetworkPortDispose:
+ * @obj: the network port to release
+ *
+ * Unconditionally release all memory associated with a network port.
+ * The network port object must not be used once this method returns.
+ *
+ * It will also unreference the associated network object,
+ * which may also be released if its ref count hits zero.
+ */
+static void
+virNetworkPortDispose(void *obj)
+{
+    virNetworkPortPtr port = obj;
+    char uuidstr[VIR_UUID_STRING_BUFLEN];
+
+    virUUIDFormat(port->uuid, uuidstr);
+    VIR_DEBUG("release network port %p %s", port, uuidstr);
+
+    virObjectUnref(port->net);
+}
+
+
 /**
  * virGetInterface:
  * @conn: the hypervisor connection

src/datatypes.h

@@ -34,6 +34,7 @@ extern virClassPtr virDomainCheckpointClass;
 extern virClassPtr virDomainSnapshotClass;
 extern virClassPtr virInterfaceClass;
 extern virClassPtr virNetworkClass;
+extern virClassPtr virNetworkPortClass;
 extern virClassPtr virNodeDeviceClass;
 extern virClassPtr virNWFilterClass;
 extern virClassPtr virNWFilterBindingClass;
@@ -116,6 +117,33 @@ extern virClassPtr virAdmClientClass;
         } \
     } while (0)
 
+#define virCheckNetworkPortReturn(obj, retval) \
+    do { \
+        virNetworkPortPtr _port = (obj); \
+        if (!virObjectIsClass(_port, virNetworkPortClass) || \
+            !virObjectIsClass(_port->net, virNetworkClass)) { \
+            virReportErrorHelper(VIR_FROM_NETWORK, \
+                                 VIR_ERR_INVALID_NETWORK_PORT, \
+                                 __FILE__, __FUNCTION__, __LINE__, \
+                                 __FUNCTION__); \
+            virDispatchError(NULL); \
+            return retval; \
+        } \
+    } while (0)
+
+#define virCheckNetworkPortGoto(obj, label) \
+    do { \
+        virNetworkPortPtr _port = (obj); \
+        if (!virObjectIsClass(_port, virNetworkPortClass) || \
+            !virObjectIsClass(_port->net, virNetworkClass)) { \
+            virReportErrorHelper(VIR_FROM_NETWORK, \
+                                 VIR_ERR_INVALID_NETWORK_PORT, \
+                                 __FILE__, __FUNCTION__, __LINE__, \
+                                 __FUNCTION__); \
+            goto label; \
+        } \
+    } while (0)
+
 #define virCheckInterfaceReturn(obj, retval) \
     do { \
         virInterfacePtr _iface = (obj); \
@@ -588,6 +616,17 @@ struct _virNetwork {
     unsigned char uuid[VIR_UUID_BUFLEN]; /* the network unique identifier */
 };
 
+/**
+* _virNetworkPort:
+*
+* Internal structure associated to a network port
+*/
+struct _virNetworkPort {
+    virObject parent;
+    virNetworkPtr net;                   /* pointer back to the connection */
+    unsigned char uuid[VIR_UUID_BUFLEN]; /* the network unique identifier */
+};
+
 /**
 * _virInterface:
 *
@@ -745,6 +784,8 @@ virDomainPtr virGetDomain(virConnectPtr conn,
 virNetworkPtr virGetNetwork(virConnectPtr conn,
                             const char *name,
                             const unsigned char *uuid);
+virNetworkPortPtr virGetNetworkPort(virNetworkPtr net,
+                                    const unsigned char *uuid);
 virInterfacePtr virGetInterface(virConnectPtr conn,
                                 const char *name,
                                 const char *mac);

src/driver-network.h

@@ -117,6 +117,40 @@ typedef int
                               virNetworkDHCPLeasePtr **leases,
                               unsigned int flags);
 
+typedef virNetworkPortPtr
+(*virDrvNetworkPortLookupByUUID)(virNetworkPtr net,
+                                 const unsigned char *uuid);
+
+typedef virNetworkPortPtr
+(*virDrvNetworkPortCreateXML)(virNetworkPtr net,
+                              const char *xmldesc,
+                              unsigned int flags);
+
+typedef int
+(*virDrvNetworkPortSetParameters)(virNetworkPortPtr port,
+                                  virTypedParameterPtr params,
+                                  int nparams,
+                                  unsigned int flags);
+
+typedef int
+(*virDrvNetworkPortGetParameters)(virNetworkPortPtr port,
+                                  virTypedParameterPtr *params,
+                                  int *nparams,
+                                  unsigned int flags);
+
+typedef char *
+(*virDrvNetworkPortGetXMLDesc)(virNetworkPortPtr port,
+                               unsigned int flags);
+
+typedef int
+(*virDrvNetworkPortDelete)(virNetworkPortPtr port,
+                           unsigned int flags);
+
+typedef int
+(*virDrvNetworkListAllPorts)(virNetworkPtr network,
+                             virNetworkPortPtr **ports,
+                             unsigned int flags);
+
 typedef struct _virNetworkDriver virNetworkDriver;
 typedef virNetworkDriver *virNetworkDriverPtr;
 
@@ -150,4 +184,11 @@ struct _virNetworkDriver {
     virDrvNetworkIsActive networkIsActive;
     virDrvNetworkIsPersistent networkIsPersistent;
     virDrvNetworkGetDHCPLeases networkGetDHCPLeases;
+    virDrvNetworkPortLookupByUUID networkPortLookupByUUID;
+    virDrvNetworkPortCreateXML networkPortCreateXML;
+    virDrvNetworkPortGetXMLDesc networkPortGetXMLDesc;
+    virDrvNetworkPortSetParameters networkPortSetParameters;
+    virDrvNetworkPortGetParameters networkPortGetParameters;
+    virDrvNetworkPortDelete networkPortDelete;
+    virDrvNetworkListAllPorts networkListAllPorts;
 };

src/libvirt-network.c

@@ -23,6 +23,7 @@
 #include "datatypes.h"
 #include "viralloc.h"
 #include "virlog.h"
+#include "virtypedparam.h"
 
 VIR_LOG_INIT("libvirt.network");
 
@@ -1246,3 +1247,446 @@ virNetworkDHCPLeaseFree(virNetworkDHCPLeasePtr lease)
     VIR_FREE(lease->clientid);
     VIR_FREE(lease);
 }
+
+
+/**
+ * virNetworkPortLookupByUUID:
+ * @net: pointer to the network object
+ * @uuid: the raw UUID for the network port
+ *
+ * Try to lookup a port on the given network based on its UUID.
+ *
+ * virNetworkPortFree should be used to free the resources after the
+ * network port object is no longer needed.
+ *
+ * Returns a new network port object or NULL in case of failure.  If the
+ * network port cannot be found, then VIR_ERR_NO_NETWORK_PORT error is raised.
+ */
+virNetworkPortPtr
+virNetworkPortLookupByUUID(virNetworkPtr net,
+                           const unsigned char *uuid)
+{
+    VIR_UUID_DEBUG(net, uuid);
+
+    virResetLastError();
+
+    virCheckNetworkReturn(net, NULL);
+    virCheckNonNullArgGoto(uuid, error);
+
+    if (net->conn->networkDriver && net->conn->networkDriver->networkPortLookupByUUID) {
+        virNetworkPortPtr ret;
+        ret = net->conn->networkDriver->networkPortLookupByUUID(net, uuid);
+        if (!ret)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(net->conn);
+    return NULL;
+}
+
+
+/**
+ * virNetworkPortLookupByUUIDString:
+ * @net: pointer to the network object
+ * @uuidstr: the string UUID for the port
+ *
+ * Try to lookup a port on the given network based on its UUID.
+ *
+ * Returns a new network port object or NULL in case of failure.  If the
+ * network port cannot be found, then VIR_ERR_NO_NETWORK_PORT error is raised.
+ */
+virNetworkPortPtr
+virNetworkPortLookupByUUIDString(virNetworkPtr net,
+                                 const char *uuidstr)
+{
+    unsigned char uuid[VIR_UUID_BUFLEN];
+    VIR_DEBUG("net=%p, uuidstr=%s", net, NULLSTR(uuidstr));
+
+    virResetLastError();
+
+    virCheckNetworkReturn(net, NULL);
+    virCheckNonNullArgGoto(uuidstr, error);
+
+    if (virUUIDParse(uuidstr, uuid) < 0) {
+        virReportInvalidArg(uuidstr,
+                            _("uuidstr in %s must be a valid UUID"),
+                            __FUNCTION__);
+        goto error;
+    }
+
+    return virNetworkPortLookupByUUID(net, &uuid[0]);
+
+ error:
+    virDispatchError(net->conn);
+    return NULL;
+}
+
+
+/**
+ * virNetworkPortSetParameters:
+ * @port: a network port object
+ * @params: pointer to interface parameter objects
+ * @nparams: number of interface parameter (this value can be the same or
+ *          less than the number of parameters supported)
+ * @flags: currently unused, pass 0
+ *
+ * Change a subset or all parameters of the network port; currently this
+ * includes bandwidth parameters.
+ *
+ * Returns -1 in case of error, 0 in case of success.
+ */
+int
+virNetworkPortSetParameters(virNetworkPortPtr port,
+                            virTypedParameterPtr params,
+                            int nparams,
+                            unsigned int flags)
+{
+    virConnectPtr conn;
+    VIR_DEBUG("port=%p, params=%p, nparams=%d, flags=0x%x", port, params, nparams, flags);
+    VIR_TYPED_PARAMS_DEBUG(params, nparams);
+
+    virResetLastError();
+
+    virCheckNetworkPortReturn(port, -1);
+    conn = port->net->conn;
+
+    virCheckReadOnlyGoto(conn->flags, error);
+
+    if (conn->networkDriver && conn->networkDriver->networkPortSetParameters) {
+        int ret;
+        ret = conn->networkDriver->networkPortSetParameters(port, params, nparams, flags);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(conn);
+    return -1;
+}
+
+
+/**
+ * virNetworkPortGetParameters:
+ * @port: a network port object
+ * @params: pointer to pointer of interface parameter objects
+ * @nparams: pointer to received number of interface parameter
+ * @flags: currently unused, pass 0
+ *
+ * Get all interface parameters. On input, @params should be initialized
+ * to NULL. On return @params will be allocated with the size large
+ * enough to hold all parameters, and @nparams will be updated to say
+ * how many parameters are present. @params should be freed by the caller
+ * on success.
+ *
+ * Returns -1 in case of error, 0 in case of success.
+ */
+int
+virNetworkPortGetParameters(virNetworkPortPtr port,
+                            virTypedParameterPtr *params,
+                            int *nparams,
+                            unsigned int flags)
+{
+    virConnectPtr conn;
+    VIR_DEBUG("port=%p, params=%p, nparams=%p, flags=0x%x", port, params, nparams, flags);
+
+    virResetLastError();
+
+    virCheckNetworkPortReturn(port, -1);
+    conn = port->net->conn;
+
+    if (conn->networkDriver && conn->networkDriver->networkPortGetParameters) {
+        int ret;
+        ret = conn->networkDriver->networkPortGetParameters(port, params, nparams, flags);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(conn);
+    return -1;
+}
+
+
+/**
+ * virNetworkPortCreateXML:
+ * @net: pointer to the network object
+ * @xmldesc: an XML description of the port
+ * @flags: currently unused, pass 0
+ *
+ * Create a new network port, based on an XML description
+ * similar to the one returned by virNetworkPortGetXMLDesc()
+ *
+ * virNetworkPortFree should be used to free the resources after the
+ * network port object is no longer needed.
+ *
+ * Returns a new network port object or NULL in case of failure
+ */
+virNetworkPortPtr
+virNetworkPortCreateXML(virNetworkPtr net,
+                        const char *xmldesc,
+                        unsigned int flags)
+{
+    VIR_DEBUG("net=%p, xmldesc=%s, flags=0x%x", net, NULLSTR(xmldesc), flags);
+
+    virResetLastError();
+
+    virCheckNetworkReturn(net, NULL);
+    virCheckNonNullArgGoto(xmldesc, error);
+    virCheckReadOnlyGoto(net->conn->flags, error);
+
+    if (net->conn->networkDriver && net->conn->networkDriver->networkPortCreateXML) {
+        virNetworkPortPtr ret;
+        ret = net->conn->networkDriver->networkPortCreateXML(net, xmldesc, flags);
+        if (!ret)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(net->conn);
+    return NULL;
+}
+
+/**
+ * virNetworkPortGetNetwork:
+ * @port: pointer to a network port
+ *
+ * Provides the network pointer associated with a port.  The
+ * reference counter on the connection is not increased by this
+ * call.
+ *
+ * Returns the virNetworkPtr or NULL in case of failure.
+ */
+virNetworkPtr
+virNetworkPortGetNetwork(virNetworkPortPtr port)
+{
+    VIR_DEBUG("port=%p", port);
+
+    virResetLastError();
+
+    virCheckNetworkPortReturn(port, NULL);
+
+    return port->net;
+}
+
+
+/**
+ * virNetworkPortGetXMLDesc:
+ * @port: a network port object
+ * @flags: currently unused, pass 0
+ *
+ * Provide an XML description of the network port. The description may be reused
+ * later to recreate the port with virNetworkPortCreateXML().
+ *
+ * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
+ *         the caller must free() the returned value.
+ */
+char *
+virNetworkPortGetXMLDesc(virNetworkPortPtr port,
+                         unsigned int flags)
+{
+    virConnectPtr conn;
+    VIR_DEBUG("port=%p, flags=0x%x", port, flags);
+
+    virResetLastError();
+
+    virCheckNetworkPortReturn(port, NULL);
+    conn = port->net->conn;
+
+    if (conn->networkDriver && conn->networkDriver->networkPortGetXMLDesc) {
+        char *ret;
+        ret = conn->networkDriver->networkPortGetXMLDesc(port, flags);
+        if (!ret)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(conn);
+    return NULL;
+}
+
+
+/**
+ * virNetworkPortGetUUID:
+ * @port: a network port object
+ * @uuid: pointer to a VIR_UUID_BUFLEN bytes array
+ *
+ * Get the UUID for a network port
+ *
+ * Returns -1 in case of error, 0 in case of success
+ */
+int
+virNetworkPortGetUUID(virNetworkPortPtr port,
+                      unsigned char *uuid)
+{
+    VIR_DEBUG("port=%p, uuid=%p", port, uuid);
+
+    virResetLastError();
+
+    virCheckNetworkPortReturn(port, -1);
+    virCheckNonNullArgGoto(uuid, error);
+
+    memcpy(uuid, &port->uuid[0], VIR_UUID_BUFLEN);
+
+    return 0;
+
+ error:
+    virDispatchError(port->net->conn);
+    return -1;
+}
+
+
+/**
+ * virNetworkPortGetUUIDString:
+ * @port: a network port object
+ * @buf: pointer to a VIR_UUID_STRING_BUFLEN bytes array
+ *
+ * Get the UUID for a network as string. For more information about
+ * UUID see RFC4122.
+ *
+ * Returns -1 in case of error, 0 in case of success
+ */
+int
+virNetworkPortGetUUIDString(virNetworkPortPtr port,
+                            char *buf)
+{
+    VIR_DEBUG("port=%p, buf=%p", port, buf);
+
+    virResetLastError();
+
+    virCheckNetworkPortReturn(port, -1);
+    virCheckNonNullArgGoto(buf, error);
+
+    virUUIDFormat(port->uuid, buf);
+    return 0;
+
+ error:
+    virDispatchError(port->net->conn);
+    return -1;
+}
+
+/**
+ * virNetworkPortDelete:
+ * @port: a port object
+ * @flags: currently unused, pass 0
+ *
+ * Delete the network port. This does not free the
+ * associated virNetworkPortPtr object. It is the
+ * caller's responsibility to ensure the port is not
+ * still in use by a virtual machine before deleting
+ * port.
+ *
+ * Returns 0 in case of success and -1 in case of failure.
+ */
+int
+virNetworkPortDelete(virNetworkPortPtr port,
+                     unsigned int flags)
+{
+    virConnectPtr conn;
+    VIR_DEBUG("port=%p, flags=0x%x", port, flags);
+
+    virResetLastError();
+
+    virCheckNetworkPortReturn(port, -1);
+    conn = port->net->conn;
+
+    virCheckReadOnlyGoto(conn->flags, error);
+
+    if (conn->networkDriver && conn->networkDriver->networkPortDelete) {
+        int ret;
+        ret = conn->networkDriver->networkPortDelete(port, flags);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(conn);
+    return -1;
+}
+
+
+/**
+ * virNetworkListAllPorts:
+ * @network: pointer to a network object
+ * @ports: Pointer to a variable to store the array containing network port
+ *        objects or NULL if the list is not required (just returns number
+ *        of ports).
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * Collect the list of network ports, and allocate an array to store those
+ * objects.
+ *
+ * Returns the number of network ports found or -1 and sets @ports to
+ * NULL in case of error.  On success, the array stored into @ports is
+ * guaranteed to have an extra allocated element set to NULL but not included
+ * in the return count, to make iteration easier.  The caller is responsible
+ * for calling virNetworkPortFree() on each array element, then calling
+ * free() on @ports.
+ */
+int
+virNetworkListAllPorts(virNetworkPtr network,
+                       virNetworkPortPtr **ports,
+                       unsigned int flags)
+{
+    VIR_DEBUG("network=%p, ports=%p, flags=0x%x", network, ports, flags);
+
+    virResetLastError();
+
+    virCheckNetworkReturn(network, -1);
+
+    if (network->conn->networkDriver &&
+        network->conn->networkDriver->networkListAllPorts) {
+        int ret;
+        ret = network->conn->networkDriver->networkListAllPorts(network, ports, flags);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(network->conn);
+    return -1;
+}
+
+
+/**
+ * virNetworkPortFree:
+ * @port: a network port object
+ *
+ * Free the network port object.
+ * The data structure is freed and should not be used thereafter.
+ *
+ * Returns 0 in case of success and -1 in case of failure.
+ */
+int
+virNetworkPortFree(virNetworkPortPtr port)
+{
+    VIR_DEBUG("port=%p", port);
+
+    virResetLastError();
+
+    virCheckNetworkPortReturn(port, -1);
+
+    virObjectUnref(port);
+    return 0;
+}

src/libvirt_private.syms

@@ -1279,6 +1279,7 @@ virGetDomainCheckpoint;
 virGetDomainSnapshot;
 virGetInterface;
 virGetNetwork;
+virGetNetworkPort;
 virGetNodeDevice;
 virGetNWFilter;
 virGetNWFilterBinding;
@@ -1288,6 +1289,7 @@ virGetStorageVol;
 virGetStream;
 virInterfaceClass;
 virNetworkClass;
+virNetworkPortClass;
 virNewConnectCloseCallbackData;
 virNodeDeviceClass;
 virNWFilterClass;

src/libvirt_public.syms

@@ -819,4 +819,19 @@ LIBVIRT_5.2.0 {
         virConnectGetStoragePoolCapabilities;
 } LIBVIRT_4.10.0;
 
+LIBVIRT_5.5.0 {
+        virNetworkListAllPorts;
+        virNetworkPortLookupByUUID;
+        virNetworkPortLookupByUUIDString;
+        virNetworkPortCreateXML;
+        virNetworkPortGetNetwork;
+        virNetworkPortGetParameters;
+        virNetworkPortGetXMLDesc;
+        virNetworkPortGetUUID;
+        virNetworkPortGetUUIDString;
+        virNetworkPortDelete;
+        virNetworkPortFree;
+        virNetworkPortSetParameters;
+} LIBVIRT_5.2.0;
+
 # .... define new API here using predicted next version number ....

src/util/virerror.c

@@ -1226,6 +1226,15 @@ const virErrorMsgTuple virErrorMsgStrings[VIR_ERR_NUMBER_LAST] = {
     [VIR_ERR_NO_DOMAIN_BACKUP] = {
         N_("Domain backup job id not found"),
         N_("Domain backup job id not found: %s") },
+    [VIR_ERR_INVALID_NETWORK_PORT] = {
+        N_("Invalid network port pointer"),
+        N_("Invalid network port pointer: %s") },
+    [VIR_ERR_NETWORK_PORT_EXIST] = {
+        N_("this network port exists already"),
+        N_("network port %s exists already") },
+    [VIR_ERR_NO_NETWORK_PORT] = {
+        N_("network port not found"),
+        N_("network port not found: %s") },
 };