/*******************************************************************************
*                              Openwave Systems.                               *
*                            Device Products Group                             *
*                            Melbourne,  AUSTRALIA                             *
****************************************************************************//**
   @file
   This is the API for the Openwave Linked List class (BREW extension).

*//*
   REVISION HISTORY:
   Date:       Who:               Email:
      - Details:
--------------------------------------------------------------------------------
   10 Nov 2004 Richard Willis     richard.willis@openwave.com
      - Initial version

*******************************************************************************/
/*******************************************************************************
*                  Copyright (c) Openwave Systems 1995-2004                    *
*                            All rights reserved.                              *
*                                                                              *
*     THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF Openwave Systems Inc.     *
*               The copyright notice above does not evidence any               *
*              actual or intended publication of such source code.             *
*******************************************************************************/

#ifndef _LINKLIST_H
#define _LINKLIST_H


/*==============================================================================

	INCLUDES

==============================================================================*/
#ifndef PREPROCESSING_ONLY //don't include if we're only pre-processing to expand the macros
#include <aee.h>
#include <aeeimage.h>
#include <aeeinterface.h>
#endif //ndef PREPROCESSING_ONLY

/*==============================================================================

	DEFINES

==============================================================================*/

												
/*==============================================================================

	TYPES

==============================================================================*/
/**@ingroup grp_init
 This is the optional item initialisation and deinitialisation function type
 that may be provided for each list.  Refer to ILINKEDLIST_oListInitialise(). */
typedef void (*tpfvInitFunc)( const void *kpvInstanceData, void *pvItem );


/*==============================================================================

	INTERFACE

==============================================================================*/
#ifndef PREPROCESSING_ONLY //don't define if we're only pre-processing to expand the macros

/**@ingroup grp_lifecycle
 This is the interface to the ILinkedList extension.  It is returned when
 the extension is created with a call to ISHELL_CreateInstance with a class
 ID of @ref AEECLSID_ILINKEDLIST.*/
typedef struct stILinkedList ILinkedList;


#ifndef DOXYGEN_SHOULD_SKIP_THIS //make doxygen ignore this block of code
///This is the definition of the virtual function structure
AEEINTERFACE( ILinkedList )
{
   //declare our virtual functions using macro expansion
   #define FUNCTION( RETURNS, NAME )   RETURNS (*NAME)(
   #define NO_PARAM                    void
   #define FIRST_PARAM( TYPE, NAME )   TYPE NAME
   #define NEXT_PARAM( TYPE, NAME )    , TYPE NAME
   #define END_FUNCTION                );
   #include "linklist.m"
};
#endif //ndef DOXYGEN_SHOULD_SKIP_THIS

#endif //ndef PREPROCESSING_ONLY


/*==============================================================================

	VIRTUAL FUNCTION ACCESSORS

==============================================================================*/
#ifndef PREPROCESSING_ONLY //don't define if we're only pre-processing to expand the macros

///@ingroup grp_lifecycle
///Wrapper for the lwAddRef() function.  This macro provides a
///convienient method for an application to call this function.
#define ILINKEDLIST_lwAddRef( psILinkedList ) \
   AEEGETPVTBL( (psILinkedList), ILinkedList )->lwListAddRef( psILinkedList )

///@ingroup grp_lifecycle
///Wrapper for the lwRelease() function.  This macro provides a
///convienient method for an application to call this function.
#define ILINKEDLIST_lwRelease( psILinkedList ) \
   AEEGETPVTBL( (psILinkedList), ILinkedList )->lwListRelease( psILinkedList )

///@ingroup grp_init
///Wrapper for the oListInitialise() function.  This macro provides a
///convienient method for an application to call this function.
#define ILINKEDLIST_oListInitialise( psILinkedList, kpczListName, kpvInstanceData, vfInitFunc, vfFreeFunc ) \
   AEEGETPVTBL( (psILinkedList), ILinkedList )->oListInitialise( psILinkedList, kpczListName, kpvInstanceData, vfInitFunc, vfFreeFunc )

///@ingroup grp_init
///Wrapper for the vListDeinitialise() function.  This macro provides a
///convienient method for an application to call this function.
#define ILINKEDLIST_vListDeinitialise( psILinkedList ) \
   AEEGETPVTBL( (psILinkedList), ILinkedList )->vListDeinitialise( psILinkedList )

///@ingroup grp_info
///Wrapper for the lwListGetNofItems() function.  This macro provides a
///convienient method for an application to call this function.
#define ILINKEDLIST_lwListGetNofItems( kpsILinkedList ) \
   AEEGETPVTBL( (kpsILinkedList), ILinkedList )->lwListGetNofItems( kpsILinkedList )

///@ingroup grp_add_delete
///Wrapper for the pvListAddItem() function.  This macro provides a
///convienient method for an application to call this function.
#define ILINKEDLIST_pvListAddItem( psILinkedList, wSize ) \
   AEEGETPVTBL( (psILinkedList), ILinkedList )->pvListAddItem( psILinkedList, wSize )

///@ingroup grp_fetch
///Wrapper for the pvListGetIndex() function.  This macro provides a
///convienient method for an application to call this function.
#define ILINKEDLIST_pvListGetIndex( psILinkedList, lwItemIndex ) \
   AEEGETPVTBL( (psILinkedList), ILinkedList )->pvListGetIndex( psILinkedList, lwItemIndex )

///@ingroup grp_fetch
///Wrapper for the pvListGetNextItem() function.  This macro provides a
///convienient method for an application to call this function.
#define ILINKEDLIST_pvListGetNextItem( psILinkedList, pvItem ) \
   AEEGETPVTBL( (psILinkedList), ILinkedList )->pvListGetNextItem( psILinkedList, pvItem )

///@ingroup grp_fetch
///Wrapper for the pvListGetPrevItem() function.  This macro provides a
///convienient method for an application to call this function.
#define ILINKEDLIST_pvListGetPrevItem( psILinkedList, pvItem ) \
   AEEGETPVTBL( (psILinkedList), ILinkedList )->pvListGetPrevItem( psILinkedList, pvItem )

///@ingroup grp_add_delete
///Wrapper for the vListDeleteIndex() function.  This macro provides a
///convienient method for an application to call this function.
#define ILINKEDLIST_vListDeleteIndex( psILinkedList, lwItemIndex ) \
   AEEGETPVTBL( (psILinkedList), ILinkedList )->vListDeleteIndex( psILinkedList, lwItemIndex )

///@ingroup grp_add_delete
///Wrapper for the vListDeleteItem() function.  This macro provides a
///convienient method for an application to call this function.
#define ILINKEDLIST_vListDeleteItem( psILinkedList, pvItem ) \
   AEEGETPVTBL( (psILinkedList), ILinkedList )->vListDeleteItem( psILinkedList, pvItem )

///@ingroup grp_add_delete
///Wrapper for the pvListDeleteItemGetNext() function.  This macro provides a
///convienient method for an application to call this function.
#define ILINKEDLIST_pvListDeleteItemGetNext( psILinkedList, pvItem ) \
   AEEGETPVTBL( (psILinkedList), ILinkedList )->pvListDeleteItemGetNext( psILinkedList, pvItem )

///@ingroup grp_info
///Wrapper for the vListValidate() function.  This macro provides a
///convienient method for an application to call this function.
#define ILINKEDLIST_oListValidate( psILinkedList ) \
   AEEGETPVTBL( (psILinkedList), ILinkedList )->oListValidate( psILinkedList )


/*==============================================================================

	FUNCTION DECLARATIONS

==============================================================================*/
/**@ingroup grp_lifecycle
@DESCRIPTION
 This function is used by the BREW core to load an instance of the class.  It
 is never called directly by an application.  Instead, it is called by BREW when
 an application requests an instance of this class via ISHELL_CreateInstance().\n\n
 The OEM should add this function to the BREW class table to allow
 ISHELL_CreateInstance() to create an instance of this extension.
@PARAMETERS
 @param[in] psIShell Contains pointer to the IShell interface. 
 @param[in] lwClassID Specifies the ClassID of the applet which is being loaded
 @param[in] ppsMe On return, points to a valid instance of the class provided
   this function returns SUCCESS.  If an error occurs, this will return NULL.
@RETURNS
 SUCCESS if the extension initialised ok, otherwise an error explaining the
 reason for the initialisation failure.
*/
int ILinkedList_New( IShell *psIShell, AEECLSID lwClassID, void **ppsMe );


#endif //ndef PREPROCESSING_ONLY

#endif /* _LINKLIST_H */



