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

[Daniel P. Berrange]

On Wed, Oct 31, 2007 at 10:03:01AM -0400, Daniel Veillard wrote:
> On Mon, Oct 29, 2007 at 03:57:01AM +0000, Daniel P. Berrange wrote:
> > for the storage APIs. 
> > +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 ?

This is akin to the  virDomainInfoPtr object - its just a struct containing
some basic status metadata. The main handle to the thing is virStoragePoolPtr
which is an opaque handle.

> > +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,

Same here - cf  virDomainInfoPtr.

> > +int                     virStoragePoolShutdown(virStoragePoolPtr pool);
> > +int			virStoragePoolDestroy	(virStoragePoolPtr pool);
> > +int			virStoragePoolFree	(virStoragePoolPtr pool);
> 
>   Hum, I really wonder about the precise semantic for those 3 operations

To be honest I've not 100% finalized, but current thoughts are:

    - virStoragePoolShutdown() de-activate the pool - eg logout of iSCSI server,
                               or unmount the disk, etc
    - virStoragePoolDestroy()  the same, but also free's the virStoragePoolPtr object
                               cf virDomainDestroy, vs virDomainShutdown
    - virStoragePoolFree       just free the virStoragePoolPtr.

I think we might want a way to remove all trace of a pool, eg

    - virStoragePoolDelete()   trash the data, eg rm -rf the directory, or remove
                               the LVM volume group, or blow away the partition table



If it were not for the historical precent of the virDomainXXXX apis, I'd be
calling this last one, virStoragePoolDestroy, but I don't want to overload
'Destory' already has defined semantics in thec context of a domain which is
that its equivalent to a forced  Shutdown + Free.  So i figure it best to
pick  virStoragePoolDelete  instead.


> > + */
> > +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.

Yep, you can only really on 'name' being consistent for as long as a storage
pool is active. It may come up with a different name next time.

For long term persistent naming, I think we need some form of unique key
which is an opaque  char *, comprised of whatever 'unique' metadata we
can pull out of the underlying physical storage - cf the mail 0/7 which
discussed 'open issues'

>   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.

The XML is basically following the style I posted in the last of my
messages in the 'Storage concepts' thread.

I'll be making some changes as suggested by Rich to make things more optional
so will post a revised XML description next time.

Dan.
-- 
|=- Red Hat, Engineering, Emerging Technologies, Boston.  +1 978 392 2496 -=|
|=-           Perl modules: http://search.cpan.org/~danberr/              -=|
|=-               Projects: http://freshmeat.net/~danielpb/               -=|
|=-  GnuPG: 7D3B9505   F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505  -=|