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 *pcFetched         // Location for actual number of HLITEM structures          
                                                                                         

   );                                                                                    
                                                                                         

    ULONG 

cHlitems        // Number of elements to skip        
                                                               

   );                                                          
                                                               

    IEnumHLITEMs **

ppEnumHlitems             // Location for newly created enumerator list        
                                                                                                  

   );                                                                                             
                                                                                                  

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.

See Also

HLITEM, IEnumXXXX, IHlinkBrowseContext::EnumNavigationStack