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