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