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