Merge "Applied reviewed header(DateTime to Uuid)" into tizen_2.2
[platform/framework/native/appfw.git] / inc / FBaseUuId.h
1 //
2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
3 //
4 // Licensed under the Apache License, Version 2.0 (the License);
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
7 //
8 //     http://www.apache.org/licenses/LICENSE-2.0
9 //
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
15 //
16
17 /**
18  * @file                FBaseUuId.h
19  * @brief               This is the header file for the %UuId class.
20  *
21  * This header file contains the declarations of the %UuId class.
22  */
23 #ifndef _FBASE_UU_ID_H_
24 #define _FBASE_UU_ID_H_
25
26 #include <FBaseTypes.h>
27 #include <FBaseObject.h>
28 #include <FBaseString.h>
29
30 #ifndef ClassId
31 #define ClassId UUID
32 #endif
33
34 namespace Tizen { namespace Base
35 {
36 /**
37  * @class       UuId
38  * @brief       This class is the base class of the wrapped UUID types and provides methods for UUIDs.
39  *
40  * @since 2.0
41  *
42  * The %UuId class is the base class of the wrapped UUID types and provides useful operators. The UUID consists of 32 hexadecimal 
43  * digits displayed in 5 groups separated by hyphens to form a total of 36 characters (32 digits and 4 hyphens '-').
44  *
45  * It also provides operators for assignment and equality, and methods for parsing, comparing, and generalization.
46  *
47  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/base_namespace.htm">Base Guide</a>.
48  *
49  * The following example demonstrates how to use the %UuId class.
50  *
51  * @code
52  *
53  * #include <FBase.h>
54  *
55  * using namespace Tizen::Base;
56  *
57  * void
58  * MyClass::UuIdSamples(void)
59  * {
60  *              UuId uuid;
61  *              String str(L"A02D0DA1-80A0-4E73-B61F-793263C029EE");
62  *              String uuidStr_upper
63  *              UuId::Parse(str, uuid);         // UuId = A02D0DA1-80A0-4E73-B61F-793263C029EE
64  *              
65  *              String uuidStr = uuid.ToString();
66  *              uuidStr.ToUpper(uuidStr_upper);
67  *              
68  *              if (str.Equals(uuidStr_upper))
69  *              {
70  *                      // ...
71  *              }
72  *
73  * }
74  * @endcode
75  */
76 class _OSP_EXPORT_ UuId
77         : public Object
78 {
79 public:
80         /**
81          * This is the default constructor for this class. @n
82          * The %UuId is set to @c 0.
83          *
84          * @since 2.0
85          */
86         UuId(void);
87
88         /**
89          * Copying of objects using this copy constructor is allowed.
90          *
91          * @since 2.0
92          *
93          * @param[in] uuid              An instance of %UuId
94          */
95         UuId(const UuId& uuid);
96
97         /**
98          * @if OSPDEPREC
99          * Initializes an instance of %UuId with the value of the specified UUID.
100          *
101          * @brief               <i> [Deprecated] </i>
102          * @deprecated  This method is deprecated as a UUID type is deprecated.
103          *                              Instead of using this method, use the UuId(const byte uuid[16]) method.
104          * @since               2.0
105          *
106          * @param[in] uuid              An instance of UUID
107          * @endif
108          */
109         UuId(const UUID& uuid);
110
111         /**
112          * Initializes an instance of %UuId with the specified uuid value.
113          *
114          * @since 2.0
115          *
116          * @param[in] uuid              A byte array of uuid value
117          */
118         UuId(const byte uuid[16]);
119
120         /**
121          * This destructor overrides Tizen::Base::Object::~Object().
122          *
123          * @since 2.0
124          */
125         virtual ~UuId(void);
126
127         /**
128          * @if OSPDEPREC
129          * Checks whether the specified instance of %UuId is equal to the specified UUID.
130          *
131          * @brief       <i> [Deprecated] </i>
132          * @deprecated This method is deprecated as a UUID type is deprecated.
133          * @since 2.0
134          *
135          * @return              @c true if the UUID and the %UuId instance are equal, @n
136          *                              else @c false
137          * @param[in]   uuid1           An instance of UUID
138          * @param[in]   uuid2           An instance of %UuId
139          * @endif
140          */
141         _OSP_EXPORT_ friend bool operator ==(const UUID& uuid1, const UuId& uuid2);
142
143         /**
144          * Checks whether the current instance of %UuId is equal to the specified instance of %UuId.
145          *
146          * @since 2.0
147          *
148          * @return              @c true if the two instances are equal, @n
149          *                              else @c false
150          * @param[in]   uuid            An instance of %UuId
151          */
152         bool operator ==(const UuId& uuid) const;
153
154         /**
155          * @if OSPDEPREC
156          * Checks whether the specified instance of %UuId is not equal to the specified UUID.
157          *
158          * @brief       <i> [Deprecated] </i>
159          * @deprecated This method is deprecated as a UUID type is deprecated.
160          * @since 2.0
161          *
162          * @return              @c true if the two IDs are not equal, @n
163          *                              else @c false
164          * @param[in]   uuid1           An instance of UUID
165          * @param[in] uuid2             An instance of %UuId
166          * @endif
167          */
168         _OSP_EXPORT_ friend bool operator !=(const UUID& uuid1, const UuId& uuid2);
169
170         /**
171          * Checks whether the current instance of %UuId is not equal to the specified instance of %UuId.
172          *
173          * @since 2.0
174          *
175          * @return              @c true if the two IDs are not equal, @n
176          *                              else @c false
177          * @param[in]   uuid            An instance of %UuId
178          */
179         bool operator !=(const UuId& uuid) const;
180
181         /**
182          * Assigns the value of the specified instance to the current instance of %UuId.
183          *
184          * @since 2.0
185          *
186          * @return              A reference to the current instance
187          * @param[in]   uuid            An instance of %UuId
188          */
189         UuId& operator =(const UuId& uuid);
190
191         /**
192          * Checks whether the specified instance of Object is equal to the current instance of %UuId.
193          *
194          * @since 2.0
195          *
196          * @return              @c true if the specified instance of Object is equal to the current instance of %UuId, @n
197          *                              else @c false
198          * @param[in]   obj             An instance of Object to compare
199          * @remarks     This method can be overridden to support value equality. @n
200          *                              Furthermore, the method must return the same result 
201          *                              as the equality operator.
202          * @see                 Tizen::Base::Object::GetHashCode()
203          */
204         virtual bool Equals(const Object& obj) const;
205
206         /**
207          * Gets the hash value of the current instance of %UuId.
208          *
209          * @since 2.0
210          *
211          * @return              The integer value equivalent of the hash value of the current instance of %UuId
212          * @remarks
213          *                              - Two equal instances must return the same hash value. @n
214          *                              For better performance, the used hash function must 
215          *                              generate a random distribution for all inputs. 
216          *                              - The default implementation of this method returns the value of the current instance.
217          */
218         virtual int GetHashCode(void) const;
219
220         /**
221          * Gets the string representing the value of the current instance.
222          *
223          * @since               2.0
224          *
225          * @return              An instance of the String class with the unicode representation of the value of the current instance, @n
226          *                              else an empty string if an error such as @c E_OUT_OF_MEMORY occurs
227          */
228         String ToString(void) const;
229
230         /**
231          * @if OSPDEPREC
232          * Gets the UUID of the %UuId instance.
233          *
234          * @brief       <i> [Deprecated] </i>
235          * @deprecated This method is deprecated as a UUID type is deprecated.
236          * @since 2.0
237          *
238          * @return              The UUID
239          * @endif
240          */
241         UUID ToUUID(void) const;
242
243         /**
244          * Parses the specified string representing a %UuId value.
245          *
246          * @since 2.0
247          *
248          * @return              An error code
249          * @param[in]   str                     A string representing the %UuId value
250          * @param[out]  uuid            An instance of %UuId
251          * @exception   E_SUCCESS                               The method is successful.
252          * @exception   E_INVALID_ARG                   The string does not contain an %UuId that can be parsed.
253          * @remarks
254          *                              - The format of a string representing a %UuId value is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (For example, 130DF2EC-8233-4975-B03D-F0AD99E3449D).
255          *                              - This method guarantees that the original value of out-parameter is not changed when the method returns an error.
256          */
257         static result Parse(const String& str, UuId& uuid);
258
259         /**
260          * Generates a new %UuId instance with a random value.
261          *
262          * @since               2.0
263          *
264          * @return              A new %UuId instance
265          */
266         static UuId* GenerateN(void);
267
268         /**
269          * Gets a new invalid %UuId instance.
270          *
271          * @since               2.0
272          *
273          * @return              A new invalid %UuId instance
274          */
275         static UuId GetInvalidUuId(void);
276
277         /**
278          * @if OSPDEPREC
279          * This attribute is pre-defined. Its value is an invalid UUID.
280          *
281          * @brief       <i> [Deprecated] </i>
282          * @deprecated  This object is provided only for backward compatibility and will be deleted in the near future.
283          *                              Use GetInvalidUuId(void) instead of this object.
284          * @since 2.0
285          * @endif
286          */
287         static const UuId INVALID_UUID;
288
289         /**
290          * A byte array of the uuid value.
291          *
292          * @since 2.0
293          */
294         byte uuid[16];
295
296 private:
297         static void ConvertToUuId(byte uuid[16]);
298
299         friend class _UuIdImpl;
300         class _UuIdImpl * __pUuIdImpl;
301
302 }; // UuId
303
304 }} // Tizen::Base
305
306 #endif