Platform SDK: Active Directory, ADSI, and Directory Services

IADsNameTranslate::SetEx

The IADsNameTranslate::SetEx method sets up an array of objects for name translation. The specified objects must already exist in the connected directory server. To set the name and format of a single directory object, you can use the IADsNameTranslate::Set method.

HRESULT IADsNameTranslate::SetEx(
  long lnFormatType,
  VARIANT pVar
);

Parameters

lnFormatType: The format type of the input names. See ADS_NAME_TYPE_ENUM for more information.
pVar: A variant array of strings that hold the names of objects.

Return Values

This method supports the standard HRESULT return values, including:

S_OK: The name has been set successfully.
E_ADS_DSNAME_ERROR_RESOLVING: Cannot resolve the name.
E_ADS_DSNAME_ERROR_NOT_FOUND: Cannot find the name.
E_ADS_DSNAME_ERROR_NOT_UNIQUE: The name is not unique.
E_ADS_DSNAME_ERROR_NO_MAPPING: Cannot map the name.
E_ADS_DSNAME_ERROR_DOMAIN_ONLY: Can resolve the domain, but not the entire path.
E_FAIL: The operation has failed.
E_OUTOFMEMORY: The name cannot be set.

Remarks

You cannot use the IADsNameTranslate::SetEx method to set name translation for objects residing on other servers, even when the referral chasing option is set on. For more information on referral chasing, see IADsNameTranslate Property Methods.

You can use IADsNameTranslate::SetEx to set names for multiple objects. All the names, however, must be of the same format.

Example Code [C++]

The following C/C++ code snippet uses the IADsNameTranslate::SetEx method to set up an array of objects whose names are to be translated from the RFC 1779 format to the Windows NT 4.0 user name format.

IADsNameTranslate *pNto;
HRESULT hr;
hr = CoCreateInstance(CLSID_NameTranslate,
                      NULL,
                      CLSCTX_INPROC_SERVER,
                      IID_IADsNameTranslate,
                      (void**)&pNto);
if(FAILED(hr)) { exit 1;}
 
hr = pNto->Init(ADS_NAME_INITTYPE_SERVER,
                  L"myServer");
if (FAILED(hr)) { exit 1;}
 
LPWSTR str[1] = { L"CN=jim,CN=Users,DC=myDomain,DC=Microsoft,DC=COM",
                  L"CN=rob,CN=Users,DC=myDomain,DC=Microsoft,DC=COM"};
DWORD dwNum = sizeof(str)/sizeof(LPWSTR);
 
VARIANT varStr;
VariantInit(&varStr);
 
hr = ADsBuildVarArrayStr(str,dwNum,&varStr);
 
hr =pNto->SetEx(ADS_NAME_TYPE_1779, varStr);
if(FAILED(hr)) {exit 1;}
VariantClear(&varStr);
 
hr = pNto->GetEx(ADS_NAME_TYPE_GUID, &varStr);
if(FAILED(hr)) {exit 1;}
 
LONG lstart, lend;
SAFEARRAY *sa = V_ARRAY(&varStr);
VARIANT varItem;
VariantInit(&varItem);
printf("Names in the translated format:\n");
for (long idx = lstart; idx <= lend; idx++) 
{
    hr = SafeArrayGetElement(sa, &idx, &varItem);
    printf("   %S\n", V_BSTR(&varItem));
    VariantClear(&varItem);
}
VariantClear(&varStr);
pNto->Release();

Example Code [Visual Basic]

The following Visual Basic® code snippet uses the IADsNameTranslate::SetEx method to set up an array of objects whose names are to be translated from the RFC 1779 format to the Windows NT 4.0 user name format.

Dim nto as New NameTranslate
dso(0)="CN=johnDoe, CN=users, DC=Microsoft dc=COM"
dso(1)="CN=janeDoe, CN=users, DC=Microsoft dc=COM"
nto.Init  ADS_NAME_INITTYPE_SERVER, "myServer"
nto.SetEx ADS_NAME_TYPE_1779, dso
trans = nto.GetEx(ADS_NAME_TYPE_NT4)   
Msgbox "Translations: " & trans(0) & "," & trans(1)

Example Code [VBScript]

The following VBScript/ASP code snippet uses the IADsNameTranslate::SetEx method to set up an array of objects whose names are to be translated from the RFC 1779 format to the Windows NT 4.0 user name format.

<%@ Language=VBScript %>
<html>
<body>
<%
  Dim nto
  const ADS_NAME_INITTYPE_SERVER = 2  ' VBScript cannot read 
  const ADS_NAME_TYPE_1779 = 1        ' enumeration definition
  const ADS_NAME_TYPE_NT4 = 3
 
  dn(0) = "CN=johnDoe,CN=Users,DC=Microsoft,DC=COM" 
  dn(1) = "CN=janeDoe,CN=Users,DC=Microsoft,DC=COM" 
 
  Set nto = Server.CreateObject("NameTranslate")
  nto.Init ADS_NAME_INITTYPE_SERVER, "myServer"
  nto.SetEx ADS_NAME_TYPE_1779, dn
  result = nto.GetEx(ADS_NAME_TYPE_NT4)
 
  Response.Write "<p>Name in the translated format: " & result(0) & ", & result(1)
 
%>
</body>
</html>

Requirements

  Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with DSClient).
  Windows 95/98: Requires Windows 95 or later (with DSClient).
  Header: Declared in Iads.h.