Main Page | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members

vtkUUID Class Reference

#include <vtkUUID.h>

Inheritance diagram for vtkUUID:

Inheritance graph
[legend]
Collaboration diagram for vtkUUID:

Collaboration graph
[legend]
List of all members.

Detailed Description

A Universal Unique IDentifier modeled after OSF DCE UUIDs.

UUID stands for a Universal Unique IDentifier. These are 128 bit numbers which is guaranteed (reasonably) to be unique across both space and time. The mechanism used to guarantee that UUIDs are Unique is through combinations of hardware addresses, time stamps and random seeds. A UUID can be used for multiple purposes, from tagging objects with an extremely short lifetime, to reliably identifying very persistent objects across a network.

There is a reference in the UUID to the hardware address of the first network card on the host which generated the UUID - this reference is intended to ensure the UUID will be unique in space as the MAC address of every network card is assigned by a single global authority and is guaranteed to be unique.

The generation of UUIDs does not require a registration authority for each single identifier. Instead, it requires a unique value over space for each UUID generator. This spatially unique value is specified as an IEEE 802 address, which is usually already applied to network-connected systems. This 48-bit address can be assigned based on an address block obtained through the IEEE registration authority. This UUID specification assumes the availability of an IEEE 802 address.

Table: UUID Format
Field NDR Data Type Octet # Note
mTimeLow unsigned long 0-3 The low field of the timestamp.
mTimeMid unsigned short 4-5 The middle field of the timestamp.
mTimeHigh unsigned short 6-7 The high field of the timestamp multiplexed with the version number.
mClockSeqHigh unsigned small 8 The high field of the clock sequence multiplexed with the variant.
mClockSeqLow unsigned small 9 The low field of the clock sequence.
mNode character 10-15 The spatially unique node identifier.

The UUID consists of a record of 16 octets and must not contain padding between fields. The total size is 128 bits.

To minimise confusion about bit assignments within octets, the UUID record definition is defined only in terms of fields that are integral numbers of octets. The version number is multiplexed with the time stamp (time_high), and the variant field is multiplexed with the clock sequence (clock_seq_high).

The next component is a timestamp which, as long as clocks always move forward, will be unique in time. The timestamp is a 60 bit value. For UUID version 1, this is represented by Coordinated Universal Time (UTC) as a count of 100-nanosecond intervals since 00:00:00.00, 15 October 1582 (the date of Gregorian reform to the Christian calendar).

The version number is multiplexed in the 4 most significant bits of the mTimeHigh field.

Table: UUID version Field
msb1 msb2 msb3 msb4 Version Description
0 0 0 1 1 DCE version, as specified herein.
0 0 1 0 2 DCE Security version, with embedded POSIX UIDs.

The variant field determines the layout of the UUID. The structure of DCE UUIDs is fixed across different versions. Other UUID variants may not interoperate with DCE UUIDs. Interoperability of UUIDs is defined as the applicability of operations such as string conversion, comparison, and lexical ordering across different systems. The variant field consists of a variable number of the msbs of the mClockSeqHigh field.

Table: UUID variant Field
msb1 msb2 msb3 Description
0 - - Reserved, NCS backward compatibility.
1 0 - DCE variant.
1 1 0 Reserved, Microsoft Corporation GUID.
1 1 1 Reserved for future definition.

The formal definition of the UUID string representation is provided by the following extended BNF:
UUID::= <time_low> <hyphen> <time_mid> <hyphen> <time_high_and_version> <hyphen> <clock_seq_hi_and_reserved> <clock_seq_low> <hyphen> <node>
time_low::= <hexOctet> <hexOctet> <hexOctet> <hexOctet>
time_mid::= <hexOctet> <hexOctet>
time_high_and_version::= <hexOctet> <hexOctet>
clock_seq_hi_and_reserved::= <hexOctet>
clock_seq_low::= <hexOctet>
node::= <hexOctet><hexOctet><hexOctet> <hexOctet><hexOctet><hexOctet>
hexOctet::= <hexDigit> <hexDigit>
hexDigit::= <digit> | <a> | <b> | <c> | <d> | <e> | <f>
digit::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
hyphen::="-"
a::="a" | "A"
b::="b" | "B"
c::="c" | "C"
d::="d" | "D"
e::="e" | "E"
f::="f" | "F"

Just in case some part of the above goes wrong, there is a random component placed into the UUID as a catch-all for uniqueness.

The following is an example of a generated UUID: 58f202ac-22cf-11d1-b12d-002035b29092 This has come from a machine with the network hardware address 002035B29092. From this it may be observed that the Network address of the ethernet adapter matches the last portion of the uuid.

Note:
This code was adapted from both mozilla's nsID class as well as e2fsprogs libuuid.
Author:
Sean McInerney
Version:
Revision
1.10
Date:
Date
2004/08/10 07:37:21
See also:
The Open Group's specification for Universal Unique Identifiers (UUIDs).

Definition at line 300 of file vtkUUID.h.

Public Member Functions

 vtkTypeRevisionMacro (vtkUUID, vtkObject)
void PrintSelf (ostream &, vtkIndent)
void Clear (void)
 Clear this UUID data to zero.

void Copy (const vtkUUID *a)
 Copy a UUID (source UUID is const).

void Copy (const char *a)
 Unmarshal a UUID from a character string.

void Copy (const unsigned char a[16])
 Copy identity from a 128-bit, 16-byte sequence.

int GetString (char buffer[37]) const
 Marshal this UUID as a character string into the provided buffer.

const char * GetString (void) const
 Marshal this UUID as a character string.

int GetBinary (unsigned char buffer[16]) const
 Pack this UUID as a 128-bit, 16-byte sequence into the provided buffer.

const unsigned char * GetBinary (void) const
 Pack this UUID into a 128-bit, 16-byte sequence.

int IsNull (void) const
 Returns true if the uuid is the NULL uuid, false otherwise.

time_t GetTime (struct timeval *a) const
 Extract the time value embedded in an ID.

long GetTime (void) const
 Extract the time value embedded in an ID.

int GetVariant (void) const
 Get an enumeration of the UUID variant.

int GetVersion (void) const
 Get an enumeration of the UUID version.

void Swap (vtkUUID *object)
 Swaps the date of this object with those of specified object.

Structure & GetData (void)
 Get the internal data structure of this UUID.

const Structure & GetData (void) const
 Get the internal data structure of this UUID.

int Compare (const vtkUUID *a) const
 Compares two UUIDs.

int Compare (const char *a) const
 Compares two UUIDs.

int Compare (const unsigned char a[16]) const
 Compares two UUIDs.


Static Public Member Functions

vtkUUID * New (void)
const char * GetVariantString (int variant)
 Get a string representation of the UUID variant.

const char * GetVersionString (int version)
 Get a string representation of the UUID version.


Static Public Attributes

const vtkUint32Type TimeOffsetLow = VTK_EXTENSIONS_UINT32(0x13814000)
 Offset between 15-Oct-1582 and 1-Jan-70 (DTSS UTC vs.

const vtkUint32Type TimeOffsetHigh = VTK_EXTENSIONS_UINT32(0x01B21DD2)
 Offset between 15-Oct-1582 and 1-Jan-70 (DTSS UTC vs.


Protected Member Functions

 vtkUUID (void)
 ~vtkUUID ()
 vtkUUID (const vtkUUID *a)
 vtkUUID (const char *a)
 vtkUUID (const unsigned char a[16])

Static Protected Member Functions

static initialization.
void ClassInitialize (void)
void ClassFinalize (void)

Constructor & Destructor Documentation

vtkUUID::vtkUUID (  void   )  [protected]
 

vtkUUID::~vtkUUID (   )  [protected]
 

vtkUUID::vtkUUID (  const vtkUUID *  a  )  [inline, protected]
 

Definition at line 453 of file vtkUUID.h.

vtkUUID::vtkUUID (  const char *  a  )  [inline, protected]
 

Definition at line 456 of file vtkUUID.h.

vtkUUID::vtkUUID (  const unsigned char  a[16]  )  [inline, protected]
 

Definition at line 459 of file vtkUUID.h.

Member Function Documentation

void vtkUUID::ClassFinalize (  void   )  [static, protected]
 

void vtkUUID::ClassInitialize (  void   )  [static, protected]
 

void vtkUUID::Clear (  void   )  [inline]
 

Clear this UUID data to zero.

Definition at line 523 of file vtkUUID.h.

References vtkUUID::Structure::Clear().

Referenced by Copy().

int vtkUUID::Compare (  const unsigned char  a[16]  )  const [inline]
 

Compares two UUIDs.

The uuid compare method compares two UUIDs, returning 1 if they are equal, or 0 if they are not. Because the uuid compare command handles the comparison of UUIDs in current and previous DCE formats, you should use it rather than string compare.

Note:
No special privileges are needed to use the uuid compare command.

Definition at line 784 of file vtkUUID.h.

References vtkUUID::Structure::Compare(), and Compare().

int vtkUUID::Compare (  const char *  a  )  const [inline]
 

Compares two UUIDs.

The uuid compare method compares two UUIDs, returning 1 if they are equal, or 0 if they are not. Because the uuid compare command handles the comparison of UUIDs in current and previous DCE formats, you should use it rather than string compare.

Note:
No special privileges are needed to use the uuid compare command.

Definition at line 777 of file vtkUUID.h.

References vtkUUID::Structure::Compare(), and Compare().

int vtkUUID::Compare (  const vtkUUID *  a  )  const [inline]
 

Compares two UUIDs.

The uuid compare method compares two UUIDs, returning 1 if they are equal, or 0 if they are not. Because the uuid compare command handles the comparison of UUIDs in current and previous DCE formats, you should use it rather than string compare.

Note:
No special privileges are needed to use the uuid compare command.

Definition at line 770 of file vtkUUID.h.

References vtkUUID::Structure::Compare(), Compare(), and GetData().

Referenced by Compare().

void vtkUUID::Copy (  const unsigned char  a[16]  )  [inline]
 

Copy identity from a 128-bit, 16-byte sequence.

Returns:
VTK_OK on success, VTK_ERROR otherwise.

Definition at line 589 of file vtkUUID.h.

References vtkUUID::Structure::Copy(), and Copy().

void vtkUUID::Copy (  const char *  a  ) 
 

Unmarshal a UUID from a character string.

Returns:
VTK_OK on success, VTK_ERROR otherwise.

void vtkUUID::Copy (  const vtkUUID *  a  )  [inline]
 

Copy a UUID (source UUID is const).

Returns:
VTK_OK on success, VTK_ERROR otherwise.

Definition at line 582 of file vtkUUID.h.

References Clear(), vtkUUID::Structure::Copy(), Copy(), and GetData().

Referenced by Copy().

const unsigned char* vtkUUID::GetBinary (  void   )  const
 

Pack this UUID into a 128-bit, 16-byte sequence.

Returns:
A pointer to internal static space holding the sequence on success or a sequence of zeroes on failure.

int vtkUUID::GetBinary (  unsigned char  buffer[16]  )  const [inline]
 

Pack this UUID as a 128-bit, 16-byte sequence into the provided buffer.

Returns:
false on failure, true otherwise.

Definition at line 626 of file vtkUUID.h.

References vtkUUID::Structure::GetBinary().

const Structure& vtkUUID::GetData (  void   )  const [inline]
 

Get the internal data structure of this UUID.

Definition at line 409 of file vtkUUID.h.

Structure& vtkUUID::GetData (  void   )  [inline]
 

Get the internal data structure of this UUID.

Definition at line 408 of file vtkUUID.h.

Referenced by Compare(), Copy(), and Swap().

const char* vtkUUID::GetString (  void   )  const
 

Marshal this UUID as a character string.

Returns:
A pointer to internal static space holding the string on success or the empty string on failure.

int vtkUUID::GetString (  char  buffer[37]  )  const
 

Marshal this UUID as a character string into the provided buffer.

Returns:
false on failure, true otherwise.

long vtkUUID::GetTime (  void   )  const
 

Extract the time value embedded in an ID.

time_t vtkUUID::GetTime (  struct timeval *  a  )  const
 

Extract the time value embedded in an ID.

int vtkUUID::GetVariant (  void   )  const [inline]
 

Get an enumeration of the UUID variant.

Definition at line 687 of file vtkUUID.h.

References vtkUUID::Structure::GetVariant().

const char * vtkUUID::GetVariantString (  int  variant  )  [inline, static]
 

Get a string representation of the UUID variant.

Definition at line 700 of file vtkUUID.h.

References GetVariantString(), VTK_UUID_VARIANT_DCE, VTK_UUID_VARIANT_MICROSOFT, VTK_UUID_VARIANT_NCS, and VTK_UUID_VARIANT_RESERVED.

Referenced by GetVariantString().

int vtkUUID::GetVersion (  void   )  const [inline]
 

Get an enumeration of the UUID version.

Definition at line 693 of file vtkUUID.h.

References vtkUUID::Structure::GetVersion().

const char * vtkUUID::GetVersionString (  int  version  )  [inline, static]
 

Get a string representation of the UUID version.

Definition at line 718 of file vtkUUID.h.

References GetVersionString(), VTK_UUID_VERSION_EMBEDDED_POSIX, VTK_UUID_VERSION_NAME, VTK_UUID_VERSION_RANDOM, and VTK_UUID_VERSION_TIME.

Referenced by GetVersionString().

int vtkUUID::IsNull (  void   )  const [inline]
 

Returns true if the uuid is the NULL uuid, false otherwise.

Definition at line 644 of file vtkUUID.h.

References vtkUUID::Structure::IsNull().

vtkUUID* vtkUUID::New (  void   )  [static]
 

Reimplemented from vtkObject.

void vtkUUID::PrintSelf (  ostream &  ,
vtkIndent 
)  [virtual]
 

Reimplemented from vtkObject.

void vtkUUID::Swap (  vtkUUID *  object  )  [inline]
 

Swaps the date of this object with those of specified object.

Definition at line 833 of file vtkUUID.h.

References GetData(), and vtkUUID::Structure::Swap().

vtkUUID::vtkTypeRevisionMacro (  vtkUUID  ,
vtkObject 
) 
 

Member Data Documentation

const vtkUint32Type vtkUUID::TimeOffsetHigh = VTK_EXTENSIONS_UINT32(0x01B21DD2) [static]
 

Offset between 15-Oct-1582 and 1-Jan-70 (DTSS UTC vs.

Unix base times).

Definition at line 347 of file vtkUUID.h.

const vtkUint32Type vtkUUID::TimeOffsetLow = VTK_EXTENSIONS_UINT32(0x13814000) [static]
 

Offset between 15-Oct-1582 and 1-Jan-70 (DTSS UTC vs.

Unix base times).

Definition at line 346 of file vtkUUID.h.

The documentation for this class was generated from the following file:
Generated on Tue Aug 10 03:45:03 2004 for vtkExtensions by doxygen 1.3.7