IEnumHLITEM

The IEnumHLITEM interface is used to enumerate an array of HLITEM structures in a hyperlink browse context navigation stack. IEnumHLITEM has the same methods as all enumerator interfaces: Next, Skip, Reset, Clone. For general information on these methods, refer to IEnumXXXX.

When to Implement

IEnumHLITEM must be implemented by all hyperlink browse context objects to support calls to IHlinkBrowseContext::EnumNavigationStack, which supplies a pointer to the enumerator's IEnumHLITEM interface. Because there is a default implementation of IHlinkBrowseContext, you do not normally need to implement this interface.

When to Use

You do not normally need to call this interface directly. The default implementation of IHlinkBrowseContext calls this interface to examine the HLITEM structures in the browse context's navigation stack to determine which hyperlink sources have been previously visited.

The prototypes of the methods are as follows:

HRESULT Next(
  ULONG celt,  // Number of HLITEM structures returned in rgelt
  HLITEM * rgelt,
               // Array to receive enumerated HLITEM structures
  ULONG * pceltFetched
               // Location for actual number of HLITEM structures
);
 
HRESULT Skip(
  ULONG celt  // Number of elements to skip
);
 
HRESULT Reset(void);
 
HRESULT Clone(
  IEnumHLITEM * ppienumhlitem  // Location for newly created 
                               // enumerator list
);
 

Remarks

IEnumHLITEM::Next

Retrieves the next celt HLITEMs in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements. The number of elements actually retrieved is returned through pceltFetched.

IEnumHLITEM::Skip

Skips the next celt HLITEMs in the enumeration sequence.

IEnumHLITEM::Reset

Resets the enumeration sequence to the beginning. There is no guarantee that the same set of elements will be enumerated after the Reset, because it depends on the implementation doing the enumeration. It can be too expensive for some collections to guarantee this condition or it may not be possible due to concurrent access to the same collection by multiple threads or processes.

IEnumHLITEM::Clone

Creates another enumerator that contains the same state as the current enumerator to iterate over the same list. Using this function, a client can record a particular point in the enumeration sequence, and then return to that point at a later time.

The caller must release this new enumerator separately from the first enumerator.

QuickInfo

  Windows NT: Use version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in hlink.h.

See Also

HLITEM, IHlinkBrowseContext::EnumNavigationStack