man/sd_bus_path_encode.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="sd_bus_path_encode">
  10
  11   <refentryinfo>
  12     <title>sd_bus_path_encode</title>
  13     <productname>systemd</productname>
  14   </refentryinfo>
  15
  16   <refmeta>
  17     <refentrytitle>sd_bus_path_encode</refentrytitle>
  18     <manvolnum>3</manvolnum>
  19   </refmeta>
  20
  21   <refnamediv>
  22     <refname>sd_bus_path_encode</refname>
  23     <refname>sd_bus_path_encode_many</refname>
  24     <refname>sd_bus_path_decode</refname>
  25     <refname>sd_bus_path_decode_many</refname>
  26
  27     <refpurpose>Convert an external identifier into an object path and back</refpurpose>
  28   </refnamediv>
  29
  30   <refsynopsisdiv>
  31     <funcsynopsis>
  32       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  33
  34       <funcprototype>
  35         <funcdef>int <function>sd_bus_path_encode</function></funcdef>
  36         <paramdef>const char *<parameter>prefix</parameter></paramdef>
  37         <paramdef>const char *<parameter>external_id</parameter></paramdef>
  38         <paramdef>char **<parameter>ret_path</parameter></paramdef>
  39       </funcprototype>
  40
  41       <funcprototype>
  42         <funcdef>int <function>sd_bus_path_encode_many</function></funcdef>
  43         <paramdef>char **<parameter>out</parameter></paramdef>
  44         <paramdef>const char *<parameter>path_template</parameter></paramdef>
  45         <paramdef>…</paramdef>
  46       </funcprototype>
  47
  48       <funcprototype>
  49         <funcdef>int <function>sd_bus_path_decode</function></funcdef>
  50         <paramdef>const char *<parameter>path</parameter></paramdef>
  51         <paramdef>const char *<parameter>prefix</parameter></paramdef>
  52         <paramdef>char **<parameter>ret_external_id</parameter></paramdef>
  53       </funcprototype>
  54
  55       <funcprototype>
  56         <funcdef>int <function>sd_bus_path_decode_many</function></funcdef>
  57         <paramdef>const char *<parameter>path</parameter></paramdef>
  58         <paramdef>const char *<parameter>path_template</parameter></paramdef>
  59         <paramdef>…</paramdef>
  60       </funcprototype>
  61     </funcsynopsis>
  62   </refsynopsisdiv>
  63
  64   <refsect1>
  65     <title>Description</title>
  66
  67     <para><function>sd_bus_path_encode()</function> and
  68     <function>sd_bus_path_decode()</function> convert external
  69     identifier strings into object paths and back. These functions are
  70     useful to map application-specific string identifiers of any kind
  71     into bus object paths in a simple, reversible and safe way.</para>
  72
  73     <para><function>sd_bus_path_encode()</function> takes a bus path
  74     prefix and an external identifier string as arguments, plus a
  75     place to store the returned bus path string. The bus path prefix
  76     must be a valid bus path, starting with a slash
  77     <literal>/</literal>, and not ending in one. The external
  78     identifier string may be in any format, may be the empty string,
  79     and has no restrictions on the charset — however, it must
  80     always be <constant>NUL</constant>-terminated. The returned string
  81     will be the concatenation of the bus path prefix plus an escaped
  82     version of the external identifier string. This operation may be
  83     reversed with <function>sd_bus_decode()</function>. It is
  84     recommended to only use external identifiers that generally
  85     require little escaping to be turned into valid bus path
  86     identifiers (for example, by sticking to a 7-bit ASCII character
  87     set), in order to ensure the resulting bus path is still short and
  88     easily processed.</para>
  89
  90     <para><function>sd_bus_path_decode()</function> reverses the
  91     operation of <function>sd_bus_path_encode()</function> and thus
  92     regenerates an external identifier string from a bus path. It
  93     takes a bus path and a prefix string, plus a place to store the
  94     returned external identifier string. If the bus path does not
  95     start with the specified prefix, 0 is returned and the returned
  96     string is set to <constant>NULL</constant>. Otherwise, the
  97     string following the prefix is unescaped and returned in the
  98     external identifier string.</para>
  99
 100     <para>The escaping used will replace all characters which are
 101     invalid in a bus object path by <literal>_</literal>, followed by a
 102     hexadecimal value. As a special case, the empty string will be
 103     replaced by a lone <literal>_</literal>.</para>
 104
 105     <para><function>sd_bus_path_encode_many()</function> works like
 106     its counterpart <function>sd_bus_path_encode()</function>, but
 107     takes a path template as argument and encodes multiple labels
 108     according to its embedded directives. For each
 109     <literal>%</literal> character found in the template, the caller
 110     must provide a string via varargs, which will be encoded and
 111     embedded at the position of the <literal>%</literal> character.
 112     Any other character in the template is copied verbatim into the
 113     encoded path.</para>
 114
 115     <para><function>sd_bus_path_decode_many()</function> does the
 116     reverse of <function>sd_bus_path_encode_many()</function>. It
 117     decodes the passed object path according to the given
 118     path template. For each <literal>%</literal> character in the
 119     template, the caller must provide an output storage
 120     (<literal>char **</literal>) via varargs. The decoded label
 121     will be stored there. Each <literal>%</literal> character will
 122     only match the current label. It will never match across labels.
 123     Furthermore, only a single directive is allowed per label.
 124     If <literal>NULL</literal> is passed as output storage, the
 125     label is verified but not returned to the caller.</para>
 126   </refsect1>
 127
 128   <refsect1>
 129     <title>Return Value</title>
 130
 131     <para>On success, <function>sd_bus_path_encode()</function>
 132     returns positive or 0, and a valid bus path in the return
 133     argument. On success, <function>sd_bus_path_decode()</function>
 134     returns a positive value if the prefixed matched, or 0 if it
 135     did not. If the prefix matched, the external identifier is returned
 136     in the return parameter. If it did not match, NULL is returned in
 137     the return parameter. On failure, a negative errno-style error
 138     number is returned by either function. The returned strings must
 139     be
 140     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>'d
 141     by the caller.</para>
 142   </refsect1>
 143
 144   <refsect1>
 145     <title>Notes</title>
 146
 147     <para><function>sd_bus_path_encode()</function> and
 148     <function>sd_bus_path_decode()</function> are available as a
 149     shared library, which can be compiled and linked to with the
 150     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 151     file.</para>
 152   </refsect1>
 153
 154   <refsect1>
 155     <title>See Also</title>
 156
 157     <para>
 158       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 159       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 160       <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 161     </para>
 162   </refsect1>
 163
 164 </refentry>