Describe best practices for property names, and recommend against dash-separated-words

Related to <https://bugs.freedesktop.org/show_bug.cgi?id=20948> whose
conclusion seemed to be that anything is allowed, but CamelCase is
considerably more interoperable.

Remove the old, vague Naming Conventions section

The defining instance of each namespaced term now contains notes on
conventional naming.

Briefly mention why to namespace object-paths

Describe conventional naming of errors

Describe conventional naming of methods and signals

Describe best-practices for naming well-known bus names

Formally define a unique connection name and a well-known bus name

Write about best-practices for interface names in the same place they're defined

I'm deliberately using a hypothetical API from example.com, rather
than a real API, to avoid perpetuating these over-simplifications any
further than they've spread already:

- "namespaces start with org.freedesktop"
- "namespaces start with org"
- "interfaces are defined by their sole implementation"
- "services have one object implementing one interface"
- "interfaces always behave like classes"
- "interfaces are always noun phrases"
- "there is a freedesktop.org D-Bus API for screensavers"

Merge branch 'dbus-1.4'

dbus_connection_can_send_type: clarify that invalid codes are allowed here

This is sufficiently unusual that it seems worth saying explicitly

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=35182
Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>

Merge branch 'dbus-1.4'

NEWS

minotaur: bail if asked to monitor >1 bus

A coworker was just tripped up by `dbus-monitor --session --system` only
monitoring the system bus. This patch would have saved him reproducing a
tricky bug several times!

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=26548
Reviewed-by: Colin Walters <walters@verbum.org>
Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>

NEWS for 1.5

Clarify that 'r' and 'e' cannot appear in signatures

Reviewed-by: Colin Walters <walters@verbum.org>
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=34529

Reserve 'm', '*', '?', '@', '&' and '^' for their uses in GVariant

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=34529
Reviewed-by: Colin Walters <walters@verbum.org>

Merge branch 'dbus-1.4'

NEWS for 1.4

machine-id: fall back to reading /etc/machine-id if D-Bus machine ID is not available

Newer systemd-based systems support a global machine ID with the same
metrics as the D-Bus machine ID, but more powerful semantics (for
example on ro media) in /etc/machine-id.

If the D-Bus machine ID cannot be read, fall back to the systemd machine
ID.

This is a first step towards allowing D-Bus to be started up during
early boot where /var is not available.

[plus a whitespace fix -smcv]

Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Reviewed-by: Colin Walters <walters@verbum.org>
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=35228

_dbus_check_fdleaks_enter, _dbus_check_fdleaks_leave: whitespace

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=35173
Reviewed-by: Colin Walters <walters@verbum.org>

Don't report file descriptors as "leaked" if they were already open

This is necessary to run the regression tests under valgrind (if
telling it to output to a dedicated fd), gdb, fakeroot etc.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=35173
Reviewed-by: Colin Walters <walters@verbum.org>

Merge branch 'dbus-1.4'

Conflicts:
NEWS

NEWS

Merge remote-tracking branch 'origin/dbus-1.4' into dbus-1.4

NEWS

dbus-1.pc.in: move -lpthread, -lrt, Winsock to Libs.private

"Private libraries  are  libraries  which  are  not  exposed through your
library, but are needed in the case of static linking"  -- pkg-config(1)

Reviewed-by: Colin Walters <walters@verbum.org>

Merge branch 'dbus-1.4'

NEWS

activation: Use _dbus_system_log for activation information

Log when we are activating something (and whether it's via systemd)
as well as when we fail to activate, and when one succeeds.

https://bugs.freedesktop.org/show_bug.cgi?id=35705

Add dbus-1-uninstalled.pc.in

See: http://smcv.pseudorandom.co.uk/2008/09/pc-uninstalled/

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=32827
Reviewed-by: Colin Walters <walters@verbum.org>

Merge branch 'dbus-1.4'

Conflicts:
NEWS

Add support for --disable-gc-sections for broken toolchains

Also use AC_LINK_IFELSE rather than reinventing it as a shell function.
This was the last user of ld_supports_flag, so, delete it.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=33466
Reviewed-by: Colin Walters <walters@verbum.org>

Drop outdated list of options from README, mention configure --help instead

Release notes for the -fPIE change

Don't force use of -fPIE for the dbus-daemon if apparently supported

It's a minor security benefit, but not automatically beneficial (it
enables ASLR, but breaks prelinking, some buggy toolchains, and some gdb
versions). Distributions who know their infrastructure works well can
enable it just as easily via

    ./configure CFLAGS="-fPIE" LDFLAGS="-pie"

without extra support from us, and that's a generic solution applicable to
many packages.

Similarly, don't force libdbus and libdbus-internal to be PIC: libtool
knows better than we do whether that's necessary/beneficial on a
particular platform.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=16621
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=27215
Bug-NB: NB#171940
Reviewed-by: Colin Walters <walters@verbum.org>

Install dbus-daemon and dbus-daemon-launch-helper in the conventional way

Also remove some pointless indirection (extra_tests etc.), don't install
the unused directory $(libexecdir)/dbus-1 (we actually install the
launch helper directly into $(libexecdir)), and allow dbus_daemondir to be
set on Windows rather than forcing dbus-daemon to be installed to
$(bindir) there.

dbus_daemon_execdir has to contain "exec" so that the dbus-daemon will be
installed by "make install-exec" and not "make install-data".

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=14512
Reviewed-by: Colin Walters <walters@verbum.org>

dbus_bus_add_match: improve error documentation.

It's simply not true that the only possible error is a lack of resources
in the bus.

Merge branch 'dbus-1.4'

When uploading docs, use rsync -p to set permissions

It turns out that rsync --chmod means "pretend the source files had
already had this chmod operation applied to them", and not "chmod the
destination files" like you'd expect.

As a result, the -p (--perms) option is also needed, so that rsync will
"preserve" the modified permissions. Otherwise, the docs will not be
group-writeable as intended, and only the person who made the previous
upload will be able to upload them next time.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=36130
Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>

Development version: 1.5.1, dbus-specification 0.17

Prepare 1.5.0

- D-Bus Specification 0.16
- libtool 9:0:6

Merge branch 'dbus-1.4'

Conflicts:
NEWS

development version

Prepare version 1.4.8

activation: Strip out code to compare by Exec=

In commit:
 075945f6        (John (J5) Palmieri     2005-07-14 20:44:15 +0000

some code was added to compare services by Exec key.  The changelog is
not pariticularly informative as to why this was added. But while
debugging other code, we noticed this.

Comparing by Exec key is not in the specification, and triggered a
problem where while converting services to use systemd for activation,
a change was made to use Exec=/bin/false and simply rely on systemd
to activate.

While I think it was broken for the service files to be changed
to Exec=/bin/false, we shouldn't be doing something here that's
not in the spec either.

Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>
Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=35750

oops, fix XML mis-nesting

list which parts of the Desktop Entry spec apply to service files

Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=19159

Merge branch 'arg0namespace-24317'

Reviewed-by: David Zeuthen <davidz@redhat.com>
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=24317
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=31818
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=34870

Merge branch 'dbus-1.4'

Mention dbus-specification.xml's separate versioning in HACKING

Check parsing (or otherwise) of path_namespace in match rules

Remove support for trailing "." on arg0namespace

Rename path_prefix to path_namespace and disallow trailing '/'

Also disallow having both path and path_namespace in the same match rule
(it wouldn't make sense, path is more specific than path_namespace).

As per IRC discussion with davidz and wjt.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=34870

Document when arg0namespace was added, for completeness

Document when argNpath was added, for completeness

specification: fix versioning

We've added things since 0.15, so this isn't still 0.15.

path_prefix: anchor matches at path-component boundaries, and give examples

It seems wrong that path_prefix="/foo" matches /foobar, and it isn't
difficult or expensive to check.

Add path_prefix match rule

Add a new path_prefix match rule that can be used for efficient
implementations of the org.freedesktop.DBus.ObjectManager interface
(see bug 34869).

https://bugs.freedesktop.org/show_bug.cgi?id=34870

Signed-off-by: David Zeuthen <davidz@redhat.com>

re-word description of arg0namespace

It's unclear at first reading whether "may contain only one element"
means "elements >= 1, as an exception to the usual rule that
elements >= 2" (which is what was intended), or "elements == 1".

"Like a bus name or interface name" is a little ambiguous because they
have different syntactic restrictions: specifically allow any valid bus
name, which also allows all interface names.

signals.h: rename argument in declaration to match implementation

Merge remote-tracking branch 'wjt/arg0namespace' into arg0namespace-24317

Break up the monster conditional in config-parser so gcov can cope

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=10887
Reviewed-by: Colin Walters <walters@verbum.org>

Update NEWS for master

Merge branch 'dbus-1.4'

Update NEWS

Merge branch 'dbus-1.4', rejecting all changes

This commit changes nothing, but means that merge tracking won't try to
apply the reversion of d1d395774435..09c9d6406b75f to master in future.

Revert merge of master (dbus-1.5) into dbus-1.4

This reverts commits d1d395774435..09c9d6406b75f, keeping Lennart's
addition of UnknownInterface etc.

connection: hook UnknownObject and UnknownInterface up where appropriate

This makes use of UnknownInterface and UnknownObject where appropriate
in the D-Bus core.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=34527
Reviewed-By: Simon McVittie <simon.mcvittie@collabora.co.uk>

protocol: introduce four new errors

UnknownInterface, UnknownObject, UnknownProperty and PropertyReadOnly,
as discussed on the ML.

The first two are already used by various bindings, such as the Qt and
Java binding, but have never been made official.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=34527
Reviewed-by: David Zeuthen <davidz@redhat.com>
Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>

Make dbus_type_is_valid into public API

This is just as useful for bindings as dbus_signature_validate, and I
think it's a good design principle to say that anything checked in a
_dbus_return_if_fail should be something the caller could check
for themselves.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=20496
Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>

Merge branch 'dbus-1.4'

add doxygen.stamp to .gitignore

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=35182
Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>

_dbus_marshal_write_fixed_multi: remove obsolete FIXME comment

As far as I can tell, we've never accepted out-of-range booleans and
canonicalized them, ever since this was first committed in 2004. If sent,
they'd be considered to be invalid by recipients, so they're unambiguously
an error.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=35182
Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>

dbus_message_iter_append_basic: remove misleading documentation

This function specifically doesn't support Unix fds and is documented as
such.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=35182
Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>

Implement uninstallation and cleanup for Doxygen docs, fixing distcheck

Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>

Merge branch 'validate-when-sending-16338' into dbus-1.4

Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>

dbus_type_is_basic etc.: it is an error to pass in bad typecodes

Previously, the comments said "this function will crash", but that's not
strictly true (checks can be disabled or made non-fatal). Their behaviour
is undefined if you do that, though.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=20496
Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>

Require specific user action to compile without 64-bit support

The D-Bus type system isn't implementable without 64-bit support, although
for historical reasons we have some sort of semi-working support for
platforms with no 64-bit integers. Let's find out whether any
practically relevant platform still lacks these types...

(GLib appears to have required 64-bit integer types since 2001.)

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=35114
Reviewed-by: Lennart Poettering <lennart@poettering.net>

Merge branch 'dbus-1.4'

autogen: add -I m4 to aclocal path

This fixes 2b5959882a403cddba754b37b58bdc49bff01f90 which forgot to add
m4/ to the command line of aclocal but moved scripts there.

Merge branch 'dbus-1.4'

Update NEWS

Merge branch 'dbus-1.4'

Fix some more stray occurrences of ELEMENT_TYPE

Do not use the name ELEMENT_TYPE

On Windows Systems ELEMENT_TYPE is already defined
in Winioctl.h this header is included indirectly
in dbus-sysdeps.h. By avoiding the use of the Name
ELEMENT_TYPE it is ensured that config-parser-common.h
can be included together with dbus-sysdeps.h

Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>

dbus_message_iter_append_fixed_array: add a check for valid booleans

The reasoning is the same as for dbus_message_iter_append_basic.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=16338
Reviewed-by: Cosimo Alfarano <cosimo.alfarano@collabora.co.uk>

dbus_message_iter_append_basic: validate booleans too

Sending, for instance, ((dbus_bool_t) 666) is a programming error and
should be diagnosed as such.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=16338
Reviewed-by: Cosimo Alfarano <cosimo.alfarano@collabora.co.uk>

dbus_message_iter_append_basic: check string-like arguments for validity

Strings: UTF-8 with no embedded NULs, by adding a new internal function,
_dbus_check_is_valid_utf8

Object paths, signatures: the obvious syntactic checks

This moves some of the burden of validation to the sender.

When sending <http://www.cl.cam.ac.uk/~mgk25/ucs/examples/UTF-8-demo.txt>
10240 times with up to 1024 parallel calls pending, on a single-core ARM
Linux device, I found that user CPU time in dbus-spam increased by up to 80%
as a result of the validation. However, when sending messages to dbus-daemon,
overall throughput only reduced by 15%, and when sending messages to an echo
service, overall throughput actually improved by around 14% (presumably
because making the sender CPU-bound influenced kernel scheduling).

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=16338
Bug-NB: NB#223152
Reviewed-by: Cosimo Alfarano <cosimo.alfarano@collabora.co.uk>

Merge branch 'dbus-1.4'

Conflicts:
NEWS

Merge branch 'doxygenate' into dbus-1.4

Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>
Conflicts:
configure.ac
doc/Makefile.am

NEWS so far

Merge branch 'changequote' into dbus-1.4

Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>

Merge branch 'require-display-for-autolaunch-19997' into dbus-1.4

Reviewed-by: Colin Walters <walters@verbum.org>

Merge branch 'modern-autofoo-32245' into dbus-1.4

Allow X11 autolaunch to be disabled even if the headers/libraries are there

In an embedded system where the D-Bus session is a core part of the
environment, like Maemo, accidentally auto-launching a second session bus
(for instance for a concurrent ssh session) is a bad idea - it can lead
to a "split brain" situation where half the applications in the GUI are
using a different bus. In these controlled environments, it'd be useful
to prevent autolaunch from ever happening.

(As a side benefit, the changes to configure.in also mean that packagers
can explicitly --enable-x11-autolaunch, to make sure that failure to find
X will make compilation fail cleanly.)

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=19997
Bug-NB: NB#219964

Don't attempt Unix X11 autolaunching if DISPLAY isn't set

The known use cases for autolaunching (ssh -Y firefox,
run konqueror in legacy DE) all need $DISPLAY too.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=19997

Merge branch 'dbus-1.4'

config-parser regression test: don't require that fd.o #34496 exists

Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>

Merge branch 'dbus-1.4'

Give XDG_DATA_HOME priority over XDG_DATA_DIRS for servicedirs

According to the XDG Base Directory Specification, “the base directory
defined by $XDG_DATA_HOME is considered more important than any of the
base directories defined by $XDG_DATA_DIRS.”  This makes it easier to
override a system service file as a normal user.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=34496
Signed-off-by: Anders Kaseorg <andersk@mit.edu>
Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>