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