man/sd_bus_path_encode.xml

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