On Mon, Oct 29, 2007 at 03:57:01AM +0000, Daniel P. Berrange wrote:
This patch adds a public header file defining the application facing contract for the storage APIs.
+/* -*- c -*- + * storage.h: + * Summary: storage management interfaces + * Description: Provides the interfaces of the libvirt library to handle + * storage management from a process running in the host + * + * Copy: Copyright (C) 2005-2007 Red Hat, Inc. + * + * See COPYING.LIB for the License of this software + * + * Author: Daniel Veillard <veillard@redhat.com>
Need to fix the author I guess :-)
+ */ + + + +#ifndef __VIR_VIRLIB_H__ +#error "Do not include storage.h directly. Use libvirt.h instead" +#endif
That would be one reason against the split, if you can't reference files individually I don't think we can export them as an API...
+#ifndef __VIR_VIRLIB_STORAGE_H__ +#define __VIR_VIRLIB_STORAGE_H__ + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * virStoragePool: + * + * a virStoragePool is a private structure representing a storage pool + */ +typedef struct _virStoragePool virStoragePool; + +/** + * virStoragePoolPtr: + * + * a virStoragePoolPtr is pointer to a virStoragePool private structure, this is the + * type used to reference a storage pool in the API. + */ +typedef virStoragePool *virStoragePoolPtr; + + +typedef enum { + VIR_STORAGE_POOL_INACTIVE = 0, + VIR_STORAGE_POOL_ACTIVE = 1, +} virStoragePoolState; + +typedef struct _virStoragePoolInfo virStoragePoolInfo; + +struct _virStoragePoolInfo { + int state; /* virStoragePoolState flags */ + unsigned long long capacity; /* Logical size bytes */ + unsigned long long allocation; /* Current allocation bytes */ +};
There is no name available ? Once you got a pointer to that structure, how do you expose its capability to the user ?
+typedef virStoragePoolInfo *virStoragePoolInfoPtr; + + +/** + * virStorageVol: + * + * a virStorageVol is a private structure representing a storage volume + */ +typedef struct _virStorageVol virStorageVol; + +/** + * virStorageVolPtr: + * + * a virStorageVolPtr is pointer to a virStorageVol private structure, this is the + * type used to reference a storage volume in the API. + */ +typedef virStorageVol *virStorageVolPtr; + + +typedef enum { + VIR_STORAGE_POOL_FILE = 0, + VIR_STORAGE_POOL_BLOCK = 1, +} virStoragePoolType; + +typedef struct _virStorageVolInfo virStorageVolInfo; + +struct _virStorageVolInfo { + int type; /* virStoragePoolType flags */ + unsigned long long capacity; /* Logical size bytes */ + unsigned long long allocation; /* Current allocation bytes */ +};
Same thing, I feel it lacks some external naming in the structure,
+typedef virStorageVolInfo *virStorageVolInfoPtr; + +/* + * Get connection from pool. + */ +virConnectPtr virStoragePoolGetConnect (virStoragePoolPtr pool); + +/* + * List active storage pools + */ +int virConnectNumOfStoragePools (virConnectPtr conn); +int virConnectListStoragePools (virConnectPtr conn, + char **const names, + int maxnames); + +/* + * List inactive storage pools + */ +int virConnectNumOfDefinedStoragePools(virConnectPtr conn); +int virConnectListDefinedStoragePools(virConnectPtr conn, + char **const names, + int maxnames); + +/* + * Lookup network by name or uuid + */ +virStoragePoolPtr virStoragePoolLookupByName(virConnectPtr conn, + const char *name); +virStoragePoolPtr virStoragePoolLookupByUUID(virConnectPtr conn, + const unsigned char *uuid); +virStoragePoolPtr virStoragePoolLookupByUUIDString(virConnectPtr conn, + const char *uuid); + +/* + * Create active transient storage pool + */ +virStoragePoolPtr virStoragePoolCreateXML(virConnectPtr conn, + const char *xmlDesc); + +/* + * Define inactive persistent storage pool + */ +virStoragePoolPtr virStoragePoolDefineXML(virConnectPtr conn, + const char *xmlDesc); + +/* + * Delete persistent storage pool + */ +int virStoragePoolUndefine(virStoragePoolPtr pool); + +/* + * Activate persistent pool + */ +int virStoragePoolCreate(virStoragePoolPtr pool); + +/* + * StoragePool destroy/free + */ +int virStoragePoolShutdown(virStoragePoolPtr pool); +int virStoragePoolDestroy (virStoragePoolPtr pool); +int virStoragePoolFree (virStoragePoolPtr pool);
Hum, I really wonder about the precise semantic for those 3 operations
+/* + * StoragePool information + */ +const char* virStoragePoolGetName (virStoragePoolPtr pool); +int virStoragePoolGetUUID (virStoragePoolPtr pool, + unsigned char *uuid); +int virStoragePoolGetUUIDString(virStoragePoolPtr pool, + char *buf); + +int virStoragePoolGetInfo(virStoragePoolPtr vol, + virStoragePoolInfoPtr info); + +char * virStoragePoolGetXMLDesc(virStoragePoolPtr pool, + int flags); + +int virStoragePoolGetAutostart(virStoragePoolPtr pool, + int *autostart); +int virStoragePoolSetAutostart(virStoragePoolPtr pool, + int autostart); + + + +/* + * List storage volumes within a pool + */ +int virStoragePoolNumOfVolumes(virStoragePoolPtr pool); +int virStoragePoolListVolumes (virStoragePoolPtr pool, + char **const names, + int maxnames); + +/* + * Lookup network by name or uuid
s/network/storage/ :-)
+ */ +virStorageVolPtr virStorageVolLookupByName(virStoragePoolPtr pool, + const char *name); +virStorageVolPtr virStorageVolLookupByUUID(virStoragePoolPtr pool, + const unsigned char *uuid); +virStorageVolPtr virStorageVolLookupByUUIDString(virStoragePoolPtr pool, + const char *uuid); + +const char* virStorageVolGetName (virStorageVolPtr vol);
so there is a public name, keep it in the structure, you can't garantee the storage will have exactly the name the user expect, aliasing is frequent in storage I think.
+int virStorageVolGetUUID (virStorageVolPtr vol, + unsigned char *uuid); +int virStorageVolGetUUIDString(virStorageVolPtr vol, + char *buf); + + +virStorageVolPtr virStorageVolCreateXML(virStoragePoolPtr pool, + const char *xmldesc, + int flags); + +int virStorageVolDestroy(virStorageVolPtr vol); +int virStorageVolFree(virStorageVolPtr vol); + +int virStorageVolGetInfo(virStorageVolPtr vol, + virStorageVolInfoPtr info); +char * virStorageVolGetXMLDesc(virStorageVolPtr pool, + int flags); + +char * virStorageVolGetPath(virStorageVolPtr vol); + +#ifdef __cplusplus +}
The API being derived from existing APIs they of course looks rather sane to me, but the XML formats is also part of the APIs not described here. Daniel -- Red Hat Virtualization group http://redhat.com/virtualization/ Daniel Veillard | virtualization library http://libvirt.org/ veillard@redhat.com | libxml GNOME XML XSLT toolkit http://xmlsoft.org/ http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/