[avahi] Re: Some notes on designing the Avahi DBUS API

[Sebastien Estienne]

Hi!
Just a short mail to let you know, that i'm working on small cli tool
(equivalent of mdnspublish, mdnsbrowse) for the moment i'm using the
simple protocol , and then i'll rewrite them using dbus.

I'm doing for 3 main reasons:
1) being familiar and testing the code and api.
2) they could be usefull for debugging/testing purpose.
3) making this the base of a tutorial on using avahi, so other
developpers have a working example of using avahi for basic and most
common needs namely publishing and browsing.

So i've the project to write some kind of tutorial on using avahi with :
-simple protocol
-dbus api using glib
-and maybe some reference client in python,qt, c-sharp (any language
that have dbus bindings)

So our helloworld would be mdns publish and browse.
I'm doing this because i think a good example is always the best
starting point on using a technology. And also because i want
avahi/zeroconf to be widely used by other softwares.

I wanted to let you know about this to not duplicate effort on this
topic and have your opinions/ideas/recommendations on the subject.

on a side note, with us we could even have the tutorial available in 3
languages namely english, german and  french.

regards,

2005/6/24, Lennart Poettering <mzzhgg at 0pointer.de>:
> 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 }
> 
> 
> BodyID:142460486.2.n.logpart (stored separately)
> 
> 


-- 
Sebastien Estienne