UUID.hh

/* 
This file is part of the BIAS library (Basic ImageAlgorithmS).

Copyright (C) 2003-2009    (see file CONTACT for details)
Multimediale Systeme der Informationsverarbeitung
Institut fuer Informatik
Christian-Albrechts-Universitaet Kiel


BIAS is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.

BIAS is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with BIAS; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/


#ifndef __BIASUUID_hh__
#define __BIASUUID_hh__

#include <ctime>
#include <climits>
#include <cstring>
#include <Base/Debug/Error.hh>
#include <Base/Debug/Debug.hh>

#include <Base/Common/BIASpragmaStart.hh>
#include <ios>

#ifdef WIN32
#include <Winsock.h> // for timeval
//#  ifdef UNICODE
//#    error using BIAS uuid with UNICODE is untested. Please disable UNICODE or this warning if you really know what you do. (look at UuidFromStringA/UuidFromStringW in rpcdce.h) (JW 12/2005)
//#  endif // UNICODE
// on Win32 there are two types: GUID and UUID, both pointing to the same struct
#  include <rpc.h>
//#  include <rpcdce.h>
// remove UUID to avoid name clash with our class
#  undef UUID
#  undef uuid_t
typedef GUID uuid_t;  // let our internal data type be of type GUID
#else // WIN32
#  include <uuid/uuid.h>
#endif //WIN32

#include <time.h>

  // true to generate consecutive IDS as default instead of MAC like ids
#ifndef DEFAULT_UUID_CONSECUTIVELY
#  define DEFAULT_UUID_CONSECUTIVELY false
#endif

namespace BIAS {

  /// forward declaration for stream operators
  class BIASImageBase_EXPORT UUID;
  
  /** @relates UUID
      @brief write a UUID to a stream */
  BIASImageBase_EXPORT std::ostream& operator<<(std::ostream & os, const UUID& id);
  /** @relates UUID
      @brief reads a UUID from a stream */
  BIASImageBase_EXPORT std::istream& operator>>(std::istream & is, UUID& id);


  /** @class UUID     
      @ingroup g_utils
      @test MyTestFile.cpp
      @brief interface class for 
      producing/storing Universally Unique IDentifiers

      A UUID is a u unique structure. 
      It is usually a 128 bit value computed from the MAC address of the 
      network 
      adapter (which means "spatial uniqueness") and a high resolution 
      timestamp providing "temporal uniqueness".
      //In addition you 

      @attention temporal uniqueness is only obtained if time is monotonic,
      i.e. you MUST NOT turn back the clock (-> NTP ?)

      For information: generating 1.000.000 UIDS on WIN32 takes approx. 
      180 msec. (jw)

      \todo The UUID representation is *not* platform independant, 
      in particular generating a consecutive ID on Windows 
      and reading it on Linux will not work! (JW)

      @author koeser 09/2003, W32: Jan Woetzel 08/2005 */
  class BIASImageBase_EXPORT UUID : public Debug
  {
  public:

    // destructor
    virtual ~UUID();

    /** @brief default constructor
        does NOT create a valid UUID to avoid performance decrease
        in case someone wants to create many UIDS that are not really used.
        (Jan Woetzel 08/2005) */
    UUID();

    /** @brief use this if you want to create a UUID "manually" */
    explicit UUID(const uuid_t &id);

    /** @brief copy constructor, calls operator= internally. */
    UUID(const BIAS::UUID& id);

    /** @brief construct from string containing ascii uuid */
    explicit UUID(const std::string &sID);

    /** @brief construct from string containing a unique long.
        User has to assert uniqueness himself, e.g. by a global counter.
        @author Jan Woetzel 2005 */
    explicit UUID(const unsigned long & n);

    /** NULLS the class members,
        invalidates this UID ( not unique anymore).
        Jan Woetzel 08/2005 */
    void clear();

    /* @return true if it is a NIL/NULL ID which is not unique 
       Jan Woetzel 08/2005 */
    bool IsNil() const;

    /** @brief static function which simply produces a uuid and returns 
        @attention calling this function on an uninitialized UUID object does
        not initialize it. It is _really_ a static function. 
        @return a new uuid which can be assigned to a UUID object 
        @author Jan Woetzel (rewrite 2005/08) */
    static UUID GenerateUUID(const bool & consecutively=
                             DEFAULT_UUID_CONSECUTIVELY);
    /// jw
    static UUID GenerateUUID_Consecutive();
    /// jw
    static UUID GenerateUUID_Global();


    /** @brief function to assign a fresh, unique ID. 
        @param consecutively: true to use a sequential, dense counter instead 
        of 16 Byte MAC like UID. 
        The ID will be unique for each program run. 
        Please mind the differnec to a sequential (local unique only) UUID w
        hich is unique for the machine, not only the run. 
        False to generate universally valid one.
        @author Jan Woetzel 08/2005   */
    void AssignUUID(const bool & consecutively=DEFAULT_UUID_CONSECUTIVELY);
    /// jw
    void AssignUUID_Global();
    /// jw
    void AssignUUID_Consecutive();


    /** @brief construct from string containing ascii uuid.
        Thsiu routine is slow! (1.000.000 times take approx 16 seconds, JW)
        @return true if succesful */
    bool SetFromString(const std::string &sID);

    /** @brief construct from a unique long. 
        User has to assert uniqueness himslef, e.g. by a global counter.
        @return true if succesful 
        @author Jan Woetzel 2005 */
    bool SetFromLong(const unsigned long &n);

    /** @brief get least significant value of UID as long value. 
        Useful in conjunction with SetFromLong if you want to use unique 
        counters instead of real UIDs.
        !!Must not be called for non-consecutive uuids!! 
        @return least significant UID value
        @author Jan Woetzel 2005 */
    unsigned long GetLong() const;

    /** @brief returns the time used to create the uuid (just seconds) */
    time_t GetUUIDCreationTime() const;

    /** @brief returns the time used to create the uuid (seconds and usecs)*/
    timeval GetUUIDCreationTimeStruct() const;

    /** @brief comparison operator only compares ids, no check of validities */
    inline bool operator==(const UUID& id) const;

    /** @brief "not equal"-operator, uses result of operator== */
    inline bool operator!=(const UUID& id) const 
    { return (!((*this)==id));  };

    /** @brief the operator< does not express temporal ordering, it does only
        compare the data areas of the two ids, e.g. for sorting, map-storage */
    inline bool operator<(const UUID& id) const;

    /** @brief operator<= does not express temporal ordering, it does only
        compare the data areas of the two ids !!! */
    inline bool operator<=(const UUID& id) const;

    /** @brief standard assignment operator */
    inline UUID& operator=(const UUID& id);

    /** @brief writes the UUID into a string object */
    void GetString(std::string& sUUID) const;
    std::string GetString() const;

    /** @brief checks whether this uuid is valid(true) or unitialized(false) */
    inline bool IsValid() const { return IsValid_; };

    /** @brief sets the valid flag to false and clears data 
        JW 09/2005: added clear in addition to just setting bool flag 
        invalid. */
    inline void Invalidate(){this->clear(); };

    /**  @brief get the pointer to the Uc[16] array with the raw uuid */
    const unsigned char *GetUUIDRaw() const;

    void SetUUIDRaw(const unsigned char * rawid);

    /// undefined behaviour if uuid is invalid
    bool IsConsecutive() const;

  protected:

    friend BIASImageBase_EXPORT std::ostream& 
        operator<<(std::ostream & os, const UUID& id);
    friend BIASImageBase_EXPORT std::istream& 
        operator>>(std::istream & is, UUID& id);

    /// the data fields of the uuid
    uuid_t theID_;

    /// flag indicating whether this uuid has been assigned a value yet
    bool IsValid_;

    /// when creating a uuid, current time is compared against the time
    /// saved during the last uuid generation
    ///
    /// Hint: If you have WIN32 compilation problems look for 
    /// WIN32_LEAN_AND_MEAN and windows.h (JW) 
    static timeval LastGenerationTime_;

    /// global counter to create next unique consecutive program run-unique ID.
    static long g_uniqueCounter;
  }; // class BIAS::UUID


  /** @brief Helper class for ascending sort of sequential BIAS::UUID instances.
      Sample usage:
      \verbatim
      #include <algorithm>
      std::vector<BIAS::UUID> v;
      std::sort(v.begin(), v.end(), BIAS::UUIDsortAscending() );
      \endverbatim
      \todo operator< of UUD may be inverse, TOOD: compare uuid_compare on 
      Linux and WIN32.
      @author Jan Woetzel */
  class UUIDsortAscending 
  { 
  public: 
    bool operator()(BIAS::UUID & a, BIAS::UUID & b) 
    { return ! (a < b); }
  };

  ////////////////////////////////////////////////////////////////////
  // inline implementation
  ////////////////////////////////////////////////////////////////////

  bool BIAS::UUID::operator==(const UUID& id) const 
  { 
#ifdef WIN32
    RPC_STATUS status;
    // TODO: this is not ANSI compatible 4238
    //return (!UuidCompare(&((GUID)id.theID_),&((GUID)theID_), &status));
    // TODO PERFORMANCE warning because of additional constructors! 
    GUID id1 = (GUID)id.theID_;
    GUID id2 = (GUID)this->theID_;
    int result = UuidCompare(&id1, &id2, &status);
    return (result==0);
#else
    return (!uuid_compare(id.theID_,theID_));
#endif
  }


  bool BIAS::UUID::operator<(const UUID& id) const 
  { 
#ifdef WIN32
    RPC_STATUS dummy;
    return (UuidCompare(&((GUID)id.theID_),&((GUID)theID_),&dummy)<0);
#else
    return (uuid_compare(id.theID_,theID_)<0);
#endif
  }


  bool BIAS::UUID::operator<=(const UUID& id) const 
  { 
#ifdef WIN32
    RPC_STATUS dummy;
    return (UuidCompare(&((GUID)id.theID_),&((GUID)theID_),&dummy)<=0);
#else
    return (uuid_compare(id.theID_,theID_)<=0);
#endif
  }


  UUID& BIAS::UUID::operator=(const UUID& id) 
  { 
    memcpy((void*)&theID_,(void*)&id.theID_,sizeof(uuid_t)); 
    IsValid_ = id.IsValid_; return (*this);
  }

} // namespace

#include <Base/Common/BIASpragmaEnd.hh>

#endif // __BIASUUID_hh__