Platform SDK: Active Directory, ADSI, and Directory Services

IADsNameTranslate

The IADsNameTranslate interface is designed for translating 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 carried out on the directory server. To have a DN translated, you communicate with the server by means of a NameTranslate object, specifying which object is of interest and what format is desired. The general practice of applying IADsNameTranslate thus involves the following steps:

Create an instance of the NameTranslate object.
Initialize the NameTranslate object by specifying the directory server, using IADsNameTranslate::Init or IADsNameTranslate::InitEx.
Set the directory object on the server by specifying the name and format, using IADsNameTranslate::Set or IADsNameTranslate::SetEx.
Retrieve the object name in the specified format, using IADsNameTranslate::Get or IADsNameTranslate::GetEx.

The IADsNameTranslate interface is implemented in an NameTranslate object that must be instantiated explicitly. The first step is to 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 codes are given at the bottom of this page to demonstrate how to create the NameTranslate object in Visual C++, Visual Basic and VBScript/Active Server Pages.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.

IDispatch Methods	Description
GetTypeInfoCount	Gets the number of type descriptions.
GetTypeInfo	Gets a description of the object's programmable interface.
GetIDsOfNames	Maps the name of the method or property to the DISPID.
Invoke	Calls one of the object's methods or gets and sets one of its properties.

IADsNameTranslate Property Methods	Description
put_ChaseReferral	Turns 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 whose name is to be translated.
Get	Gets the name of the object, 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.

Example Code [C++]

To create an instance of the NameTranslate object, you need to 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,
                  L"aDsServer",
                  L"aUser",
                  L"userDomain",
                  L"passwd");
if (FAILED(hr)) { exit 1;}
 
hr =pNto->Set(ADS_NAME_TYPE_1779,
             L"cn=jsmith,cn=users,dc=Microsoft,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 NameTranslate
dso="CN=jsmith, CN=users, DC=Microsoft dc=COM"
 
nto.Init  ADS_NAME_INITTYPE_SERVER, "aDsServer"
nto.Set ADS_NAME_TYPE_1779, dso
trans = nto.Get(ADS_NAME_TYPE_NT4)   ' trans="Microsoft\jsmith"

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   = "jsmith"
  dom    = "Microsoft"
  passwd = "top secret" 
  dn = "CN=jsmith,CN=Users,DC=Microsoft,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