Re: DBus methods without name grabbing

[Jan Moringen <jan.moringen@uni-bielefeld.de>]

[-- Attachment #1: Type: text/plain, Size: 4798 bytes --]

Hi,

I finally got to improving my patch. Feedback would be appreciated.

> > --- doc/misc/dbus.texi	2011-01-04 12:38:33 +0000
> > +++ doc/misc/dbus.texi	2011-01-05 04:09:22 +0000
> > @@ -1491,6 +1491,16 @@
> >  to the service from D-Bus.
> >  @end defun
> >  
> > +@defun dbus-register-service bus service
> > +Register the known name @var{service} on D-Bus @var{bus}.
> > +
> > +@var{bus} is either the symbol @code{:system} or the symbol
> > +@code{:session}.
> > +
> > +@var{service} is the service name to be registered on the D-Bus.  It
> > +must be a known name.
> > +@end defun
> > +
> >  @defun dbus-unregister-service bus service
> >  Unregister all objects from D-Bus @var{bus}, registered by Emacs for
> >  @var{service}.
> 
> Maybe we shall rearrange the whole node a little bit. In the
> introductionary paragraph, service names could be described more
> detailed, especially their registration policies. Afterwards,
> dbus-register-service shall follow.

Done.

> The explanation of dont-register-service in dbus-register-method and
> dbus-register-property could be shortened, referring to the explanation
> in dbus-register-service.

I don't see which parts of the these discussions could be shortened.

> > --- etc/NEWS	2011-01-04 16:57:45 +0000
> > +++ etc/NEWS	2011-01-05 04:09:22 +0000
> > @@ -558,7 +558,9 @@
> >  *** dbus-register-{method,property} do not necessarily register names anymore.
> > -
> > +*** New function dbus-register-service
> > +    Register a service known name on a D-Bus without simultaneously
> > +    registering a property or a method
> 
> I guess we could join both entries.

Done.

> > --- src/dbusbind.c	2011-01-04 11:11:43 +0000
> > +++ src/dbusbind.c	2011-01-05 04:09:22 +0000
> > +DEFUN ("dbus-register-service", Fdbus_register_service, Sdbus_register_service,
> > +       2, 2, 0,
> > +       doc: /* Register known name SERVICE on the D-Bus BUS.
> > +
> > +BUS is either a Lisp symbol, `:system' or `:session', or a string
> > +denoting the bus address.
> > +
> > +SERVICE is the D-Bus service name that should be registered.  It must
> > +be a known name.
> > +
> > +Return nil.*/)
> > +  (Lisp_Object bus, Lisp_Object service)
> 
> Your implementation looks OK to me. However, I have a more general
> function in mind. Something like this:
> 
> --8<---------------cut here---------------start------------->8---
> DEFUN ("dbus-register-service", Fdbus_register_service, Sdbus_register_service,
>        2, MANY, 0, doc: /* Register known name SERVICE on the D-Bus BUS.
> 
> BUS is either a Lisp symbol, `:system' or `:session', or a string
> denoting the bus address.
> 
> SERVICE is the D-Bus service name that should be registered.
> 
> FLAGS are integers, which control how the service name is registered.
> The following integer constants could be used:
> 
> `dbus-service-allow-replacement': Allow another service to become the
> primary owner if requested.
> 
> `dbus-service-replace-existing': Request to replace the current
> primary owner.
> 
> `dbus-service-do-not-queue': If we can not become the primary owner do
> not place us in the queue.
> 
> The function returns an integer, indicating the result of the
> operation.  There are predefined constants to check:
> 
> `dbus-service-primary-owner': Service has become the primary owner of
> the requested name.
> 
> `dbus-service-in-queue': Service could not become the primary owner
> and has been placed in the queue.
> 
> `dbus-service-exists': Service is already in the queue.
> 
> `dbus-service-already-owner': Service is already the primary owner.
> 
> Example:
> 
> \(dbus-register-service :session dbus-service-emacs)
> 
>   => 1 ;; This is `dbus-service-primary-owner'.
> 
> \(dbus-register-service
>   :session "org.freedesktop.TextEditor"
>   dbus-service-allow-replacement dbus-service-replace-existing)
> 
>   => 4 ;; This is `dbus-service-already-owner'.
> 
> usage: (dbus-register-service BUS SERVICE &rest FLAGS)  */)
>   (int nargs, register Lisp_Object *args)
> --8<---------------cut here---------------end--------------->8---
> 
> The constants shall be declared as well, for initialization you could
> use DBUS_NAME_FLAG* and DBUS_REQUEST_NAME_REPLY* from dbus-shared.h.

I'm not sure about the integer constant and how they would be declared.
I used keywords instead.

> And while we are at this, maybe dbus-unregister-service could also
> return a similar result, based on DBUS_RELEASE_NAME_REPLY*.

Done.

> > @@ -2028,18 +2066,8 @@
> > +  /* Request the name.  */
> > +  Fdbus_register_service (bus, service);
> 
> As you have said the other message, the check for dont-register-service
> is missing.

This is fixed now.

> Furthermore, I would also propose to use dbus-register-service in
> dbus-register-property (in dbus.el).

Done.

Kind regards,
Jan

[-- Attachment #2: dbus-un-register-service.patch --]
[-- Type: text/x-patch, Size: 22908 bytes --]

# Bazaar merge directive format 2 (Bazaar 0.90)
# revision_id: jan.moringen@uni-bielefeld.de-20110108054407-\
#   33fj9wo8x4hb8oiu
# target_branch: bzr://bzr.savannah.gnu.org/emacs/trunk/
# testament_sha1: e93dadb08dca5ffc0f5f12e68e26573ef00e56e8
# timestamp: 2011-01-08 06:44:49 +0100
# base_revision_id: ken.manheimer@gmail.com-20110104195021-\
#   1x68s956czngphh2
# 
# Begin patch
=== modified file 'doc/misc/ChangeLog'
--- doc/misc/ChangeLog	2011-01-04 12:38:33 +0000
+++ doc/misc/ChangeLog	2011-01-08 05:37:49 +0000
@@ -1,3 +1,8 @@
+2011-01-08  Jan Moringen  <jmoringe@techfak.uni-bielefeld.de>
+
+	* dbus.texi (Receiving Method Calls): rearranged node to mention
+	dbus-register-service and dbus-unregister-service first
+
 2011-01-04  Jan Moringen  <jan.moringen@uni-bielefeld.de>
 
 	* dbus.texi (Receiving Method Calls): Describe new optional

=== modified file 'doc/misc/dbus.texi'
--- doc/misc/dbus.texi	2011-01-04 12:38:33 +0000
+++ doc/misc/dbus.texi	2011-01-08 05:37:49 +0000
@@ -1244,9 +1244,37 @@
 @cindex method calls, returning
 @cindex returning method calls
 
-Emacs can also offer own methods, which can be called by other
-applications.  These methods could be an implementation of an
-interface of a well known service, like @samp{org.freedesktop.TextEditor}.
+In order to register methods on the D-Bus, Emacs has to request a well
+known name on the D-Bus under which it will be available for other
+clients.  Names on the D-Bus can be registered and unregistered using
+the following functions:
+
+@defun dbus-register-service bus service &rest flags
+Register the known name @var{service} on D-Bus @var{bus}.
+
+@var{bus} is either the symbol @code{:system} or the symbol
+@code{:session}.
+
+@var{service} is the service name to be registered on the D-Bus.  It
+must be a known name.
+@end defun
+
+@defun dbus-unregister-service bus service
+Unregister all objects from D-Bus @var{bus}, registered by Emacs for
+@var{service}.
+
+@var{bus} is either the symbol @code{:system} or the symbol
+@code{:session}.
+
+@var{service} is the D-Bus service name of the D-Bus.  It must be a
+known name.  Emacs releases its association to @var{service} from
+D-Bus.
+@end defun
+
+When a name has been chosen, Emacs can offer own methods, which can be
+called by other applications.  These methods could be an
+implementation of an interface of a well known service, like
+@samp{org.freedesktop.TextEditor}.
 
 It could be also an implementation of an own interface.  In this case,
 the service name must be @samp{org.gnu.Emacs}.  The object path shall
@@ -1491,18 +1519,6 @@
 to the service from D-Bus.
 @end defun
 
-@defun dbus-unregister-service bus service
-Unregister all objects from D-Bus @var{bus}, registered by Emacs for
-@var{service}.
-
-@var{bus} is either the symbol @code{:system} or the symbol
-@code{:session}.
-
-@var{service} is the D-Bus service name of the D-Bus.  It must be a
-known name.  Emacs releases its association to @var{service} from
-D-Bus.
-@end defun
-
 
 @node Signals
 @chapter Sending and receiving signals.

=== modified file 'etc/NEWS'
--- etc/NEWS	2011-01-04 16:57:45 +0000
+++ etc/NEWS	2011-01-08 05:43:02 +0000
@@ -557,8 +557,13 @@
 *** It is possible now, to access alternative buses than the default
 system or session bus.
 
-*** dbus-register-{method,property} do not necessarily register names anymore.
+*** dbus-register-{service,method,property} 
+    The -method and -property functions do not automatically register
+    names anymore.
 
+    The new function dbus-register-service registers a service known
+    name on a D-Bus without simultaneously registering a property or a
+    method
 ** Tramp
 
 *** There exists a new inline access method "ksu" (kerberized su).

=== modified file 'lisp/ChangeLog'
--- lisp/ChangeLog	2011-01-04 19:50:21 +0000
+++ lisp/ChangeLog	2011-01-08 05:44:07 +0000
@@ -1,3 +1,11 @@
+2011-01-08  Jan Moringen  <jmoringe@techfak.uni-bielefeld.de>
+
+	* net/dbus.el (dbus-unregister-service): translate returned
+	integer into a symbol
+
+	* net/dbus.el (dbus-register-property): use
+	`dbus-register-service' to do the name registration
+
 2011-01-04  Ken Manheimer  <ken.manheimer@gmail.com>
 
 	* Summary: Reconcile with changes in line movement behavior for

=== modified file 'lisp/net/dbus.el'
--- lisp/net/dbus.el	2011-01-04 10:57:24 +0000
+++ lisp/net/dbus.el	2011-01-08 05:44:07 +0000
@@ -193,9 +193,14 @@
 	       (puthash key (delete elt value) dbus-registered-objects-table)
 	     (remhash key dbus-registered-objects-table))))))
    dbus-registered-objects-table)
-  (dbus-call-method
-   bus dbus-service-dbus dbus-path-dbus dbus-interface-dbus
-   "ReleaseName" service))
+  (let ((reply (dbus-call-method
+		bus dbus-service-dbus dbus-path-dbus dbus-interface-dbus
+		"ReleaseName" service)))
+    (case reply
+      (1 :released)
+      (2 :non-existent)
+      (3 :not-owner)
+      (t reply))))
 
 (defun dbus-call-method-non-blocking-handler (&rest args)
   "Handler for reply messages of asynchronous D-Bus message calls.
@@ -917,14 +922,18 @@
   ;; Add the handler.  We use `dbus-service-emacs' as service name, in
   ;; order to let unregister SERVICE despite of this default handler.
   (dbus-register-method
-   bus service path dbus-interface-properties "Get" 'dbus-property-handler
-   dont-register-service)
-  (dbus-register-method
-   bus service path dbus-interface-properties "GetAll" 'dbus-property-handler
-   dont-register-service)
-  (dbus-register-method
-   bus service path dbus-interface-properties "Set" 'dbus-property-handler
-   dont-register-service)
+   bus service path dbus-interface-properties "Get"
+   'dbus-property-handler nil)
+  (dbus-register-method
+   bus service path dbus-interface-properties "GetAll" 
+   'dbus-property-handler nil)
+  (dbus-register-method
+   bus service path dbus-interface-properties "Set" 
+   'dbus-property-handler nil)
+
+  ;; Register the name SERVICE with BUS.
+  (unless dont-register-service
+    (dbus-register-service bus service))
 
   ;; Send the PropertiesChanged signal.
   (when emits-signal

=== modified file 'src/ChangeLog'
--- src/ChangeLog	2011-01-04 11:11:43 +0000
+++ src/ChangeLog	2011-01-08 05:38:56 +0000
@@ -1,3 +1,34 @@
+2011-01-08  Jan Moringen  <jmoringe@techfak.uni-bielefeld.de>
+
+	Symbols for flags, return values in request-service in dbusbind.c
+	* dbusbind.c (QCdbus_request_name_allow_replacement): new symbol;
+	used by dbus-register-service
+	(QCdbus_request_name_replace_existing): likewise
+	(QCdbus_request_name_do_not_queue): likewise
+	(QCdbus_request_name_reply_primary_owner): likewise
+	(QCdbus_request_name_reply_in_queue): likewise
+	(QCdbus_request_name_reply_exists): likewise
+	(QCdbus_request_name_reply_already_owner): likewise
+	(Fdbus_register_service): changed number of arguments to MANY;
+	rest arguments are used to supply flags; adapted docstring
+	accordingly; translate value returned by DBus to a symbol
+	(Fdbus_register_method): use Fdbus_register_service to do the name
+	registration
+	(syms_of_dbusbind): added symbols :allow-replacement,
+	:replace-existing, :do-not-queue, :primary-owner, :existing,
+	:in-queue and :already-owner
+
+2011-01-05  Jan Moringen  <jmoringe@techfak.uni-bielefeld.de>
+
+	Added function dbus-register-service in dbusbind.c
+	* dbusbind.c (Qdbus_register_service): new variable; holds
+	function dbus-register-service
+	(Fdbus_register_service): new function; register a service known
+	name on a D-Bus
+	(Fdbus_register_method): use Fdbus_register_service to register
+	the service name
+	(syms_of_dbusbind): added symbol `dbus-register-service'
+
 2011-01-04  Jan Moringen  <jan.moringen@uni-bielefeld.de>
 
 	* dbusbind.c (Fdbus_register_method): Added optional parameter

=== modified file 'src/dbusbind.c'
--- src/dbusbind.c	2011-01-04 11:11:43 +0000
+++ src/dbusbind.c	2011-01-08 05:38:56 +0000
@@ -38,6 +38,7 @@
 Lisp_Object Qdbus_method_return_internal;
 Lisp_Object Qdbus_method_error_internal;
 Lisp_Object Qdbus_send_signal;
+Lisp_Object Qdbus_register_service;
 Lisp_Object Qdbus_register_signal;
 Lisp_Object Qdbus_register_method;
 
@@ -50,6 +51,17 @@
 /* Lisp symbol for method call timeout.  */
 Lisp_Object QCdbus_timeout;
 
+/* Lisp symbols for name request flags.  */
+Lisp_Object QCdbus_request_name_allow_replacement;
+Lisp_Object QCdbus_request_name_replace_existing;
+Lisp_Object QCdbus_request_name_do_not_queue;
+
+/* Lisp symbols for name request replies.  */
+Lisp_Object QCdbus_request_name_reply_primary_owner;
+Lisp_Object QCdbus_request_name_reply_in_queue;
+Lisp_Object QCdbus_request_name_reply_exists;
+Lisp_Object QCdbus_request_name_reply_already_owner;
+
 /* Lisp symbols of D-Bus types.  */
 Lisp_Object QCdbus_type_byte, QCdbus_type_boolean;
 Lisp_Object QCdbus_type_int16, QCdbus_type_uint16;
@@ -1835,6 +1847,114 @@
   xd_in_read_queued_messages = 0;
 }
 
+DEFUN ("dbus-register-service", Fdbus_register_service, Sdbus_register_service,
+       2, MANY, 0,
+       doc: /* Register known name SERVICE on the D-Bus BUS.
+
+BUS is either a Lisp symbol, `:system' or `:session', or a string
+denoting the bus address.
+
+SERVICE is the D-Bus service name that should be registered.  It must
+be a known name.
+
+FLAGS are keywords, which control how the service name is registered.
+The following keywords are recognized:
+
+`:allow-replacement': Allow another service to become the primary
+owner if requested.
+
+`:replace-existing': Request to replace the current primary owner.
+
+`:do-not-queue': If we can not become the primary owner do not place
+us in the queue.
+
+The function returns a keyword, indicating the result of the
+operation.  The following keyword can be returned:
+
+`:primary-owner': Service has become the primary owner of the
+requested name.
+
+`:in-queue': Service could not become the primary owner and has been
+placed in the queue.
+
+`:exists': Service is already in the queue.
+
+`:already-owner': Service is already the primary owner.
+
+Example:
+
+\(dbus-register-service :session dbus-service-emacs)
+
+  => :primary-owner.
+
+\(dbus-register-service
+:session "org.freedesktop.TextEditor"
+dbus-service-allow-replacement dbus-service-replace-existing)
+
+  => :already-owner.
+
+usage: (dbus-register-service BUS SERVICE &rest FLAGS)  */)
+  (int nargs, register Lisp_Object *args)
+{
+  Lisp_Object bus, service;
+  struct gcpro gcpro1, gcpro2;
+  DBusConnection *connection;
+  unsigned int i;
+  unsigned int value;
+  unsigned int flags = 0;
+  int result;
+  DBusError derror;
+
+  bus = args[0];
+  service = args[1];
+
+  /* Check parameters.  */
+  CHECK_STRING (service);
+
+  /* Process flags.  */
+  for (i = 2; i < nargs; ++i) {
+    value = ((EQ (args[i], QCdbus_request_name_replace_existing)) 
+	     ? DBUS_NAME_FLAG_REPLACE_EXISTING
+	     : (EQ (args[i], QCdbus_request_name_allow_replacement)) 
+	     ? DBUS_NAME_FLAG_ALLOW_REPLACEMENT
+	     : (EQ (args[i], QCdbus_request_name_do_not_queue)) 
+	     ? DBUS_NAME_FLAG_DO_NOT_QUEUE
+	     : -1);
+    if (value == -1)
+      xsignal0 (Qdbus_error); 
+		//	"Unrecognized name request flag");
+    flags |= value;
+  }
+
+  /* Open a connection to the bus.  */
+  connection = xd_initialize (bus, TRUE);
+
+  /* Request the known name from the bus.  We can ignore the result,
+     it is set to -1 if there is an error - kind of redundancy.  */
+  dbus_error_init (&derror);
+  result = dbus_bus_request_name (connection, SDATA (service), flags, 
+				  &derror);
+  if (dbus_error_is_set (&derror))
+    XD_ERROR (derror);
+
+  /* Cleanup.  */
+  dbus_error_free (&derror);
+
+  /* Return object.  */
+  switch (result) {
+  case DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER:
+    return QCdbus_request_name_reply_primary_owner;
+  case DBUS_REQUEST_NAME_REPLY_IN_QUEUE:
+    return QCdbus_request_name_reply_in_queue;
+  case DBUS_REQUEST_NAME_REPLY_EXISTS:
+    return QCdbus_request_name_reply_exists;
+  case DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER:
+    return QCdbus_request_name_reply_already_owner;
+  default:
+    return Qnil;
+  }
+}
+
 DEFUN ("dbus-register-signal", Fdbus_register_signal, Sdbus_register_signal,
        6, MANY, 0,
        doc: /* Register for signal SIGNAL on the D-Bus BUS.
@@ -2014,6 +2134,7 @@
   DBusConnection *connection;
   int result;
   DBusError derror;
+  Lisp_Object args[2] = { bus, service };
 
   /* Check parameters.  */
   CHECK_STRING (service);
@@ -2028,18 +2149,9 @@
   /* Open a connection to the bus.  */
   connection = xd_initialize (bus, TRUE);
 
-  /* Request the known name from the bus.  We can ignore the result,
-     it is set to -1 if there is an error - kind of redundancy.  */
-  if (NILP (dont_register_service))
-    {
-      dbus_error_init (&derror);
-      result = dbus_bus_request_name (connection, SDATA (service), 0, &derror);
-      if (dbus_error_is_set (&derror))
-	XD_ERROR (derror);
-
-      /* Cleanup.  */
-      dbus_error_free (&derror);
-    }
+  /* Request the name.  */
+  if (!(NILP(dont_register_service)))
+    Fdbus_register_service (2, args);
 
   /* Create a hash table entry.  We use nil for the unique name,
      because the method might be called from anybody.  */
@@ -2091,6 +2203,10 @@
   staticpro (&Qdbus_send_signal);
   defsubr (&Sdbus_send_signal);
 
+  Qdbus_register_service = intern_c_string ("dbus-register-service");
+  staticpro (&Qdbus_register_service);
+  defsubr (&Sdbus_register_service);
+
   Qdbus_register_signal = intern_c_string ("dbus-register-signal");
   staticpro (&Qdbus_register_signal);
   defsubr (&Sdbus_register_signal);
@@ -2112,6 +2228,27 @@
   QCdbus_session_bus = intern_c_string (":session");
   staticpro (&QCdbus_session_bus);
 
+  QCdbus_request_name_allow_replacement = intern_c_string (":allow-replacement");
+  staticpro (&QCdbus_request_name_allow_replacement);
+
+  QCdbus_request_name_replace_existing = intern_c_string (":replace-existing");
+  staticpro (&QCdbus_request_name_replace_existing);
+
+  QCdbus_request_name_do_not_queue = intern_c_string (":do-not-queue");
+  staticpro (&QCdbus_request_name_do_not_queue);
+
+  QCdbus_request_name_reply_primary_owner = intern_c_string (":primary-owner");
+  staticpro (&QCdbus_request_name_reply_primary_owner);
+
+  QCdbus_request_name_reply_exists = intern_c_string (":exists");
+  staticpro (&QCdbus_request_name_reply_exists);
+
+  QCdbus_request_name_reply_in_queue = intern_c_string (":in-queue");
+  staticpro (&QCdbus_request_name_reply_in_queue);
+
+  QCdbus_request_name_reply_already_owner = intern_c_string (":already-owner");
+  staticpro (&QCdbus_request_name_reply_already_owner);
+
   QCdbus_timeout = intern_c_string (":timeout");
   staticpro (&QCdbus_timeout);
 

# Begin bundle
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
rfRbLYcrs2JxaUhtb7v7i7kinChIJDq/zwA=