first cut of hal service description file

[Havoc Pennington]

On Thu, 2005-03-31 at 00:17 -0500, David Zeuthen wrote:
>  - I couldn't find how to describe what signals to emit so I just
>    assumed <signal> was the way to go; does this make sense?

Yes, that sounds good. The example in the spec has:
    <signal name="Changed">
              <arg name="new_value" type="boolean"/>
            </signal>

>  - Exceptions; since we're going to generate client side code for
>    languages/runtimes that support exceptions we need a way to annotate
>    what exceptions a method can throw; e.g. in pseudo-code
> 
>      using namespace org::freedesktop::Hal;
> 
>      class Device {
>        void Lock() throws NoSuchDevice, PermissionDenied,
>                           DeviceAlreadyLocked;
>      };

I'm unconvinced we want this:

 - Only one language of interest actually has the throws in the method 
   signature (Java).

 - because of that, reflection-based bindings (generating introspection
   data from the language introspection features) will never get the 
   throws info right.

 - all D-BUS methods can throw exceptions, because IPC is involved.
 
 - You can get security and other exceptions from the bus itself, and I 
   want to be able to add more of those over time, and exceptions   
   specific to particular transports (e.g. if you tunneled over X11 
   protocol, you might have associated exceptions). So at the very 
   least, bindings should always have a "DBusException" that 
   would be used for all these errors from the bus so it doesn't change
   method signatures if we add new errors.

 - Real-life code almost always special-cases one or two specific 
   exceptions, then has a fallback case for "any other exception"

 - Because most languages don't enforce type safety here, I really 
   doubt the exception info in manually-maintained introspection
   files will ever be accurate.

 - this is just plain complicated and doesn't add corresponding value.

>    I just added comments about what hald can throw at you today.

This is the right approach I think.

>  - As noted for objects implementing the org.freedesktop.Hal.Device
>    interface, there is no way to know a'priori what objects these are
>    except perhaps that they reside in a certain name space. 

The object path should only be in the XML format when it's being used to
introspect live objects probably. If you're using this as "IDL" then it
doesn't need object paths. I don't think we're ready to use it as IDL
yet other than as a way to write specs - we haven't defined where to
install files or anything of that nature.

>    Any chance we can have some kind of proxy manager so it becomes
>    even easier to write client code? Ideally, I'd like to be able
>    to just pass the object_path to the generated function...

I think there's some historical discussion of this pretty far back in
the archives. I don't remember any details of it though and I could be
wrong.

Off the cuff, I wouldn't do a proxy manager for this; the main purpose
of the proxy is just to save typing in the interface/path/etc. over and
over and have an object to connect signal handlers to. But if you're
only invoking one function, and the interface/path/etc. are hardcoded in
that function, the proxy serves no purpose. Just generate code like:

 void generated_function (const char *path, int arg1) {
  call_method ("my.bus.Name", "my.Interface", path, DBUS_TYPE_INT32,
arg1, DBUS_TYPE_INVALID);
}

>  - Where am I supposed to ship the hald.xml (and should it be named
>    hald.xml) at all? 

Not defined at all yet.

>    - do we expect certain languages/runtimes to load the hald.xml
>      file at runtime to generate proxies on the fly? (Java, Mono
>      comes to mind). If yes, we need to ship it with the runtime
>      package (hal.rpm)

IMO generating proxies on the fly should be done by calling Introspect()
on the remote object, rather than by loading files.

>    - do we expect certain languages/runtimes to consume the hald.xml
>      file at build time? (glib comes mind)

Well it's sort of necessary for C/C++, unless we make people just use
varargs (which is not IMO totally crazy, but I understand people may
find it annoying). Personally in my apps I think I'd tend to just use
varargs and the proxy object directly but I find it hard to explain why
that "feels right" to me.

>    I suppose the answer to these questions are both yes.

I think it's no to the first, yes to the second. In other words I'd put
the xml files in -devel

We should most likely call them something other than .xml also... some
extension specific to what they are.

One of the general themes I'm getting to here is that I think the .xml
files should be optional; if you want to just write a cheesy app in
python without any "IDL" file then you should be able to do that. You'll
make life a little annoying for C programmers, but if someone complains
the IDL can be added later.

>  - To deploy the hal service in a message bus scenario, I still need to
>    write a policy file; would be crack to generate this from the service
>    description file using annotations?

You mean from the "IDL" file or the .service file?

I'm not sure I see how to do this generically, but a simple custom
script to do it for HAL makes plenty of sense. This would be one of the
benefits of using XML for the IDL file (you can easily write your script
in whatever language)

>  - I've used the term 'service description file' throughout this email
>    as I wasn't really sure what it's called :-) - we probably need a
>    glossary before 1.0 (if we don't have one already).

There is one at the end of the spec, just extend it ;-)

Havoc