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