src/libvirt-network.c

   1 /*
   2  * libvirt-network.c: entry points for virNetworkPtr APIs
   3  *
   4  * Copyright (C) 2006-2015 Red Hat, Inc.
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library.  If not, see
  18  * <http://www.gnu.org/licenses/>.
  19  */
  20
  21 #include <config.h>
  22
  23 #include "datatypes.h"
  24 #include "viralloc.h"
  25 #include "virlog.h"
  26 #include "virtypedparam.h"
  27
  28 VIR_LOG_INIT("libvirt.network");
  29
  30 #define VIR_FROM_THIS VIR_FROM_NETWORK
  31
  32 /**
  33  * virNetworkGetConnect:
  34  * @net: pointer to a network
  35  *
  36  * Provides the connection pointer associated with a network.  The
  37  * reference counter on the connection is not increased by this
  38  * call.
  39  *
  40  * Returns the virConnectPtr or NULL in case of failure.
  41  *
  42  * Since: 0.3.0
  43  */
  44 virConnectPtr
  45 virNetworkGetConnect(virNetworkPtr net)
  46 {
  47     VIR_DEBUG("net=%p", net);
  48
  49     virResetLastError();
  50
  51     virCheckNetworkReturn(net, NULL);
  52
  53     return net->conn;
  54 }
  55
  56
  57 /**
  58  * virConnectListAllNetworks:
  59  * @conn: Pointer to the hypervisor connection.
  60  * @nets: Pointer to a variable to store the array containing the network
  61  *        objects or NULL if the list is not required (just returns number
  62  *        of networks).
  63  * @flags: bitwise-OR of virConnectListAllNetworksFlags.
  64  *
  65  * Collect the list of networks, and allocate an array to store those
  66  * objects. This API solves the race inherent between virConnectListNetworks
  67  * and virConnectListDefinedNetworks.
  68  *
  69  * Normally, all networks are returned; however, @flags can be used to
  70  * filter the results for a smaller list of targeted networks.  The valid
  71  * flags are divided into groups, where each group contains bits that
  72  * describe mutually exclusive attributes of a network, and where all bits
  73  * within a group describe all possible networks.
  74  *
  75  * The first group of @flags is VIR_CONNECT_LIST_NETWORKS_ACTIVE (up) and
  76  * VIR_CONNECT_LIST_NETWORKS_INACTIVE (down) to filter the networks by state.
  77  *
  78  * The second group of @flags is VIR_CONNECT_LIST_NETWORKS_PERSISTENT (defined)
  79  * and VIR_CONNECT_LIST_NETWORKS_TRANSIENT (running but not defined), to filter
  80  * the networks by whether they have persistent config or not.
  81  *
  82  * The third group of @flags is VIR_CONNECT_LIST_NETWORKS_AUTOSTART
  83  * and VIR_CONNECT_LIST_NETWORKS_NO_AUTOSTART, to filter the networks by
  84  * whether they are marked as autostart or not.
  85  *
  86  * Returns the number of networks found or -1 and sets @nets to  NULL in case
  87  * of error.  On success, the array stored into @nets is guaranteed to have an
  88  * extra allocated element set to NULL but not included in the return count,
  89  * to make iteration easier.  The caller is responsible for calling
  90  * virNetworkFree() on each array element, then calling free() on @nets.
  91  *
  92  * Since: 0.10.2
  93  */
  94 int
  95 virConnectListAllNetworks(virConnectPtr conn,
  96                           virNetworkPtr **nets,
  97                           unsigned int flags)
  98 {
  99     VIR_DEBUG("conn=%p, nets=%p, flags=0x%x", conn, nets, flags);
 100
 101     virResetLastError();
 102
 103     if (nets)
 104         *nets = NULL;
 105
 106     virCheckConnectReturn(conn, -1);
 107
 108     if (conn->networkDriver &&
 109         conn->networkDriver->connectListAllNetworks) {
 110         int ret;
 111         ret = conn->networkDriver->connectListAllNetworks(conn, nets, flags);
 112         if (ret < 0)
 113             goto error;
 114         return ret;
 115     }
 116
 117     virReportUnsupportedError();
 118
 119  error:
 120     virDispatchError(conn);
 121     return -1;
 122 }
 123
 124
 125 /**
 126  * virConnectNumOfNetworks:
 127  * @conn: pointer to the hypervisor connection
 128  *
 129  * Provides the number of active networks.
 130  *
 131  * Returns the number of network found or -1 in case of error
 132  *
 133  * Since: 0.2.0
 134  */
 135 int
 136 virConnectNumOfNetworks(virConnectPtr conn)
 137 {
 138     VIR_DEBUG("conn=%p", conn);
 139
 140     virResetLastError();
 141
 142     virCheckConnectReturn(conn, -1);
 143
 144     if (conn->networkDriver && conn->networkDriver->connectNumOfNetworks) {
 145         int ret;
 146         ret = conn->networkDriver->connectNumOfNetworks(conn);
 147         if (ret < 0)
 148             goto error;
 149         return ret;
 150     }
 151
 152     virReportUnsupportedError();
 153
 154  error:
 155     virDispatchError(conn);
 156     return -1;
 157 }
 158
 159
 160 /**
 161  * virConnectListNetworks:
 162  * @conn: pointer to the hypervisor connection
 163  * @names: array to collect the list of names of active networks
 164  * @maxnames: size of @names
 165  *
 166  * Collect the list of active networks, and store their names in @names
 167  *
 168  * The use of this function is discouraged. Instead, use
 169  * virConnectListAllNetworks().
 170  *
 171  * Returns the number of networks found or -1 in case of error.  Note that
 172  * this command is inherently racy; a network can be started between a call
 173  * to virConnectNumOfNetworks() and this call; you are only guaranteed that
 174  * all currently active networks were listed if the return is less than
 175  * @maxnames. The client must call free() on each returned name.
 176  *
 177  * Since: 0.2.0
 178  */
 179 int
 180 virConnectListNetworks(virConnectPtr conn, char **const names, int maxnames)
 181 {
 182     VIR_DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
 183
 184     virResetLastError();
 185
 186     virCheckConnectReturn(conn, -1);
 187     virCheckNonNullArrayArgGoto(names, maxnames, error);
 188     virCheckNonNegativeArgGoto(maxnames, error);
 189
 190     if (conn->networkDriver && conn->networkDriver->connectListNetworks) {
 191         int ret;
 192         ret = conn->networkDriver->connectListNetworks(conn, names, maxnames);
 193         if (ret < 0)
 194             goto error;
 195         return ret;
 196     }
 197
 198     virReportUnsupportedError();
 199
 200  error:
 201     virDispatchError(conn);
 202     return -1;
 203 }
 204
 205
 206 /**
 207  * virConnectNumOfDefinedNetworks:
 208  * @conn: pointer to the hypervisor connection
 209  *
 210  * Provides the number of inactive networks.
 211  *
 212  * Returns the number of networks found or -1 in case of error
 213  *
 214  * Since: 0.2.0
 215  */
 216 int
 217 virConnectNumOfDefinedNetworks(virConnectPtr conn)
 218 {
 219     VIR_DEBUG("conn=%p", conn);
 220
 221     virResetLastError();
 222
 223     virCheckConnectReturn(conn, -1);
 224
 225     if (conn->networkDriver && conn->networkDriver->connectNumOfDefinedNetworks) {
 226         int ret;
 227         ret = conn->networkDriver->connectNumOfDefinedNetworks(conn);
 228         if (ret < 0)
 229             goto error;
 230         return ret;
 231     }
 232
 233     virReportUnsupportedError();
 234
 235  error:
 236     virDispatchError(conn);
 237     return -1;
 238 }
 239
 240
 241 /**
 242  * virConnectListDefinedNetworks:
 243  * @conn: pointer to the hypervisor connection
 244  * @names: pointer to an array to store the names
 245  * @maxnames: size of the array
 246  *
 247  * list the inactive networks, stores the pointers to the names in @names
 248  *
 249  * The use of this function is discouraged. Instead, use
 250  * virConnectListAllNetworks().
 251  *
 252  * Returns the number of names provided in the array or -1 in case of error.
 253  * Note that this command is inherently racy; a network can be defined between
 254  * a call to virConnectNumOfDefinedNetworks() and this call; you are only
 255  * guaranteed that all currently defined networks were listed if the return
 256  * is less than @maxnames.  The client must call free() on each returned name.
 257  *
 258  * Since: 0.2.0
 259  */
 260 int
 261 virConnectListDefinedNetworks(virConnectPtr conn, char **const names,
 262                               int maxnames)
 263 {
 264     VIR_DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
 265
 266     virResetLastError();
 267
 268     virCheckConnectReturn(conn, -1);
 269     virCheckNonNullArrayArgGoto(names, maxnames, error);
 270     virCheckNonNegativeArgGoto(maxnames, error);
 271
 272     if (conn->networkDriver && conn->networkDriver->connectListDefinedNetworks) {
 273         int ret;
 274         ret = conn->networkDriver->connectListDefinedNetworks(conn, names, maxnames);
 275         if (ret < 0)
 276             goto error;
 277         return ret;
 278     }
 279
 280     virReportUnsupportedError();
 281
 282  error:
 283     virDispatchError(conn);
 284     return -1;
 285 }
 286
 287
 288 /**
 289  * virNetworkLookupByName:
 290  * @conn: pointer to the hypervisor connection
 291  * @name: name for the network
 292  *
 293  * Try to lookup a network on the given hypervisor based on its name.
 294  *
 295  * virNetworkFree should be used to free the resources after the
 296  * network object is no longer needed.
 297  *
 298  * Returns a new network object or NULL in case of failure.  If the
 299  * network cannot be found, then VIR_ERR_NO_NETWORK error is raised.
 300  *
 301  * Since: 0.2.0
 302  */
 303 virNetworkPtr
 304 virNetworkLookupByName(virConnectPtr conn, const char *name)
 305 {
 306     VIR_DEBUG("conn=%p, name=%s", conn, NULLSTR(name));
 307
 308     virResetLastError();
 309
 310     virCheckConnectReturn(conn, NULL);
 311     virCheckNonNullArgGoto(name, error);
 312
 313     if (conn->networkDriver && conn->networkDriver->networkLookupByName) {
 314         virNetworkPtr ret;
 315         ret = conn->networkDriver->networkLookupByName(conn, name);
 316         if (!ret)
 317             goto error;
 318         return ret;
 319     }
 320
 321     virReportUnsupportedError();
 322
 323  error:
 324     virDispatchError(conn);
 325     return NULL;
 326 }
 327
 328
 329 /**
 330  * virNetworkLookupByUUID:
 331  * @conn: pointer to the hypervisor connection
 332  * @uuid: the raw UUID for the network
 333  *
 334  * Try to lookup a network on the given hypervisor based on its UUID.
 335  *
 336  * virNetworkFree should be used to free the resources after the
 337  * network object is no longer needed.
 338  *
 339  * Returns a new network object or NULL in case of failure.  If the
 340  * network cannot be found, then VIR_ERR_NO_NETWORK error is raised.
 341  *
 342  * Since: 0.2.0
 343  */
 344 virNetworkPtr
 345 virNetworkLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
 346 {
 347     VIR_UUID_DEBUG(conn, uuid);
 348
 349     virResetLastError();
 350
 351     virCheckConnectReturn(conn, NULL);
 352     virCheckNonNullArgGoto(uuid, error);
 353
 354     if (conn->networkDriver && conn->networkDriver->networkLookupByUUID) {
 355         virNetworkPtr ret;
 356         ret = conn->networkDriver->networkLookupByUUID(conn, uuid);
 357         if (!ret)
 358             goto error;
 359         return ret;
 360     }
 361
 362     virReportUnsupportedError();
 363
 364  error:
 365     virDispatchError(conn);
 366     return NULL;
 367 }
 368
 369
 370 /**
 371  * virNetworkLookupByUUIDString:
 372  * @conn: pointer to the hypervisor connection
 373  * @uuidstr: the string UUID for the network
 374  *
 375  * Try to lookup a network on the given hypervisor based on its UUID.
 376  *
 377  * Returns a new network object or NULL in case of failure.  If the
 378  * network cannot be found, then VIR_ERR_NO_NETWORK error is raised.
 379  *
 380  * Since: 0.2.0
 381  */
 382 virNetworkPtr
 383 virNetworkLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
 384 {
 385     unsigned char uuid[VIR_UUID_BUFLEN];
 386     VIR_DEBUG("conn=%p, uuidstr=%s", conn, NULLSTR(uuidstr));
 387
 388     virResetLastError();
 389
 390     virCheckConnectReturn(conn, NULL);
 391     virCheckNonNullArgGoto(uuidstr, error);
 392
 393     if (virUUIDParse(uuidstr, uuid) < 0) {
 394         virReportInvalidArg(uuidstr,
 395                             _("uuidstr in %1$s must be a valid UUID"),
 396                             __FUNCTION__);
 397         goto error;
 398     }
 399
 400     return virNetworkLookupByUUID(conn, &uuid[0]);
 401
 402  error:
 403     virDispatchError(conn);
 404     return NULL;
 405 }
 406
 407
 408 /**
 409  * virNetworkCreateXML:
 410  * @conn: pointer to the hypervisor connection
 411  * @xmlDesc: an XML description of the network
 412  *
 413  * Create and start a new virtual network, based on an XML description
 414  * similar to the one returned by virNetworkGetXMLDesc()
 415  *
 416  * virNetworkFree should be used to free the resources after the
 417  * network object is no longer needed.
 418  *
 419  * Returns a new network object or NULL in case of failure
 420  *
 421  * Since: 0.2.0
 422  */
 423 virNetworkPtr
 424 virNetworkCreateXML(virConnectPtr conn, const char *xmlDesc)
 425 {
 426     VIR_DEBUG("conn=%p, xmlDesc=%s", conn, NULLSTR(xmlDesc));
 427
 428     virResetLastError();
 429
 430     virCheckConnectReturn(conn, NULL);
 431     virCheckNonNullArgGoto(xmlDesc, error);
 432     virCheckReadOnlyGoto(conn->flags, error);
 433
 434     if (conn->networkDriver && conn->networkDriver->networkCreateXML) {
 435         virNetworkPtr ret;
 436         ret = conn->networkDriver->networkCreateXML(conn, xmlDesc);
 437         if (!ret)
 438             goto error;
 439         return ret;
 440     }
 441
 442     virReportUnsupportedError();
 443
 444  error:
 445     virDispatchError(conn);
 446     return NULL;
 447 }
 448
 449
 450 /**
 451  * virNetworkCreateXMLFlags:
 452  * @conn: pointer to the hypervisor connection
 453  * @xmlDesc: an XML description of the network
 454  * @flags: bitwise-OR of virNetworkCreateFlags
 455  *
 456  * Create and start a new virtual network, based on an XML description
 457  * similar to the one returned by virNetworkGetXMLDesc()
 458  *
 459  * virNetworkFree should be used to free the resources after the
 460  * network object is no longer needed.
 461  *
 462  * Returns a new network object or NULL in case of failure
 463  *
 464  * Since: 7.8.0
 465  */
 466 virNetworkPtr
 467 virNetworkCreateXMLFlags(virConnectPtr conn, const char *xmlDesc, unsigned int flags)
 468 {
 469     VIR_DEBUG("conn=%p, xmlDesc=%s, flags=0x%x", conn, NULLSTR(xmlDesc), flags);
 470
 471     virResetLastError();
 472
 473     virCheckConnectReturn(conn, NULL);
 474     virCheckNonNullArgGoto(xmlDesc, error);
 475     virCheckReadOnlyGoto(conn->flags, error);
 476
 477     if (conn->networkDriver && conn->networkDriver->networkCreateXMLFlags) {
 478         virNetworkPtr ret;
 479         ret = conn->networkDriver->networkCreateXMLFlags(conn, xmlDesc, flags);
 480         if (!ret)
 481             goto error;
 482         return ret;
 483     }
 484
 485     virReportUnsupportedError();
 486
 487  error:
 488     virDispatchError(conn);
 489     return NULL;
 490 }
 491
 492
 493 /**
 494  * virNetworkDefineXML:
 495  * @conn: pointer to the hypervisor connection
 496  * @xml: the XML description for the network, preferably in UTF-8
 497  *
 498  * Define an inactive persistent virtual network or modify an existing
 499  * persistent one from the XML description.
 500  *
 501  * virNetworkFree should be used to free the resources after the
 502  * network object is no longer needed.
 503  *
 504  * Returns NULL in case of error, a pointer to the network otherwise
 505  *
 506  * Since: 0.2.0
 507  */
 508 virNetworkPtr
 509 virNetworkDefineXML(virConnectPtr conn, const char *xml)
 510 {
 511     VIR_DEBUG("conn=%p, xml=%s", conn, NULLSTR(xml));
 512
 513     virResetLastError();
 514
 515     virCheckConnectReturn(conn, NULL);
 516     virCheckReadOnlyGoto(conn->flags, error);
 517     virCheckNonNullArgGoto(xml, error);
 518
 519     if (conn->networkDriver && conn->networkDriver->networkDefineXML) {
 520         virNetworkPtr ret;
 521         ret = conn->networkDriver->networkDefineXML(conn, xml);
 522         if (!ret)
 523             goto error;
 524         return ret;
 525     }
 526
 527     virReportUnsupportedError();
 528
 529  error:
 530     virDispatchError(conn);
 531     return NULL;
 532 }
 533
 534
 535 /**
 536  * virNetworkDefineXMLFlags:
 537  * @conn: pointer to the hypervisor connection
 538  * @xml: the XML description for the network, preferably in UTF-8
 539  * @flags: bitwise-OR of virNetworkDefineFlags
 540  *
 541  * Define an inactive persistent virtual network or modify an existing
 542  * persistent one from the XML description.
 543  *
 544  * virNetworkFree should be used to free the resources after the
 545  * network object is no longer needed.
 546  *
 547  * Returns NULL in case of error, a pointer to the network otherwise
 548  *
 549  * Since: 7.7.0
 550  */
 551 virNetworkPtr
 552 virNetworkDefineXMLFlags(virConnectPtr conn, const char *xml, unsigned int flags)
 553 {
 554     VIR_DEBUG("conn=%p, xml=%s, flags=0x%x", conn, NULLSTR(xml), flags);
 555
 556     virResetLastError();
 557
 558     virCheckConnectReturn(conn, NULL);
 559     virCheckReadOnlyGoto(conn->flags, error);
 560     virCheckNonNullArgGoto(xml, error);
 561
 562     if (conn->networkDriver && conn->networkDriver->networkDefineXMLFlags) {
 563         virNetworkPtr ret;
 564         ret = conn->networkDriver->networkDefineXMLFlags(conn, xml, flags);
 565         if (!ret)
 566             goto error;
 567         return ret;
 568     }
 569
 570     virReportUnsupportedError();
 571
 572  error:
 573     virDispatchError(conn);
 574     return NULL;
 575 }
 576
 577
 578 /**
 579  * virNetworkUndefine:
 580  * @network: pointer to a defined network
 581  *
 582  * Undefine a network but does not stop it if it is running
 583  *
 584  * Returns 0 in case of success, -1 in case of error
 585  *
 586  * Since: 0.2.0
 587  */
 588 int
 589 virNetworkUndefine(virNetworkPtr network)
 590 {
 591     virConnectPtr conn;
 592     VIR_DEBUG("network=%p", network);
 593
 594     virResetLastError();
 595
 596     virCheckNetworkReturn(network, -1);
 597     conn = network->conn;
 598
 599     virCheckReadOnlyGoto(conn->flags, error);
 600
 601     if (conn->networkDriver && conn->networkDriver->networkUndefine) {
 602         int ret;
 603         ret = conn->networkDriver->networkUndefine(network);
 604         if (ret < 0)
 605             goto error;
 606         return ret;
 607     }
 608
 609     virReportUnsupportedError();
 610
 611  error:
 612     virDispatchError(network->conn);
 613     return -1;
 614 }
 615
 616
 617 /**
 618  * virNetworkUpdate:
 619  * @network: pointer to a defined network
 620  * @section: which section of the network to update
 621  *           (see virNetworkUpdateSection for descriptions)
 622  * @command: what action to perform (add/delete/modify)
 623  *           (see virNetworkUpdateCommand for descriptions)
 624  * @parentIndex: which parent element, if there are multiple parents
 625  *           of the same type (e.g. which <ip> element when modifying
 626  *           a <dhcp>/<host> element), or "-1" for "don't care" or
 627  *           "automatically find appropriate one".
 628  * @xml: the XML description for the network, preferably in UTF-8
 629  * @flags: bitwise OR of virNetworkUpdateFlags.
 630  *
 631  * Update the definition of an existing network, either its live
 632  * running state, its persistent configuration, or both.
 633  *
 634  * Returns 0 in case of success, -1 in case of error
 635  *
 636  * Since: 0.10.2
 637  */
 638 int
 639 virNetworkUpdate(virNetworkPtr network,
 640                  unsigned int command, /* virNetworkUpdateCommand */
 641                  unsigned int section, /* virNetworkUpdateSection */
 642                  int parentIndex,
 643                  const char *xml,
 644                  unsigned int flags)
 645 {
 646     virConnectPtr conn;
 647     VIR_DEBUG("network=%p, command=%d, section=%d, parentIndex=%d, xml=%s, flags=0x%x",
 648               network, command, section, parentIndex, xml, flags);
 649
 650     virResetLastError();
 651
 652     virCheckNetworkReturn(network, -1);
 653     conn = network->conn;
 654
 655     virCheckReadOnlyGoto(conn->flags, error);
 656     virCheckNonNullArgGoto(xml, error);
 657
 658     if (conn->networkDriver && conn->networkDriver->networkUpdate) {
 659         int ret;
 660         int rc;
 661
 662         /* Since its introduction in v0.10.2-rc1~9 the @section and @command
 663          * arguments were mistakenly swapped when passed to driver's callback.
 664          * Detect if the other side is fixed already or not. */
 665         rc = VIR_DRV_SUPPORTS_FEATURE(conn->driver, conn,
 666                                       VIR_DRV_FEATURE_NETWORK_UPDATE_HAS_CORRECT_ORDER);
 667
 668         VIR_DEBUG("Argument order feature detection returned: %d", rc);
 669         if (rc < 0)
 670             goto error;
 671
 672         if (rc == 0) {
 673             /* Feature not supported, preserve swapped order */
 674             ret = conn->networkDriver->networkUpdate(network, section, command,
 675                                                      parentIndex, xml, flags);
 676         } else {
 677             /* Feature supported, correct order can be used */
 678             ret = conn->networkDriver->networkUpdate(network, command, section,
 679                                                      parentIndex, xml, flags);
 680         }
 681
 682         if (ret < 0)
 683             goto error;
 684         return ret;
 685     }
 686
 687     virReportUnsupportedError();
 688
 689  error:
 690     virDispatchError(network->conn);
 691     return -1;
 692 }
 693
 694
 695 /**
 696  * virNetworkCreate:
 697  * @network: pointer to a defined network
 698  *
 699  * Create and start a defined network. If the call succeed the network
 700  * moves from the defined to the running networks pools.
 701  *
 702  * Returns 0 in case of success, -1 in case of error
 703  *
 704  * Since: 0.2.0
 705  */
 706 int
 707 virNetworkCreate(virNetworkPtr network)
 708 {
 709     virConnectPtr conn;
 710     VIR_DEBUG("network=%p", network);
 711
 712     virResetLastError();
 713
 714     virCheckNetworkReturn(network, -1);
 715     conn = network->conn;
 716
 717     virCheckReadOnlyGoto(conn->flags, error);
 718
 719     if (conn->networkDriver && conn->networkDriver->networkCreate) {
 720         int ret;
 721         ret = conn->networkDriver->networkCreate(network);
 722         if (ret < 0)
 723             goto error;
 724         return ret;
 725     }
 726
 727     virReportUnsupportedError();
 728
 729  error:
 730     virDispatchError(network->conn);
 731     return -1;
 732 }
 733
 734
 735 /**
 736  * virNetworkDestroy:
 737  * @network: a network object
 738  *
 739  * Destroy the network object. The running instance is shutdown if not down
 740  * already and all resources used by it are given back to the hypervisor. This
 741  * does not free the associated virNetworkPtr object.
 742  * This function may require privileged access
 743  *
 744  * Returns 0 in case of success and -1 in case of failure.
 745  *
 746  * Since: 0.2.0
 747  */
 748 int
 749 virNetworkDestroy(virNetworkPtr network)
 750 {
 751     virConnectPtr conn;
 752     VIR_DEBUG("network=%p", network);
 753
 754     virResetLastError();
 755
 756     virCheckNetworkReturn(network, -1);
 757     conn = network->conn;
 758
 759     virCheckReadOnlyGoto(conn->flags, error);
 760
 761     if (conn->networkDriver && conn->networkDriver->networkDestroy) {
 762         int ret;
 763         ret = conn->networkDriver->networkDestroy(network);
 764         if (ret < 0)
 765             goto error;
 766         return ret;
 767     }
 768
 769     virReportUnsupportedError();
 770
 771  error:
 772     virDispatchError(network->conn);
 773     return -1;
 774 }
 775
 776
 777 /**
 778  * virNetworkFree:
 779  * @network: a network object
 780  *
 781  * Free the network object. The running instance is kept alive.
 782  * The data structure is freed and should not be used thereafter.
 783  *
 784  * Returns 0 in case of success and -1 in case of failure.
 785  *
 786  * Since: 0.2.0
 787  */
 788 int
 789 virNetworkFree(virNetworkPtr network)
 790 {
 791     VIR_DEBUG("network=%p", network);
 792
 793     virResetLastError();
 794
 795     virCheckNetworkReturn(network, -1);
 796
 797     virObjectUnref(network);
 798     return 0;
 799 }
 800
 801
 802 /**
 803  * virNetworkRef:
 804  * @network: the network to hold a reference on
 805  *
 806  * Increment the reference count on the network. For each
 807  * additional call to this method, there shall be a corresponding
 808  * call to virNetworkFree to release the reference count, once
 809  * the caller no longer needs the reference to this object.
 810  *
 811  * This method is typically useful for applications where multiple
 812  * threads are using a connection, and it is required that the
 813  * connection remain open until all threads have finished using
 814  * it. ie, each new thread using a network would increment
 815  * the reference count.
 816  *
 817  * Returns 0 in case of success, -1 in case of failure.
 818  *
 819  * Since: 0.6.0
 820  */
 821 int
 822 virNetworkRef(virNetworkPtr network)
 823 {
 824     VIR_DEBUG("network=%p", network);
 825
 826     virResetLastError();
 827
 828     virCheckNetworkReturn(network, -1);
 829
 830     virObjectRef(network);
 831     return 0;
 832 }
 833
 834
 835 /**
 836  * virNetworkGetName:
 837  * @network: a network object
 838  *
 839  * Get the public name for that network
 840  *
 841  * Returns a pointer to the name or NULL, the string need not be deallocated
 842  * its lifetime will be the same as the network object.
 843  *
 844  * Since: 0.2.0
 845  */
 846 const char *
 847 virNetworkGetName(virNetworkPtr network)
 848 {
 849     VIR_DEBUG("network=%p", network);
 850
 851     virResetLastError();
 852
 853     virCheckNetworkReturn(network, NULL);
 854
 855     return network->name;
 856 }
 857
 858
 859 /**
 860  * virNetworkGetUUID:
 861  * @network: a network object
 862  * @uuid: pointer to a VIR_UUID_BUFLEN bytes array
 863  *
 864  * Get the UUID for a network
 865  *
 866  * Returns -1 in case of error, 0 in case of success
 867  *
 868  * Since: 0.2.0
 869  */
 870 int
 871 virNetworkGetUUID(virNetworkPtr network, unsigned char *uuid)
 872 {
 873     VIR_DEBUG("network=%p, uuid=%p", network, uuid);
 874
 875     virResetLastError();
 876
 877     virCheckNetworkReturn(network, -1);
 878     virCheckNonNullArgGoto(uuid, error);
 879
 880     memcpy(uuid, &network->uuid[0], VIR_UUID_BUFLEN);
 881
 882     return 0;
 883
 884  error:
 885     virDispatchError(network->conn);
 886     return -1;
 887 }
 888
 889
 890 /**
 891  * virNetworkGetUUIDString:
 892  * @network: a network object
 893  * @buf: pointer to a VIR_UUID_STRING_BUFLEN bytes array
 894  *
 895  * Get the UUID for a network as string. For more information about
 896  * UUID see RFC4122.
 897  *
 898  * Returns -1 in case of error, 0 in case of success
 899  *
 900  * Since: 0.2.0
 901  */
 902 int
 903 virNetworkGetUUIDString(virNetworkPtr network, char *buf)
 904 {
 905     VIR_DEBUG("network=%p, buf=%p", network, buf);
 906
 907     virResetLastError();
 908
 909     virCheckNetworkReturn(network, -1);
 910     virCheckNonNullArgGoto(buf, error);
 911
 912     virUUIDFormat(network->uuid, buf);
 913     return 0;
 914
 915  error:
 916     virDispatchError(network->conn);
 917     return -1;
 918 }
 919
 920
 921 /**
 922  * virNetworkGetXMLDesc:
 923  * @network: a network object
 924  * @flags: bitwise-OR of virNetworkXMLFlags
 925  *
 926  * Provide an XML description of the network. The description may be reused
 927  * later to relaunch the network with virNetworkCreateXML().
 928  *
 929  * Normally, if a network included a physical function, the output includes
 930  * all virtual functions tied to that physical interface.  If @flags includes
 931  * VIR_NETWORK_XML_INACTIVE, then the expansion of virtual interfaces is
 932  * not performed.
 933  *
 934  * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case
 935  * of error. The caller must free() the returned value.
 936  *
 937  * Since: 0.2.0
 938  */
 939 char *
 940 virNetworkGetXMLDesc(virNetworkPtr network, unsigned int flags)
 941 {
 942     virConnectPtr conn;
 943     VIR_DEBUG("network=%p, flags=0x%x", network, flags);
 944
 945     virResetLastError();
 946
 947     virCheckNetworkReturn(network, NULL);
 948     conn = network->conn;
 949
 950     if (conn->networkDriver && conn->networkDriver->networkGetXMLDesc) {
 951         char *ret;
 952         ret = conn->networkDriver->networkGetXMLDesc(network, flags);
 953         if (!ret)
 954             goto error;
 955         return ret;
 956     }
 957
 958     virReportUnsupportedError();
 959
 960  error:
 961     virDispatchError(network->conn);
 962     return NULL;
 963 }
 964
 965
 966 /**
 967  * virNetworkGetBridgeName:
 968  * @network: a network object
 969  *
 970  * Provides a bridge interface name to which a domain may connect
 971  * a network interface in order to join the network.
 972  *
 973  * Returns a 0 terminated interface name, or NULL in case of
 974  * error. The caller must free() the returned value.
 975  *
 976  * Since: 0.2.0
 977  */
 978 char *
 979 virNetworkGetBridgeName(virNetworkPtr network)
 980 {
 981     virConnectPtr conn;
 982     VIR_DEBUG("network=%p", network);
 983
 984     virResetLastError();
 985
 986     virCheckNetworkReturn(network, NULL);
 987     conn = network->conn;
 988
 989     if (conn->networkDriver && conn->networkDriver->networkGetBridgeName) {
 990         char *ret;
 991         ret = conn->networkDriver->networkGetBridgeName(network);
 992         if (!ret)
 993             goto error;
 994         return ret;
 995     }
 996
 997     virReportUnsupportedError();
 998
 999  error:
1000     virDispatchError(network->conn);
1001     return NULL;
1002 }
1003
1004
1005 /**
1006  * virNetworkGetAutostart:
1007  * @network: a network object
1008  * @autostart: the value returned
1009  *
1010  * Provides a boolean value indicating whether the network
1011  * configured to be automatically started when the host
1012  * machine boots.
1013  *
1014  * Returns -1 in case of error, 0 in case of success
1015  *
1016  * Since: 0.2.1
1017  */
1018 int
1019 virNetworkGetAutostart(virNetworkPtr network,
1020                        int *autostart)
1021 {
1022     virConnectPtr conn;
1023     VIR_DEBUG("network=%p, autostart=%p", network, autostart);
1024
1025     virResetLastError();
1026
1027     virCheckNetworkReturn(network, -1);
1028     virCheckNonNullArgGoto(autostart, error);
1029
1030     conn = network->conn;
1031
1032     if (conn->networkDriver && conn->networkDriver->networkGetAutostart) {
1033         int ret;
1034         ret = conn->networkDriver->networkGetAutostart(network, autostart);
1035         if (ret < 0)
1036             goto error;
1037         return ret;
1038     }
1039
1040     virReportUnsupportedError();
1041
1042  error:
1043     virDispatchError(network->conn);
1044     return -1;
1045 }
1046
1047
1048 /**
1049  * virNetworkSetAutostart:
1050  * @network: a network object
1051  * @autostart: whether the network should be automatically started 0 or 1
1052  *
1053  * Configure the network to be automatically started
1054  * when the host machine boots.
1055  *
1056  * Returns -1 in case of error, 0 in case of success
1057  *
1058  * Since: 0.2.1
1059  */
1060 int
1061 virNetworkSetAutostart(virNetworkPtr network,
1062                        int autostart)
1063 {
1064     virConnectPtr conn;
1065     VIR_DEBUG("network=%p, autostart=%d", network, autostart);
1066
1067     virResetLastError();
1068
1069     virCheckNetworkReturn(network, -1);
1070     conn = network->conn;
1071
1072     virCheckReadOnlyGoto(conn->flags, error);
1073
1074     if (conn->networkDriver && conn->networkDriver->networkSetAutostart) {
1075         int ret;
1076         ret = conn->networkDriver->networkSetAutostart(network, autostart);
1077         if (ret < 0)
1078             goto error;
1079         return ret;
1080     }
1081
1082     virReportUnsupportedError();
1083
1084  error:
1085     virDispatchError(network->conn);
1086     return -1;
1087 }
1088
1089
1090 /**
1091  * virNetworkIsActive:
1092  * @net: pointer to the network object
1093  *
1094  * Determine if the network is currently running
1095  *
1096  * Returns 1 if running, 0 if inactive, -1 on error
1097  *
1098  * Since: 0.7.3
1099  */
1100 int
1101 virNetworkIsActive(virNetworkPtr net)
1102 {
1103     VIR_DEBUG("net=%p", net);
1104
1105     virResetLastError();
1106
1107     virCheckNetworkReturn(net, -1);
1108
1109     if (net->conn->networkDriver->networkIsActive) {
1110         int ret;
1111         ret = net->conn->networkDriver->networkIsActive(net);
1112         if (ret < 0)
1113             goto error;
1114         return ret;
1115     }
1116
1117     virReportUnsupportedError();
1118  error:
1119     virDispatchError(net->conn);
1120     return -1;
1121 }
1122
1123
1124 /**
1125  * virNetworkIsPersistent:
1126  * @net: pointer to the network object
1127  *
1128  * Determine if the network has a persistent configuration
1129  * which means it will still exist after shutting down
1130  *
1131  * Returns 1 if persistent, 0 if transient, -1 on error
1132  *
1133  * Since: 0.7.3
1134  */
1135 int
1136 virNetworkIsPersistent(virNetworkPtr net)
1137 {
1138     VIR_DEBUG("net=%p", net);
1139
1140     virResetLastError();
1141
1142     virCheckNetworkReturn(net, -1);
1143
1144     if (net->conn->networkDriver->networkIsPersistent) {
1145         int ret;
1146         ret = net->conn->networkDriver->networkIsPersistent(net);
1147         if (ret < 0)
1148             goto error;
1149         return ret;
1150     }
1151
1152     virReportUnsupportedError();
1153  error:
1154     virDispatchError(net->conn);
1155     return -1;
1156 }
1157
1158
1159 /**
1160  * virConnectNetworkEventRegisterAny:
1161  * @conn: pointer to the connection
1162  * @net: pointer to the network
1163  * @eventID: the event type to receive
1164  * @cb: callback to the function handling network events
1165  * @opaque: opaque data to pass on to the callback
1166  * @freecb: optional function to deallocate opaque when not used anymore
1167  *
1168  * Adds a callback to receive notifications of arbitrary network events
1169  * occurring on a network.  This function requires that an event loop
1170  * has been previously registered with virEventRegisterImpl() or
1171  * virEventRegisterDefaultImpl().
1172  *
1173  * If @net is NULL, then events will be monitored for any network. If @net
1174  * is non-NULL, then only the specific network will be monitored.
1175  *
1176  * Most types of event have a callback providing a custom set of parameters
1177  * for the event. When registering an event, it is thus necessary to use
1178  * the VIR_NETWORK_EVENT_CALLBACK() macro to cast the supplied function pointer
1179  * to match the signature of this method.
1180  *
1181  * The virNetworkPtr object handle passed into the callback upon delivery
1182  * of an event is only valid for the duration of execution of the callback.
1183  * If the callback wishes to keep the network object after the callback
1184  * returns, it shall take a reference to it, by calling virNetworkRef().
1185  * The reference can be released once the object is no longer required
1186  * by calling virNetworkFree().
1187  *
1188  * The return value from this method is a positive integer identifier
1189  * for the callback. To unregister a callback, this callback ID should
1190  * be passed to the virConnectNetworkEventDeregisterAny() method.
1191  *
1192  * Returns a callback identifier on success, -1 on failure.
1193  *
1194  * Since: 1.2.1
1195  */
1196 int
1197 virConnectNetworkEventRegisterAny(virConnectPtr conn,
1198                                   virNetworkPtr net,
1199                                   int eventID,
1200                                   virConnectNetworkEventGenericCallback cb,
1201                                   void *opaque,
1202                                   virFreeCallback freecb)
1203 {
1204     VIR_DEBUG("conn=%p, eventID=%d, cb=%p, opaque=%p, freecb=%p",
1205               conn, eventID, cb, opaque, freecb);
1206
1207     virResetLastError();
1208
1209     virCheckConnectReturn(conn, -1);
1210     if (net) {
1211         virCheckNetworkGoto(net, error);
1212         if (net->conn != conn) {
1213             virReportInvalidArg(net,
1214                                 _("network '%1$s' in %2$s must match connection"),
1215                                 net->name, __FUNCTION__);
1216             goto error;
1217         }
1218     }
1219     virCheckNonNullArgGoto(cb, error);
1220     virCheckNonNegativeArgGoto(eventID, error);
1221
1222     if (eventID >= VIR_NETWORK_EVENT_ID_LAST) {
1223         virReportInvalidArg(eventID,
1224                             _("eventID in %1$s must be less than %2$d"),
1225                             __FUNCTION__, VIR_NETWORK_EVENT_ID_LAST);
1226         goto error;
1227     }
1228
1229     if (conn->networkDriver && conn->networkDriver->connectNetworkEventRegisterAny) {
1230         int ret;
1231         ret = conn->networkDriver->connectNetworkEventRegisterAny(conn, net,
1232                                                                   eventID,
1233                                                                   cb, opaque,
1234                                                                   freecb);
1235         if (ret < 0)
1236             goto error;
1237         return ret;
1238     }
1239
1240     virReportUnsupportedError();
1241  error:
1242     virDispatchError(conn);
1243     return -1;
1244 }
1245
1246
1247 /**
1248  * virConnectNetworkEventDeregisterAny:
1249  * @conn: pointer to the connection
1250  * @callbackID: the callback identifier
1251  *
1252  * Removes an event callback. The callbackID parameter should be the
1253  * value obtained from a previous virConnectNetworkEventRegisterAny() method.
1254  *
1255  * Returns 0 on success, -1 on failure
1256  *
1257  * Since: 1.2.1
1258  */
1259 int
1260 virConnectNetworkEventDeregisterAny(virConnectPtr conn,
1261                                     int callbackID)
1262 {
1263     VIR_DEBUG("conn=%p, callbackID=%d", conn, callbackID);
1264
1265     virResetLastError();
1266
1267     virCheckConnectReturn(conn, -1);
1268     virCheckNonNegativeArgGoto(callbackID, error);
1269
1270     if (conn->networkDriver &&
1271         conn->networkDriver->connectNetworkEventDeregisterAny) {
1272         int ret;
1273         ret = conn->networkDriver->connectNetworkEventDeregisterAny(conn,
1274                                                                     callbackID);
1275         if (ret < 0)
1276             goto error;
1277         return ret;
1278     }
1279
1280     virReportUnsupportedError();
1281  error:
1282     virDispatchError(conn);
1283     return -1;
1284 }
1285
1286
1287 /**
1288  * virNetworkGetDHCPLeases:
1289  * @network: Pointer to network object
1290  * @mac: Optional ASCII formatted MAC address of an interface
1291  * @leases: Pointer to a variable to store the array containing details on
1292  *          obtained leases, or NULL if the list is not required (just returns
1293  *          number of leases).
1294  * @flags: Extra flags, not used yet, so callers should always pass 0
1295  *
1296  * For DHCPv4, the information returned:
1297  * - Network Interface Name
1298  * - Expiry Time
1299  * - MAC address
1300  * - IAID (NULL)
1301  * - IPv4 address (with type and prefix)
1302  * - Hostname (can be NULL)
1303  * - Client ID (can be NULL)
1304  *
1305  * For DHCPv6, the information returned:
1306  * - Network Interface Name
1307  * - Expiry Time
1308  * - MAC address
1309  * - IAID (can be NULL, only in rare cases)
1310  * - IPv6 address (with type and prefix)
1311  * - Hostname (can be NULL)
1312  * - Client DUID
1313  *
1314  * Note: @mac, @iaid, @ipaddr, @clientid are in ASCII form, not raw bytes.
1315  * Note: @expirytime can 0, in case the lease is for infinite time.
1316  *
1317  * The API fetches leases info of guests in the specified network. If the
1318  * optional parameter @mac is specified, the returned list will contain only
1319  * lease info about a specific guest interface with @mac. There can be
1320  * multiple leases for a single @mac because this API supports DHCPv6 too.
1321  *
1322  * On success, the array stored into @leases is guaranteed to
1323  * have an extra allocated element set to NULL but not included in the return
1324  * count, to make iteration easier. The caller is responsible for calling
1325  * virNetworkDHCPLeaseFree() on each array element, then calling free() on @leases.
1326  *
1327  * See also virNetworkGetDHCPLeasesForMAC() as a convenience for filtering
1328  * the list to a single MAC address.
1329  *
1330  * Example of usage:
1331  *
1332  *   virNetworkDHCPLeasePtr *leases = NULL;
1333  *   virNetworkPtr network = ... obtain a network pointer here ...;
1334  *   size_t i;
1335  *   int nleases;
1336  *   unsigned int flags = 0;
1337  *
1338  *   nleases = virNetworkGetDHCPLeases(network, NULL, &leases, flags);
1339  *   if (nleases < 0)
1340  *       error();
1341  *
1342  *   ... do something with returned values, for example:
1343  *
1344  *   for (i = 0; i < nleases; i++) {
1345  *       virNetworkDHCPLeasePtr lease = leases[i];
1346  *
1347  *       printf("Time(epoch): %lu, MAC address: %s, "
1348  *              "IP address: %s, Hostname: %s, ClientID: %s\n",
1349  *              lease->expirytime, lease->mac, lease->ipaddr,
1350  *              lease->hostname, lease->clientid);
1351  *
1352  *              virNetworkDHCPLeaseFree(leases[i]);
1353  *   }
1354  *
1355  *   free(leases);
1356  *
1357  * Returns the number of leases found or -1 and sets @leases to NULL in
1358  * case of error.
1359  *
1360  * Since: 1.2.6
1361  */
1362 int
1363 virNetworkGetDHCPLeases(virNetworkPtr network,
1364                         const char *mac,
1365                         virNetworkDHCPLeasePtr **leases,
1366                         unsigned int flags)
1367 {
1368     virConnectPtr conn;
1369     VIR_DEBUG("network=%p, mac='%s' leases=%p, flags=0x%x",
1370                network, NULLSTR(mac), leases, flags);
1371
1372     virResetLastError();
1373
1374     if (leases)
1375         *leases = NULL;
1376
1377     virCheckNetworkReturn(network, -1);
1378
1379     conn = network->conn;
1380
1381     if (conn->networkDriver && conn->networkDriver->networkGetDHCPLeases) {
1382         int ret;
1383         ret = conn->networkDriver->networkGetDHCPLeases(network, mac, leases, flags);
1384         if (ret < 0)
1385             goto error;
1386         return ret;
1387     }
1388
1389     virReportUnsupportedError();
1390
1391  error:
1392     virDispatchError(network->conn);
1393     return -1;
1394 }
1395
1396
1397 /**
1398  * virNetworkDHCPLeaseFree:
1399  * @lease: pointer to a leases object
1400  *
1401  * Frees all the memory occupied by @lease.
1402  *
1403  * Since: 1.2.6
1404  */
1405 void
1406 virNetworkDHCPLeaseFree(virNetworkDHCPLeasePtr lease)
1407 {
1408     if (!lease)
1409         return;
1410     g_free(lease->iface);
1411     g_free(lease->mac);
1412     g_free(lease->iaid);
1413     g_free(lease->ipaddr);
1414     g_free(lease->hostname);
1415     g_free(lease->clientid);
1416     g_free(lease);
1417 }
1418
1419
1420 /**
1421  * virNetworkPortLookupByUUID:
1422  * @net: pointer to the network object
1423  * @uuid: the raw UUID for the network port
1424  *
1425  * Try to lookup a port on the given network based on its UUID.
1426  *
1427  * virNetworkPortFree should be used to free the resources after the
1428  * network port object is no longer needed.
1429  *
1430  * Returns a new network port object or NULL in case of failure.  If the
1431  * network port cannot be found, then VIR_ERR_NO_NETWORK_PORT error is raised.
1432  *
1433  * Since: 5.5.0
1434  */
1435 virNetworkPortPtr
1436 virNetworkPortLookupByUUID(virNetworkPtr net,
1437                            const unsigned char *uuid)
1438 {
1439     VIR_UUID_DEBUG(net, uuid);
1440
1441     virResetLastError();
1442
1443     virCheckNetworkReturn(net, NULL);
1444     virCheckNonNullArgGoto(uuid, error);
1445
1446     if (net->conn->networkDriver && net->conn->networkDriver->networkPortLookupByUUID) {
1447         virNetworkPortPtr ret;
1448         ret = net->conn->networkDriver->networkPortLookupByUUID(net, uuid);
1449         if (!ret)
1450             goto error;
1451         return ret;
1452     }
1453
1454     virReportUnsupportedError();
1455
1456  error:
1457     virDispatchError(net->conn);
1458     return NULL;
1459 }
1460
1461
1462 /**
1463  * virNetworkPortLookupByUUIDString:
1464  * @net: pointer to the network object
1465  * @uuidstr: the string UUID for the port
1466  *
1467  * Try to lookup a port on the given network based on its UUID.
1468  *
1469  * Returns a new network port object or NULL in case of failure.  If the
1470  * network port cannot be found, then VIR_ERR_NO_NETWORK_PORT error is raised.
1471  *
1472  * Since: 5.5.0
1473  */
1474 virNetworkPortPtr
1475 virNetworkPortLookupByUUIDString(virNetworkPtr net,
1476                                  const char *uuidstr)
1477 {
1478     unsigned char uuid[VIR_UUID_BUFLEN];
1479     VIR_DEBUG("net=%p, uuidstr=%s", net, NULLSTR(uuidstr));
1480
1481     virResetLastError();
1482
1483     virCheckNetworkReturn(net, NULL);
1484     virCheckNonNullArgGoto(uuidstr, error);
1485
1486     if (virUUIDParse(uuidstr, uuid) < 0) {
1487         virReportInvalidArg(uuidstr,
1488                             _("uuidstr in %1$s must be a valid UUID"),
1489                             __FUNCTION__);
1490         goto error;
1491     }
1492
1493     return virNetworkPortLookupByUUID(net, &uuid[0]);
1494
1495  error:
1496     virDispatchError(net->conn);
1497     return NULL;
1498 }
1499
1500
1501 /**
1502  * virNetworkPortSetParameters:
1503  * @port: a network port object
1504  * @params: pointer to interface parameter objects
1505  * @nparams: number of interface parameter (this value can be the same or
1506  *          less than the number of parameters supported)
1507  * @flags: currently unused, pass 0
1508  *
1509  * Change a subset or all parameters of the network port; currently this
1510  * includes bandwidth parameters.
1511  *
1512  * Returns -1 in case of error, 0 in case of success.
1513  *
1514  * Since: 5.5.0
1515  */
1516 int
1517 virNetworkPortSetParameters(virNetworkPortPtr port,
1518                             virTypedParameterPtr params,
1519                             int nparams,
1520                             unsigned int flags)
1521 {
1522     virConnectPtr conn;
1523     VIR_DEBUG("port=%p, params=%p, nparams=%d, flags=0x%x", port, params, nparams, flags);
1524     VIR_TYPED_PARAMS_DEBUG(params, nparams);
1525
1526     virResetLastError();
1527
1528     virCheckNetworkPortReturn(port, -1);
1529     conn = port->net->conn;
1530
1531     virCheckReadOnlyGoto(conn->flags, error);
1532
1533     if (conn->networkDriver && conn->networkDriver->networkPortSetParameters) {
1534         int ret;
1535         ret = conn->networkDriver->networkPortSetParameters(port, params, nparams, flags);
1536         if (ret < 0)
1537             goto error;
1538         return ret;
1539     }
1540
1541     virReportUnsupportedError();
1542
1543  error:
1544     virDispatchError(conn);
1545     return -1;
1546 }
1547
1548
1549 /**
1550  * virNetworkPortGetParameters:
1551  * @port: a network port object
1552  * @params: pointer to pointer of interface parameter objects
1553  * @nparams: pointer to received number of interface parameter
1554  * @flags: currently unused, pass 0
1555  *
1556  * Get all interface parameters. On input, @params should be initialized
1557  * to NULL. On return @params will be allocated with the size large
1558  * enough to hold all parameters, and @nparams will be updated to say
1559  * how many parameters are present. @params should be freed by the caller
1560  * on success.
1561  *
1562  * Returns -1 in case of error, 0 in case of success.
1563  *
1564  * Since: 5.5.0
1565  */
1566 int
1567 virNetworkPortGetParameters(virNetworkPortPtr port,
1568                             virTypedParameterPtr *params,
1569                             int *nparams,
1570                             unsigned int flags)
1571 {
1572     virConnectPtr conn;
1573     VIR_DEBUG("port=%p, params=%p, nparams=%p, flags=0x%x", port, params, nparams, flags);
1574
1575     virResetLastError();
1576
1577     virCheckNetworkPortReturn(port, -1);
1578     conn = port->net->conn;
1579
1580     virCheckNonNullArgGoto(nparams, error);
1581     virCheckNonNegativeArgGoto(*nparams, error);
1582
1583     if (conn->networkDriver && conn->networkDriver->networkPortGetParameters) {
1584         int ret;
1585         ret = conn->networkDriver->networkPortGetParameters(port, params, nparams, flags);
1586         if (ret < 0)
1587             goto error;
1588         return ret;
1589     }
1590
1591     virReportUnsupportedError();
1592
1593  error:
1594     virDispatchError(conn);
1595     return -1;
1596 }
1597
1598
1599 /**
1600  * virNetworkPortCreateXML:
1601  * @net: pointer to the network object
1602  * @xmldesc: an XML description of the port
1603  * @flags: bitwise-OR of virNetworkPortCreateFlags
1604  *
1605  * Create a new network port, based on an XML description
1606  * similar to the one returned by virNetworkPortGetXMLDesc()
1607  *
1608  * virNetworkPortFree should be used to free the resources after the
1609  * network port object is no longer needed.
1610  *
1611  * Returns a new network port object or NULL in case of failure
1612  *
1613  * Since: 5.5.0
1614  */
1615 virNetworkPortPtr
1616 virNetworkPortCreateXML(virNetworkPtr net,
1617                         const char *xmldesc,
1618                         unsigned int flags)
1619 {
1620     VIR_DEBUG("net=%p, xmldesc=%s, flags=0x%x", net, NULLSTR(xmldesc), flags);
1621
1622     virResetLastError();
1623
1624     virCheckNetworkReturn(net, NULL);
1625     virCheckNonNullArgGoto(xmldesc, error);
1626     virCheckReadOnlyGoto(net->conn->flags, error);
1627
1628     if (net->conn->networkDriver && net->conn->networkDriver->networkPortCreateXML) {
1629         virNetworkPortPtr ret;
1630         ret = net->conn->networkDriver->networkPortCreateXML(net, xmldesc, flags);
1631         if (!ret)
1632             goto error;
1633         return ret;
1634     }
1635
1636     virReportUnsupportedError();
1637
1638  error:
1639     virDispatchError(net->conn);
1640     return NULL;
1641 }
1642
1643 /**
1644  * virNetworkPortGetNetwork:
1645  * @port: pointer to a network port
1646  *
1647  * Provides the network pointer associated with a port.  The
1648  * reference counter on the connection is not increased by this
1649  * call.
1650  *
1651  * Returns the virNetworkPtr or NULL in case of failure.
1652  *
1653  * Since: 5.5.0
1654  */
1655 virNetworkPtr
1656 virNetworkPortGetNetwork(virNetworkPortPtr port)
1657 {
1658     VIR_DEBUG("port=%p", port);
1659
1660     virResetLastError();
1661
1662     virCheckNetworkPortReturn(port, NULL);
1663
1664     return port->net;
1665 }
1666
1667
1668 /**
1669  * virNetworkPortGetXMLDesc:
1670  * @port: a network port object
1671  * @flags: currently unused, pass 0
1672  *
1673  * Provide an XML description of the network port. The description may be reused
1674  * later to recreate the port with virNetworkPortCreateXML().
1675  *
1676  * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
1677  *         the caller must free() the returned value.
1678  *
1679  * Since: 5.5.0
1680  */
1681 char *
1682 virNetworkPortGetXMLDesc(virNetworkPortPtr port,
1683                          unsigned int flags)
1684 {
1685     virConnectPtr conn;
1686     VIR_DEBUG("port=%p, flags=0x%x", port, flags);
1687
1688     virResetLastError();
1689
1690     virCheckNetworkPortReturn(port, NULL);
1691     conn = port->net->conn;
1692
1693     if (conn->networkDriver && conn->networkDriver->networkPortGetXMLDesc) {
1694         char *ret;
1695         ret = conn->networkDriver->networkPortGetXMLDesc(port, flags);
1696         if (!ret)
1697             goto error;
1698         return ret;
1699     }
1700
1701     virReportUnsupportedError();
1702
1703  error:
1704     virDispatchError(conn);
1705     return NULL;
1706 }
1707
1708
1709 /**
1710  * virNetworkPortGetUUID:
1711  * @port: a network port object
1712  * @uuid: pointer to a VIR_UUID_BUFLEN bytes array
1713  *
1714  * Get the UUID for a network port
1715  *
1716  * Returns -1 in case of error, 0 in case of success
1717  *
1718  * Since: 5.5.0
1719  */
1720 int
1721 virNetworkPortGetUUID(virNetworkPortPtr port,
1722                       unsigned char *uuid)
1723 {
1724     VIR_DEBUG("port=%p, uuid=%p", port, uuid);
1725
1726     virResetLastError();
1727
1728     virCheckNetworkPortReturn(port, -1);
1729     virCheckNonNullArgGoto(uuid, error);
1730
1731     memcpy(uuid, &port->uuid[0], VIR_UUID_BUFLEN);
1732
1733     return 0;
1734
1735  error:
1736     virDispatchError(port->net->conn);
1737     return -1;
1738 }
1739
1740
1741 /**
1742  * virNetworkPortGetUUIDString:
1743  * @port: a network port object
1744  * @buf: pointer to a VIR_UUID_STRING_BUFLEN bytes array
1745  *
1746  * Get the UUID for a network as string. For more information about
1747  * UUID see RFC4122.
1748  *
1749  * Returns -1 in case of error, 0 in case of success
1750  *
1751  * Since: 5.5.0
1752  */
1753 int
1754 virNetworkPortGetUUIDString(virNetworkPortPtr port,
1755                             char *buf)
1756 {
1757     VIR_DEBUG("port=%p, buf=%p", port, buf);
1758
1759     virResetLastError();
1760
1761     virCheckNetworkPortReturn(port, -1);
1762     virCheckNonNullArgGoto(buf, error);
1763
1764     virUUIDFormat(port->uuid, buf);
1765     return 0;
1766
1767  error:
1768     virDispatchError(port->net->conn);
1769     return -1;
1770 }
1771
1772 /**
1773  * virNetworkPortDelete:
1774  * @port: a port object
1775  * @flags: currently unused, pass 0
1776  *
1777  * Delete the network port. This does not free the
1778  * associated virNetworkPortPtr object. It is the
1779  * caller's responsibility to ensure the port is not
1780  * still in use by a virtual machine before deleting
1781  * port.
1782  *
1783  * Returns 0 in case of success and -1 in case of failure.
1784  *
1785  * Since: 5.5.0
1786  */
1787 int
1788 virNetworkPortDelete(virNetworkPortPtr port,
1789                      unsigned int flags)
1790 {
1791     virConnectPtr conn;
1792     VIR_DEBUG("port=%p, flags=0x%x", port, flags);
1793
1794     virResetLastError();
1795
1796     virCheckNetworkPortReturn(port, -1);
1797     conn = port->net->conn;
1798
1799     virCheckReadOnlyGoto(conn->flags, error);
1800
1801     if (conn->networkDriver && conn->networkDriver->networkPortDelete) {
1802         int ret;
1803         ret = conn->networkDriver->networkPortDelete(port, flags);
1804         if (ret < 0)
1805             goto error;
1806         return ret;
1807     }
1808
1809     virReportUnsupportedError();
1810
1811  error:
1812     virDispatchError(conn);
1813     return -1;
1814 }
1815
1816
1817 /**
1818  * virNetworkListAllPorts:
1819  * @network: pointer to a network object
1820  * @ports: Pointer to a variable to store the array containing network port
1821  *        objects or NULL if the list is not required (just returns number
1822  *        of ports).
1823  * @flags: extra flags; not used yet, so callers should always pass 0
1824  *
1825  * Collect the list of network ports, and allocate an array to store those
1826  * objects.
1827  *
1828  * Returns the number of network ports found or -1 and sets @ports to
1829  * NULL in case of error.  On success, the array stored into @ports is
1830  * guaranteed to have an extra allocated element set to NULL but not included
1831  * in the return count, to make iteration easier.  The caller is responsible
1832  * for calling virNetworkPortFree() on each array element, then calling
1833  * free() on @ports.
1834  *
1835  * Since: 5.5.0
1836  */
1837 int
1838 virNetworkListAllPorts(virNetworkPtr network,
1839                        virNetworkPortPtr **ports,
1840                        unsigned int flags)
1841 {
1842     VIR_DEBUG("network=%p, ports=%p, flags=0x%x", network, ports, flags);
1843
1844     virResetLastError();
1845
1846     virCheckNetworkReturn(network, -1);
1847
1848     if (network->conn->networkDriver &&
1849         network->conn->networkDriver->networkListAllPorts) {
1850         int ret;
1851         ret = network->conn->networkDriver->networkListAllPorts(network, ports, flags);
1852         if (ret < 0)
1853             goto error;
1854         return ret;
1855     }
1856
1857     virReportUnsupportedError();
1858
1859  error:
1860     virDispatchError(network->conn);
1861     return -1;
1862 }
1863
1864
1865 /**
1866  * virNetworkPortFree:
1867  * @port: a network port object
1868  *
1869  * Free the network port object.
1870  * The data structure is freed and should not be used thereafter.
1871  *
1872  * Returns 0 in case of success and -1 in case of failure.
1873  *
1874  * Since: 5.5.0
1875  */
1876 int
1877 virNetworkPortFree(virNetworkPortPtr port)
1878 {
1879     VIR_DEBUG("port=%p", port);
1880
1881     virResetLastError();
1882
1883     virCheckNetworkPortReturn(port, -1);
1884
1885     virObjectUnref(port);
1886     return 0;
1887 }
1888
1889
1890 /**
1891  * virNetworkPortRef:
1892  * @port: a network port object
1893  *
1894  * Increment the reference count on the network port. For each
1895  * additional call to this method, there shall be a corresponding
1896  * call to virNetworkPortFree to release the reference count, once
1897  * the caller no longer needs the reference to this object.
1898  *
1899  * This method is typically useful for applications where multiple
1900  * threads are using a network port, and it is required that the
1901  * port remain resident until all threads have finished using
1902  * it. ie, each new thread using a network port would increment
1903  * the reference count.
1904  *
1905  * Returns 0 in case of success, -1 in case of failure.
1906  *
1907  * Since: 5.5.0
1908  */
1909 int
1910 virNetworkPortRef(virNetworkPortPtr port)
1911 {
1912     VIR_DEBUG("port=%p", port);
1913
1914     virResetLastError();
1915
1916     virCheckNetworkPortReturn(port, -1);
1917
1918     virObjectRef(port);
1919     return 0;
1920 }
1921
1922
1923 /**
1924  * virNetworkSetMetadata:
1925  * @network: a network object
1926  * @type: type of metadata, from virNetworkMetadataType
1927  * @metadata: new metadata text
1928  * @key: XML namespace key, or NULL
1929  * @uri: XML namespace URI, or NULL
1930  * @flags: bitwise-OR of virNetworkUpdateFlags
1931  *
1932  * Sets the appropriate network element given by @type to the
1933  * value of @metadata.  A @type of VIR_NETWORK_METADATA_DESCRIPTION
1934  * is free-form text; VIR_NETWORK_METADATA_TITLE is free-form, but no
1935  * newlines are permitted, and should be short (although the length is
1936  * not enforced). For these two options @key and @uri are irrelevant and
1937  * must be set to NULL.
1938  *
1939  * For type VIR_NETWORK_METADATA_ELEMENT @metadata must be well-formed
1940  * XML belonging to namespace defined by @uri with local name @key.
1941  *
1942  * Passing NULL for @metadata says to remove that element from the
1943  * network XML (passing the empty string leaves the element present).
1944  *
1945  * The resulting metadata will be present in virNetworkGetXMLDesc(),
1946  * as well as quick access through virNetworkGetMetadata().
1947  *
1948  * @flags controls whether the live network state, persistent configuration,
1949  * or both will be modified.
1950  *
1951  * Returns 0 on success, -1 in case of failure.
1952  *
1953  * Since: 9.7.0
1954  */
1955 int
1956 virNetworkSetMetadata(virNetworkPtr network,
1957                       int type,
1958                       const char *metadata,
1959                       const char *key,
1960                       const char *uri,
1961                       unsigned int flags)
1962 {
1963     virConnectPtr conn;
1964
1965     VIR_DEBUG("network=%p, type=%d, metadata='%s', key='%s', uri='%s', flags=0x%x",
1966               network, type, NULLSTR(metadata), NULLSTR(key), NULLSTR(uri),
1967               flags);
1968
1969     virResetLastError();
1970
1971     virCheckNetworkReturn(network, -1);
1972     conn = network->conn;
1973
1974     virCheckReadOnlyGoto(conn->flags, error);
1975
1976     switch (type) {
1977     case VIR_NETWORK_METADATA_TITLE:
1978         if (metadata && strchr(metadata, '\n')) {
1979             virReportInvalidArg(metadata, "%s",
1980                                 _("metadata title can't contain newlines"));
1981             goto error;
1982         }
1983         G_GNUC_FALLTHROUGH;
1984     case VIR_NETWORK_METADATA_DESCRIPTION:
1985         virCheckNullArgGoto(uri, error);
1986         virCheckNullArgGoto(key, error);
1987         break;
1988     case VIR_NETWORK_METADATA_ELEMENT:
1989         virCheckNonNullArgGoto(uri, error);
1990         if (metadata)
1991             virCheckNonNullArgGoto(key, error);
1992         break;
1993     default:
1994         /* For future expansion */
1995         break;
1996     }
1997
1998     if (conn->networkDriver->networkSetMetadata) {
1999         int ret;
2000         ret = conn->networkDriver->networkSetMetadata(network, type, metadata, key, uri,
2001                                                       flags);
2002         if (ret < 0)
2003             goto error;
2004         return ret;
2005     }
2006
2007     virReportUnsupportedError();
2008
2009  error:
2010     virDispatchError(network->conn);
2011     return -1;
2012 }
2013
2014
2015 /**
2016  * virNetworkGetMetadata:
2017  * @network: a network object
2018  * @type: type of metadata, from virNetworkMetadataType
2019  * @uri: XML namespace identifier
2020  * @flags: bitwise-OR of virNetworkUpdateFlags
2021  *
2022  * Retrieves the appropriate network element given by @type.
2023  * If VIR_NETWORK_METADATA_ELEMENT is requested parameter @uri
2024  * must be set to the name of the namespace the requested elements
2025  * belong to, otherwise must be NULL.
2026  *
2027  * If an element of the network XML is not present, the resulting
2028  * error will be VIR_ERR_NO_NETWORK_METADATA.  This method forms
2029  * a shortcut for seeing information from virNetworkSetMetadata()
2030  * without having to go through virNetworkGetXMLDesc().
2031  *
2032  * @flags controls whether the live network state or persistent
2033  * configuration will be queried.
2034  *
2035  * Returns the metadata string on success (caller must free),
2036  * or NULL in case of failure.
2037  *
2038  * Since: 9.7.0
2039  */
2040 char *
2041 virNetworkGetMetadata(virNetworkPtr network,
2042                       int type,
2043                       const char *uri,
2044                       unsigned int flags)
2045 {
2046     virConnectPtr conn;
2047
2048     VIR_DEBUG("network=%p, type=%d, uri='%s', flags=0x%x",
2049                network, type, NULLSTR(uri), flags);
2050
2051     virResetLastError();
2052
2053     virCheckNetworkReturn(network, NULL);
2054
2055     VIR_EXCLUSIVE_FLAGS_GOTO(VIR_NETWORK_UPDATE_AFFECT_LIVE,
2056                              VIR_NETWORK_UPDATE_AFFECT_CONFIG,
2057                              error);
2058
2059     switch (type) {
2060     case VIR_NETWORK_METADATA_TITLE:
2061     case VIR_NETWORK_METADATA_DESCRIPTION:
2062         virCheckNullArgGoto(uri, error);
2063         break;
2064     case VIR_NETWORK_METADATA_ELEMENT:
2065         virCheckNonNullArgGoto(uri, error);
2066         break;
2067     default:
2068         /* For future expansion */
2069         break;
2070     }
2071
2072     conn = network->conn;
2073
2074     if (conn->networkDriver->networkGetMetadata) {
2075         char *ret;
2076         if (!(ret = conn->networkDriver->networkGetMetadata(network, type, uri, flags)))
2077             goto error;
2078         return ret;
2079     }
2080
2081     virReportUnsupportedError();
2082
2083  error:
2084     virDispatchError(network->conn);
2085     return NULL;
2086 }