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

FILE:      AEELocalStorage.h

SERVICES:  ILocalStorage

GENERAL DESCRIPTION:

    ILocalStorage provides an API to store an opaque 
     void pointer keyed by an AEECLSID.  This 
     interface should be supported (via IQueryInterface)
     by the Module object passed to the CreateInstance
     function of modules that meet the BREW kModule format.

   ILocalStorage's intended use when derived from
     an IModule is to store class variables
     for the interfaces implemented by a kModule, for
     example, the class' vtable.

PUBLIC CLASSES AND STATIC FUNCTIONS:

    ILocalStorage

INITIALIZATION & SEQUENCING REQUIREMENTS:

    See Exported Routines

        Copyright © 2004 QUALCOMM Incorporated.
               All Rights Reserved.
            QUALCOMM Proprietary/GTDR
=====================================================*/
#ifndef AEELOCALSTORAGE_H
#define AEELOCALSTORAGE_H

#include "AEEQueryInterface.h"

#define AEEIID_LOCALSTORAGE 0x0101e921

#define INHERIT_ILocalStorage(iname) \
   INHERIT_IQueryInterface(iname); \
   void  (*Lock)(iname *p);\
   void  (*Unlock)(iname *p);\
   int   (*Get)(iname *p, AEECLSID cls, void **ppValue);\
   int   (*Set)(iname *p, AEECLSID cls, void *pValue);\
   int   (*Clear)(iname *p, AEECLSID cls)

// declare the actual LocalStorage interface
AEEINTERFACE_DEFINE(ILocalStorage);

#define ILOCALSTORAGE_AddRef(p)               AEEGETPVTBL((p),ILocalStorage)->AddRef((p))
#define ILOCALSTORAGE_Release(p)              AEEGETPVTBL((p),ILocalStorage)->Release((p))
#define ILOCALSTORAGE_QueryInterface(p,i,ppo) AEEGETPVTBL((p),ILocalStorage)->QueryInterface((p),(i),(ppo))
#define ILOCALSTORAGE_Lock(p)                 AEEGETPVTBL((p),ILocalStorage)->Lock((p))
#define ILOCALSTORAGE_Unlock(p)               AEEGETPVTBL((p),ILocalStorage)->Unlock((p))
#define ILOCALSTORAGE_Get(p,c,pv)             AEEGETPVTBL((p),ILocalStorage)->Get((p),(c),(pv))
#define ILOCALSTORAGE_Set(p,c,v)              AEEGETPVTBL((p),ILocalStorage)->Set((p),(c),(v))
#define ILOCALSTORAGE_Clear(p,c)              AEEGETPVTBL((p),ILocalStorage)->Clear((p),(c))

/*=====================================================================
INTERFACES DOCUMENTATION
=======================================================================

ILocalStorage Interface

  ILocalStorage is implemented by the Module object passed to kModule 
  CreateInstance.  It is intended to be used by class implementations
  to store "Class" variables, i.e. globals, e.g. the class vtable.

  See AEEkModTable.h for more information.
  
=============================================================================

ILOCALSTORAGE_AddRef()

Description:
    This function is inherited from IBASE_AddRef(). 

Version:
   Introduced BREW PK 3.1

See Also:
    BREW SDK(TM) AEE Hierarchy Chart.
    ILOCALSTORAGE_Release()

=============================================================================

ILOCALSTORAGE_Release()

Description:
    This function is inherited from IBASE_Release(). 

Version:
   Introduced BREW PK 3.1

See Also:
    BREW SDK(TM) AEE Hierarchy Chart.
    ILOCALSTORAGE_AddRef()

=============================================================================

ILOCALSTORAGE_QueryInterface()

Description:
    This function is inherited from IQI_QueryInterface(). 

Version:
   Introduced BREW PK 3.1

See Also:
    BREW SDK(TM) AEE Hierarchy Chart.

=============================================================================

ILOCALSTORAGE_Get()

Description: 
   Find and return a class data pointer for the specified class id.

Prototype:
   int ILOCALSTORAGE_Get(ILocalStorage *picd, AEECLSID cls, void **ppValue);

Parameters:
   picd : pointer to the ILocalStorage interface
   cls : the AEECLSID of the class to get the data for
   void **ppValue: [out] pointer to be filled with the pointer to class
               data (if any)

Return value:
   SUCCESS if data is found (has been set)
   ENOSUCH if data can't be found (has not been set, or has been cleared)

Comments:  
   None

Version:
   Introduced BREW PK 3.1

See Also:
   ILOCALSTORAGE_Set()
   ILOCALSTORAGE_Clear()

=============================================================================

ILOCALSTORAGE_Set()

Description: 
   Set a class data pointer for the specified class id.

Prototype:
   int ILOCALSTORAGE_Set(ILocalStorage *picd, AEECLSID cls, void *pValue)

Parameters:
   picd : pointer to the ILocalStorage interface
   cls : the AEECLSID of the class to Set the data for
   void *pValue: pointer to class data to set

Return value:
   SUCCESS if data is set
   ENOMEMORY if memory is exhausted

Comments:  
   ILOCALSTORAGE_Set() is an implicit ILOCALSTORAGE_Clear() on any previous 
    value set.

Version:
   Introduced BREW PK 3.1

See Also:
   ILOCALSTORAGE_Get()
   ILOCALSTORAGE_Clear()

=============================================================================

ILOCALSTORAGE_Clear()

Description: 
   Clear a class data pointer for the specified class id.

Prototype:
   int ILOCALSTORAGE_Clear(ILocalStorage *picd, AEECLSID cls)

Parameters:
   picd : pointer to the ILocalStorage interface
   cls : the AEECLSID of the class to clear

Return value:
   SUCCESS if data is cleared
   ENOSUCH if data was not found (has not been set)

Comments:  
   None.

Version:
   Introduced BREW PK 3.1

See Also:
   ILOCALSTORAGE_Get()
   ILOCALSTORAGE_Set()

=============================================================================

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


#endif /* #ifndef AEELOCALSTORAGE_H */
