Directory Services

IDirectorySearch::GetColumn

The IDirectorySearch::GetColumn method gets data from a named column of the search result.

HRESULT GetColumn( 
  ADS_SEARCH_HANDLE hSearchHandle,
  LPWSTR szColumnName,
  PADS_SEARCH_COLUMN pSearchColumn
);

Parameters

hSearchHandle: [in] Provides a handle to the search context.
szColumnName: [in] Provides the name of the column for which data is requested.
pSearchColumn: [out] Provides the address of a method-allocated ADS_SEARCH_COLUMN structure that contains the column from the current row of the search result.

Return Values

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

For other return values, see ADSI Error Codes.

Return Code	Description
S_OK	The column was obtained successfully.
E_ADS_BAD_PARAMETER	The search handle or the column is invalid.
E_ADS_COLUMN_NOT_SET	No attributes and values can be found for the column.

Remarks

The method allocates the memory for the ADS_SEARCH_COLUMN structure to hold the data of the column. But the caller is responsible for freeing the memory by calling IDirectorySearch::FreeColumn.

The IDirectorySearch::GetColumn method tries to read the schema definition of the requested attribute so it can return the attibute values in the appropriate format in the ADSVALUE structures (contained in the ADS_SEARCH_COLUMN structure). However, GetColumn can succeed even when the schema definition is not available, in which case the dwADsType member of the ADS_SEARCH_COLUMN structure returns ADSTYPE_PROV_SPECIFIC and the value is returned in an ADS_PROV_SPECIFIC structure. So when you are processing the results of a GetColumn call, you must check dwADsType to be sure that the data was returned in the expected format.

Example Code [C++]

ADS_SEARCH_COLUMN col;
/*.. Omit the set preference and execute*/
while( m_pSearch->GetNextRow( hSearch) != S_ADS_NOMORE_ROWS )
{
   // Get the Name and display it in the list.
   hr = m_pSearch->GetColumn( hSearch, pszAttr[0], &col );
   if ( SUCCEEDED(hr) )
   {
		switch (col.dwADsType)
		{
			 case ADSTYPE_CASE_IGNORE_STRING:
				printf("%S\n", col.pADsValues->CaseIgnoreString);
			 break;
 
			 case ADSTYPE_PROV_SPECIFIC:
				printf("%S\n", col.pADsValues-->ProviderSpecific.lpValue);
			 break;
 
			 default:
				printf("Unexpected ADsType: %d\n", col.dwADsType);
			 break;
	}

		{
	 
			 m_pSearch->FreeColumn( &col );
	}
   }
m_pSearch->CloseSearchHandle( hSearch );

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.