libvirt 部分API 介紹

標籤：.net   version   相關資訊   環境   memory   能力   duration   rate   stream   

感謝朋友支援本部落格。歡迎共同探討交流，因為能力和時間有限，錯誤之處在所難免，歡迎指正！

假設轉載，請保留作者資訊。

部落格地址：http://blog.csdn.net/qq_21398167

原博文地址：http://blog.csdn.net/qq_21398167/article/details/46422583

http://libvirt.org/html/index.html  官網包括全部的api
API 概述

進階 libvirt API 可劃分為 5 個 API 部分：Hypervisor串連 API、域 API、網路功能 API、儲存卷 API 以及儲存池 API。

為給定Hypervisor建立串連後會產生全部 libvirt 通訊（比如，清單 6 中所看到的的 open 調用）。該串連為全部其它要使用的 API 提供路徑。在 C API 中，該行為通過 virConnectOpen 調用（以及其它進行認證的調用）提供。這些函數的傳回值是一個 virConnectPtr 對象，它代表到Hypervisor的一個串連。該對象作為全部其它管理功能的基礎，是對給定Hypervisor進行並發 API 呼叫所必需的語句。重要的並發調用是 virConnectGetCapabilities 和 virNodeGetInfo。前者返回Hypervisor和驅動程式的功能，後者擷取有關節點的資訊。

該資訊以 XML 文檔的形式返回，這樣通過解析便可瞭解可能發生的行為。

進入Hypervisor後，便能夠使用一組 API 呼叫函數反覆使用該Hypervisor上的各種資源。virConnectListDomains API 呼叫函數返回一列域標識符，它們代表該Hypervisor上的活動域。

API 實現大量針對域的函數。要探究或管理域。首先須要一個 virDomainPtr 對象。您可通過多種方式獲得該控制代碼（使用 ID、UUID 或網域名稱）。繼續來看反覆域的範例，您能夠使用該函數返回的索引表並調用 virDomainLookupByID 來擷取域控制代碼。

有了該域控制代碼，就能夠運行非常多操作，從探究域（virDomainGetUUID、virDomainGetInfo、virDomainGetXMLDesc、virDomainMemoryPeek）到控制域（virDomainCreate、virDomainSuspend、virDomainResume、virDomainDestroy 和 virDomainMigrate）。

您還可使用 API 管理並檢查虛擬網路和儲存資源。建立了 API 模型之後。須要一個 virNetworkPtr 對象來管理並檢查虛擬網路，且須要一個 virStoragePoolPtr（儲存池）或 virStorageVolPtr（卷）對象來管理這些資源。

API 還支援一種事件機制。您可使用該機制注冊為在特定事件（比方域的啟動、中止、恢複或停止）發生時獲得通知。

（1）串連 Hypervisor 相關的API：以virConnect 開頭的一系列函數。

僅僅有與 Hypervisor 建立了串連之後，才幹進行虛擬機器管理操作，所以串連 Hypervisor 的API是其它全部API使用的前提條件。與 Hypervisor 建立的串連是為其它API的運行提供了路徑，是其它虛擬化管理功能的基礎。

virConnectOpen    函數能夠建立一個串連。其傳回值是一個virConnectPtr 對象，該對象就代表到Hypervisor 的一個串連；假設串連出錯，則返回空值（NULL）。
virConnectOpenReadOnly   函數會建立一個僅僅讀的串連。在該串連上能夠使用一些查詢的功能，而不使用建立、改動等功能。
virConnectOpenAuth  函數提供了更具認證建立的串連。
virConnectGetCapabilities 函數是返回對 Hypervisor 和驅動的功能的描寫敘述的 XML 格式的字串。virConnectListDomains     函數返回一列域標識符，它們代表該 Hypervisor 上的活動域。
virConnectGetHostname
virConnectGetMaxVcpus
virConnectGetType
virConnectGetVersion
virConnectGetLibVersion
virConnectGetURI
virConnectIsEncrypted
virConnectIsSecure
virConnectClose       關閉串連

（2）域管理的 API：以virDomain 開頭的一系列函數。

虛擬機器的管理，最主要的職能就是對各個節點上的域的管理，故 libvirt API 中實現了非常多針對域管理的函數。

要管理域，首先就要擷取virDomainPtr 這個域對象。然後才幹對域進行操作。有非常多種方式來擷取域對象，如 virDomainPtr

virDomainLookupByID (virConnectPtr conn, int id) 函數是依據域的 id 值到 conn 這個串連上去尋找對應的域。。virDomainLookupByName、virDomainLookupByUUID 等函數各自是依據域的名稱和 UUID 去尋找對應的域。

在得到了某個域的對象後，就能夠進行非常多的操作。能夠是查詢域的資訊
virDomainGetHostname
virDomainGetInfo
virDomainGetVcpus
virDomainGetVcpusFlags
virDomainGetCPUStats
也能夠是控制域的生命週期。如：
virDomainCreate
virDomainSuspend
virDomainResume
virDomainDestroy
virDomainMigrate
建立虛擬機器
virDomainDefineXML()
virFileReadAll()    該函數原型為intvirFileReadAll(const char *path, int maxlen, char **buf)。功能是將參數“path”指定路徑的檔案內容讀到一個緩衝區中。並將緩衝區地址記錄在參數“*buf”中。而參數“maxlen”指定檔案的最大長度。利用該API。我們能夠將xml設定檔都到一個緩衝區中。以方便接下來的使用

virDomainCreateXML()  該函數原型為virDomainPtr    virDomainCreateXML      (virConnectPtrconn,  const char * xmlDesc,  unsigned int flags)，功能是依據參數“xmlDesc”定義的配置方式建立一個域並返回該域的指標。參數“conn”是指向虛擬機器管理器的指標。而通過設定不同的“flags”標誌。能夠使建立的域具有不同的屬性。

（3）節點管理的 API：以virNode 開頭的一系列函數。
域是執行在物理節點之上，libvirt也提供了對節點的資訊查詢和控制的功能。節點管理的多數函數都須要使用一個串連 Hypervisor 的對象作為當中的一個傳入參數，以便能夠查詢或改動到該串連上的節點的資訊。

virNodeGetInfo函數是擷取節點的物理硬體資訊，http://my.oschina.net/u/274153/blog/55011
virNodeGetCPUStats 函數能夠擷取節點上各個 CPU 的使用統計資訊
virNodeGetMemoryStats 函數能夠擷取節點上的記憶體的使用統計資訊
virNodeGetFreeMemory 函數能夠擷取節點上可用的空暇記憶體大小。

也有一些設定或者控制節點的函數virNodeSetMemoryParameters 函數能夠設定節點上的記憶體調度的參數
virNodeSuspendForDuration 函數能夠讓節點（宿主機）暫停執行一段時間
virNodeGetCellsFreeMemory

（4）網路管理的 API：以 virNetwork 開頭的一系列函數和部分以 virInterface 開頭的函數。
libvirt 對虛擬化環境中的網路管理也提供了豐富的API。libvirt 首先須要建立virNetworkPtr 對象，然後才幹查詢或控制虛擬網路。一些查詢網路相關資訊的函數。如：

virNetworkGetName(virNetworkPtr network) 函數能夠擷取網路的名稱
 network: a network object
 Returns: a pointer to the name or NULL, the string need not be deallocated its lifetime will be the same    as the network object.

virNetworkGetBridgeName 函數能夠擷取該網路中橋接器的名稱
virNetworkGetUUID 函數能夠擷取網路的 UUID 標識
virNetworkGetXMLDesc 函數能夠擷取網路的以 XML 格式的描寫敘述資訊
virNetworkIsActive 函數能夠查詢網路是否正在使用中。一些控制或更改網路設定的函數，有：
int virNetworkCreate  (virNetworkPtr network) 獲得network屬性

virNetworkCreateXML(virConnectPtr conn,const char * xmlDesc) 函數能夠依據提供的 XML 格式的字串建立一個網路（返 回 virNetworkPtr 對象）
 conn: pointer to the hypervisor connection
 xmlDesc: an XML description of the network
 Returns: a new network object or NULL in case of failure
virDomainInterfacePtr
virNetworkDestroy 函數能夠銷毀一個網路（同一時候也會關閉使用該網路的域）
virNetworkFree 函數能夠回收一個網路（但不會關閉正在執行的域）
virNetworkUpdate 函數可依據提供的 XML 格式的網路設定來更新一個已存在的網路。

另外，
virInterfaceCreate、
virInterfaceFree、
virInterfaceDestroy、
virInterfaceGetName、
virInterfaceIsActive 等函數能夠用於建立、釋放和銷毀網路介面，以及查詢網路介面的名稱和啟用狀態。

（5）儲存卷管理的 API：以 virStorageVol 開頭的一系列函數。

libvirt 對儲存卷（volume）的管理。主要是對域的鏡像檔案的管理，這些鏡像檔案可能是 raw、qcow2、vmdk、qed等各種格式。libvirt 對儲存卷的管理，首先須要建立virStorageVolPtr 這個儲存卷的對象。然後才幹對其進行查詢或控制操作。libvirt 提供了3個函數來分別通過不同的方式來擷取儲存卷對象。如：
virStorageVolLookupByKey 函數能夠依據全域唯一的索引值來獲得一個儲存卷對象
virStorageVolLookupByName 函數能夠依據名稱在一個儲存資源集區（storage pool）中擷取一個儲存卷對象virStorageVolLookupByPath 函數能夠依據它在節點上路徑來擷取一個儲存卷對象。有一些函數用於查詢儲存卷的資訊，如：virStorageVolGetInfo 函數能夠查詢某個儲存卷的使用方式
virStorageVolGetName 函數能夠擷取儲存卷的名稱
virStorageVolGetPath 函數能夠擷取儲存卷的路徑
virStorageVolGetConnect 函數能夠查詢儲存卷的串連。一些函數用於建立和改動儲存卷。如：
virStorageVolCreateXML 函數能夠依據提供的 XML 描寫敘述來建立一個儲存卷
virStorageVolFree 函數能夠釋放儲存卷的控制代碼（可是儲存卷依舊存在）
virStorageVolDelete 函數能夠刪除一個儲存卷，virStorageVolResize 函數能夠調整儲存卷的大小。

（6）儲存池管理的 API：以virStoragePool 開頭的一系列函數。

libvirt 對儲存池（pool）的管理，包含對本地的基本檔案系統、普通網際網路共用檔案系統、iSCSI共用檔案系統、LVM分區等的管理。

libvirt 須要基於 virStoragePoolPtr 這個儲存池對象才幹進行查詢和控制操作。一些函數能夠通過查詢擷取一個儲存池對象。如：
virStoragePoolLookupByName 函數能夠依據儲存池的名稱來擷取一個儲存池對象
virStoragePoolLookupByVolume 能夠依據一個儲存卷返回其相應的儲存池對象
virStoragePoolCreateXML 函數能夠依據 XML 描寫敘述來建立一個儲存池（預設已啟用）
virStoragePoolDefineXML 函數能夠依據 XML 描寫敘述資訊靜態地定義個儲存池（尚未啟用）
virStoragePoolCreate 函數能夠啟用一個儲存池。
virStoragePoolGetInfo、
virStoragePoolGetName、
virStoragePoolGetUUID等函數能夠分別擷取儲存池的資訊、名稱和 UUID 標識。
virStoragePoolIsActive函數能夠查詢儲存池是否處於使用中狀態。

virStoragePoolFree 函數能夠釋放儲存池相關的記憶體（可是不改變其在宿主機中的狀態）
virStoragePoolDestroy 函數能夠用於銷毀一個儲存池（但並沒有釋放virStoragePoolPtr 對象，之後還能夠用virStoragePoolCreate 函數又一次啟用它）。
virStoragePoolDelete 函數能夠物理刪除一個儲存池資源（該操作不可恢複）。

（7）事件管理的API：以virEvent 開頭的一系列函數。

libvirt 支援事件機制，使用該機制注冊之後，能夠在發生特定的事件（如：域的啟動、暫停、恢複、停止等）之時，得到自訂的一些通知。

（8）資料流管理的API：以virStream 開頭的一系列函數。

libvirt 還提供了一系列函數用於資料流的傳輸。
 
（9）Error handing
virSetErrorFunc
virConnSetErrorFunc
virCopyLastError
virGetLastError
virSaveLastError
virResetError
virFreeError
virConnResetError
virConnCopyLastError
virConnGetLastError

virDomainMigrate   虛擬機器移轉
virDomainReboot 虛擬機器重新啟動
int virDomainRef   (virDomainPtr domain)
int virDomainReset   (virDomainPtr domain,
      unsigned int flags)
int virDomainRestore  (virConnectPtr conn,
      const char * from)
int virDomainRestoreFlags  (virConnectPtr conn,
      const char * from,
      const char * dxml,

libvirt 部分API 介紹