[avahi] Some notes on designing the Avahi DBUS API

[Lennart Poettering]

Hi!

(Sebastien, I am CC'ing this to you, since you seem to be interested
in working on the DBUS stuff, too.)

Just some quick notes on which avahi-core API functions should be
exported over DBUS and which should not:

There are a bunch of functions which may be used to add low-level RRs
to the server. While they are useful when writing applications that
link directly against avahi-core, I doubt that it makes sense to
export them via DBUS to application developers. This would only
complicate things and induce abuse.

Those functions are:
   avahi_server_add()
   avahi_server_add_ptr()
   avahi_server_add_txt()
   avahi_server_add_txt_va()
   avahi_server_add_txt_strlst()
   avahi_server_add_dns_server_address()
   avahi_server_add_dns_server_name()

On the other hand, the useful functions of style avahi_server_add_xxx() are:
   avahi_server_add_address()
        (though this may be ommited, since noone should use this
        anyway. For local addresses the avahi stack is much better in
        registering addresses, and registering remote addresses is a
        bad idea. The Apple API supports this function nonetheless, so
        we should do so as well)

   avahi_server_add_service()
   avahi_server_add_service_va()
   avahi_server_add_service_strlst()
        These functions are essentially the same, just with different
        arguments, only one should be really used.

On the browsing side, the following functions should be hidden from
the user:
   avahi_record_browser_new()
   avahi_dns_server_browser_new()

The useful functions are:
   avahi_host_name_resolver_new()
   avahi_address_resolver_new()
   avahi_domain_browser_new()
   avahi_service_type_browser_new()
   avahi_service_browser()
   avahi_service_resolver()

The avahi_entry_group_xxx stuff must be available to the client, it is very
important for multi-protocol software. And it's the only way to be
notified of conflicts of user generated RRs.

The following functions should NOT be available to the clients:

    avahi_server_{new,free}()
    avahi_server_dump()
    avahi_server_iterate()
    avahi_server_{get,set}_data()
    avahi_server_set_{host,domain}_name()
    avahi_server_config_xxx()
    
Though avahi_server_new() shouldn't be exported to the clients (there
should be only one instance of this thing which is maintained by the
daemon anyway) the events that are dispatched by the callback
function attached to a server object should be forwarded to the
clients, (probably in terms of "DBUS signals").

The following functions are useful to clients and should be exported:

    avahi_server_get_{host_name,domain_name, host_name_fqdn}()

And that's it.    
   
If we limit the DBUS API to these functions there should be no need to
have rr.h available on the client side. The strlst stuff (which I have
recently documented in doxygen) is probably easily mapped to a DBUS
array of strings, so the should no real need for this on the client
side as well (though it makes some sense to have it, simply because it
makes construction of TXT data easy). To ease the use of DBUS
withouht libavahi-client it might make sense to pass IP addresses as
formatted ascii strings. (its easy to parse this on the server side
using avahi_address_parse())

So I'd suggest the following C-to-DBUS type mappings:

   AvahiAddress => STRING
   AvahiIfIndex => INT32
   AvahiProtocol => UINT8

All other mappings should be trivial.

I hope these notes help you to get the DBUS stuff quickly into a
usable state. 

BTW: Do you know a tool which i can easily use to get a list of
available DBUS services on the system?

I made a bunch of smaller changes to the current SVN to match the
updated RFC. Due to this the core might be a bit unstable now. The
avahi-core API has changed a bit too, so be warned... My TODO list for
bringing avahi up to the level of the new RFC just contains 4 points
now (from originally 12).

Lennart

-- 
name { Lennart Poettering } loc { Hamburg - Germany }
mail { mzft (at) 0pointer (dot) de } gpg { 1A015CC4 }  
www { http://0pointer.de/lennart/ } icq# { 11060553 }
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.freedesktop.org/archives/avahi/attachments/20050624/803d4db3/attachment.pgp