summaryrefslogtreecommitdiff
path: root/man/sd_bus_path_encode.xml
blob: 986eccc6a8a1c8a79ba043179d0a5987d6b4ebc9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2014 Zbigniew Jędrzejewski-Szmek

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="sd_bus_path_encode">

  <refentryinfo>
    <title>sd_bus_path_encode</title>
    <productname>systemd</productname>

    <authorgroup>
      <author>
        <contrib>A monkey with a typewriter</contrib>
        <firstname>Zbigniew</firstname>
        <surname>Jędrzejewski-Szmek</surname>
        <email>zbyszek@in.waw.pl</email>
      </author>
    </authorgroup>
  </refentryinfo>

  <refmeta>
    <refentrytitle>sd_bus_path_encode</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>sd_bus_path_encode</refname>
    <refname>sd_bus_path_encode_many</refname>
    <refname>sd_bus_path_decode</refname>
    <refname>sd_bus_path_decode_many</refname>

    <refpurpose>Convert an external identifier into an object path and back</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>

      <funcprototype>
        <funcdef>int <function>sd_bus_path_encode</function></funcdef>
        <paramdef>const char *<parameter>prefix</parameter></paramdef>
        <paramdef>const char *<parameter>external_id</parameter></paramdef>
        <paramdef>char **<parameter>ret_path</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_bus_path_encode_many</function></funcdef>
        <paramdef>char **<parameter>out</parameter></paramdef>
        <paramdef>const char *<parameter>path_template</parameter></paramdef>
        <paramdef>…</paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_bus_path_decode</function></funcdef>
        <paramdef>const char *<parameter>path</parameter></paramdef>
        <paramdef>const char *<parameter>prefix</parameter></paramdef>
        <paramdef>char **<parameter>ret_external_id</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_bus_path_decode_many</function></funcdef>
        <paramdef>const char *<parameter>path</parameter></paramdef>
        <paramdef>const char *<parameter>path_template</parameter></paramdef>
        <paramdef>…</paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><function>sd_bus_path_encode()</function> and
    <function>sd_bus_path_decode()</function> convert external
    identifier strings into object paths and back. These functions are
    useful to map application-specific string identifiers of any kind
    into bus object paths in a simple, reversible and safe way.</para>

    <para><function>sd_bus_path_encode()</function> takes a bus path
    prefix and an external identifier string as arguments, plus a
    place to store the returned bus path string. The bus path prefix
    must be a valid bus path, starting with a slash
    <literal>/</literal>, and not ending in one. The external
    identifier string may be in any format, may be the empty string,
    and has no restrictions on the charset — however, it must
    always be <constant>NUL</constant>-terminated. The returned string
    will be the concatenation of the bus path prefix plus an escaped
    version of the external identifier string. This operation may be
    reversed with <function>sd_bus_decode()</function>. It is
    recommended to only use external identifiers that generally
    require little escaping to be turned into valid bus path
    identifiers (for example, by sticking to a 7-bit ASCII character
    set), in order to ensure the resulting bus path is still short and
    easily processed.</para>

    <para><function>sd_bus_path_decode()</function> reverses the
    operation of <function>sd_bus_path_encode()</function> and thus
    regenerates an external identifier string from a bus path. It
    takes a bus path and a prefix string, plus a place to store the
    returned external identifier string. If the bus path does not
    start with the specified prefix, 0 is returned and the returned
    string is set to <constant>NULL</constant>. Otherwise, the
    string following the prefix is unescaped and returned in the
    external identifier string.</para>

    <para>The escaping used will replace all characters which are
    invalid in a bus object path by <literal>_</literal>, followed by a
    hexadecimal value. As a special case, the empty string will be
    replaced by a lone <literal>_</literal>.</para>

    <para><function>sd_bus_path_encode_many()</function> works like
    its counterpart <function>sd_bus_path_encode()</function>, but
    takes a path template as argument and encodes multiple labels
    according to its embedded directives. For each
    <literal>%</literal> character found in the template, the caller
    must provide a string via varargs, which will be encoded and
    embedded at the position of the <literal>%</literal> character.
    Any other character in the template is copied verbatim into the
    encoded path.</para>

    <para><function>sd_bus_path_decode_many()</function> does the
    reverse of <function>sd_bus_path_encode_many()</function>. It
    decodes the passed object path according to the given
    path template. For each <literal>%</literal> character in the
    template, the caller must provide an output storage
    (<literal>char **</literal>) via varargs. The decoded label
    will be stored there. Each <literal>%</literal> character will
    only match the current label. It will never match across labels.
    Furthermore, only a single directive is allowed per label.
    If <literal>NULL</literal> is passed as output storage, the
    label is verified but not returned to the caller.</para>
  </refsect1>

  <refsect1>
    <title>Return Value</title>

    <para>On success, <function>sd_bus_path_encode()</function>
    returns positive or 0, and a valid bus path in the return
    argument. On success, <function>sd_bus_path_decode()</function>
    returns a positive value if the prefixed matched, or 0 if it
    did not. If the prefix matched, the external identifier is returned
    in the return parameter. If it did not match, NULL is returned in
    the return parameter. On failure, a negative errno-style error
    number is returned by either function. The returned strings must
    be
    <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>'d
    by the caller.</para>
  </refsect1>

  <refsect1>
    <title>Notes</title>

    <para><function>sd_bus_path_encode()</function> and
    <function>sd_bus_path_decode()</function> are available as a
    shared library, which can be compiled and linked to with the
    <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
    file.</para>
  </refsect1>

  <refsect1>
    <title>See Also</title>

    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    </para>
  </refsect1>

</refentry>