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 systemd.
   7
   8 Copyright 2014 Zbigniew Jędrzejewski-Szmek
   9
  10 systemd 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 systemd 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 systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="sd_bus_path_encode" conditional="ENABLE_KDBUS">
  25
  26   <refentryinfo>
  27     <title>sd_bus_path_encode</title>
  28     <productname>systemd</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_decode</refname>
  48
  49     <refpurpose>Convert an external identifier into an object path and back</refpurpose>
  50   </refnamediv>
  51
  52   <refsynopsisdiv>
  53     <funcsynopsis>
  54       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  55
  56       <funcprototype>
  57         <funcdef>int <function>sd_bus_path_encode</function></funcdef>
  58         <paramdef>const char *<parameter>prefix</parameter></paramdef>
  59         <paramdef>const char *<parameter>external_id</parameter></paramdef>
  60         <paramdef>char **<parameter>ret_path</parameter></paramdef>
  61       </funcprototype>
  62
  63       <funcprototype>
  64         <funcdef>int <function>sd_bus_path_decode</function></funcdef>
  65         <paramdef>const char *<parameter>prefix</parameter></paramdef>
  66         <paramdef>const char *<parameter>path</parameter></paramdef>
  67         <paramdef>char **<parameter>ret_external_id</parameter></paramdef>
  68       </funcprototype>
  69     </funcsynopsis>
  70   </refsynopsisdiv>
  71
  72   <refsect1>
  73     <title>Description</title>
  74
  75     <para><function>sd_bus_path_encode()</function> and
  76     <function>sd_bus_path_decode()</function> convert external
  77     identifier strings into object paths and back. These functions are
  78     useful to map application-specific string identifiers of any kind
  79     into bus object paths in a simple, reversible and safe way.</para>
  80
  81     <para><function>sd_bus_path_encode()</function> takes a bus path
  82     prefix and an external identifier string as arguments, plus a
  83     place to store the returned bus path string. The bus path prefix
  84     must be a valid bus path, starting with a slash
  85     <literal>/</literal>, and not ending in one. The external
  86     identifier string may be in any format, may be the empty string,
  87     and has no restrictions on the charset — however, it must
  88     always be <constant>NUL</constant>-terminated. The returned string
  89     will be the concatenation of the bus path prefix plus an escaped
  90     version of the external identifier string. This operation may be
  91     reversed with <function>sd_bus_decode()</function>. It is
  92     recommended to only use external identifiers that generally
  93     require little escaping to be turned into valid bus path
  94     identifiers (for example, by sticking to a 7-bit ASCII character
  95     set), in order to ensure the resulting bus path is still short and
  96     easily processed.</para>
  97
  98     <para><function>sd_bus_path_decode()</function> reverses the
  99     operation of <function>sd_bus_path_encode()</function> and thus
 100     regenerates an external identifier string from a bus path. It
 101     takes a bus path and a prefix string, plus a place to store the
 102     returned external identifier string. If the bus path does not
 103     start with the specified prefix, 0 is returned and the returned
 104     string is set to <constant>NULL</constant>. Otherwise, the
 105     string following the prefix is unescaped and returned in the
 106     external identifier string.</para>
 107
 108     <para>The escaping used will replace all characters which are
 109     invalid in a bus object path by <literal>_</literal>, followed by a
 110     hexadecimal value. As a special case, the empty string will be
 111     replaced by a lone <literal>_</literal>.</para>
 112   </refsect1>
 113
 114   <refsect1>
 115     <title>Return Value</title>
 116
 117     <para>On success, <function>sd_bus_path_encode()</function>
 118     returns positive or 0, and a valid bus path in the return
 119     argument. On success, <function>sd_bus_path_decode()</function>
 120     returns a positive value if the prefixed matched, or 0 if it
 121     did not. If the prefix matched, the external identifier is returned
 122     in the return parameter. If it did not match, NULL is returned in
 123     the return parameter. On failure, a negative errno-style error
 124     number is returned by either function. The returned strings must
 125     be
 126     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>'d
 127     by the caller.</para>
 128   </refsect1>
 129
 130   <refsect1>
 131     <title>Notes</title>
 132
 133     <para><function>sd_bus_path_encode()</function> and
 134     <function>sd_bus_path_decode()</function> are available as a
 135     shared library, which can be compiled and linked to with the
 136     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 137     file.</para>
 138   </refsect1>
 139
 140   <refsect1>
 141     <title>See Also</title>
 142
 143     <para>
 144       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 145       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 146       <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 147     </para>
 148   </refsect1>
 149
 150 </refentry>