NAME
   Win32::NameTranslate - Convenience perl wrapper around IADsNameTranslate
   interface

VERSION
   version 0.06

DESCRIPTION
   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" is usually accessed via Win32::OLE, this wrapper
   just makes it slightly easier to use.

SYNPOSIS
     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 );

EXPORTS
   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.

   "ADS_NAME_INITTYPE_ENUM"
       The "ADS_NAME_INITTYPE_ENUM" enumeration specifies the types of
       initialisation to perform on a "NameTranslate" object.

       "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,
           "[email protected]".

       "ADS_NAME_TYPE_ENTERPRISE_SIMPLE"
           Simple enterprise name format. For example,
           "[email protected]".

       "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.

       "ADS_NAME_TYPE_USER_PRINCIPAL_NAME"
           User principal name format. For example,
           "[email protected]".

       "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/[email protected]".

       "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)"

CONSTRUCTOR
   "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' );

METHODS
   The "set" method must be called before the "get" method.

   "set"
       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.

       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.

       Examples:

         # 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.

   "get"
       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".

       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.

       Examples:

         # 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.

SEE ALSO
   <http://msdn.microsoft.com/en-us/library/windows/desktop/aa706046%28v=vs
   .85%29.aspx>

   <http://www.rlmueller.net/NameTranslateFAQ.htm>

AUTHOR
   Chris Williams <[email protected]>

COPYRIGHT AND LICENSE
   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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.