Directory Services

IADsNameTranslate

The IADsNameTranslate interface translates distinguished names (DNs) among various formats as defined in the ADS_NAME_TYPE_ENUM enumeration. The feature is available to objects in Active Directory®.

Name translations are performed on the directory server. To translate a DN, communicate with the server by means of a NameTranslate object, and specify which object is of interest and what format is desired. The following is the general process for using the IADsNameTranslate interface.

First, create an instance of the NameTranslate object.

Second, initialize the NameTranslate object by specifying the directory server using the IADsNameTranslate::Init or IADsNameTranslate::InitEx methods.

Third, set the directory object on the server by specifying the name with the IADsNameTranslate::Set method and the format with the IADsNameTranslate::SetEx method.

Fourth, retrieve the object name in the specified format with the IADsNameTranslate::Get or IADsNameTranslate::GetEx method.

The IADsNameTranslate interface is implemented in an NameTranslate object that must be explicitly instantiated. First, call the CoCreateInstance function in Visual C++, using the New operator in Visual Basic®, or invoking the CreateObject function in Visual Basic Scripting Edition. The example code is provided at the end of this topic to demonstrate how to create the NameTranslate object in Visual C++, Visual Basic, and VBScript/Active Server Pages.

Note The format elements as defined in the ADS_NAME_TYPE_ENUM enumeration and used by IADsNameTranslate are not equivalent and are non-interchangeable with the format elements used by the DsCrackName function. Do not confuse the proper use of these similarly named but non-interchangeable element formats.

Methods in Vtable Order

The IADsNameTranslate interface inherits the methods of the standard COM interfaces:

IUnknown
IDispatch

In addition, IADsNameTranslate defines the following methods.

Method	Description
put_ChaseReferral	Toggle referral chasing on or off.
Init	Initializes the Name Translate object with default credentials.
InitEx	Initializes the Name Translate object with specified credentials.
Set	Specifies the object name to be translated.
Get	Gets the object name, set by Set, in a specified format.
SetEx	Sets the names of multiple objects at the same time.
GetEx	Gets the names of the objects, set by SetEx, in a specified format.

Properties

The IADsNameTranslate interface defines the following property. The preceding table includes an access method for this property.

Property	Description
ChaseReferral	Toggles referral chasing on or off.

Example Code [C++]

To create an instance of the NameTranslate object, supply CLSID_NameTranslate as the class identifier and IID_IADsNameTranslate as the interface identifier when invoking the CoCreateInstance function.

IADsNameTranslate *pNto;
HRESULT hr;
hr = CoCreateInstance(CLSID_NameTranslate,
					NULL,
					CLSCTX_INPROC_SERVER,
					IID_IADsNameTranslate,
					(void**)&pNto);
if(FAILED(hr)) { exit 1;}
 
hr = pNto->InitEx(ADS_NAME_INITTYPE_SERVER,
				CComBSTR("aDsServer"),
				CComBSTR("aUser"),
				CComBSTR("userDomain"),
				CComBSTR("passwd"));
if (FAILED(hr)) { exit 1;}
 
hr =pNto->Set(ADS_NAME_TYPE_1779,
			 CComBSTR("cn=jeffsmith,cn=users,dc=Fabrikam,dc=com"));
if(FAILED(hr)) {exit 1;}
 
BSTR bstr;
hr = pNto->Get(ADS_NAME_TYPE_NT4, &bstr);
printf("Translation: %S\n", bstr);
 
SysFreeString(bstr);
pNto->Release();

Example Code [Visual Basic]

Declare an object variable as "New NameTranslate" to create an instance of the NameTranslate object in a Visual Basic® application.

Dim nto As New IADsNameTranslate
dso="CN=jeffsmith, CN=users, DC=Fabrikam dc=COM"
 
nto.Init  ADS_NAME_INITTYPE_SERVER, "aDsServer"
nto.Set ADS_NAME_TYPE_1779, dso
trans = nto.Get(ADS_NAME_TYPE_NT4)   ' trans="Fabrikam\jeffsmith"

Example Code [VBScript]

Use CreateObject("NameTranslate") (or Server.CreateObject("NameTranslate") on an ASP page) to create an instance of the NameTranslate object in VBScript.

<%@ Language=VBScript %>
<html>
<body>
<%
  Dim nto
  const ADS_NAME_INITTYPE_SERVER = 2
  const ADS_NAME_TYPE_1779 = 1
  const ADS_NAME_TYPE_NT4 = 3
 
  server = "aDsServer"
  user   = "jeffsmith"
  dom	= "Fabrikam"
  passwd = "top secret" 
  dn = "CN=jeffsmith,CN=Users,DC=Fabrikam,DC=COM" 
 
  Set nto = Server.CreateObject("NameTranslate")
  nto.InitEx ADS_NAME_INITTYPE_SERVER, server, user, dom, passwd
  nto.Set ADS_NAME_TYPE_1779, dn
  result = nto.Get(ADS_NAME_TYPE_NT4)
 
  Response.Write "<p>Translated name: " & result
 
%>
</body>
</html>

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Header: Declared in Iads.h.