1package Data::UUID; 2 3use strict; 4 5use Carp; 6use vars qw($VERSION @ISA @EXPORT @EXPORT_OK); 7 8require Exporter; 9require DynaLoader; 10require Digest::MD5; 11 12@ISA = qw(Exporter DynaLoader); 13# Items to export into callers namespace by default. Note: do not export 14# names by default without a very good reason. Use EXPORT_OK instead. 15# Do not simply export all your public functions/methods/constants. 16@EXPORT = qw( 17 NameSpace_DNS 18 NameSpace_OID 19 NameSpace_URL 20 NameSpace_X500 21); 22$VERSION = '1.218'; 23 24bootstrap Data::UUID $VERSION; 25 261; 27__END__ 28 29=head1 NAME 30 31Data::UUID - Perl extension for generating Globally/Universally 32Unique Identifiers (GUIDs/UUIDs). 33 34=head1 SYNOPSIS 35 36 use Data::UUID; 37 38 $ug = new Data::UUID; 39 $uuid1 = $ug->create(); 40 $uuid2 = $ug->create_from_name(<namespace>, <name>); 41 42 $res = $ug->compare($uuid1, $uuid2); 43 44 $str = $ug->to_string( $uuid ); 45 $uuid = $ug->from_string( $str ); 46 47=head1 DESCRIPTION 48 49This module provides a framework for generating v3 UUIDs (Universally Unique 50Identifiers, also known as GUIDs (Globally Unique Identifiers). A UUID is 128 51bits long, and is guaranteed to be different from all other UUIDs/GUIDs 52generated until 3400 CE. 53 54UUIDs were originally used in the Network Computing System (NCS) and later in 55the Open Software Foundation's (OSF) Distributed Computing Environment. 56Currently many different technologies rely on UUIDs to provide unique identity 57for various software components. Microsoft COM/DCOM for instance, uses GUIDs 58very extensively to uniquely identify classes, applications and components 59across network-connected systems. 60 61The algorithm for UUID generation, used by this extension, is described in the 62Internet Draft "UUIDs and GUIDs" by Paul J. Leach and Rich Salz. (See RFC 634122.) It provides reasonably efficient and reliable framework for generating 64UUIDs and supports fairly high allocation rates -- 10 million per second per 65machine -- and therefore is suitable for identifying both extremely short-lived 66and very persistent objects on a given system as well as across the network. 67 68This modules provides several methods to create a UUID: 69 70 # creates binary (16 byte long binary value) UUID. 71 $ug->create(); 72 $ug->create_bin(); 73 74 # creates binary (16-byte long binary value) UUID based on particular 75 # namespace and name string. 76 $ug->create_from_name(<namespace>, <name>); 77 $ug->create_from_name_bin(<namespace>, <name>); 78 79 # creates UUID string, using conventional UUID string format, 80 # such as: 4162F712-1DD2-11B2-B17E-C09EFE1DC403 81 $ug->create_str(); 82 $ug->create_from_name_str(<namespace>, <name>); 83 84 # creates UUID string as a hex string, 85 # such as: 0x4162F7121DD211B2B17EC09EFE1DC403 86 $ug->create_hex(); 87 $ug->create_from_name_hex(<namespace>, <name>); 88 89 # creates UUID string as a Base64-encoded string 90 $ug->create_b64(); 91 $ug->create_from_name_b64(<namespace>, <name>); 92 93 Binary UUIDs can be converted to printable strings using following methods: 94 95 # convert to conventional string representation 96 $ug->to_string(<uuid>); 97 98 # convert to hex string 99 $ug->to_hexstring(<uuid>); 100 101 # convert to Base64-encoded string 102 $ug->to_b64string(<uuid>); 103 104 Conversly, string UUIDs can be converted back to binary form: 105 106 # recreate binary UUID from string 107 $ug->from_string(<uuid>); 108 $ug->from_hexstring(<uuid>); 109 110 # recreate binary UUID from Base64-encoded string 111 $ug->from_b64string(<uuid>); 112 113 Finally, two binary UUIDs can be compared using the following method: 114 115 # returns -1, 0 or 1 depending on whether uuid1 less 116 # than, equals to, or greater than uuid2 117 $ug->compare(<uuid1>, <uuid2>); 118 119Examples: 120 121 use Data::UUID; 122 123 # this creates a new UUID in string form, based on the standard namespace 124 # UUID NameSpace_URL and name "www.mycompany.com" 125 126 $ug = new Data::UUID; 127 print $ug->create_from_name_str(NameSpace_URL, "www.mycompany.com"); 128 129=head2 EXPORT 130 131The module allows exporting of several standard namespace UUIDs: 132 133=over 134 135=item NameSpace_DNS 136 137=item NameSpace_URL 138 139=item NameSpace_OID 140 141=item NameSpace_X500 142 143=back 144 145=head1 AUTHOR 146 147Alexander Golomshtok <agolomsh@cpan.org> 148 149=head1 SEE ALSO 150 151The Internet Draft "UUIDs and GUIDs" by Paul J. Leach and Rich Salz (RFC 4122) 152 153=cut 154