1##
2##  OSSP uuid - Universally Unique Identifier
3##  Copyright (c) 2004-2008 Ralf S. Engelschall <rse@engelschall.com>
4##  Copyright (c) 2004-2008 The OSSP Project <http://www.ossp.org/>
5##
6##  This file is part of OSSP uuid, a library for the generation
7##  of UUIDs which can found at http://www.ossp.org/pkg/lib/uuid/
8##
9##  Permission to use, copy, modify, and distribute this software for
10##  any purpose with or without fee is hereby granted, provided that
11##  the above copyright notice and this permission notice appear in all
12##  copies.
13##
14##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
15##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
16##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
17##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
18##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
19##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
20##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
21##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
22##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
23##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
24##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25##  SUCH DAMAGE.
26##
27##  uuid++.pod: manual page for C++ API
28##
29
30=pod
31
32=head1 NAME
33
34B<OSSP uuid> - B<Universally Unique Identifier> (C++ API)
35
36=head1 VERSION
37
38OSSP uuid UUID_VERSION_STR
39
40=head1 DESCRIPTION
41
42B<uuid++> is the ISO-C++ language binding of the B<OSSP uuid> C API.
43It provides a thin ISO-C++ class B<uuid> wrapping the ISO-C API type
44B<uuid_t>.
45
46=head1 APPLICATION PROGRAMMING INTERFACE
47
48The ISO-C++ Application Programming Interface (API) of B<OSSP uuid>
49consists of the following components:
50
51=head2 CONSTANTS
52
53The constants are the same to those provided by the ISO-C API.
54See uuid(3) for details.
55
56=head2 CLASSES
57
58The following classes are provided:
59
60=over 4
61
62=item B<uuid>
63
64This is the class corresponding to the C API type B<uuid_t>.
65It is the main object.
66
67=item B<uuid_error_t>
68
69This is the class corresponding to the C API function B<uuid_error>.
70It is the object thrown as an exception in case of any errors.
71
72=back
73
74=head2 METHODS
75
76The following methods are provided:
77
78=over 4
79
80=item B<uuid>();
81
82The standard constructor.
83
84=item B<uuid>(const uuid &_obj);
85
86The copy constructor for B<uuid> class.
87
88=item B<uuid>(const uuid_t *_obj);
89
90The import constructor for C API objects.
91
92=item B<uuid>(const void *_bin);
93
94The import constructor for binary representation.
95
96=item B<uuid>(const char *_str);
97
98The import constructor for string representation.
99
100=item ~B<uuid>();
101
102The standard destructor for B<uuid> class.
103
104=item uuid &B<uuid::operator=>(const uuid &_obj);
105
106The assignment operator corresponding to the copy constructor.
107
108=item uuid &B<uuid::operator=>(const uuid_t *_obj);
109
110The assignment operator corresponding to the import constructor for C API objects.
111
112=item uuid &B<uuid::operator=>(const void *_bin);
113
114The assignment operator corresponding to the import constructor for binary representation.
115
116=item uuid &B<uuid::operator=>(const char *_str);
117
118The assignment operator corresponding to the import constructor for string and single integer value representation.
119
120=item uuid B<uuid::clone>(void);
121
122Regular method corresponding to the C API function B<uuid_clone>.
123
124=item void B<uuid::load>(const char *_name);
125
126Regular method corresponding to the C API function B<uuid_load>.
127
128=item void B<uuid::make>(unsigned int _mode, ...);
129
130Regular method corresponding to the C API function B<uuid_make>.
131
132=item int B<uuid::isnil>(void);
133
134Regular method corresponding to the C API function B<uuid_isnil>.
135
136=item int B<uuid::compare>(const uuid &_obj);
137
138Regular method corresponding to the C API function B<uuid_compare>.
139
140=item int B<uuid::operator==>(const uuid &_obj);
141
142The comparison operator corresponding to B<uuid_compare> usage for equality.
143
144=item int B<uuid::operator!=>(const uuid &_obj);
145
146The comparison operator corresponding to B<uuid_compare> usage for inequality.
147
148=item int B<uuid::operatorE<lt>>(const uuid &_obj);
149
150The comparison operator corresponding to B<uuid_compare> usage for less-than.
151
152=item int B<uuid::operatorE<lt>=>(const uuid &_obj);
153
154The comparison operator corresponding to B<uuid_compare> usage for less-than-or-equal.
155
156=item int B<uuid::operatorE<gt>>(const uuid &_obj);
157
158The comparison operator corresponding to B<uuid_compare> usage for greater-than.
159
160=item int B<uuid::operatorE<gt>=>(const uuid &_obj);
161
162The comparison operator corresponding to B<uuid_compare> usage for greater-than-or-equal.
163
164=item void B<uuid::import>(const void *_bin);
165
166Regular method corresponding to the C API function B<uuid_import> for binary representation usage.
167
168=item void B<uuid::import>(const char *_str);
169
170Regular method corresponding to the C API function B<uuid_import> for string representation usage.
171
172=item void *B<uuid::binary>(void);
173
174Regular method corresponding to the C API function B<uuid_export> for binary representation usage.
175
176=item char *B<uuid::string>(void);
177
178Regular method corresponding to the C API function B<uuid_export> for string representation usage.
179
180=item char *B<uuid::integer>(void);
181
182Regular method corresponding to the C API function B<uuid_export> for single integer value representation usage.
183
184=item char *B<uuid::summary>(void);
185
186Regular method corresponding to the C API function B<uuid_export> for textual summary representation usage.
187
188=item unsigned long B<uuid::version>(void);
189
190Regular method corresponding to the C API function B<uuid_version>.
191
192=item B<uuid_error_t>()
193
194The standard constructor for B<uuid_error_t> class.
195
196=item B<uuid_error_t>(uuid_rc_t _code)
197
198The standard constructor for B<uuid_error_t> class with return code initialization.
199
200=item ~B<uuid_error_t>()
201
202The standard destructor for B<uuid_error_t> class.
203
204=item void B<uuid_error_t::code>(uuid_rc_t _code)
205
206Regular method for setting the return code.
207
208=item uuid_rc_t B<uuid_error_t::code>(void)
209
210Regular method for fetching the return code.
211
212=item char *B<uuid_error_t::string>(void)
213
214Regular method for fetching the string corresponding to the current return code.
215
216=back
217
218=head1 EXAMPLE
219
220The following shows an example usage of the C++ API. Exception handling is
221omitted for code simplification and has to be re-added for production
222code.
223
224 /* generate a DCE 1.1 v1 UUID from system environment */
225 char *uuid_v1(void)
226 {
227     uuid id;
228     char *str;
229
230     id.make(UUID_MAKE_V1);
231     str = id.string();
232     return str;
233 }
234
235 /* generate a DCE 1.1 v3 UUID from an URL */
236 char *uuid_v3(const char *url)
237 {
238     uuid id;
239     uuid id_ns;
240     char *str;
241
242     id_ns.load("ns:URL");
243     id.make(UUID_MAKE_V3, &id_ns, url);
244     str = id.string();
245     return str;
246 }
247
248=head1 SEE ALSO
249
250uuid(3).
251
252=cut
253
254