Directory Services

IADsNameTranslate::GetEx

The IADsNameTranslate::GetEx method gets the object names in the specified format. The object names must be set by IADsNameTranslate::SetEx.

HRESULT GetEx( 
  long lnFormatType,
  VARIANT* pVarStr
);

Parameters

lnFormatType: The format type used for the output names. For more information about the various types of formats you can use, see ADS_NAME_TYPE_ENUM. This method does not support the ADS_NAME_TYPE_SID_OR_SID_HISTORY_NAME element in ADS_NAME_TYPE_ENUM.
pVarStr: A variant array of strings that hold names of the objects returned.

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 has 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

This method gets the names of multiple objects. However, all of the names returned use a single format.

When referral chasing is on, this method will not attempt to chase and resolve the path of a specified object not residing on the connected server.

Example Code [C++]

The following C/C++ code example shows how to translate a distinguished names that is compliant with RFC 1779 to the GUID format. The computer name of the directory server is "myServer".

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 code example shows how to convert multiple names from the RFC 1779 type to the GUID type. The computer name of the directory server is "myServer".

Dim nto As new NameTranslate
Dim result As Variant
Dim ns(1) As String
 
nto.Init ADS_NAME_INITTTYPE_SERVER, "myServer"
 
ns(0)="CN=rob,CN=users,DC=example,DC=Fabrikam,DC=COM,O=Internet"
ns(1)="CN=jim,CN=users,DC=example,DC=Fabrikam,DC=COM,O=Internet"
 
nto.SetEx ADS_NAME_TYPE_1779, ns
nto.GetEx ADS_NAME_TYPE_GUID, result
MsgBox "name(0): " & result(0) & " name(1): " & result(1)

Example Code [VBScript]

The following VBScript/ASP code example translates two distinguished names compliant with RFC 1779 to the GUID format. The computer name of the directory server is "myServer".

<%@ 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 = "myServer"
  user   = "jeffsmith"
  dom	= "Fabrikam"
  passwd = "top secret" 
 
  Set nto = Server.CreateObject("NameTranslate")
  nto.InitEx ADS_NAME_INITTYPE_SERVER, server, user, dom, passwd
 
  ns(0)="CN=rob,CN=users,DC=example,DC=Fabrikam,DC=COM,O=Internet"
  ns(1)="CN=jim,CN=users,DC=example,DC=Fabrikam,DC=COM,O=Internet"
 
  nto.SetEx ADS_NAME_TYPE_1779, ns
  result = nto.GetEx(ADS_NAME_TYPE_GUID)
 
  Response.Write "<p>Names 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.