Directory Services

IADsNameTranslate::SetEx

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

HRESULT SetEx( 
  long lnFormatType,
  VARIANT pVar
);

Parameters

lnFormatType: The format type of the input names. For more information, see ADS_NAME_TYPE_ENUM.
pVar: A variant array of strings that hold object names.

Return Values

This method supports the standard HRESULT return values, including:

Return Code	Description
S_OK	The name has been set successfully.
E_FAIL	The operation failed.
E_OUTOFMEMORY	A memory allocation failure occurred.
E_ADS_BAD_PARAMETER	One or more parameters are invalid.
HRESULT_FROM_WIN32(ERROR_DS_NAME_ERROR_RESOLVING)	Cannot resolve the name.
HRESULT_FROM_WIN32(ERROR_DS_NAME_ERROR_NOT_FOUND)	The name cannot be found or the caller does not have permission to access the name.
HRESULT_FROM_WIN32(ERROR_DS_NAME_ERROR_NOT_UNIQUE)	The input name is mapped to more than one output name or the desired format did not have a single, unique value for the object found.
HRESULT_FROM_WIN32(ERROR_DS_NAME_ERROR_NO_MAPPING)	The input name was found, but the associated output format cannot be found.
HRESULT_FROM_WIN32(ERROR_DS_NAME_ERROR_DOMAIN_ONLY)	Unable to resolve the entire name, but the domain in which the object resides could be determined.
HRESULT_FROM_WIN32(ERROR_DS_NAME_ERROR_NO_SYNTACTICAL_MAPPING)	A syntactical mapping cannot be performed on the client without transmitting over the network.
HRESULT_FROM_WIN32(ERROR_DS_NAME_ERROR_TRUST_REFERRAL)	The name is from an external trusted forest.

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 about 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 example 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,
				CComBSTR("myServer"));
if (FAILED(hr)) { exit 1;}
 
LPWSTR str[1] = { L"CN=jim,CN=Users,DC=myDomain,DC=Fabrikam,DC=COM",
				L"CN=rob,CN=Users,DC=myDomain,DC=Fabrikam,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 example 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=jeffSmith, CN=users, DC=Fabrikam dc=COM"
dso(1)="CN=brendaDiaz, CN=users, DC=Fabrikam 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 example 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=jeffSmith,CN=Users,DC=Fabrikam,DC=COM" 
  dn(1) = "CN=brendaDiaz,CN=Users,DC=Fabrikam,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

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.