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