(轉)libvirt 部分API 介紹

標籤：ram   mem   family   ast   dea   註冊   一段   const   blog   

感謝朋友支援本部落格，歡迎共同探討交流，由於能力和時間有限，錯誤之處在所難免，歡迎指正！
如果轉載，請保留作者資訊。
部落格地址：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 介紹