diff options
| author | Will Thompson <will.thompson@collabora.co.uk> | 2010-11-21 17:01:25 +0000 |
|---|---|---|
| committer | Will Thompson <will.thompson@collabora.co.uk> | 2010-11-21 17:02:30 +0000 |
| commit | b4ae31b9827de0f1cb09a94fce43aa5e2283f8f6 (patch) | |
| tree | a546696ed384c528ee08c196738c23035d9d713d | |
| parent | b3fa6eff0dafc733e1c842859883cd5de8c456b6 (diff) | |
| download | dbus-b4ae31b9827de0f1cb09a94fce43aa5e2283f8f6.tar.gz | |
Document the rationale for argXpath matching.
| -rw-r--r-- | doc/dbus-specification.xml | 32 |
1 files changed, 22 insertions, 10 deletions
diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index c7345874..89ccd9fa 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -3604,16 +3604,28 @@ <row> <entry><literal>arg[0, 1, 2, 3, ...]path</literal></entry> <entry>Any string</entry> - <entry>Argument path matches provide a specialised form of wildcard - matching for path-like namespaces. As with normal argument matches, - if the argument is exactly equal to the string given in the match - rule then the rule is satisfied. Additionally, there is also a - match when either the string given in the match rule or the - appropriate message argument ends with '/' and is a prefix of the - other. An example argument path match is arg0path='/aa/bb/'. This - would match messages with first arguments of '/', '/aa/', - '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match - messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.</entry> + <entry> + <para>Argument path matches provide a specialised form of wildcard + matching for path-like namespaces. As with normal argument matches, + if the argument is exactly equal to the string given in the match + rule then the rule is satisfied. Additionally, there is also a + match when either the string given in the match rule or the + appropriate message argument ends with '/' and is a prefix of the + other. An example argument path match is arg0path='/aa/bb/'. This + would match messages with first arguments of '/', '/aa/', + '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match + messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.</para> + + <para>This is intended for monitoring “directories” in file system-like + hierarchies, as used in the <citetitle>dconf</citetitle> configuration + system. An application interested in all nodes in a particular hierarchy would + monitor <literal>arg0path='/ca/example/foo/'</literal>. Then the service could + emit a signal with zeroth argument <literal>"/ca/example/foo/bar"</literal> to + represent a modification to the “bar” property, or a signal with zeroth + argument <literal>"/ca/example/"</literal> to represent atomic modification of + many properties within that directory, and the interested application would be + notified in both cases.</para> + </entry> </row> </tbody> </tgroup> |