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