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@xxxxxxxxxx>
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@xxxxxxxxxx | libxml GNOME XML XSLT toolkit http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/
--
Libvir-list mailing list
Libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list