windows-xp/Source/XPSP1/NT/shell/osshell/dskquota/ui/dynarray.cpp

///////////////////////////////////////////////////////////////////////////////
/*  File: dynarray.cpp

    Description: Wrapper classes around the DPA_xxxxx and DSA_xxxxx functions 
        provided by the common control's library.  The classes add value by 
        providing multi-threaded protection, iterators and automatic cleanup 
        semantics.  

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/14/96    Initial creation.                                    BrianAu
    09/03/96    Added exception handling.                            BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
#include "pch.h" // PCH
#pragma hdrstop

#include "dynarray.h"



///////////////////////////////////////////////////////////////////////////////
/*  Function: PointerList::PointerList

    Description: Constructor.  

    Arguments:
        cItemGrow - Number of items to grow list when expansion is required.
                    Default value is 0 which causes DPA to use 8.

    Returns: Nothing.
    
    Exception: Throws OutOfMemory.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    09/03/96    Initial creation.                                    BrianAu
    02/21/97    Added cItemGrow argument.                            BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
PointerList::PointerList(
    INT cItemGrow
    )
      : m_hdpa(NULL)
{
    InitializeCriticalSection(&m_cs);
    if (NULL == (m_hdpa = DPA_CreateEx(cItemGrow, NULL)))
    {
        DeleteCriticalSection(&m_cs);
        throw CAllocException();
    }
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: PointerList::~PointerList

    Description: Destructor.  Destroys the DPA and closes the mutex handle.

    Arguments: None.

    Returns: Nothing.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/14/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
PointerList::~PointerList(
    VOID
    )
{
    Lock();
    if (NULL != m_hdpa)
        DPA_Destroy(m_hdpa);

    ReleaseLock();
    DeleteCriticalSection(&m_cs);
}



///////////////////////////////////////////////////////////////////////////////
/*  Function: PointerList::Count

    Description: Returns the number of elements in the list.

    Arguments: None.

    Returns: Count of elements in list.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/14/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
UINT 
PointerList::Count(
    VOID
    )
{
    UINT n = 0;

    AutoLockCs lock(m_cs);  // Get lock on container.  Will automatically release.

    DBGASSERT((NULL != m_hdpa));
    n = DPA_GetPtrCount(m_hdpa);

    return n;
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: PointerList::Insert

    Description: Inserts a pointer into the pointer list at a given index.
        If the index is beyond the upper bounds of the array, the array
        is extended by one and the item is appended to the list.

    Arguments:
        pvItem - Pointer value to add to list.

        index - List index where pointer is to be inserted.  All following
            items are shifted to one index higher.  The list automatically
            grows to accomodate as required.

    Returns: Nothing.

    Exceptions: OutOfMemory.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/14/96    Initial creation.                                    BrianAu
    09/03/96    Added exception handling.                            BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
VOID 
PointerList::Insert(
    LPVOID pvItem, 
    UINT index
    )
{
    DBGASSERT((NULL != pvItem));

    AutoLockCs lock(m_cs);  // Get lock on container.  Will automatically release.

    DBGASSERT((NULL != m_hdpa));

    if (DPA_InsertPtr(m_hdpa, index, pvItem) < 0)
    {
        throw CAllocException();
    }
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: PointerList::Replace

    Description: Replaces a pointer in the pointer list at a given index.
        If the index is beyond the upper bounds of the array, the array
        is extended by one and the item is appended to the list.

    Arguments:
        pvItem - Pointer value to add to list.

        index - List index where pointer is to be replaced.
          
    Returns:
        TRUE  - Success.
        FALSE - Invalid index or empty container.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/14/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
BOOL
PointerList::Replace(
    LPVOID pvItem, 
    UINT index
    )
{
    DBGASSERT((NULL != pvItem));

    AutoLockCs lock(m_cs);  // Get lock on container.  Will automatically release.

    DBGASSERT((NULL != m_hdpa));

    return DPA_SetPtr(m_hdpa, index, pvItem);
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: PointerList::Append

    Description: Appends a pointer to the end of the list.

    Arguments:
        pvItem - Pointer value to add to list.

    Returns: Nothing.

    Exceptions: OutOfMemory.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/14/96    Initial creation.                                    BrianAu
    09/03/96    Added exception handling.                            BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
VOID
PointerList::Append(
    LPVOID pvItem
    )
{
    DBGASSERT((NULL != pvItem));

    AutoLockCs lock(m_cs);  // Get lock on container.  Will automatically release.

    //
    // Yes, this is correct.  We're "inserting" an item to append something
    // to the list.  This saves a ( count - 1 ) calculation.
    //
    DBGASSERT((NULL != m_hdpa));
    Insert(pvItem, DPA_GetPtrCount(m_hdpa));
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: PointerList::Remove

    Description: Removes a pointer from the list at a given index.

    Arguments: 
        ppvItem - Address of variable to contain removed pointer value.

        index - List index where pointer is to be removed.  All following
            items are shifted to one index lower. 

    Returns:
        TRUE  - Success.
        FASLE - Index is invalid (or container is empty).

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/14/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
BOOL
PointerList::Remove(
    LPVOID *ppvItem, 
    UINT index
    )
{
    DBGASSERT((NULL != ppvItem));
    DBGASSERT((NULL != m_hdpa));

    AutoLockCs lock(m_cs);  // Get lock on container.  Will automatically release.

    *ppvItem = DPA_DeletePtr(m_hdpa, index);
    if (NULL == *ppvItem)
        return FALSE;

    return TRUE;
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: PointerList::RemoveLast

    Description: Removes the last pointer from the list.

    Arguments: 
        ppvItem - Address of variable to contain removed pointer value.
            All following items are shifted to one index lower. 

    Returns: 
        TRUE  - Success.
        FALSE - Container is emtpy.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/14/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
BOOL 
PointerList::RemoveLast(
    LPVOID *ppvItem
    )
{
    DBGASSERT((NULL != ppvItem));

    AutoLockCs lock(m_cs);  // Get lock on container.  Will automatically release.

    if (0 == Count())
        return FALSE;

    Remove(ppvItem, Count() - 1);
    return TRUE;
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: PointerList::Retrieve

    Description: Retrieve a pointer from the list at a given index.
        The pointer value is merely retrieved and not removed from the list.

    Arguments:
        ppvItem - Address of variable to contain retrieved pointer value.

        index - List index where pointer is to be retrieved.  

    Returns: 
        TRUE  - Success.
        FALSE - Invalid index or container is empty.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/14/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
BOOL
PointerList::Retrieve(
    LPVOID *ppvItem, 
    UINT index
    )
{
    DBGASSERT((NULL != ppvItem));

    AutoLockCs lock(m_cs);  // Get lock on container.  Will automatically release.

    DBGASSERT((NULL != m_hdpa));
    *ppvItem = DPA_GetPtr(m_hdpa, index);

    if (NULL == *ppvItem)
        return FALSE;

    return TRUE;
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: PointerList::RetrieveLast

    Description: Retrieves the last pointer from the list.

    Arguments: 
        ppvItem - Address of variable to contain retrieved pointer value.

    Returns:
        TRUE  - Success.
        FALSE - Container is empty.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/14/96    Initial creation.                                    BrianAu
    09/03/96    Added exception handling.                            BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
BOOL
PointerList::RetrieveLast(
    LPVOID *ppvItem
    )
{
    DBGASSERT((NULL != ppvItem));

    AutoLockCs lock(m_cs);  // Get lock on container.  Will automatically release.

    if (0 == Count())
        return FALSE;

    Retrieve(ppvItem, Count() - 1);
    return TRUE;
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: PointerList::FindIndex

    Description: Returns the list index associated with a given pointer
        value.  If duplicates exist, the index of the first item is returned.

    Arguments: 
        pvItem - Pointer value of item to be found.

        pIndex - Address of index variable to hold resulting index.

    Returns:
        TRUE  = Success
        FALSE = Item not found in list.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/14/96    Initial creation.                                    BrianAu
    09/03/96    Changed returned value to BOOL.                      BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
BOOL
PointerList::FindIndex(
    LPVOID pvItem, 
    INT *pIndex
    )
{
    INT i = -1;

    DBGASSERT((NULL != pIndex));
    DBGASSERT((NULL != pvItem));

    AutoLockCs lock(m_cs);  // Get lock on container.  Will automatically release.

    DBGASSERT((NULL != m_hdpa));
    i = *pIndex = DPA_GetPtrIndex(m_hdpa, pvItem);

    if (-1 == i)
        return FALSE;

    return TRUE;
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: PointerList::Sort

    Description: Sorts the list given a comparison function.

    Arguments: 
        pfnCompare - Address of comparison callback.

        lParam - 32-bit parameter passed to the callback.

    Returns:
        TRUE  = Success
        FALSE = Item not found in list.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    02/21/97    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
BOOL
PointerList::Sort(
    PFNDPACOMPARE pfnCompare, 
    LPARAM lParam
    )
{
    DBGASSERT((NULL != pfnCompare));

    AutoLockCs lock(m_cs);  // Get lock on container.  Will automatically release.

    DBGASSERT((NULL != m_hdpa));
    DBGASSERT((NULL != pfnCompare));

    return DPA_Sort(m_hdpa, pfnCompare, lParam);
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: PointerList::Search

    Description: Searches the list for a given item.

    Arguments: 
        pvKey - Address of key item used for search.

        pfnCompare - Address of comparison callback.

        uOptions - Options controlling sort operation.
            DPAS_SORTED       = Array is already sorted.  
                                Will use binary search.
            DPAS_INSERTBEFORE = If no exact match is found, return index of
                                previous best match.
            DPAS_INSERTAFTER  = If no exact match is found, return index of
                                next best match.

        iStart - Index of where to start search.  0 for start of list.

        lParam - 32-bit parameter passed to the callback.

    Returns: Index of found item or -1 if none found.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    02/21/97    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
INT
PointerList::Search(
    LPVOID pvKey,
    PFNDPACOMPARE pfnCompare, 
    UINT uOptions,
    INT iStart,
    LPARAM lParam
    )
{
    DBGASSERT((NULL != pfnCompare));

    AutoLockCs lock(m_cs);  // Get lock on container.  Will automatically release.

    DBGASSERT((NULL != m_hdpa));
    DBGASSERT((NULL != pvKey));
    DBGASSERT((NULL != pfnCompare));

    return DPA_Search(m_hdpa, pvKey, iStart, pfnCompare, lParam, uOptions);
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: PointerListIterator::operator = 

    Description: Assignment for PointerListIterator.

    Arguments:
        rhs - Reference to constant iterator that is the rhs of the assignment.

    Returns:
        Returns a reference to "this" iterator object following the assignment.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    02/27/97    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
PointerListIterator&
PointerListIterator::operator = (
    const PointerListIterator& rhs
    )
{
    if (this != &rhs)
    {
        m_pList = rhs.m_pList;
        m_Index = rhs.m_Index;
    }
    return *this;
}



///////////////////////////////////////////////////////////////////////////////
/*  Function: PointerListIterator::Advance

    Description: Both the Next() and Prev() iterator functions call this
        one function.  It handles the actual iteration.

    Arguments:
        ppvOut - Address of pointer variable to contain the value of the 
            pointer at the "current" iterator location.  The iterator is
            advance (or retreated) after the pointer value is copied to the
            destination.

        bForward - TRUE  = Advance toward end of list.
                   FALSE = Advance toward front of list.

    Returns:
        NO_ERROR      - Iterator advanced.  Returned pointer is valid.
        E_FAIL        - Iterator already at begining or end of list.  Returned
                        pointer will be NULL.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/14/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
HRESULT 
PointerListIterator::Advance(
    LPVOID *ppvOut, 
    BOOL bForward
    )
{
    LPVOID pv       = NULL;
    HRESULT hResult = NO_ERROR;

    DBGASSERT((NULL != ppvOut));

    m_pList->Lock();
    if (0 < m_pList->Count() && m_Index != EndOfList)
    {
        //
        // Get pointer value at index "m_Index".
        //
        DBGASSERT((NULL != m_pList->m_hdpa));
        pv = DPA_GetPtr(m_pList->m_hdpa, m_Index);

        if (bForward)
        {
            //
            // Advance iterator index.
            //
            if ((UINT)(++m_Index) == m_pList->Count())
                m_Index = EndOfList;
        }
        else
        {
            //
            // Retreat iterator index.
            //
            m_Index--;  // Will be -1 (EndOfList) if currently 0.
        }
    }
    else
        hResult = E_FAIL;

    m_pList->ReleaseLock();

    *ppvOut = pv;  // Return pointer value.

    return hResult;
}



///////////////////////////////////////////////////////////////////////////////
/*  Function: StructureList::StructureList

    Description: Constructor.

    Arguments:
        cbItem - Size of each item in bytes.

        cItemGrow - Number of items to grow array at each expansion.


    Returns: Nothing.

    Exceptions: OutOfMemory

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    09/06/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
StructureList::StructureList(
    INT cbItem, 
    INT cItemGrow
    )
{
    InitializeCriticalSection(&m_cs);

    if (NULL == (m_hdsa = DSA_Create(cbItem, cItemGrow)))
    {
        DeleteCriticalSection(&m_cs);
        throw CAllocException();
    }
}




///////////////////////////////////////////////////////////////////////////////
/*  Function: StructureList::~StructureList

    Description: Destructor.  Destroys the DSA and closes the mutex handle.

    Arguments: None.

    Returns: Nothing.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/24/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
StructureList::~StructureList(void)
{
    Lock();

    if (NULL != m_hdsa)
        DSA_Destroy(m_hdsa);

    ReleaseLock();
    DeleteCriticalSection(&m_cs);
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: StructureListIterator::operator = 

    Description: Assignment for StructureListIterator.

    Arguments:
        rhs - Reference to constant iterator that is the rhs of the assignment.

    Returns:
        Returns a reference to "this" iterator object following the assignment.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    02/27/97    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
StructureListIterator&
StructureListIterator::operator = (
    const StructureListIterator& rhs
    )
{
    if (this != &rhs)
    {
        m_pList = rhs.m_pList;
        m_Index = rhs.m_Index;
    }
    return *this;
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: StructureList::Count

    Description: Returns the number of elements in the list.

    Arguments: None.

    Returns: Count of elements in list.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/24/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
UINT StructureList::Count(VOID)
{
    UINT n = 0;

    AutoLockCs lock(m_cs);  // Get lock on container.  Will auto-release.

    DBGASSERT((NULL != m_hdsa));
    n = DSA_GetItemCount(m_hdsa);

    return n;
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: StructureList::Insert

    Description: Insert an item into the Structure list at a given index.
        If the index is beyond the upper bounds of the array, the array
        is extended by one and the item is appended to the list.

    Arguments:
        pvItem - Address of item to add to list.

        index - List index where item is to be inserted.  All following
            items are shifted to one index higher.  The list automatically
            grows to accomodate as required.

    Returns: Nothing.

    Exceptions: OutOfMemory.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/24/96    Initial creation.                                    BrianAu
    09/06/96    Added exception handling.                            BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
VOID
StructureList::Insert(
    LPVOID pvItem, 
    UINT index
    )
{
    DBGASSERT((NULL != pvItem));

    AutoLockCs lock(m_cs);   // Get lock on container.  Will auto-release.

    DBGASSERT((NULL != m_hdsa));

    if (DSA_InsertItem(m_hdsa, index, pvItem) < 0)
    {
        throw CAllocException();
    }
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: StructureList::Replace

    Description: Replaces an item in the Structure list at a given index.
        If the index is beyond the upper bounds of the array, the array
        is extended by one and the item is appended to the list.

    Arguments:
        pvItem - Address of item to replace existing item.

        index - List index where item is to be replaced.  

    Returns:
        TRUE  - Success.
        FALSE - Invalid index or empty container.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/24/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
BOOL
StructureList::Replace(
    LPVOID pvItem, 
    UINT index
    )
{
    DBGASSERT((NULL != pvItem));

    AutoLockCs lock(m_cs);  // Get lock on container.  Will auto-release.

    DBGASSERT((NULL != m_hdsa));

    return DSA_SetItem(m_hdsa, index, pvItem);
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: StructureList::Append

    Description: Appends an item to the end of the list.

    Arguments:
        pvItem - Address of item to add to list.

    Returns: Nothing.

    Exceptions: OutOfMemory.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/24/96    Initial creation.                                    BrianAu
    09/06/96    Added exception handling.                            BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
VOID
StructureList::Append(
    LPVOID pvItem
    )
{
    DBGASSERT((NULL != pvItem));

    AutoLockCs lock(m_cs);  // Get lock on container. Will auto-release.
    //
    // Yes, this is correct.  We're "inserting" an item to append something
    // to the list.  This saves a ( count - 1 ) calculation.
    //
    DBGASSERT((NULL != m_hdsa));
    Insert(pvItem, DSA_GetItemCount(m_hdsa));
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: StructureList::Remove

    Description: Removes an item from the list at a given index.

    Arguments: 
        pvItem - Address of buffer to receive removed item.  Assumes buffer
            is sized properly.

        index - List index where item is to be removed.  All following
            items are shifted to one index lower. 

    Returns:
        TRUE  - Success.
        FALSE - Invalid index or container is empty.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/24/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
BOOL
StructureList::Remove(
    LPVOID pvItem, 
    UINT index
    )
{
    DBGASSERT((NULL != pvItem));

    AutoLockCs lock(m_cs);  // Get lock on container.  Will auto-release.
    DBGASSERT((NULL != m_hdsa));

    if (!DSA_GetItem(m_hdsa, index, pvItem) ||
        !DSA_DeleteItem(m_hdsa, index))
    {
        return FALSE;
    }
    return TRUE;
}



///////////////////////////////////////////////////////////////////////////////
/*  Function: StructureList::Retrieve

    Description: Retrieve an item from the list at a given index.
        The item value is merely copied and not removed from the list.

    Arguments:
        pvItem - Address of buffer to receive removed item.  Assumes buffer
            is sized properly.

        index - List index where item is to be retrieved.  

    Returns:
        TRUE  - Success.
        FALSE - Invalid index or empty container.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/24/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
BOOL
StructureList::Retrieve(
    LPVOID pvItem, 
    UINT index
    )
{
    DBGASSERT((NULL != pvItem));

    AutoLockCs lock(m_cs);  // Get lock on container.  Will auto-release.
    DBGASSERT((NULL != m_hdsa));

    if (!DSA_GetItem(m_hdsa, index, pvItem))
    {
        return FALSE;
    }
    return TRUE;
}

    
///////////////////////////////////////////////////////////////////////////////
/*  Function: StructureList::RemoveLast

    Description: Removes the last item from the list.

    Arguments: 
        pvItem - Address of buffer to receive removed item.  Assumes buffer
            is sized properly.

    Returns:
        TRUE  - Success.
        FALSE - Empty container.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/24/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
BOOL
StructureList::RemoveLast(
    LPVOID pvItem
    )
{
    DBGASSERT((NULL != pvItem));

    AutoLockCs lock(m_cs);  // Get lock on container.  Will auto-release.

    DBGASSERT((NULL != m_hdsa));

    if (0 == DSA_GetItemCount(m_hdsa))
        return FALSE;

    Remove(pvItem, DSA_GetItemCount(m_hdsa) - 1);
    return TRUE;
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: StructureList::RetrieveLast

    Description: Retrieves the last pointer from the list.

    Arguments: 
        pvItem - Address of buffer to receive removed item.  Assumes buffer
            is sized properly.

    Returns:
        TRUE  - Success.
        FALSE - Empty container.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/24/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
BOOL
StructureList::RetrieveLast(
    LPVOID pvItem
    )
{
    DBGASSERT((NULL != pvItem));

    AutoLockCs lock(m_cs);  // Get lock on container.  Will auto-release.
    DBGASSERT((NULL != m_hdsa));

    if (0 == DSA_GetItemCount(m_hdsa))
        return FALSE;

    Retrieve(pvItem, DSA_GetItemCount(m_hdsa) - 1);
    return TRUE;
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: StructureList::Clear

    Description: Removes all items from the list.

    Arguments: None.

    Returns: Nothing.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/26/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
VOID
StructureList::Clear(
    VOID
    )
{
    AutoLockCs lock(m_cs);  // Get lock on container.  Will auto-release.

    DBGASSERT((NULL != m_hdsa));
    DSA_DeleteAllItems(m_hdsa);
}


///////////////////////////////////////////////////////////////////////////////
/*  Function: StructureListIterator::Advance

    Description: Both the Next() and Prev() iterator functions call this
        one function.  It handles the actual iteration.

    Arguments:
        ppvOut - Address of pointer variable to receive the address of the 
            item at the "current" iterator location.  The iterator is
            advance (or retreated) after the pointer value is copied to the
            destination.

        bForward - TRUE  = Advance toward end of list.
                   FALSE = Advance toward front of list.

    Returns:
        NO_ERROR      - Iterator advanced.  Returned pointer is valid.
        E_FAIL        - Iterator already at begining or end of list.  Returned
                        pointer will be NULL.

    Revision History:

    Date        Description                                          Programmer
    --------    ---------------------------------------------------  ----------
    06/24/96    Initial creation.                                    BrianAu
*/
///////////////////////////////////////////////////////////////////////////////
HRESULT 
StructureListIterator::Advance(
    LPVOID *ppvOut, 
    BOOL bForward
    )
{
    LPVOID pv       = NULL;
    HRESULT hResult = NO_ERROR;

    DBGASSERT((NULL != ppvOut));

    m_pList->Lock();
    if (0 < m_pList->Count() && m_Index != EndOfList)
    {
        //
        // Get address of item at index "m_Index".
        //
        DBGASSERT((NULL != m_pList->m_hdsa));
        pv = DSA_GetItemPtr(m_pList->m_hdsa, m_Index);

        if (bForward)
        {
            //
            // Advance iterator index.
            //
            if ((UINT)(++m_Index) == m_pList->Count())
                m_Index = EndOfList;
        }
        else
        {
            //
            // Retreat iterator index.
            //
            m_Index--;  // Will be -1 (EndOfList) if currently 0.
        }
    }
    else
        hResult = E_FAIL;

    m_pList->ReleaseLock();
    *ppvOut = pv;  // Return pointer value.

    return hResult;
}