sd_bus_emit_signal_to(3)

1SD_BUS_EMIT_SIGNAL(3)         sd_bus_emit_signal         SD_BUS_EMIT_SIGNAL(3)
2
3
4

NAME

6       sd_bus_emit_signal, sd_bus_emit_signalv, sd_bus_emit_signal_to,
7       sd_bus_emit_signal_tov, sd_bus_emit_interfaces_added,
8       sd_bus_emit_interfaces_added_strv, sd_bus_emit_interfaces_removed,
9       sd_bus_emit_interfaces_removed_strv, sd_bus_emit_properties_changed,
10       sd_bus_emit_properties_changed_strv, sd_bus_emit_object_added,
11       sd_bus_emit_object_removed - Convenience functions for emitting
12       (standard) D-Bus signals
13

SYNOPSIS

15       #include <systemd/sd-bus-vtable.h>
16
17       int sd_bus_emit_signal(sd_bus *bus, const char *path,
18                              const char *interface, const char *member,
19                              const char *types, ...);
20
21       int sd_bus_emit_signalv(sd_bus *bus, const char *path,
22                               const char *interface, const char *member,
23                               const char *types, va_list ap);
24
25       int sd_bus_emit_signal_to(sd_bus *bus, const char *destination,
26                                 const char *path, const char *interface,
27                                 const char *member, const char *types, ...);
28
29       int sd_bus_emit_signal_tov(sd_bus *bus, const char *destination,
30                                  const char *path, const char *interface,
31                                  const char *member, const char *types,
32                                  va_list ap);
33
34       int sd_bus_emit_interfaces_added(sd_bus *bus, const char *path,
35                                        const char *interface, ...);
36
37       int sd_bus_emit_interfaces_added_strv(sd_bus *bus, const char *path,
38                                             const char **interfaces);
39
40       int sd_bus_emit_interfaces_removed(sd_bus *bus, const char *path,
41                                          const char *interface, ...);
42
43       int sd_bus_emit_interfaces_removed_strv(sd_bus *bus, const char *path,
44                                               const char **interfaces);
45
46       int sd_bus_emit_properties_changed(sd_bus *bus, const char *path,
47                                          const char *interface,
48                                          const char *name, ...);
49
50       int sd_bus_emit_properties_changed_strv(sd_bus *bus, const char *path,
51                                               const char *interface,
52                                               const char **names);
53
54       int sd_bus_emit_object_added(sd_bus *bus, const char *path);
55
56       int sd_bus_emit_object_removed(sd_bus *bus, const char *path);
57

DESCRIPTION

59       sd_bus_emit_signal() is a convenience function for initializing a bus
60       message object and emitting the corresponding D-Bus signal. It combines
61       the sd_bus_message_new_signal(3), sd_bus_message_append(3) and
62       sd_bus_send(3) functions into a single function call.
63       sd_bus_emit_signalv() is equivalent to sd_bus_message_append(), except
64       that it is called with a "va_list" instead of a variable number of
65       arguments.
66
67       sd_bus_emit_signal_to() and sd_bus_emit_signal_tov() are identical to
68       sd_bus_emit_signal() and sd_bus_emit_signalv(), except that they can
69       emit the signal to a single destination. Give destination as NULL to
70       broadcast the signal.
71
72       sd_bus_emit_interfaces_added() and sd_bus_emit_interfaces_removed() are
73       used to implement the InterfacesAdded and InterfacesRemoved signals of
74       the org.freedesktop.DBus.ObjectManager interface. They take a path
75       whose interfaces have been modified as an argument and a variable list
76       of interfaces that have been added or removed, respectively. The final
77       argument passed to sd_bus_emit_interfaces_added() and
78       sd_bus_emit_interfaces_removed() must be NULL. This allows both
79       functions to safely determine the number of passed interface arguments.
80       sd_bus_emit_interfaces_added_strv() and
81       sd_bus_emit_interfaces_removed_strv() are identical to their respective
82       counterparts but both take the list of interfaces as a single argument
83       instead of a variable number of arguments.
84
85       sd_bus_emit_properties_changed() is used to implement the
86       PropertiesChanged signal of the org.freedesktop.DBus.Properties
87       interface. It takes an object path, interface and a variable list of
88       property names as its arguments. The final argument passed to
89       sd_bus_emit_properties_changed() must be NULL. This allows it to safely
90       determine the number of passed property names.
91       sd_bus_emit_properties_changed_strv() is identical to
92       sd_bus_emit_properties_changed() but takes the list of property names
93       as a single argument instead of a variable number of arguments.
94
95       sd_bus_emit_object_added() and sd_bus_emit_object_removed() are
96       convenience functions for emitting the InterfacesAdded or
97       InterfacesRemoved signals for all interfaces registered on a specific
98       object path, respectively. This includes any parent fallback vtables if
99       they are not overridden by a more applicable child vtable. It also
100       includes all the standard D-Bus interfaces implemented by sd-bus itself
101       on any registered object.
102
103       Note that sd_bus_emit_interfaces_added(),
104       sd_bus_emit_interfaces_removed(), sd_bus_emit_object_added() and
105       sd_bus_emit_object_removed() require an object manager to have been
106       registered on the given object path or one of its parent object paths
107       using sd_bus_add_object_manager(3).
108

RETURN VALUE

110       On success, these functions return a non-negative integer. On failure,
111       they return a negative errno-style error code.
112
113   Errors
114       Returned errors may indicate the following problems:
115
116       -EINVAL
117           One of the required parameters is NULL or invalid. A reserved D-Bus
118           interface was passed as the interface parameter.
119
120       -ENOPKG
121           The bus cannot be resolved.
122
123       -ECHILD
124           The bus was created in a different process, library or module
125           instance.
126
127       -ENOMEM
128           Memory allocation failed.
129
130       -ESRCH
131           One of sd_bus_emit_interfaces_added(),
132           sd_bus_emit_interfaces_removed(), sd_bus_emit_object_added() or
133           sd_bus_emit_object_removed() was called on an object without an
134           object manager registered on its own object path or one of its
135           parent object paths.
136
137       See the man pages of sd_bus_message_new_signal(3),
138       sd_bus_message_append(3) and sd_bus_send(3) for more possible errors.
139

NOTES

141       Functions described here are available as a shared library, which can
142       be compiled against and linked to with the libsystemd pkg-config(1)
143       file.
144
145       The code described here uses getenv(3), which is declared to be not
146       multi-thread-safe. This means that the code calling the functions
147       described here must not call setenv(3) from a parallel thread. It is
148       recommended to only do calls to setenv() from an early phase of the
149       program when no other threads have been started.
150

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

SEE ALSO