|
|
|
|
Frequently Asked Questions about NameTranslate
NameTranslate refers to 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. DsCrackNames uses RPC calls to Active Directory instead of LDAP queries. Although a search of Active Directory is still required to translate names, IADsNameTranslate is more efficient than other methods. 2. On what clients is NameTranslate available? The IADsNameTranslate interface is available on any client with Windows 2000 or above, or any other 32-bit client with DSClient installed. On Windows 95, Windows 98, Windows ME, or Windows NT clients, if DSClient is not installed, the IADsNameTranslate interface is only available if ADS is installed. The object is provided by ADSI on the client, but it must connect to Active Directory. The user must either be authenticated to the domain, or must provide credentials. 3. What can NameTranslate do for me? The IADsNameTranslate interface can translate Active Directory object names between several formats. NameTranslate can be used to convert the name of any Active Directory object from one format to another. Among the formats supported by NameTranslate are:
4. Why do I need to use NameTranslate? If you use the LDAP provider, which is more powerful and exposes more attributes than the WinNT provider, you must bind to Active Directory objects with the Distinguished Name of the object. However, most people refer to objects by their NT names. Users call this their UserName, or User ID. This single string value uniquely identifies the account in the domain. It is easier to remember and deal with than the lengthy Distinguished Name with its many components. In addition, the WshNetwork object can determine the NT name of the current user and the computer, but not the Distinguished Name. 5. How do I use NameTranslate? The steps required to convert names with the IADsNameTranslate interface are:
6. How about a quick example of the use of NameTranslate? The VBScript code below converts the NT name of a user to the Distinguished Name: ' Constants for the NameTranslate object. Const
ADS_NAME_INITTYPE_GC = 3 ' Initialize
NameTranslate by locating the Global Catalog. ' Use the
Get method to retrieve the RPC 1779 Distinguished Name.
' Escape any "/" characters with backslash escape character. ' All other characters that need to be escaped will be escaped. strUserDN =
Replace(strUserDN, "/", "\/")
The following characters can appear in Distinguished Names, but must be escaped with the backslash "\" escape character:
,\/#+<>;"=
The Get method of the NameTranslate object will return the Distinguished Name with these characters properly escaped, with the exception of the forward slash character "/". If this character is found in the Distinguished Name, it should be replaced by "\/" before using the Distinguished Name in a binding string. Otherwise, an error will be raised. 7. What are the options when I initialize NameTranslate? The Init method of the NameTranslate object accepts any of the following values: Const ADS_NAME_INITTYPE_DOMAIN = 1 Const ADS_NAME_INITTYPE_SERVER = 2 Const ADS_NAME_INITTYPE_GC = 3 With ADS_NAME_INITTYPE_DOMAIN you specify the domain that the NameTranslate object will connect to. With ADS_NAME_INITTYPE_SERVER you specify the server (domain controller) that the NameTranslate object will connect to. With ADS_NAME_INITTYPE_GC the NameTranslate object locates a Global Catalog. Unless you are converting the name of an object in another domain, there is no need to use anything other than ADS_NAME_INITTYPE_GC. Code examples using each follow: Const ADS_NAME_INITTYPE_DOMAIN = 1 Set objTrans = CreateObject("NameTranslate") objTrans.Init ADS_NAME_INITTYPE_DOMAIN, "MyDomain.com"
Const ADS_NAME_INITTYPE_SERVER = 2 Set objTrans = CreateObject("NameTranslate") objTrans.Init ADS_NAME_INITTYPE_SERVER, "MyServer"
The server name can be in the form "MyServer" or "MyServer.MyDomain.com"
Const ADS_NAME_INITTYPE_GC = 3 Set objTrans = CreateObject("NameTranslate") objTrans.Init ADS_NAME_INIITTYPE_GC, "" 8. What formats are accepted by the Set and Get methods of NameTranslate? The following constants define the formats used with the Set and Get methods to convert names: Const ADS_NAME_TYPE_1779 = 1 Const ADS_NAME_TYPE_CANONICAL = 2 Const ADS_NAME_TYPE_NT4 = 3 Const ADS_NAME_TYPE_DISPLAY = 4 Const ADS_NAME_TYPE_DOMAIN_SIMPLE = 5 Const ADS_NAME_TYPE_ENTERPRISE_SIMPLE = 6 Const ADS_NAME_TYPE_GUID = 7 Const ADS_NAME_TYPE_UNKNOWN = 8 Const ADS_NAME_TYPE_USER_PRINCIPAL_NAME = 9 Const ADS_NAME_TYPE_CANONICAL_EX = 10 Const ADS_NAME_TYPE_SERVICE_PRINCIPAL_NAME = 11 Const ADS_NAME_TYPE_SID_OR_SID_HISTORY_NAME = 12 9. How do I convert an NT name to a Distinguished Name? The VBScript example below converts the NT name of any user, in conjunction with the NetBIOS name of the domain, to the Distinguished Name of the user object: ' Constants for the NameTranslate object. Const
ADS_NAME_INITTYPE_GC = 3 strNetBIOSDomain = "MyDomain"
' Specify the NT name of the user. ' Initialize
NameTranslate by locating the Global Catalog. ' Use the
Get method to retrieve the RPC 1779 Distinguished Name. ' Escape any "/" characters with backslash escape character. ' All other characters that need to be escaped will be escaped. strUserDN =
Replace(strUserDN, "/", "\/") If the object with the specified NT name does not exist, the Set method of the NameTranslate object raises an error. To programmatically determine the NetBIOS name of the domain you have authenticated to, see FAQ # 16 below. 10. How do I convert the NetBIOS name of a computer to it's Distinguished Name? Computer accounts are just like user accounts, except that the sAMAccountName attribute of computer objects is terminated with "$". The NT name of a computer is the NetBIOS name with "$" appended on the end. The WshNetwork object returns the NetBIOS name of the computer. Before you can convert this name with NameTranslate, you must append the "$". For example: ' Constants for the NameTranslate object. Const
ADS_NAME_INITTYPE_GC = 3 strNetBIOSDomain = "MyDomain"
' Retrieve the NetBIOS name of the computer object from WshNetwork. ' Append a "$" on the end. Set objNetwork = GetObject("Wscript.Network") strComputer
= objNetwork.ComputerName & "$" ' Initialize
NameTranslate by locating the Global Catalog. ' Use the
Get method to retrieve the RPC 1779 Distinguished Name. This assumes that the Distinguished Name of the computer object does not contain any forward slash characters "/". If there are any forward slash characters, they must be escaped with the backslash escape character "\" to avoid an error when you bind to the object. If you use NameTranslate to convert the Distinguished Name of a computer object to the NT from, you will need to parse the value returned by the Get method for the NetBIOS domain name and the NT name of the computer. If you want the NetBIOS name of the computer, you will need to strip off the trailing "$". 11. How do I convert a Distinguished Name to an NT name? The VBScript example below converts the Distinguished Name of any user object to the NT form, which includes the NetBIOS name of the domain and the NT name of the user. ' Constants for the NameTranslate object. Const
ADS_NAME_INITTYPE_GC = 3 strUserDN = "cn=TestUser,ou=Sales,dc=MyDomain,dc=com"
' Use the NameTranslate object to convert the Distinguished Name ' of the
user to the NT Name required for the WinNT provider. ' Initialize
NameTranslate by locating the Global Catalog. ' Use the
Get method to retrieve the NT Name.
' Parse for the NetBIOS name of the domain and the NT name of the user. strNetBIOSDomain = Mid(strNTName, 1, InStr(strNTName, "\") - 1) strUserName
= Mid(strNTName, InStr(strNTName, "\") + 1) If the object with the specified Distinguished Name does not exist, the Set method of the NameTranslate object will raise an error. 12. How do I convert an NT Name to a Display Name? The VBScript example below converts the NT form of any user name to the Display Name of the user object (the value of the displayName attribute): ' Constants for the NameTranslate object. Const
ADS_NAME_INITTYPE_GC = 3 strNetBIOSDomain = "MyDomain"
' Specify the NT name of the user. ' Initialize
NameTranslate by locating the Global Catalog. ' Use the
Get method to retrieve the Display Name. If the NT name of the user does not exist, the Set
method of the NameTranslate object raises an error. However, if the object does
not have a value assigned to the displayName attribute, the Get method of the
NameTranslate object raises an error. The VBScript example below converts the NT form of any user name to the User Principal Name (the value of the userPrincipalName attribute): ' Constants for the NameTranslate object. Const
ADS_NAME_INITTYPE_GC = 3 strNetBIOSDomain = "MyDomain"
' Specify the NT name of the user. ' Initialize
NameTranslate by locating the Global Catalog. ' Use the
Get method to retrieve the User Principal Name. If the NT name of the user does not exist, the Set
method of the NameTranslate object raises an error. However, if the object does
not have a value assigned to the userPrincipalName attribute, the Get method of
the NameTranslate object raises an error. The VBScript example below converts the NT form of any user name to the GUID of the object. This is the value of the objectGUID attribute converted to a string format. It is also the value returned by the GUID property method of the object. ' Constants for the NameTranslate object. Const
ADS_NAME_INITTYPE_GC = 3 strNetBIOSDomain = "MyDomain"
' Specify the NT name of the user. ' Initialize
NameTranslate by locating the Global Catalog. ' Use the
Get method to retrieve the GUID of the user object. If the NT name of the user does not exist, the Set method of the NameTranslate object raises an error. 15. Can I convert the Display Name of a user to the Distinguished Name? Yes, you can, as long as the user has a Display Name that is unique. If you specify ADS_NAME_INITTYPE_GC, the Display Name must be unique in the forest. Otherwise, it must be unique in the domain. An error will be raised by the Set method if the Display Name value you specify does not uniquely identify the object. The corresponding attribute is displayName. Of course, the value cannot be empty (null). A VBScript example follows: ' Constants for the NameTranslate object. Const
ADS_NAME_INITTYPE_GC = 3 strDisplay = "Test User"
' Use the NameTranslate object to convert the
Display Name ' Initialize
NameTranslate by locating the Global Catalog. ' Use the
Get method to retrieve the Distinguished Name of the user object. If the Distinguished Name has any forward slash characters "/", they should be escaped with the backslash escape character "\" before using the Distinguished Name to bind to the corresponding object.
Most uses of the NameTranslate object require the NetBIOS name of the domain. If the client OS is NT or above, the environment variable %USERDOMAIN% is the NetBIOS name of the domain the user authenticated to. In VBScript, you can use the WshShell object to retrieve the value of this environment variable. For example: Set objShell = CreateObject("Wscript.Shell") strNetBIOSDomain = objShell.Environment("Process").Item("userdomain") On any client, you can use the RootDSE object to retrieve the default naming context, which is the Distinguished Name of the domain that the user authenticated to. Then, you can use the NameTranslate object to convert this to the NetBIOS name of the domain. For example: ' Constants
for the NameTranslate object.
' Determine
DNS name of domain from RootDSE. If the client is NT or above, you can also retrieve the NetBIOS domain name from the WshNetwork object. For example: Set objNetwork = CreateObject("Wscript.Network") strNetBIOSDomain = objNetwork.UserDomain Finally, if the client is Windows 2000 or above, or NT with DSClient installed, you can use the WinNTSystemInfo object. For example: Set objWinNTSysInfo = CreateObject("WinNTSystemInfo") strNetBIOSDomain = objWinNTSysInfo.DomainName You might attempt to retrieve the NetBIOS domain name from the domain object (binding with the DNS domain name retrieved from the RootDSE object). However, the nETBIOSName attribute of the domain object only has a value if the NetBIOS domain name is different from the Relative Distinguished Name of the domain (which is the top level domain component of the domain). Note that the only method above that works on all clients (including Win9x) is the one that retrieves the DNS domain name from the RootDSE object and uses NameTranslate to convert this to the NT format. 17. How do I specify credentials with NameTranslate? The InitEx method of the NameTranslate object is similar to the Init method, but allows you to specify a user name, domain, and password. The same connection options are supported. A VBScript example: ' Constants for the NameTranslate object. Const
ADS_NAME_INITTYPE_GC = 3 ' Specify a domain, user name, and password. ' The connection to Active Directory will be made with these credentials. strDomain = "MyDomain" strUser = "TestUser" strPassword = "xyz321"
' Initialize NameTranslate by locating the Global Catalog. ' Specify
credentials. ' Use the
Get method to retrieve the RPC 1779 Distinguished Name. ' Escape any "/" characters with backslash escape character. ' All other characters that need to be escaped will be escaped. strUserDN =
Replace(strUserDN, "/", "\/") 18. Can I convert the names of more than one object at a time? Yes, you can. The SetEx and GetEx methods of the NameTranslate object are similar to the Set and Get methods, except that they deal with arrays of names. A VBScript example: Dim arrNTNames(2) Dim arrUserDNs
' Constants for the NameTranslate object. Const
ADS_NAME_INITTYPE_GC = 3 arrNTNames(1) = "MyDomain\JoeSmith"
arrNTNames(2) = "MyDomain\MaryNelson" ' Initialize
NameTranslate by locating the Global Catalog. ' Use the
GetEx method to retrieve the RPC 1779 Distinguished Names. For k = 0 To UBound(arrUserDNs) Wscript.Echo arrUserDNs(k) Next
The array passed to the SetEx method can be declared with or without the upper bound specified. For example, you could use "Dim arrNTNames". However, then you must use the Array function to populate the array. For example, you could use:
Dim arrNTNames arrNTNames = Array("MyDomain\TestUser", "MyDomain\JoeSmith", "MyDomain\MaryNelson")
However, the array created by the GetEx method must not be declared with an upper bound or a "Type mismatch" error will be raised. You can enumerate the array created by the GetEx method in a "For Next" loop, as above, or your can use a "For Each" loop. For example, you could use:
Dim strDN For Each strDN In arrUserDNs Wscript.Echo strDN Next
If any of the objects specified in the array passed to the SetEx method are not found in Active Directory, the SetEx method raises an error. If any of the values in the array created by the GetEx method cannot be determined, the GetEx method raises an error.
20. Where can I get more information? For more information on NameTranslate, see the following links: IADsNameTranslate Interface: http://msdn2.microsoft.com/en-us/library/Aa706046.aspx ADS_NAME_INITTYPE_ENUM: http://msdn2.microsoft.com/en-us/library/Aa772266.aspx ADS_NAME_TYPE_ENUM: http://msdn2.microsoft.com/en-us/library/Aa772267.aspx Init Method: http://msdn2.microsoft.com/en-us/library/Aa706049.aspx Set Method: http://msdn2.microsoft.com/en-us/library/Aa706053.aspx Get Method: http://msdn2.microsoft.com/en-us/library/Aa706047.aspx InitEx Method: http://msdn2.microsoft.com/en-us/library/Aa706050.aspx SetEx Method: http://msdn2.microsoft.com/en-us/library/Aa706054.aspx GetEx Method: http://msdn2.microsoft.com/en-us/library/Aa706048.aspx |
Send mail to
HilltopLab@RLMueller.Net with questions or comments about this web site.
|