mirror of
https://github.com/systemd/systemd
synced 2025-09-22 05:14:44 +02:00
Compare commits
5 Commits
c083264115
...
6829d8ce69
Author | SHA1 | Date | |
---|---|---|---|
![]() |
6829d8ce69 | ||
![]() |
9b62e232ea | ||
![]() |
fc91667d77 | ||
![]() |
6ba8071ca1 | ||
![]() |
50b88e87c8 |
@ -121,7 +121,7 @@ manpages = [
|
|||||||
'sd_bus_match_signal',
|
'sd_bus_match_signal',
|
||||||
'sd_bus_match_signal_async'],
|
'sd_bus_match_signal_async'],
|
||||||
''],
|
''],
|
||||||
['sd_bus_add_object_vtable',
|
['sd_bus_add_object',
|
||||||
'3',
|
'3',
|
||||||
['SD_BUS_METHOD',
|
['SD_BUS_METHOD',
|
||||||
'SD_BUS_METHOD_WITH_NAMES',
|
'SD_BUS_METHOD_WITH_NAMES',
|
||||||
@ -134,7 +134,9 @@ manpages = [
|
|||||||
'SD_BUS_VTABLE_END',
|
'SD_BUS_VTABLE_END',
|
||||||
'SD_BUS_VTABLE_START',
|
'SD_BUS_VTABLE_START',
|
||||||
'SD_BUS_WRITABLE_PROPERTY',
|
'SD_BUS_WRITABLE_PROPERTY',
|
||||||
'sd_bus_add_fallback_vtable'],
|
'sd_bus_add_fallback',
|
||||||
|
'sd_bus_add_fallback_vtable',
|
||||||
|
'sd_bus_add_object_vtable'],
|
||||||
''],
|
''],
|
||||||
['sd_bus_attach_event', '3', ['sd_bus_detach_event', 'sd_bus_get_event'], ''],
|
['sd_bus_attach_event', '3', ['sd_bus_detach_event', 'sd_bus_get_event'], ''],
|
||||||
['sd_bus_call', '3', ['sd_bus_call_async'], ''],
|
['sd_bus_call', '3', ['sd_bus_call_async'], ''],
|
||||||
|
@ -41,7 +41,10 @@
|
|||||||
|
|
||||||
<para>See
|
<para>See
|
||||||
<literallayout><citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
<literallayout><citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||||
|
<citerefentry><refentrytitle>sd_bus_add_object</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||||
<citerefentry><refentrytitle>sd_bus_add_object_vtable</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
<citerefentry><refentrytitle>sd_bus_add_object_vtable</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||||
|
<citerefentry><refentrytitle>sd_bus_add_fallback</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||||
|
<citerefentry><refentrytitle>sd_bus_add_fallback_vtable</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||||
<citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
<citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||||
<citerefentry><refentrytitle>sd_bus_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
<citerefentry><refentrytitle>sd_bus_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||||
<citerefentry><refentrytitle>sd_bus_call_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
<citerefentry><refentrytitle>sd_bus_call_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||||
|
@ -3,20 +3,22 @@
|
|||||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
||||||
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
|
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
|
||||||
|
|
||||||
<refentry id="sd_bus_add_object_vtable"
|
<refentry id="sd_bus_add_object"
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude">
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||||
|
|
||||||
<refentryinfo>
|
<refentryinfo>
|
||||||
<title>sd_bus_add_object_vtable</title>
|
<title>sd_bus_add_object</title>
|
||||||
<productname>systemd</productname>
|
<productname>systemd</productname>
|
||||||
</refentryinfo>
|
</refentryinfo>
|
||||||
|
|
||||||
<refmeta>
|
<refmeta>
|
||||||
<refentrytitle>sd_bus_add_object_vtable</refentrytitle>
|
<refentrytitle>sd_bus_add_object</refentrytitle>
|
||||||
<manvolnum>3</manvolnum>
|
<manvolnum>3</manvolnum>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
|
<refname>sd_bus_add_object</refname>
|
||||||
|
<refname>sd_bus_add_fallback</refname>
|
||||||
<refname>sd_bus_add_object_vtable</refname>
|
<refname>sd_bus_add_object_vtable</refname>
|
||||||
<refname>sd_bus_add_fallback_vtable</refname>
|
<refname>sd_bus_add_fallback_vtable</refname>
|
||||||
<refname>SD_BUS_VTABLE_START</refname>
|
<refname>SD_BUS_VTABLE_START</refname>
|
||||||
@ -76,6 +78,24 @@
|
|||||||
<paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
|
<paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
|
||||||
</funcprototype>
|
</funcprototype>
|
||||||
|
|
||||||
|
<funcprototype>
|
||||||
|
<funcdef>int <function>sd_bus_add_object</function></funcdef>
|
||||||
|
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
||||||
|
<paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
|
||||||
|
<paramdef>const char *<parameter>path</parameter></paramdef>
|
||||||
|
<paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
|
||||||
|
<paramdef>void *<parameter>userdata</parameter></paramdef>
|
||||||
|
</funcprototype>
|
||||||
|
|
||||||
|
<funcprototype>
|
||||||
|
<funcdef>int <function>sd_bus_add_fallback</function></funcdef>
|
||||||
|
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
||||||
|
<paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
|
||||||
|
<paramdef>const char *<parameter>path</parameter></paramdef>
|
||||||
|
<paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
|
||||||
|
<paramdef>void *<parameter>userdata</parameter></paramdef>
|
||||||
|
</funcprototype>
|
||||||
|
|
||||||
<funcprototype>
|
<funcprototype>
|
||||||
<funcdef>int <function>sd_bus_add_object_vtable</function></funcdef>
|
<funcdef>int <function>sd_bus_add_object_vtable</function></funcdef>
|
||||||
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
||||||
@ -188,40 +208,82 @@
|
|||||||
<refsect1>
|
<refsect1>
|
||||||
<title>Description</title>
|
<title>Description</title>
|
||||||
|
|
||||||
<para><function>sd_bus_add_object_vtable()</function> is used to declare attributes for the path object
|
<para><function>sd_bus_add_object_vtable()</function> is used to declare attributes for the
|
||||||
path <parameter>path</parameter> connected to the bus connection <parameter>bus</parameter> under the
|
object path <parameter>path</parameter> connected to the bus connection
|
||||||
interface <parameter>interface</parameter>. The table <parameter>vtable</parameter> may contain property
|
<parameter>bus</parameter> under the interface <parameter>interface</parameter>. The table
|
||||||
declarations using <constant>SD_BUS_PROPERTY()</constant> or
|
<parameter>vtable</parameter> may contain property declarations using
|
||||||
<constant>SD_BUS_WRITABLE_PROPERTY()</constant>, method declarations using
|
<constant>SD_BUS_PROPERTY()</constant> or <constant>SD_BUS_WRITABLE_PROPERTY()</constant>,
|
||||||
<constant>SD_BUS_METHOD()</constant>, <constant>SD_BUS_METHOD_WITH_NAMES()</constant>,
|
method declarations using <constant>SD_BUS_METHOD()</constant>,
|
||||||
|
<constant>SD_BUS_METHOD_WITH_NAMES()</constant>,
|
||||||
<constant>SD_BUS_METHOD_WITH_OFFSET()</constant>, or
|
<constant>SD_BUS_METHOD_WITH_OFFSET()</constant>, or
|
||||||
<constant>SD_BUS_METHOD_WITH_NAMES_OFFSET()</constant>, and signal declarations using
|
<constant>SD_BUS_METHOD_WITH_NAMES_OFFSET()</constant>, and signal declarations using
|
||||||
<constant>SD_BUS_SIGNAL_WITH_NAMES()</constant> or <constant>SD_BUS_SIGNAL()</constant>, see below. The
|
<constant>SD_BUS_SIGNAL_WITH_NAMES()</constant> or <constant>SD_BUS_SIGNAL()</constant>, see
|
||||||
<replaceable>userdata</replaceable> parameter contains a pointer that will be passed to various callback
|
below. The <replaceable>userdata</replaceable> parameter contains a pointer that will be passed
|
||||||
functions. It may be specified as <constant>NULL</constant> if no value is necessary.</para>
|
to various callback functions. It may be specified as <constant>NULL</constant> if no value is
|
||||||
|
necessary. An interface can have any number of vtables attached to it.</para>
|
||||||
|
|
||||||
<para><function>sd_bus_add_fallback_vtable()</function> is similar to
|
<para><function>sd_bus_add_fallback_vtable()</function> is similar to
|
||||||
<function>sd_bus_add_object_vtable()</function>, but is used to register "fallback" attributes. When
|
<function>sd_bus_add_object_vtable()</function>, but is used to register "fallback" attributes.
|
||||||
looking for an attribute declaration, bus object paths registered with
|
When looking for an attribute declaration, bus object paths registered with
|
||||||
<function>sd_bus_add_object_vtable()</function> are checked first. If no match is found, the fallback
|
<function>sd_bus_add_object_vtable()</function> are checked first. If no match is found, the
|
||||||
vtables are checked for each prefix of the bus object path, i.e. with the last slash-separated components
|
fallback vtables are checked for each prefix of the bus object path, i.e. with the last
|
||||||
successively removed. This allows the vtable to be used for an arbitrary number of dynamically created
|
slash-separated components successively removed. This allows the vtable to be used for an
|
||||||
objects.</para>
|
arbitrary number of dynamically created objects.</para>
|
||||||
|
|
||||||
<para>Parameter <replaceable>find</replaceable> is a function which is used to locate the target object
|
<para>Parameter <replaceable>find</replaceable> is a function which is used to locate the target
|
||||||
based on the bus object path <replaceable>path</replaceable>. It must return <constant>1</constant> and
|
object based on the bus object path <replaceable>path</replaceable>. It must return
|
||||||
set the <parameter>ret_found</parameter> output parameter if the object is found, return
|
<constant>1</constant> and set the <parameter>ret_found</parameter> output parameter if the
|
||||||
<constant>0</constant> if the object was not found, and return a negative errno-style error code or
|
object is found, return <constant>0</constant> if the object was not found, and return a
|
||||||
initialize the error structure <replaceable>ret_error</replaceable> on error. The pointer passed in
|
negative errno-style error code or initialize the error structure
|
||||||
<parameter>ret_found</parameter> will be used as the <parameter>userdata</parameter> parameter for the
|
<replaceable>ret_error</replaceable> on error. The pointer passed in
|
||||||
callback functions (offset by the <parameter>offset</parameter> offsets as specified in the vtable
|
<parameter>ret_found</parameter> will be used as the <parameter>userdata</parameter> parameter
|
||||||
entries).</para>
|
for the callback functions (offset by the <parameter>offset</parameter> offsets as specified in
|
||||||
|
the vtable entries).</para>
|
||||||
|
|
||||||
<para>For both functions, a match slot is created internally. If the output parameter
|
<para><function>sd_bus_add_object()</function> attaches a callback directly to the object path
|
||||||
<replaceable>slot</replaceable> is <constant>NULL</constant>, a "floating" slot object is created, see
|
<parameter>path</parameter>. An object path can have any number of callbacks attached to it.
|
||||||
|
Each callback is prepended to the list of callbacks which are always called in order.
|
||||||
|
<function>sd_bus_add_fallback()</function> is similar to
|
||||||
|
<function>sd_bus_add_object()</function> but applies to fallback paths instead.</para>
|
||||||
|
|
||||||
|
<para>When a request is received, any associated callbacks are called sequentially until a
|
||||||
|
callback returns a non-zero integer. Return zero from a callback to give other callbacks the
|
||||||
|
chance to process the request. Callbacks are called in the following order: first, callbacks
|
||||||
|
attached directly to the request object path are called, followed by any D-Bus method callbacks
|
||||||
|
attached to the request object path, interface and member. Finally, the property callbacks
|
||||||
|
attached to the request object path, interface and member are called. If the final callback
|
||||||
|
returns zero, an error reply is sent back to the caller indicating no matching object for the
|
||||||
|
request was found. Note that you can return a positive integer from a callback without
|
||||||
|
immediately sending a reply. This informs sd-bus this callback will take responsibility for
|
||||||
|
replying to the request without forcing the callback to produce a reply immediately. This allows
|
||||||
|
a callback to perform any number of asynchronous operations required to construct a reply. Note
|
||||||
|
that if producing a reply takes too long, the method call will time out at the caller.</para>
|
||||||
|
|
||||||
|
<para>If a callback was invoked to handle a request that expects a reply and the callback
|
||||||
|
returns a negative value, the value is interpreted as a negative errno-style error code and sent
|
||||||
|
back to the caller as a D-Bus error as if
|
||||||
|
<citerefentry><refentrytitle>sd_bus_reply_method_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||||
|
was called. Additionally, all callbacks take a <structname>sd_bus_error</structname> output
|
||||||
|
parameter that can be used to provide more detailed error information. If
|
||||||
|
<parameter>ret_error</parameter> is set when the callback finishes, the corresponding D-Bus
|
||||||
|
error is sent back to the caller as if
|
||||||
|
<citerefentry><refentrytitle>sd_bus_reply_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||||
|
was called. Any error stored in <parameter>ret_error</parameter> takes priority over any
|
||||||
|
negative values returned by the same callback when determining which error to send back to
|
||||||
|
the caller. Use
|
||||||
|
<citerefentry><refentrytitle>sd_bus_error_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||||
|
or one of its variants to set <parameter>ret_error</parameter> and return a negative integer
|
||||||
|
from a callback with a single function call. To send an error reply after a callback has already
|
||||||
|
finished, use
|
||||||
|
<citerefentry><refentrytitle>sd_bus_reply_method_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||||
|
or one of its variants.</para>
|
||||||
|
|
||||||
|
<para>For all functions, a match slot is created internally. If the output parameter
|
||||||
|
<replaceable>slot</replaceable> is <constant>NULL</constant>, a "floating" slot object is
|
||||||
|
created, see
|
||||||
<citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
<citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||||
Otherwise, a pointer to the slot object is returned. In that case, the reference to the slot object
|
Otherwise, a pointer to the slot object is returned. In that case, the reference to the slot
|
||||||
should be dropped when the vtable is not needed anymore, see
|
object should be dropped when the vtable is not needed anymore, see
|
||||||
<citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
<citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
@ -245,23 +307,28 @@
|
|||||||
<term><constant>SD_BUS_METHOD_WITH_OFFSET()</constant></term>
|
<term><constant>SD_BUS_METHOD_WITH_OFFSET()</constant></term>
|
||||||
<term><constant>SD_BUS_METHOD()</constant></term>
|
<term><constant>SD_BUS_METHOD()</constant></term>
|
||||||
|
|
||||||
<listitem><para>Declare a D-Bus method with the name <replaceable>member</replaceable>, parameter
|
<listitem><para>Declare a D-Bus method with the name <replaceable>member</replaceable>,
|
||||||
signature <replaceable>signature</replaceable>, result signature <replaceable>result</replaceable>.
|
parameter signature <replaceable>signature</replaceable>, result signature
|
||||||
Parameters <replaceable>in_names</replaceable> and <replaceable>out_names</replaceable> specify the
|
<replaceable>result</replaceable>. Parameters <replaceable>in_names</replaceable> and
|
||||||
argument names of the input and output arguments in the function signature. The handler function
|
<replaceable>out_names</replaceable> specify the argument names of the input and output
|
||||||
<replaceable>handler</replaceable> must be of type <function>sd_bus_message_handler_t</function>.
|
arguments in the function signature. The handler function
|
||||||
It will be called to handle the incoming messages that call this method. It receives a pointer that
|
<replaceable>handler</replaceable> must be of type
|
||||||
is the <replaceable>userdata</replaceable> parameter passed to the registration function offset by
|
<function>sd_bus_message_handler_t</function>. It will be called to handle the incoming
|
||||||
<replaceable>offset</replaceable> bytes. This may be used to pass pointers to different fields in
|
messages that call this method. It receives a pointer that is the
|
||||||
the same data structure to different methods in the same
|
<replaceable>userdata</replaceable> parameter passed to the registration function offset
|
||||||
vtable. <replaceable>in_names</replaceable> and <replaceable>out_names</replaceable> should be
|
by <replaceable>offset</replaceable> bytes. This may be used to pass pointers to different
|
||||||
created using the <constant>SD_BUS_PARAM()</constant> macro, see below. Parameter
|
fields in the same data structure to different methods in the same vtable. To send a reply
|
||||||
|
from <parameter>handler</parameter>, call
|
||||||
|
<citerefentry><refentrytitle>sd_bus_reply_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||||
|
with the message the callback was invoked with. <replaceable>in_names</replaceable> and
|
||||||
|
<replaceable>out_names</replaceable> should be created using the
|
||||||
|
<constant>SD_BUS_PARAM()</constant> macro, see below. Parameter
|
||||||
<replaceable>flags</replaceable> is a combination of flags, see below.</para>
|
<replaceable>flags</replaceable> is a combination of flags, see below.</para>
|
||||||
|
|
||||||
<para><constant>SD_BUS_METHOD_WITH_NAMES()</constant>,
|
<para><constant>SD_BUS_METHOD_WITH_NAMES()</constant>,
|
||||||
<constant>SD_BUS_METHOD_WITH_OFFSET()</constant>, and <constant>SD_BUS_METHOD()</constant> are
|
<constant>SD_BUS_METHOD_WITH_OFFSET()</constant>, and <constant>SD_BUS_METHOD()</constant>
|
||||||
variants which specify zero offset (<replaceable>userdata</replaceable> parameter is passed with
|
are variants which specify zero offset (<replaceable>userdata</replaceable> parameter is
|
||||||
no change), leave the names unset (i.e. no parameter names), or both.</para>
|
passed with no change), leave the names unset (i.e. no parameter names), or both.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
@ -285,29 +352,31 @@
|
|||||||
<term><constant>SD_BUS_WRITABLE_PROPERTY()</constant></term>
|
<term><constant>SD_BUS_WRITABLE_PROPERTY()</constant></term>
|
||||||
<term><constant>SD_BUS_PROPERTY()</constant></term>
|
<term><constant>SD_BUS_PROPERTY()</constant></term>
|
||||||
|
|
||||||
<listitem><para>Declare a D-Bus property with the name <replaceable>member</replaceable> and value
|
<listitem><para>Declare a D-Bus property with the name <replaceable>member</replaceable>
|
||||||
signature <replaceable>signature</replaceable>. Parameters <replaceable>get</replaceable> and
|
and value signature <replaceable>signature</replaceable>. Parameters
|
||||||
<replaceable>set</replaceable> are the getter and setter methods. They are called with a pointer
|
<replaceable>get</replaceable> and <replaceable>set</replaceable> are the getter and
|
||||||
that is the <replaceable>userdata</replaceable> parameter passed to the registration function
|
setter methods. They are called with a pointer that is the
|
||||||
offset by <replaceable>offset</replaceable> bytes. This may be used pass pointers to different
|
<replaceable>userdata</replaceable> parameter passed to the registration function offset
|
||||||
fields in the same data structure to different setters and getters in the same vtable. Parameter
|
by <replaceable>offset</replaceable> bytes. This may be used pass pointers to different
|
||||||
<replaceable>flags</replaceable> is a combination of flags, see below.</para>
|
fields in the same data structure to different setters and getters in the same vtable.
|
||||||
|
Parameter <replaceable>flags</replaceable> is a combination of flags, see below.</para>
|
||||||
|
|
||||||
<para>The setter and getter methods may be omitted (specified as <constant>NULL</constant>), if the
|
<para>The setter and getter methods may be omitted (specified as
|
||||||
property has one of the basic types or <literal>as</literal> in case of read-only properties. In
|
<constant>NULL</constant>), if the property is one of the basic types or
|
||||||
those cases, the <replaceable>userdata</replaceable> and <replaceable>offset</replaceable>
|
<literal>as</literal> in case of read-only properties. In those cases, the
|
||||||
parameters must together point to valid variable of the corresponding type. A default setter and
|
<replaceable>userdata</replaceable> and <replaceable>offset</replaceable> parameters must
|
||||||
getters will be provided, which simply copy the argument between this variable and the message.
|
together point to a valid variable of the corresponding type. A default setter and getter
|
||||||
|
will be provided, which simply copy the argument between this variable and the message.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para><constant>SD_BUS_PROPERTY()</constant> is used to define a read-only property.</para>
|
<para><constant>SD_BUS_PROPERTY()</constant> is used to define a read-only property.
|
||||||
</listitem>
|
</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><constant>SD_BUS_PARAM()</constant></term>
|
<term><constant>SD_BUS_PARAM()</constant></term>
|
||||||
<listitem><para>Parameter names should be wrapped in this macro, see the example below.</para>
|
<listitem><para>Parameter names should be wrapped in this macro, see the example below.
|
||||||
</listitem>
|
</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</refsect2>
|
</refsect2>
|
||||||
@ -332,10 +401,9 @@
|
|||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><constant>SD_BUS_VTABLE_HIDDEN</constant></term>
|
<term><constant>SD_BUS_VTABLE_HIDDEN</constant></term>
|
||||||
|
|
||||||
<listitem><para>Make this vtable entry hidden. It will not be shown in introspection data. If
|
<listitem><para>Make this vtable entry hidden. It will not be shown in introspection data.
|
||||||
specified for <constant>SD_BUS_VTABLE_START()</constant>, all entries in the array are hidden.
|
If specified for <constant>SD_BUS_VTABLE_START()</constant>, all entries in the array are
|
||||||
</para>
|
hidden.</para></listitem>
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
@ -343,8 +411,7 @@
|
|||||||
|
|
||||||
<listitem><para>Mark this vtable entry as unprivileged. If not specified, the
|
<listitem><para>Mark this vtable entry as unprivileged. If not specified, the
|
||||||
<constant>org.freedesktop.systemd1.Privileged</constant> annotation with value
|
<constant>org.freedesktop.systemd1.Privileged</constant> annotation with value
|
||||||
<literal>true</literal> will be shown in introspection data.</para>
|
<literal>true</literal> will be shown in introspection data.</para></listitem>
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
@ -361,27 +428,28 @@
|
|||||||
<term><constant>SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION</constant></term>
|
<term><constant>SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION</constant></term>
|
||||||
|
|
||||||
<listitem><para>Those three flags correspond to different values of the
|
<listitem><para>Those three flags correspond to different values of the
|
||||||
<constant>org.freedesktop.DBus.Property.EmitsChangedSignal</constant> annotation, which specifies
|
<constant>org.freedesktop.DBus.Property.EmitsChangedSignal</constant> annotation, which
|
||||||
whether the <constant>org.freedesktop.DBus.Properties.PropertiesChanged</constant> signal is
|
specifies whether the
|
||||||
emitted whenever the property changes. <constant>SD_BUS_VTABLE_PROPERTY_CONST</constant> corresponds to
|
<constant>org.freedesktop.DBus.Properties.PropertiesChanged</constant> signal is emitted
|
||||||
<constant>const</constant> and means that the property never changes during the lifetime of the
|
whenever the property changes. <constant>SD_BUS_VTABLE_PROPERTY_CONST</constant>
|
||||||
object it belongs to, so no signal needs to be emitted.
|
corresponds to <constant>const</constant> and means that the property never changes during
|
||||||
<constant>SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE</constant> corresponds to <constant>true</constant> and means
|
the lifetime of the object it belongs to, so no signal needs to be emitted.
|
||||||
that the signal is emitted. <constant>SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION</constant> corresponds to
|
<constant>SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE</constant> corresponds to
|
||||||
<constant>invalidates</constant> and means that the signal is emitted, but the value is not included
|
<constant>true</constant> and means that the signal is emitted.
|
||||||
in the signal.</para>
|
<constant>SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION</constant> corresponds to
|
||||||
</listitem>
|
<constant>invalidates</constant> and means that the signal is emitted, but the value is
|
||||||
|
not included in the signal.</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><constant>SD_BUS_VTABLE_PROPERTY_EXPLICIT</constant></term>
|
<term><constant>SD_BUS_VTABLE_PROPERTY_EXPLICIT</constant></term>
|
||||||
|
|
||||||
<listitem><para>Mark this vtable property entry as requiring explicit request to for the value to
|
<listitem><para>Mark this vtable property entry as requiring explicit request to for the
|
||||||
be shown (generally because the value is large or slow to calculate). This entry cannot be combined
|
value to be shown (generally because the value is large or slow to calculate). This entry
|
||||||
with <constant>SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE</constant>, and will not be shown in property listings by
|
cannot be combined with <constant>SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE</constant>, and will
|
||||||
default (e.g. <command>busctl introspect</command>). This corresponds to the
|
not be shown in property listings by default (e.g. <command>busctl introspect</command>).
|
||||||
<constant>org.freedesktop.systemd1.Explicit</constant> annotation in introspection data.</para>
|
This corresponds to the <constant>org.freedesktop.systemd1.Explicit</constant> annotation
|
||||||
</listitem>
|
in introspection data.</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</refsect2>
|
</refsect2>
|
||||||
@ -395,9 +463,9 @@
|
|||||||
|
|
||||||
<programlisting><xi:include href="vtable-example.c" parse="text" /></programlisting>
|
<programlisting><xi:include href="vtable-example.c" parse="text" /></programlisting>
|
||||||
|
|
||||||
<para>This creates a simple client on the bus (the user bus, when run as normal user).
|
<para>This creates a simple client on the bus (the user bus, when run as normal user). We may
|
||||||
We may use the D-Bus <constant>org.freedesktop.DBus.Introspectable.Introspect</constant>
|
use the D-Bus <constant>org.freedesktop.DBus.Introspectable.Introspect</constant> call to
|
||||||
call to acquire the XML description of the interface:</para>
|
acquire the XML description of the interface:</para>
|
||||||
|
|
||||||
<programlisting><xi:include href="vtable-example.xml" parse="text" /></programlisting>
|
<programlisting><xi:include href="vtable-example.xml" parse="text" /></programlisting>
|
||||||
</example>
|
</example>
|
||||||
@ -407,8 +475,8 @@
|
|||||||
<title>Return Value</title>
|
<title>Return Value</title>
|
||||||
|
|
||||||
<para>On success, <function>sd_bus_add_object_vtable</function> and
|
<para>On success, <function>sd_bus_add_object_vtable</function> and
|
||||||
<function>sd_bus_add_fallback_vtable</function> calls return 0 or a positive integer. On failure, they
|
<function>sd_bus_add_fallback_vtable</function> calls return 0 or a positive integer. On
|
||||||
return a negative errno-style error code.</para>
|
failure, they return a negative errno-style error code.</para>
|
||||||
|
|
||||||
<refsect2>
|
<refsect2>
|
||||||
<title>Errors</title>
|
<title>Errors</title>
|
||||||
@ -419,8 +487,9 @@
|
|||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><constant>-EINVAL</constant></term>
|
<term><constant>-EINVAL</constant></term>
|
||||||
|
|
||||||
<listitem><para>One of the required parameters is <constant>NULL</constant> or invalid. A reserved
|
<listitem><para>One of the required parameters is <constant>NULL</constant> or invalid. A
|
||||||
D-Bus interface was passed as the <replaceable>interface</replaceable> parameter.</para></listitem>
|
reserved D-Bus interface was passed as the <replaceable>interface</replaceable> parameter.
|
||||||
|
</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
@ -445,8 +514,8 @@
|
|||||||
<term><constant>-EPROTOTYPE</constant></term>
|
<term><constant>-EPROTOTYPE</constant></term>
|
||||||
|
|
||||||
<listitem><para><function>sd_bus_add_object_vtable</function> and
|
<listitem><para><function>sd_bus_add_object_vtable</function> and
|
||||||
<function>sd_bus_add_fallback_vtable</function> have been both called
|
<function>sd_bus_add_fallback_vtable</function> have been both called for the same bus
|
||||||
for the same bus object path, which is not allowed.</para></listitem>
|
object path, which is not allowed.</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
Loading…
x
Reference in New Issue
Block a user