IShellFolder::CompareIDs (Windows Embedded CE 6.0)

Article
01/05/2012

1/6/2010

This method determines the relative order of two file objects or folders, given their item identifier lists.

Syntax

HRESULT CompareIDs(
  LPARAM lParam,
  LPCITEMIDLIST pidl1,
  LPCITEMIDLIST pidl2
);

Parameters

lParam
[in] Value that specifies how the comparison should be performed.

pidl1
[in] Pointer to the first item's ITEMIDLIST structure. It is relative to the folder. This ITEMIDLIST structure can contain more than one element; therefore, the entire structure must be compared, not just the first element.

pidl2
[in] Pointer to the second item's ITEMIDLIST structure. It will be relative to the folder. This ITEMIDLIST structure can contain more than one element; therefore, the entire structure must be compared, not just the first element.

Return Value

If this method is successful, the CODE field of the HRESULT contains one of the values in the following table.

Value	Description
Negative	Indicates that the first item should precede the second (pidl1 < pidl2).
Zero	Indicates that the two items are the same (pidl1 = pidl2).
Positive	Indicates that the first item should follow the second (pidl1 > pidl2).

For information regarding the extraction of the CODE field from the returned HRESULT, see Remarks.

If this method is unsuccessful, it returns an error code.

Remarks

Note to Callers

Use the HRESULT_CODE macro to extract the CODE field from the HRESULT and then cast the result as a short, as follows:

HRESULT hres = psf->CompareIDs(lParam, pidl1, pidl2);
if ((short)HRESULT_CODE(hres) < 0)
   { /* pidl1 comes first */ }
else if ((short)HRESULT_CODE(hres) > 0) 
   { /* pidl2 comes first */ }
else 
   { /* The two pidls are equal */ }

Note to Implementers

The lower sixteen bits of lParam define the sorting rule. Most applications set the sorting rule to the default value of zero, indicating that the two items should be compared by name. The system does not define any other sorting rules. Some folder objects might allow calling applications to use the lower sixteen bits of lParam to specify folder-specific sorting rules. The rules and their associated lParam values are defined by the folder.

The upper sixteen bits of lParam are reserved.

To extract the sorting rule, use a bitwise AND operator (&) to combine lParam with SHCIDS_COLUMNMASK (0X0000FFFF). This operation masks off the upper sixteen bits of lParam.

The following example shows how to use the MAKE_HRESULT macro to construct the return value. In this example, the function ComputeResult is implemented to compute the result.

short sResult = ComputeResult();
return MAKE_HRESULT(SEVERITY_SUCCESS, 0, sResult);

Note that a short only contains 16 bits, so the ComputeResult function must return a 16-bit value. Otherwise, the value is truncated.

Requirements

Header	shobjidl.h, shobjidl.idl
Library	Developer Implemented
Windows Embedded CE	Windows CE .NET 4.2 and later

Share via