Some comments on the PolicyKit API

[Matthias Clasen]

Some comments from reading over the PK API docs:


PolicyKit Library
-------------------

- I already mentioned that we had discussed making the result abstract,
otherwise you always have to extend the public enum when you add e.g.
POLKIT_RESULT_ONLY_VIA_WHEEL_GROUP_AUTH.

- If you don't make it abstract, you should probably at least add
warnings that the enum may grow.

- Also, should this include some hints how to handle the denied
results, by calling a suitable function in some other library ?

- Didn't we decide that POLKIT_RESULT_NOT_AUTHORIZED_TO_KNOW was crack ?

- polkit_result_to_string_representation(): Should probably point out if
the "string representation" is suitable for ui display or suitable for
serialization, or what the purpose is.

- PolicyKitContext:
"This class is used to represent the interface to PolicyKit." - this
could, umm, be expanded a bit... not immediately clear what this means.
All PK-using applications need to create and keep such a context ?
Can you just recreate it every time, or do you need to call it ?
Does it make sense to have multiple contexts in the same application ?

- Seen in PolKitContextConfigChangedCB docs: "Mechanisms should..."
Does this point out the need to have some distinction between for-apps
api vs for-mechanism api ?

- The file monitoring api seems unclear at best. Why should I use PK
to monitor files, and not gnome-vfs or inotify ? I'm missing something
here.

- polkit_context_set_file_monitor: "Register a functions" should be
"Register a function"

- polkit_context_set_load_descriptions - should probably point out that
loading descriptions is useful only for policy editors (or is it ?).
Also, does this load translations for the current locale ?

- polkit_context_init: Is it useful to separate initialization from
creation ? If yes, can I just call this at any time, or only right after
creation, or what ?

- PolKitPolicyCache: Is that really something you want to expose as part
of the api ? what use do applications have for it ?

- polkit_context_can_session_do_action: "can only be one of..." I wonder
if it is smart to make that guarantee, cf the above discussion of
results.

- Seats: is it really worth exposing seats as separate objects ? Looks
to me like they could just as well just be an attribute of a session.
Actually, doesn't CK already maintain the session <-> seat association ?
Is it a good idea to replicate that inside PK ?

Caller: "This class is used to represent a caller in another process" -
might be worthwhile to weaken that to "possibly in another process",
since presumably, you _can_ do it all in a single process ?


PolicyKit D-Bus Helper Library
--------------------------------------

I question the wisdom of a library where every public function says
"note that this will do a lot of blocking IO so it is best avoided".
How much io can that be, really ? Should the advice better be to cache
the result, instead ?


PolicyKit Granting Library
--------------------------------

Not entirely clear what the audience of this library is. I assume this
is glue code to allow implementing authentication uis for different
desktops ? That should be spelled out clearly somewhere up top. Also,
a little example might help.


Matthias