[Libvir] PATCH: 2/7 public API header files

[Daniel Veillard]

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 at 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 at redhat.com  | libxml GNOME XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine  http://rpmfind.net/