[Emacs-diffs] emacs/doc/misc dbus.texi

[Michael Albinus]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Michael Albinus <albinus>       08/11/26 07:08:07

Modified files:
        doc/misc       : dbus.texi 

Log message:
        * dbus.texi (Type Conversion): New defuns `dbus-string-to-byte-array',
        `dbus-escape-as-identifier', `dbus-byte-array-to-string' and
        `dbus-unescape-from-identifier'.
        (Receiving Method Calls): New constants `dbus-service-emacs' and
        `dbus-path-emacs'.
        (Signals): Use the constants in the example.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/misc/dbus.texi?cvsroot=emacs&r1=1.24&r2=1.25

Patches:
Index: dbus.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/misc/dbus.texi,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -b -r1.24 -r1.25
--- dbus.texi   19 Nov 2008 04:28:40 -0000      1.24
+++ dbus.texi   26 Nov 2008 07:08:07 -0000      1.25
@@ -945,6 +945,37 @@
 @result{} 3
 @end lisp
 
address@hidden dbus-string-to-byte-array string
+Sometimes, D-Bus methods require as input parameter an array of bytes,
+instead of a string.  If it is guaranteed, that @var{string} is an
+UTF8 string, this function performs the conversion.  Example:
+
address@hidden
+(dbus-string-to-byte-array "/etc/hosts")
+
address@hidden (:array :byte 47 :byte 101 :byte 116 :byte 99 :byte 47
+           :byte 104 :byte 111 :byte 115 :byte 116 :byte 115)
address@hidden lisp
address@hidden defun
+
address@hidden dbus-escape-as-identifier string
+Escape an arbitrary @var{string} so it follows the rules for a C
+identifier.  The escaped string can be used as object path component,
+interface element component, bus name component or member name in
+D-Bus.
+
+The escaping consists of replacing all non-alphanumerics, and the
+first character if it's a digit, with an underscore and two
+lower-case hex digits.  As a special case, "" is escaped to
+"_".  Example:
+
address@hidden
+(dbus-escape-as-identifier "0123abc_xyz\x01\xff")
+
address@hidden "_30123abc_5fxyz_01_ff"
address@hidden lisp
address@hidden defun
+
 
 @section Output parameters.
 
@@ -991,6 +1022,30 @@
 (@var{NUMBER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} 
@var{BOOL}) @dots{}))
 @end lisp
 
address@hidden dbus-byte-array-to-string byte-array
+If a D-Bus method or signal returns an array of bytes, which are known
+to represent an UTF8 string, this function converts @var{byte-array}
+to the corresponding string.  Example:
+
address@hidden
+(dbus-byte-array-to-string '(47 101 116 99 47 104 111 115 116 115))
+
address@hidden "/etc/hosts"
address@hidden lisp
address@hidden defun
+
address@hidden dbus-unescape-from-identifier string
+Retrieve the original string from the encoded @var{string}.
address@hidden must have been coded with
address@hidden  Example:
+
address@hidden
+(dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff")
+
address@hidden "0123abc_xyz
ÿ"
address@hidden lisp
address@hidden defun
+
 
 @node Synchronous Methods
 @chapter Calling methods in a blocking way.
@@ -1173,6 +1228,16 @@
 @address@hidden is the name of the application which
 provides the interface.
 
address@hidden Constant dbus-service-emacs
+The well known service name of Emacs.
address@hidden deffn
+
address@hidden Constant dbus-path-emacs
+The object path head "/org/gnu/Emacs" used by Emacs.  All object
+paths, used by offered methods or signals, shall start with this
+string.
address@hidden deffn
+
 @defun dbus-register-method bus service path interface method handler
 With this function, an application registers @var{method} on the D-Bus
 @var{bus}.
@@ -1296,8 +1361,9 @@
 
 @lisp
 (dbus-send-signal
-  :session "org.gnu.Emacs" "/org/gnu/Emacs"
-  "org.gnu.Emacs.FileManager" "FileModified" "/home/albinus/.emacs")
+  :session dbus-service-emacs dbus-path-emacs
+  (concat dbus-service-emacs ".FileManager") "FileModified"
+  "/home/albinus/.emacs")
 @end lisp
 @end defun