man/sd_bus_path_encode.xml

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