inc/FBaseUuId.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                FBaseUuId.h
  20  * @brief               This is the header file for the %UuId class.
  21  *
  22  * This header file contains the declarations of the %UuId class.
  23  */
  24 #ifndef _FBASE_UU_ID_H_
  25 #define _FBASE_UU_ID_H_
  26
  27 #include <FBaseTypes.h>
  28 #include <FBaseObject.h>
  29 #include <FBaseString.h>
  30
  31 #ifndef ClassId
  32 #define ClassId UUID
  33 #endif
  34
  35 namespace Tizen { namespace Base
  36 {
  37 /**
  38  * @class       UuId
  39  * @brief       This class is the base class of the wrapped UUID types and provides useful operators.
  40  *
  41  * @since 2.0
  42  *
  43  * 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 '-').
  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 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 IDs 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. Furthermore, the method must return the same result as the equality operator.
 200          * @see                 Tizen::Base::Object::GetHashCode()
 201          */
 202         virtual bool Equals(const Object& obj) const;
 203
 204         /**
 205          * Gets the hash value of the current instance of %UuId.
 206          *
 207          * @since 2.0
 208          *
 209          * @return              The integer value equivalent of the hash value of the current instance of %UuId
 210          * @remarks     Two equal instances must return the same hash value. For better performance,
 211          *                      the used hash function must generate a random distribution for all inputs. @n
 212          *                      The default implementation of this method returns the value of the current instance.
 213          */
 214         virtual int GetHashCode(void) const;
 215
 216         /**
 217          * Gets the string representing the value of the current instance when implemented by a class.
 218          *
 219          * @since 2.0
 220          *
 221          * @return              An instance of the String class with the unicode representation of the value of the current instance @n
 222          *                      If an error such as E_OUT_OF_MEMORY occurs, an empty string is returned.
 223          */
 224         String ToString(void) const;
 225
 226         /**
 227          * @if OSPDEPREC
 228          * Gets the UUID of the %UuId instance.
 229          *
 230          * @brief       <i> [Deprecated] </i>
 231          * @deprecated This method is deprecated as a UUID type is deprecated.
 232          * @since 2.0
 233          *
 234          * @return              The UUID
 235          * @endif
 236          */
 237         UUID ToUUID(void) const;
 238
 239         /**
 240          * Parses the specified string representing a %UuId value.
 241          *
 242          * @since 2.0
 243          *
 244          * @return              An error code
 245          * @param[in]   str                     A string representing the %UuId value
 246          * @param[out]  uuid            An instance of %UuId
 247          * @exception   E_SUCCESS                               The method is successful.
 248          * @exception   E_INVALID_ARG                   The string does not contain an %UuId that can be parsed.
 249          * @remarks
 250          *                              - The format of a string representing a %UuId value is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (For example, 130DF2EC-8233-4975-B03D-F0AD99E3449D).
 251          *                              - This method guarantees that the original value of out-parameter is not changed when the method returns error.
 252          */
 253         static result Parse(const String& str, UuId& uuid);
 254
 255         /**
 256          * Generates a new %UuId instance with a random value.
 257          *
 258          * @since 2.0
 259          *
 260          * @return              A new %UuId instance
 261          */
 262         static UuId* GenerateN(void);
 263
 264         /**
 265          * Get a new invalid %UuId instance.
 266          *
 267          * @since 2.0
 268          *
 269          * @return              A new invalid %UuId instance
 270          */
 271         static UuId GetInvalidUuId(void);
 272
 273         /**
 274          * @if OSPDEPREC
 275          * This attribute is pre-defined. Its value is an invalid UUID.
 276          *
 277          * @brief       <i> [Deprecated] </i>
 278          * @deprecated  This object is provided only for backward compatibility and will be deleted in the near future.
 279          *                              Use GetInvalidUuId(void) instead of this object.
 280          * @since 2.0
 281          * @endif
 282          */
 283         static const UuId INVALID_UUID;
 284
 285         /**
 286          * A byte array of uuid value.
 287          *
 288          * @since 2.0
 289          */
 290         byte uuid[16];
 291
 292 private:
 293         static void ConvertToUuId(byte uuid[16]);
 294
 295         friend class _UuIdImpl;
 296         class _UuIdImpl * __pUuIdImpl;
 297
 298 }; // UuId
 299
 300 }} // Tizen::Base
 301
 302 #endif