[thirdparty/systemd.git] / src / libsystemd / sd-bus / bus-introspect.c

/* SPDX-License-Identifier: LGPL-2.1-or-later */

#include "bus-internal.h"
#include "bus-introspect.h"
#include "bus-objects.h"
#include "bus-protocol.h"
#include "bus-signature.h"
#include "fd-util.h"
#include "fileio.h"
#include "memory-util.h"
#include "memstream-util.h"
#include "string-util.h"

#define BUS_INTROSPECT_DOCTYPE                                       \
        "<!DOCTYPE node PUBLIC \"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN\"\n" \
        "\"https://www.freedesktop.org/standards/dbus/1.0/introspect.dtd\">\n"

#define BUS_INTROSPECT_INTERFACE_PEER                                \
        " <interface name=\"org.freedesktop.DBus.Peer\">\n"             \
        "  <method name=\"Ping\"/>\n"                                   \
        "  <method name=\"GetMachineId\">\n"                            \
        "   <arg type=\"s\" name=\"machine_uuid\" direction=\"out\"/>\n" \
        "  </method>\n"                                                 \
        " </interface>\n"

#define BUS_INTROSPECT_INTERFACE_INTROSPECTABLE                      \
        " <interface name=\"org.freedesktop.DBus.Introspectable\">\n"   \
        "  <method name=\"Introspect\">\n"                              \
        "   <arg name=\"xml_data\" type=\"s\" direction=\"out\"/>\n"    \
        "  </method>\n"                                                 \
        " </interface>\n"

#define BUS_INTROSPECT_INTERFACE_PROPERTIES                          \
        " <interface name=\"org.freedesktop.DBus.Properties\">\n"       \
        "  <method name=\"Get\">\n"                                     \
        "   <arg name=\"interface_name\" direction=\"in\" type=\"s\"/>\n" \
        "   <arg name=\"property_name\" direction=\"in\" type=\"s\"/>\n" \
        "   <arg name=\"value\" direction=\"out\" type=\"v\"/>\n"       \
        "  </method>\n"                                                 \
        "  <method name=\"GetAll\">\n"                                  \
        "   <arg name=\"interface_name\" direction=\"in\" type=\"s\"/>\n" \
        "   <arg name=\"props\" direction=\"out\" type=\"a{sv}\"/>\n"   \
        "  </method>\n"                                                 \
        "  <method name=\"Set\">\n"                                     \
        "   <arg name=\"interface_name\" direction=\"in\" type=\"s\"/>\n" \
        "   <arg name=\"property_name\" direction=\"in\" type=\"s\"/>\n" \
        "   <arg name=\"value\" direction=\"in\" type=\"v\"/>\n"        \
        "  </method>\n"                                                 \
        "  <signal name=\"PropertiesChanged\">\n"                       \
        "   <arg type=\"s\" name=\"interface_name\"/>\n"                \
        "   <arg type=\"a{sv}\" name=\"changed_properties\"/>\n"        \
        "   <arg type=\"as\" name=\"invalidated_properties\"/>\n"       \
        "  </signal>\n"                                                 \
        " </interface>\n"

#define BUS_INTROSPECT_INTERFACE_OBJECT_MANAGER                      \
        " <interface name=\"org.freedesktop.DBus.ObjectManager\">\n"    \
        "  <method name=\"GetManagedObjects\">\n"                       \
        "   <arg type=\"a{oa{sa{sv}}}\" name=\"object_paths_interfaces_and_properties\" direction=\"out\"/>\n" \
        "  </method>\n"                                                 \
        "  <signal name=\"InterfacesAdded\">\n"                         \
        "   <arg type=\"o\" name=\"object_path\"/>\n"                   \
        "   <arg type=\"a{sa{sv}}\" name=\"interfaces_and_properties\"/>\n" \
        "  </signal>\n"                                                 \
        "  <signal name=\"InterfacesRemoved\">\n"                       \
        "   <arg type=\"o\" name=\"object_path\"/>\n"                   \
        "   <arg type=\"as\" name=\"interfaces\"/>\n"                   \
        "  </signal>\n"                                                 \
        " </interface>\n"

int introspect_begin(struct introspect *i, bool trusted) {
        FILE *f;

        assert(i);

        *i = (struct introspect) {
                .trusted = trusted,
        };

        f = memstream_init(&i->m);
        if (!f)
                return -ENOMEM;

        fputs(BUS_INTROSPECT_DOCTYPE
              "<node>\n", f);

        return 0;
}

int introspect_write_default_interfaces(struct introspect *i, bool object_manager) {
        assert(i);
        assert(i->m.f);

        fputs(BUS_INTROSPECT_INTERFACE_PEER
              BUS_INTROSPECT_INTERFACE_INTROSPECTABLE
              BUS_INTROSPECT_INTERFACE_PROPERTIES, i->m.f);

        if (object_manager)
                fputs(BUS_INTROSPECT_INTERFACE_OBJECT_MANAGER, i->m.f);

        return 0;
}

static int set_interface_name(struct introspect *i, const char *interface_name) {
        assert(i);
        assert(i->m.f);

        if (streq_ptr(i->interface_name, interface_name))
                return 0;

        if (i->interface_name)
                fputs(" </interface>\n", i->m.f);

        if (interface_name)
                fprintf(i->m.f, " <interface name=\"%s\">\n", interface_name);

        return free_and_strdup(&i->interface_name, interface_name);
}

int introspect_write_child_nodes(struct introspect *i, OrderedSet *s, const char *prefix) {
        char *node;

        assert(i);
        assert(i->m.f);
        assert(prefix);

        assert_se(set_interface_name(i, NULL) >= 0);

        while ((node = ordered_set_steal_first(s))) {
                const char *e;

                e = object_path_startswith(node, prefix);
                if (e && e[0])
                        fprintf(i->m.f, " <node name=\"%s\"/>\n", e);

                free(node);
        }

        return 0;
}

static void introspect_write_flags(struct introspect *i, int type, uint64_t flags) {
        assert(i);
        assert(i->m.f);

        if (flags & SD_BUS_VTABLE_DEPRECATED)
                fputs("   <annotation name=\"org.freedesktop.DBus.Deprecated\" value=\"true\"/>\n", i->m.f);

        if (type == _SD_BUS_VTABLE_METHOD && (flags & SD_BUS_VTABLE_METHOD_NO_REPLY))
                fputs("   <annotation name=\"org.freedesktop.DBus.Method.NoReply\" value=\"true\"/>\n", i->m.f);

        if (IN_SET(type, _SD_BUS_VTABLE_PROPERTY, _SD_BUS_VTABLE_WRITABLE_PROPERTY)) {
                if (flags & SD_BUS_VTABLE_PROPERTY_EXPLICIT)
                        fputs("   <annotation name=\"org.freedesktop.systemd1.Explicit\" value=\"true\"/>\n", i->m.f);

                if (flags & SD_BUS_VTABLE_PROPERTY_CONST)
                        fputs("   <annotation name=\"org.freedesktop.DBus.Property.EmitsChangedSignal\" value=\"const\"/>\n", i->m.f);
                else if (flags & SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION)
                        fputs("   <annotation name=\"org.freedesktop.DBus.Property.EmitsChangedSignal\" value=\"invalidates\"/>\n", i->m.f);
                else if (!(flags & SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE))
                        fputs("   <annotation name=\"org.freedesktop.DBus.Property.EmitsChangedSignal\" value=\"false\"/>\n", i->m.f);
        }

        if (!i->trusted &&
            IN_SET(type, _SD_BUS_VTABLE_METHOD, _SD_BUS_VTABLE_WRITABLE_PROPERTY) &&
            !(flags & SD_BUS_VTABLE_UNPRIVILEGED))
                fputs("   <annotation name=\"org.freedesktop.systemd1.Privileged\" value=\"true\"/>\n", i->m.f);
}

/* Note that "names" is both an input and an output parameter. It initially points to the first argument name in a
   NULL-separated list of strings, and is then advanced with each argument, and the resulting pointer is returned. */
static int introspect_write_arguments(struct introspect *i, const char *signature, const char **names, const char *direction) {
        int r;

        assert(i);
        assert(i->m.f);

        for (;;) {
                size_t l;

                if (!*signature)
                        return 0;

                r = signature_element_length(signature, &l);
                if (r < 0)
                        return r;

                fprintf(i->m.f, "   <arg type=\"%.*s\"", (int) l, signature);

                if (**names != '\0') {
                        fprintf(i->m.f, " name=\"%s\"", *names);
                        *names += strlen(*names) + 1;
                }

                if (direction)
                        fprintf(i->m.f, " direction=\"%s\"/>\n", direction);
                else
                        fputs("/>\n", i->m.f);

                signature += l;
        }
}

int introspect_write_interface(
                struct introspect *i,
                const char *interface_name,
                const sd_bus_vtable *v) {

        const sd_bus_vtable *vtable = ASSERT_PTR(v);
        const char *names = "";
        int r;

        assert(i);
        assert(i->m.f);
        assert(interface_name);

        r = set_interface_name(i, interface_name);
        if (r < 0)
                return r;

        for (; v->type != _SD_BUS_VTABLE_END; v = bus_vtable_next(vtable, v)) {

                /* Ignore methods, signals and properties that are
                 * marked "hidden", but do show the interface
                 * itself */

                if (v->type != _SD_BUS_VTABLE_START && (v->flags & SD_BUS_VTABLE_HIDDEN))
                        continue;

                switch (v->type) {

                case _SD_BUS_VTABLE_START:
                        if (v->flags & SD_BUS_VTABLE_DEPRECATED)
                                fputs("  <annotation name=\"org.freedesktop.DBus.Deprecated\" value=\"true\"/>\n", i->m.f);
                        break;

                case _SD_BUS_VTABLE_METHOD:
                        fprintf(i->m.f, "  <method name=\"%s\">\n", v->x.method.member);
                        if (bus_vtable_has_names(vtable))
                                names = strempty(v->x.method.names);
                        introspect_write_arguments(i, strempty(v->x.method.signature), &names, "in");
                        introspect_write_arguments(i, strempty(v->x.method.result), &names, "out");
                        introspect_write_flags(i, v->type, v->flags);
                        fputs("  </method>\n", i->m.f);
                        break;

                case _SD_BUS_VTABLE_PROPERTY:
                case _SD_BUS_VTABLE_WRITABLE_PROPERTY:
                        fprintf(i->m.f, "  <property name=\"%s\" type=\"%s\" access=\"%s\">\n",
                                v->x.property.member,
                                v->x.property.signature,
                                v->type == _SD_BUS_VTABLE_WRITABLE_PROPERTY ? "readwrite" : "read");
                        introspect_write_flags(i, v->type, v->flags);
                        fputs("  </property>\n", i->m.f);
                        break;

                case _SD_BUS_VTABLE_SIGNAL:
                        fprintf(i->m.f, "  <signal name=\"%s\">\n", v->x.signal.member);
                        if (bus_vtable_has_names(vtable))
                                names = strempty(v->x.signal.names);
                        introspect_write_arguments(i, strempty(v->x.signal.signature), &names, NULL);
                        introspect_write_flags(i, v->type, v->flags);
                        fputs("  </signal>\n", i->m.f);
                        break;
                }

        }

        return 0;
}

int introspect_finish(struct introspect *i, char **ret) {
        assert(i);
        assert(i->m.f);

        assert_se(set_interface_name(i, NULL) >= 0);

        fputs("</node>\n", i->m.f);

        return memstream_finalize(&i->m, ret, NULL);
}

void introspect_done(struct introspect *i) {
        assert(i);

        /* Normally introspect_finish() does all the work, this is just a backup for error paths */

        memstream_done(&i->m);
        free(i->interface_name);
}
Commit	Line	Data
	1	/* SPDX-License-Identifier: LGPL-2.1-or-later */
	2
	3	#include "bus-internal.h"
	4	#include "bus-introspect.h"
	5	#include "bus-objects.h"
	6	#include "bus-protocol.h"
	7	#include "bus-signature.h"
	8	#include "fd-util.h"
	9	#include "fileio.h"
	10	#include "memory-util.h"
	11	#include "memstream-util.h"
	12	#include "string-util.h"
	13
	14	#define BUS_INTROSPECT_DOCTYPE \
	15	"<!DOCTYPE node PUBLIC \"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN\"\n" \
	16	"\"https://www.freedesktop.org/standards/dbus/1.0/introspect.dtd\">\n"
	17
	18	#define BUS_INTROSPECT_INTERFACE_PEER \
	19	" <interface name=\"org.freedesktop.DBus.Peer\">\n" \
	20	" <method name=\"Ping\"/>\n" \
	21	" <method name=\"GetMachineId\">\n" \
	22	" <arg type=\"s\" name=\"machine_uuid\" direction=\"out\"/>\n" \
	23	" </method>\n" \
	24	" </interface>\n"
	25
	26	#define BUS_INTROSPECT_INTERFACE_INTROSPECTABLE \
	27	" <interface name=\"org.freedesktop.DBus.Introspectable\">\n" \
	28	" <method name=\"Introspect\">\n" \
	29	" <arg name=\"xml_data\" type=\"s\" direction=\"out\"/>\n" \
	30	" </method>\n" \
	31	" </interface>\n"
	32
	33	#define BUS_INTROSPECT_INTERFACE_PROPERTIES \
	34	" <interface name=\"org.freedesktop.DBus.Properties\">\n" \
	35	" <method name=\"Get\">\n" \
	36	" <arg name=\"interface_name\" direction=\"in\" type=\"s\"/>\n" \
	37	" <arg name=\"property_name\" direction=\"in\" type=\"s\"/>\n" \
	38	" <arg name=\"value\" direction=\"out\" type=\"v\"/>\n" \
	39	" </method>\n" \
	40	" <method name=\"GetAll\">\n" \
	41	" <arg name=\"interface_name\" direction=\"in\" type=\"s\"/>\n" \
	42	" <arg name=\"props\" direction=\"out\" type=\"a{sv}\"/>\n" \
	43	" </method>\n" \
	44	" <method name=\"Set\">\n" \
	45	" <arg name=\"interface_name\" direction=\"in\" type=\"s\"/>\n" \
	46	" <arg name=\"property_name\" direction=\"in\" type=\"s\"/>\n" \
	47	" <arg name=\"value\" direction=\"in\" type=\"v\"/>\n" \
	48	" </method>\n" \
	49	" <signal name=\"PropertiesChanged\">\n" \
	50	" <arg type=\"s\" name=\"interface_name\"/>\n" \
	51	" <arg type=\"a{sv}\" name=\"changed_properties\"/>\n" \
	52	" <arg type=\"as\" name=\"invalidated_properties\"/>\n" \
	53	" </signal>\n" \
	54	" </interface>\n"
	55
	56	#define BUS_INTROSPECT_INTERFACE_OBJECT_MANAGER \
	57	" <interface name=\"org.freedesktop.DBus.ObjectManager\">\n" \
	58	" <method name=\"GetManagedObjects\">\n" \
	59	" <arg type=\"a{oa{sa{sv}}}\" name=\"object_paths_interfaces_and_properties\" direction=\"out\"/>\n" \
	60	" </method>\n" \
	61	" <signal name=\"InterfacesAdded\">\n" \
	62	" <arg type=\"o\" name=\"object_path\"/>\n" \
	63	" <arg type=\"a{sa{sv}}\" name=\"interfaces_and_properties\"/>\n" \
	64	" </signal>\n" \
	65	" <signal name=\"InterfacesRemoved\">\n" \
	66	" <arg type=\"o\" name=\"object_path\"/>\n" \
	67	" <arg type=\"as\" name=\"interfaces\"/>\n" \
	68	" </signal>\n" \
	69	" </interface>\n"
	70
	71	int introspect_begin(struct introspect *i, bool trusted) {
	72	FILE *f;
	73
	74	assert(i);
	75
	76	*i = (struct introspect) {
	77	.trusted = trusted,
	78	};
	79
	80	f = memstream_init(&i->m);
	81	if (!f)
	82	return -ENOMEM;
	83
	84	fputs(BUS_INTROSPECT_DOCTYPE
	85	"<node>\n", f);
	86
	87	return 0;
	88	}
	89
	90	int introspect_write_default_interfaces(struct introspect *i, bool object_manager) {
	91	assert(i);
	92	assert(i->m.f);
	93
	94	fputs(BUS_INTROSPECT_INTERFACE_PEER
	95	BUS_INTROSPECT_INTERFACE_INTROSPECTABLE
	96	BUS_INTROSPECT_INTERFACE_PROPERTIES, i->m.f);
	97
	98	if (object_manager)
	99	fputs(BUS_INTROSPECT_INTERFACE_OBJECT_MANAGER, i->m.f);
	100
	101	return 0;
	102	}
	103
	104	static int set_interface_name(struct introspect i, const char interface_name) {
	105	assert(i);
	106	assert(i->m.f);
	107
	108	if (streq_ptr(i->interface_name, interface_name))
	109	return 0;
	110
	111	if (i->interface_name)
	112	fputs(" </interface>\n", i->m.f);
	113
	114	if (interface_name)
	115	fprintf(i->m.f, " <interface name=\"%s\">\n", interface_name);
	116
	117	return free_and_strdup(&i->interface_name, interface_name);
	118	}
	119
	120	int introspect_write_child_nodes(struct introspect i, OrderedSet s, const char *prefix) {
	121	char *node;
	122
	123	assert(i);
	124	assert(i->m.f);
	125	assert(prefix);
	126
	127	assert_se(set_interface_name(i, NULL) >= 0);
	128
	129	while ((node = ordered_set_steal_first(s))) {
	130	const char *e;
	131
	132	e = object_path_startswith(node, prefix);
	133	if (e && e[0])
	134	fprintf(i->m.f, " <node name=\"%s\"/>\n", e);
	135
	136	free(node);
	137	}
	138
	139	return 0;
	140	}
	141
	142	static void introspect_write_flags(struct introspect *i, int type, uint64_t flags) {
	143	assert(i);
	144	assert(i->m.f);
	145
	146	if (flags & SD_BUS_VTABLE_DEPRECATED)
	147	fputs(" <annotation name=\"org.freedesktop.DBus.Deprecated\" value=\"true\"/>\n", i->m.f);
	148
	149	if (type == _SD_BUS_VTABLE_METHOD && (flags & SD_BUS_VTABLE_METHOD_NO_REPLY))
	150	fputs(" <annotation name=\"org.freedesktop.DBus.Method.NoReply\" value=\"true\"/>\n", i->m.f);
	151
	152	if (IN_SET(type, _SD_BUS_VTABLE_PROPERTY, _SD_BUS_VTABLE_WRITABLE_PROPERTY)) {
	153	if (flags & SD_BUS_VTABLE_PROPERTY_EXPLICIT)
	154	fputs(" <annotation name=\"org.freedesktop.systemd1.Explicit\" value=\"true\"/>\n", i->m.f);
	155
	156	if (flags & SD_BUS_VTABLE_PROPERTY_CONST)
	157	fputs(" <annotation name=\"org.freedesktop.DBus.Property.EmitsChangedSignal\" value=\"const\"/>\n", i->m.f);
	158	else if (flags & SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION)
	159	fputs(" <annotation name=\"org.freedesktop.DBus.Property.EmitsChangedSignal\" value=\"invalidates\"/>\n", i->m.f);
	160	else if (!(flags & SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE))
	161	fputs(" <annotation name=\"org.freedesktop.DBus.Property.EmitsChangedSignal\" value=\"false\"/>\n", i->m.f);
	162	}
	163
	164	if (!i->trusted &&
	165	IN_SET(type, _SD_BUS_VTABLE_METHOD, _SD_BUS_VTABLE_WRITABLE_PROPERTY) &&
	166	!(flags & SD_BUS_VTABLE_UNPRIVILEGED))
	167	fputs(" <annotation name=\"org.freedesktop.systemd1.Privileged\" value=\"true\"/>\n", i->m.f);
	168	}
	169
	170	/* Note that "names" is both an input and an output parameter. It initially points to the first argument name in a
	171	NULL-separated list of strings, and is then advanced with each argument, and the resulting pointer is returned. */
	172	static int introspect_write_arguments(struct introspect i, const char signature, const char *names, const char direction) {
	173	int r;
	174
	175	assert(i);
	176	assert(i->m.f);
	177
	178	for (;;) {
	179	size_t l;
	180
	181	if (!*signature)
	182	return 0;
	183
	184	r = signature_element_length(signature, &l);
	185	if (r < 0)
	186	return r;
	187
	188	fprintf(i->m.f, " <arg type=\"%.*s\"", (int) l, signature);
	189
	190	if (**names != '\0') {
	191	fprintf(i->m.f, " name=\"%s\"", *names);
	192	names += strlen(names) + 1;
	193	}
	194
	195	if (direction)
	196	fprintf(i->m.f, " direction=\"%s\"/>\n", direction);
	197	else
	198	fputs("/>\n", i->m.f);
	199
	200	signature += l;
	201	}
	202	}
	203
	204	int introspect_write_interface(
	205	struct introspect *i,
	206	const char *interface_name,
	207	const sd_bus_vtable *v) {
	208
	209	const sd_bus_vtable *vtable = ASSERT_PTR(v);
	210	const char *names = "";
	211	int r;
	212
	213	assert(i);
	214	assert(i->m.f);
	215	assert(interface_name);
	216
	217	r = set_interface_name(i, interface_name);
	218	if (r < 0)
	219	return r;
	220
	221	for (; v->type != _SD_BUS_VTABLE_END; v = bus_vtable_next(vtable, v)) {
	222
	223	/* Ignore methods, signals and properties that are
	224	* marked "hidden", but do show the interface
	225	* itself */
	226
	227	if (v->type != _SD_BUS_VTABLE_START && (v->flags & SD_BUS_VTABLE_HIDDEN))
	228	continue;
	229
	230	switch (v->type) {
	231
	232	case _SD_BUS_VTABLE_START:
	233	if (v->flags & SD_BUS_VTABLE_DEPRECATED)
	234	fputs(" <annotation name=\"org.freedesktop.DBus.Deprecated\" value=\"true\"/>\n", i->m.f);
	235	break;
	236
	237	case _SD_BUS_VTABLE_METHOD:
	238	fprintf(i->m.f, " <method name=\"%s\">\n", v->x.method.member);
	239	if (bus_vtable_has_names(vtable))
	240	names = strempty(v->x.method.names);
	241	introspect_write_arguments(i, strempty(v->x.method.signature), &names, "in");
	242	introspect_write_arguments(i, strempty(v->x.method.result), &names, "out");
	243	introspect_write_flags(i, v->type, v->flags);
	244	fputs(" </method>\n", i->m.f);
	245	break;
	246
	247	case _SD_BUS_VTABLE_PROPERTY:
	248	case _SD_BUS_VTABLE_WRITABLE_PROPERTY:
	249	fprintf(i->m.f, " <property name=\"%s\" type=\"%s\" access=\"%s\">\n",
	250	v->x.property.member,
	251	v->x.property.signature,
	252	v->type == _SD_BUS_VTABLE_WRITABLE_PROPERTY ? "readwrite" : "read");
	253	introspect_write_flags(i, v->type, v->flags);
	254	fputs(" </property>\n", i->m.f);
	255	break;
	256
	257	case _SD_BUS_VTABLE_SIGNAL:
	258	fprintf(i->m.f, " <signal name=\"%s\">\n", v->x.signal.member);
	259	if (bus_vtable_has_names(vtable))
	260	names = strempty(v->x.signal.names);
	261	introspect_write_arguments(i, strempty(v->x.signal.signature), &names, NULL);
	262	introspect_write_flags(i, v->type, v->flags);
	263	fputs(" </signal>\n", i->m.f);
	264	break;
	265	}
	266
	267	}
	268
	269	return 0;
	270	}
	271
	272	int introspect_finish(struct introspect i, char *ret) {
	273	assert(i);
	274	assert(i->m.f);
	275
	276	assert_se(set_interface_name(i, NULL) >= 0);
	277
	278	fputs("</node>\n", i->m.f);
	279
	280	return memstream_finalize(&i->m, ret, NULL);
	281	}
	282
	283	void introspect_done(struct introspect *i) {
	284	assert(i);
	285
	286	/* Normally introspect_finish() does all the work, this is just a backup for error paths */
	287
	288	memstream_done(&i->m);
	289	free(i->interface_name);
	290	}