Directory Services

IDirectoryObject::GetObjectAttributes

The IDirectoryObject::GetObjectAttributes method retrieves one or more specified attributes of the directory service object.

HRESULT GetObjectAttributes( 
  LPWSTR* pAttributeNames,
  DWORD dwNumberAttributes,
  PADS_ATTR_INFO* ppAttributeEntries,
  DWORD* pdwNumAttributesReturned
);

Parameters

pAttributeNames: [in] Specifies an array of names of the requested attributes.
To request all of the object's attributes, set pAttributeNames to NULL and set the dwNumberAttributes parameter to (DWORD)-1.
dwNumberAttributes: [in] Specifies the size of the pAttributeNames array. If -1, all of the object's attributes are requested.
ppAttributeEntries: [out] Pointer to a variable that receives a pointer to an array of ADS_ATTR_INFO structures that contain the requested attribute values. If no attributes could be obtained from the directory service object, the returned pointer is NULL.
pdwNumAttributesReturned: [out] Pointer to a DWORD variable that receives the number of attributes retrieved in the ppAttributeEntries array.

Return Values

This method returns the standard values, as well as the following:

For more information and other return values, see ADSI Error Codes.

Return Code	Description
S_OK	The attribute definitions were obtained successfully.
E_ADS_PROPERTY_NOT_FOUND	One or more requested attributes cannot be found.

Remarks

ADSI allocates the memory for the array of ADS_ATTR_INFO structures returned in the ppAttributeEntries parameter. The caller must call FreeADsMem to free the array.

The order of attributes returned in ppAttributeEntries is not necessarily the same as requested in pAttributeNames.

The IDirectoryObject::GetObjectAttributes method attempts to read the schema definition of the requested attributes so it can return the attibute values in the appropriate format in the ADSVALUE structures contained in the ADS_ATTR_INFO structures. However, GetObjectAttributes can succeed even when the schema definition is not available, in which case the dwADsType member of the ADS_ATTR_INFO structure returns ADSTYPE_PROV_SPECIFIC and the value is returned in an ADS_PROV_SPECIFIC structure. When you process the results of a GetObjectAttributes call, verify dwADsType to ensure that the data was returned in the expected format.

Example Code [C++]

The following C++ code example shows how the IDirectoryObject::GetObjectAttributes method can be used.

HRESULT hr;
IDirectoryObject *pDirObject = NULL;
 
hr = ADsGetObject(L"LDAP://CN=Jeff Smith,OU=Sales,DC=Fabrikam,DC=com",
					 IID_IDirectoryObject, 
					 (void**) &pDirObject );
 
if ( SUCCEEDED(hr) )
{
	ADS_ATTR_INFO *pAttrInfo=NULL;
	DWORD dwReturn;
	LPWSTR pAttrNames[]={L"givenName",L"sn", L"otherTelephone" };
	DWORD dwNumAttr=sizeof(pAttrNames)/sizeof(LPWSTR);

	//////////////////////////////////////////////////////
	// Get attribute values requested.
	// Be aware that the order is not necessarily the 
	// same as requested using pAttrNames.
	//////////////////////////////////////////////////////
	hr = pDirObject->GetObjectAttributes( pAttrNames, 
										dwNumAttr, 
										&pAttrInfo, 
										&dwReturn );
	 
	if ( SUCCEEDED(hr) )
	{
		for(DWORD idx = 0; idx < dwReturn; idx++ )
		{
			if ( _wcsicmp(pAttrInfo[idx].pszAttrName,L"givenName") == 0 )
			{
				switch (pAttrInfo[idx].dwADsType)
				{
					case ADSTYPE_CASE_IGNORE_STRING:
						printf("First Name: %S\n", pAttrInfo[idx].pADsValues->CaseIgnoreString);
						break;
		 
					case ADSTYPE_PROV_SPECIFIC:
						printf("First Name: %S\n", pAttrInfo[idx].pADsValues->ProviderSpecific.lpValue);
						break;
		 
					default:
						printf("Invalid ADsType: %d\n", pAttrInfo[idx].dwADsType);
						break;
			}
		}
			else if ( _wcsicmp(pAttrInfo[idx].pszAttrName, L"sn") == 0 )
			{
				switch (pAttrInfo[idx].dwADsType)
				{
					case ADSTYPE_CASE_IGNORE_STRING:
						printf("Last Name: %S\n", pAttrInfo[idx].pADsValues->CaseIgnoreString);
						break;
		 
					case ADSTYPE_PROV_SPECIFIC:
						printf("Last Name: %S\n", pAttrInfo[idx].pADsValues->ProviderSpecific.lpValue);
						break;
		 
					default:
						printf("Invalid ADsType: %d\n", pAttrInfo[idx].dwADsType);
						break;
			}
		}
			else if ( _wcsicmp(pAttrInfo[idx].pszAttrName, L"otherTelephone") == 0  )
			{   // Print the multi-valued property, "Other Telephones".
				switch (pAttrInfo[idx].dwADsType)
				{
					case ADSTYPE_CASE_IGNORE_STRING:
						printf("Other Telephones:");
						for (DWORD val=0; val < pAttrInfo[idx].dwNumValues; val++) 
						printf("  %S\n", pAttrInfo[idx].pADsValues[val].CaseIgnoreString);
						break;
		 
					case ADSTYPE_PROV_SPECIFIC:
						printf("Other Telephones:");
						for (DWORD val=0; val < pAttrInfo[idx].dwNumValues; val++) 
						printf("  %S\n", pAttrInfo[idx].pADsValues[val].CaseIgnoreString);
						break;
		 
					default:
						printf("Other Telephones:");
						for (DWORD val=0; val < pAttrInfo[idx].dwNumValues; val++) 
						printf("  %S\n", pAttrInfo[idx].pADsValues[val].CaseIgnoreString);
						break;
			}
		}
	}

		/////////////////////////////////////////////////////////////
		// Use FreeADsMem for all memory obtained from the ADSI call. 
		/////////////////////////////////////////////////////////////
		FreeADsMem( pAttrInfo );

}
 
	pDirObject->Release();
}

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.