[libvirt] [PATCH 10/13] Add support for an explicit RTC change event

[Daniel P. Berrange]

On Mon, Mar 22, 2010 at 05:17:42PM +0100, Daniel Veillard wrote:
> On Fri, Mar 19, 2010 at 03:38:58PM +0000, Daniel P. Berrange wrote:
> > This introduces a new event type
> > 
> >    VIR_DOMAIN_EVENT_ID_RTC_CHANGE
> > 
> > This event includes the new UTC offset measured in seconds.
> > Thus there is a new callback definition for this event type
> > 
> >  typedef void (*virConnectDomainEventRTCChangeCallback)(virConnectPtr conn,
> >                                                         virDomainPtr dom,
> >                                                         long long utcoffset,
> >                                                         void *opaque);
> > 
> > If the guest XML configuration for the <clock> is set to
> > offset='variable', then the XML will automatically be
> > updated with the new UTC offset value. This ensures that
> > during migration/save/restore the new offset is preserved.
> > 
> > * daemon/remote.c: Dispatch RTC change events to client
> > * examples/domain-events/events-c/event-test.c: Watch for
> >   RTC change events
> > * include/libvirt/libvirt.h.in: Define new RTC change event ID
> >   and callback signature
> > * src/conf/domain_event.c, src/conf/domain_event.h,
> >   src/libvirt_private.syms: Extend API to handle RTC change events
> > * src/qemu/qemu_driver.c: Connect to the QEMU monitor event
> >   for RTC changes and emit a libvirt RTC change event
> > * src/remote/remote_driver.c: Receive and dispatch RTC change
> >   events to application
> > * src/remote/remote_protocol.x: Wire protocol definition for
> >   RTC change events
> > * src/qemu/qemu_monitor.c, src/qemu/qemu_monitor.h,
> >   src/qemu/qemu_monitor_json.c: Watch for RTC_CHANGE event
> >   from QEMU monitor
> 
>   Okay, in taht case we need to add a new event handler,
> 
> [...]
> > --- a/include/libvirt/libvirt.h.in
> > +++ b/include/libvirt/libvirt.h.in
> > @@ -1842,6 +1842,10 @@ int virDomainAbortJob(virDomainPtr dom);
> >  typedef void (*virConnectDomainEventGenericCallback)(virConnectPtr conn,
> >                                                       virDomainPtr dom,
> >                                                       void *opaque);
> 
> > +typedef void (*virConnectDomainEventRTCChangeCallback)(virConnectPtr conn,
> > +                                                       virDomainPtr dom,
> > +                                                       long long utcoffset,
> > +                                                       void *opaque);
> 
>   I think the time unit of the offset should be documented there, and
> maybe a bit of explanation people may get confused and expect the offset
> to be relative to the previous offset instead of absolute

Where should we put API docs for typedef's like this ?  If I add the
magic /** style comments in the header, will the docs generator pick
them up, or should I put them in the libvirt.c file instead ?

Daniel
-- 
|: Red Hat, Engineering, London    -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org -o- http://virt-manager.org -o- http://deltacloud.org :|
|: http://autobuild.org        -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-   F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|