On Fri, Sep 07, 2007 at 06:52:21PM +0200, T?th Istv?n wrote:
Hello!
I am currently working on java bindings for libvirt, and in the process I have found a few bugs with the documentation, and also what I believe to be a design problem in the API.
1. The parameterized C macros do not have their arguments listed either on libvirt.org, or in the docs folder in the distribution list, even though there is a a documentation block in the actual source file. I guess it's some kind of problem with the tool used for generating the docs.
Sounds like its a bug - will let Daniel debug that one.
2. The virConnectGetCapabilities function docs says that it returns an opaque pointer to a struct, when in fact it returns an XML string describing the capabilities.
Yes, that's a bug in the docs from previous iteration of the patches for that API. Will remove it.
3. I have found no sanctioned way to actually get the data from DomainBlockStats and DomainInterfaceStats. The strucures are defined as _virDomainBlockStats and struct _virDomainInterfaceStats, and there is only an *Ptr type typedef-ed on them, as in the case of, say virConnectPtr, which IS really meant to be opaque.
Well the struct definition is in the header file - you don't need a typedef to be able to access the fields.
I believe that the fields of these structs ARE meant to be read by the applications linking the library, and are not really meant to be opaque. (or if they are, they should have some functions/macros that you can access their contents with)
Yes, anything you see in libvirt.h is fair game for applications to use. Private stuff is simply not installed into /usr/include
I think the right way to fix this would be simply to typedef them as typedef struct _virDomainBlockStats virDomainBlockStats; typedef struct _virDomainInterfaceStats DomainInterfaceStats;
For the sake of consistency with other structs, yes we should add these typedefs - they're not required for sake of accessing the fields in the struct though. 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 -=|