sd_bus_path_encode.xml revision 3802a3d3d7af51ddff31943d5514382f01265770
3802a3d3d7af51ddff31943d5514382f01265770Lennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
a6278b88305b237b02eabff0d870b57fe851822dLennart PoetteringThis file is part of systemd.
a6278b88305b237b02eabff0d870b57fe851822dLennart PoetteringCopyright 2014 Zbigniew Jędrzejewski-Szmek
a6278b88305b237b02eabff0d870b57fe851822dLennart Poetteringsystemd is free software; you can redistribute it and/or modify it
a6278b88305b237b02eabff0d870b57fe851822dLennart Poetteringunder the terms of the GNU Lesser General Public License as published by
a6278b88305b237b02eabff0d870b57fe851822dLennart Poetteringthe Free Software Foundation; either version 2.1 of the License, or
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering(at your option) any later version.
a6278b88305b237b02eabff0d870b57fe851822dLennart Poetteringsystemd is distributed in the hope that it will be useful, but
a6278b88305b237b02eabff0d870b57fe851822dLennart PoetteringWITHOUT ANY WARRANTY; without even the implied warranty of
a6278b88305b237b02eabff0d870b57fe851822dLennart PoetteringMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
a6278b88305b237b02eabff0d870b57fe851822dLennart PoetteringLesser General Public License for more details.
a6278b88305b237b02eabff0d870b57fe851822dLennart PoetteringYou should have received a copy of the GNU Lesser General Public License
a6278b88305b237b02eabff0d870b57fe851822dLennart Poetteringalong with systemd; If not, see <http://www.gnu.org/licenses/>.
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering<refentry id="sd_bus_path_encode" conditional="ENABLE_KDBUS">
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <refentryinfo>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <contrib>A monkey with a typewriter</contrib>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering </authorgroup>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering </refentryinfo>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <refentrytitle>sd_bus_path_encode</refentrytitle>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <refpurpose>Convert an external identifier into an object path and back</refpurpose>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <refsynopsisdiv>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <funcsynopsis>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <funcprototype>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <funcdef>int <function>sd_bus_path_encode</function></funcdef>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <paramdef>const char *<parameter>prefix</parameter></paramdef>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <paramdef>const char *<parameter>external_id</parameter></paramdef>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <paramdef>char **<parameter>ret_path</parameter></paramdef>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering </funcprototype>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <funcprototype>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <funcdef>int <function>sd_bus_path_decode</function></funcdef>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <paramdef>const char *<parameter>prefix</parameter></paramdef>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <paramdef>const char *<parameter>path</parameter></paramdef>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <paramdef>char **<parameter>ret_external_id</parameter></paramdef>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering </funcprototype>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering </funcsynopsis>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering </refsynopsisdiv>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <para><function>sd_bus_path_encode()</function> and
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <function>sd_bus_path_decode()</function> convert external
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering identifier strings into object paths and back. These functions are
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering useful to map application-specific string identifiers of any kind
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering into bus object paths in a simple, reversible and safe way.</para>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <para><function>sd_bus_path_encode()</function> takes a bus path
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering prefix and an external identifier string as arguments, plus a
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering place to store the returned bus path string. The bus path prefix
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering must be a valid bus path, starting with a slash
b8bde11658366290521e3d03316378b482600323Jan Engelhardt <literal>/</literal>, and not ending in one. The external
b8bde11658366290521e3d03316378b482600323Jan Engelhardt identifier string may be in any format, may be the empty string,
b8bde11658366290521e3d03316378b482600323Jan Engelhardt and has no restrictions on the charset — however, it must
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering always be <constant>NUL</constant>-terminated. The returned string
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering will be the concatenation of the bus path prefix plus an escaped
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering version of the external identifier string. This operation may be
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering reversed with <function>sd_bus_decode()</function>. It is
b8bde11658366290521e3d03316378b482600323Jan Engelhardt recommended to only use external identifiers that generally
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering require little escaping to be turned into valid bus path
b8bde11658366290521e3d03316378b482600323Jan Engelhardt identifiers (for example, by sticking to a 7-bit ASCII character
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering set), in order to ensure the resulting bus path is still short and
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering easily processed.</para>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <para><function>sd_bus_path_decode()</function> reverses the
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering operation of <function>sd_bus_path_encode()</function> and thus
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering regenerates an external identifier string from a bus path. It
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering takes a bus path and a prefix string, plus a place to store the
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering returned external identifier string. If the bus path does not
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering start with the specified prefix, 0 is returned and the returned
b8bde11658366290521e3d03316378b482600323Jan Engelhardt string is set to <constant>NULL</constant>. Otherwise, the
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering string following the prefix is unescaped and returned in the
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering external identifier string.</para>
dca348bcbb462305864526c587495a14a76bfcdeJan Engelhardt <para>The escaping used will replace all characters which are
b8bde11658366290521e3d03316378b482600323Jan Engelhardt invalid in a bus object path by <literal>_</literal>, followed by a
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering hexadecimal value. As a special case, the empty string will be
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering replaced by a lone <literal>_</literal>.</para>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <para>On success, <function>sd_bus_path_encode()</function>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering returns positive or 0, and a valid bus path in the return
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering argument. On success, <function>sd_bus_path_decode()</function>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering returns a positive value if the prefixed matched, or 0 if it
b8bde11658366290521e3d03316378b482600323Jan Engelhardt did not. If the prefix matched, the external identifier is returned
b8bde11658366290521e3d03316378b482600323Jan Engelhardt in the return parameter. If it did not match, NULL is returned in
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering the return parameter. On failure, a negative errno-style error
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering number is returned by either function. The returned strings must
5aded369782f28255bc6b494ca905d7acaea7a56Zbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>'d
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering by the caller.</para>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <para><function>sd_bus_path_encode()</function> and
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <function>sd_bus_path_decode()</function> are available as a
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering shared library, which can be compiled and linked to with the
5aded369782f28255bc6b494ca905d7acaea7a56Zbigniew Jędrzejewski-Szmek <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
5aded369782f28255bc6b494ca905d7acaea7a56Zbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>