Win32::NameTranslate - Convenience perl wrapper around IADsNameTranslate interface
version 0.06
Win32::NameTranslate is a convenience wrapper around the IADsNameTranslate interface, which can be used to convert the names of Active Directory objects from one format to another. IADsNameTranslate is an ADSI implementation of the DsCrackNames API.
IADsNameTranslate
ADSI
DsCrackNames
IADsNameTranslate is usually accessed via Win32::OLE, this wrapper just makes it slightly easier to use.
use strict; use warnings; use Win32::NameTranslate qw[:all]; use Win32::OLE; # Create a new name translator, using Global Catalog my $trans = Win32::NameTranslate->new( ADS_NAME_INITTYPE_GC ); my $canonical = 'localdomain.local/_SomeOU/_AnotherOU/Tommy Tester'; # Specify Canonical format and name to lookup $trans->set( ADS_NAME_TYPE_CANONICAL, $canonical ) || die Win32::OLE->LastError; # Lets get the RFC 1779 'LDAP' type name my $rfc = $trans->get( ADS_NAME_TYPE_1779 ); # rfc = 'CN=tommy tester,OU=_AnotherOU,OU=_SomeOU,DC=localdomain,DC=local' my @multiple = ( 'localdomain.local/_SomeOU/_AnotherOU/Tommy Tester', 'localdomain.local/_Admins/_Enterprise/Johnny Admin', ); # We can lookup multiple names by providing an arrayref $trans->set( ADS_NAME_TYPE_CANONICAL, \@multiple ) || die Win32::OLE->LastError; my @rfcs = $trans->get( ADS_NAME_TYPE_1779 );
A number of constants are defined and exported by this module. You may specify :all to import all the constants into your namespace. Nothing is imported by default.
:all
ADS_NAME_INITTYPE_ENUM
The ADS_NAME_INITTYPE_ENUM enumeration specifies the types of initialisation to perform on a NameTranslate object.
NameTranslate
ADS_NAME_INITTYPE_DOMAIN
Initializes a NameTranslate object by setting the domain that the object binds to.
ADS_NAME_INITTYPE_SERVER
Initializes a NameTranslate object by setting the server that the object binds to.
ADS_NAME_INITTYPE_GC
Initializes a NameTranslate object by locating the global catalog that the object binds to.
ADS_NAME_TYPE_ENUM
The ADS_NAME_TYPE_ENUM enumeration specifies the formats used for representing distinguished names:
ADS_NAME_TYPE_1779
Name format as specified in RFC 1779. For example, "CN=Jeff Smith,CN=users,DC=Fabrikam,DC=com".
ADS_NAME_TYPE_CANONICAL
Canonical name format. For example, "Fabrikam.com/Users/Jeff Smith".
ADS_NAME_TYPE_NT4
Account name format used in Windows NT 4.0. For example, "Fabrikam\JeffSmith".
ADS_NAME_TYPE_DISPLAY
Display name format. For example, "Jeff Smith".
ADS_NAME_TYPE_DOMAIN_SIMPLE
Simple domain name format. For example, "JeffSmith@Fabrikam.com".
ADS_NAME_TYPE_ENTERPRISE_SIMPLE
Simple enterprise name format. For example, "JeffSmith@Fabrikam.com".
ADS_NAME_TYPE_GUID
Global Unique Identifier format. For example, "{95ee9fff-3436-11d1-b2b0-d15ae3ac8436}".
ADS_NAME_TYPE_UNKNOWN
Unknown name type. The system will estimate the format. This element is a meaningful option only with the set method, but not with the get method.
set
get
ADS_NAME_TYPE_USER_PRINCIPAL_NAME
User principal name format. For example, "JeffSmith@Fabrikam.com".
ADS_NAME_TYPE_CANONICAL_EX
Extended canonical name format. For example, "Fabrikam.com/Users Jeff Smith".
ADS_NAME_TYPE_SERVICE_PRINCIPAL_NAME
Service principal name format. For example, "www/www.fabrikam.com@fabrikam.com".
ADS_NAME_TYPE_SID_OR_SID_HISTORY_NAME
A SID string, as defined in the Security Descriptor Definition Language (SDDL), for either the SID of the current object or one from the object SID history. For example, "O:AOG:DAD:(A;;RPWPCCDCLCSWRCWDWOGA;;;S-1-0-0)"
new
Creates a new Win32::NameTranslate object, initialising a NameTranslate object internally.
Without any arguments it binds to ADS_NAME_INITTYPE_GC.
Can take five arguments.
The first argument is the type of initialisation to be performed, ADS_NAME_INITTYPE_ENUM.
The second argument is the name of the server or domain, depending on the type of initialisation. When ADS_NAME_INITTYPE_SERVER is used, specify the machine name of a directory server. When ADS_NAME_INITTYPE_DOMAIN is used, specify the domain name. This value is ignored when ADS_NAME_INITTYPE_GC is issued.
Optionally, you may provide a further three arguments to specify user credential than the current user, if these are provided, then all must be provided. The arguments are: username, user domain name and user password, respectively.
Examples:
# Just use default, which is ADS_NAME_INITTYPE_GC my $trans = Win32::NameTranslate->new(); # Bind to a specific domain my $trans = Win32::NameTranslate->new( ADS_NAME_INITTYPE_DOMAIN, 'localdomain.local' ); # Bind to a specific domain providing credentials my $trans = Win32::NameTranslate->new( ADS_NAME_INITTYPE_DOMAIN, 'localdomain.local', 'johnny', 'LOCAL', 'sekret' );
The set method must be called before the get method.
Directs the directory service to set up a specified object for name translation. This is a single wrapper around the underlying IADsNameTranslate::Set and IADsNameTranslate::SetEx methods.
IADsNameTranslate::Set
IADsNameTranslate::SetEx
The first argument required is a format type, ADS_NAME_TYPE_ENUM.
The second argument required is either a scalar of the name to translate or an arrayref of a number of names to translate.
# translate a single name from Canonical name format $trans->set( ADS_NAME_TYPE_CANONICAL, "Fabrikam.com/Users/Jeff Smith" ); # translate a number of names from Canonical name format $trans->set( ADS_NAME_TYPE_CANONICAL, [ "Fabrikam.com/Users/Jeff Smith", "Fabrikam.com/Users/Johnny Rotten", "Fabrikam.com/Users/Billy Bookcase" ] );
The method will return a true value on success or false on failure. You may check Win32::OLE->LastError to see what the error was.
true
false
Win32::OLE->LastError
Retrieves the name of a directory object in the specified format. set must be called before using this method. This is a single wrapper around the underlying IADsNameTranslate::Get and IADsNameTranslate::GetEx methods. What is returned is determined on whether set was called with a scalar or arrayref.
IADsNameTranslate::Get
IADsNameTranslate::GetEx
scalar
arrayref
The first argument required is the format type, ADS_NAME_TYPE_ENUM, of the output name.
If set was called with a single name to translate the result is a single output name.
If set was called with an arrayref the result is a list of output names.
# translate to RFC 1779 my $result = $trans->get( ADS_NAME_TYPE_1779 ); # we passed an arrayref, so get a list back my @results = $trans->get( ADS_NAME_TYPE_1779 );
multiple
Returns true or false (respectively) depending on whether set was called with an arrayref or not.
http://msdn.microsoft.com/en-us/library/windows/desktop/aa706046%28v=vs.85%29.aspx
http://www.rlmueller.net/NameTranslateFAQ.htm
Chris Williams <chris@bingosnet.co.uk>
This software is copyright (c) 2014 by Chris Williams.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Win32::NameTranslate, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Win32::NameTranslate
CPAN shell
perl -MCPAN -e shell install Win32::NameTranslate
For more information on module installation, please visit the detailed CPAN module installation guide.