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

FILE:  AEEkShell.h

SERVICES:  Domain-safe CreateInstance

GENERAL DESCRIPTION:

    IkShell_CreateInstance() instantiates classes
     from modules that adhere to the BREW kModule
     format.

PUBLIC CLASSES AND STATIC FUNCTIONS:

    IkShell

INITIALIZATION & SEQUENCING REQUIREMENTS:

    See Exported Routines

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

#include "AEEQueryInterface.h"

typedef int (*AEEkPFNCI)(IQueryInterface *piShell, 
                         IQueryInterface *piModule, 
                         AEECLSID cls, void **ppif);

#define AEEIID_KSHELL 0x0101e922

#define INHERIT_IkShell(iname) \
   INHERIT_IQueryInterface(iname); \
   int   (*CreateInstance)(iname *p, AEECLSID cls, void **ppif);\
   int   (*QueryClass)(iname *p, AEECLSID cls)

// declare the actual Create interface
AEEINTERFACE_DEFINE(IkShell);

#define IKSHELL_AddRef(p)                 AEEGETPVTBL((p),IkShell)->AddRef((p))
#define IKSHELL_Release(p)                AEEGETPVTBL((p),IkShell)->Release((p))
#define IKSHELL_QueryInterface(p,cls,ppo) AEEGETPVTBL((p),IkShell)->QueryInterface((p),(cls),(ppo))
#define IKSHELL_CreateInstance(p,cls,ppo) AEEGETPVTBL((p),IkShell)->CreateInstance((p),(cls),(ppo))
#define IKSHELL_QueryClass(p,cls)         AEEGETPVTBL((p),IkShell)->QueryClass((p),(cls))

/*=====================================================================
  DATA STRUCTURE DOCUMENTATION
=======================================================================

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

AEEkPFNCI

Description: 

Definition:
   typedef int (*AEEkPFNCI)(IQueryInterface *pikShell, 
                            IQueryInterface *piModule, 
                            AEECLSID cls, void **ppif);

Parameters:
   pikShell: the shell for the current process. Use this interface to
             get to IkShell and other system services (via IQI, more
             to come).
   piModule: NOT IModule, but a system object created
             by BREW to supply per-module services, like
             ILocalStorage.  See the implementation of 
             IWebUtil or IWebOpts for usage examples.  This object
             is per-process, per-module (where "module" in kStaticClass
             is determined by the value of pfnCreateInstance)
   cls: class to be instantiated (more than one class
        may be supported per pfnCreateInstance function, but each needs
        a new AEEkStaticClass)
   ppif: [out] where the new class instance is placed
         on SUCCESS

Return value:
    SUCCESS on success, some other AEEError on failure

Comments:
    The CreateInstance() function is treated as "synchronized", i.e.
    only one thread per process will enter the function at a time, 
    though the thread may re-enter the function (if CreateInstance()
    chains to another CreateInstance()...)  This is done to allow
    process-local and module-local storage to be allocated in a 
    safe way.

Version:
   Introduced BREW PK 3.1

See Also:
    AEEkStaticClass
    IKSHELL_CreateInstance()
=====================================================================

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

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

IkShell Interface

  IkShell is a BREW kModule's first interface back to BREW.  It provides
  kModules the ability to query and instantiate classes.  In BREW 3.1, the
  classes that may be instantiated via IkShell are restricted to those
  in AEEkStaticClass lists.  

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

IKSHELL_AddRef()

Description:
    This function is inherited from IBASE_AddRef(). 

Version:
   Introduced BREW PK 3.1

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

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

IKSHELL_Release()

Description:
    This function is inherited from IBASE_Release(). 

Version:
   Introduced BREW PK 3.1

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

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

IKSHELL_QueryInterface()

Description:
    This function is inherited from IQI_QueryInterface(). 

Version:
   Introduced BREW PK 3.1

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

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

IKShell_CreateInstance()

Description: 
   Instantiates an instance of the class specified.

Prototype:
   int IKSHELL_CreateInstance(IkShell *piks, AEECLSID cls, void **ppif);

Parameters:
   piks : pointer to the IkShell interface
   cls : the AEECLSID of the class to instantiate
   void **ppif: [out] pointer to be filled with new instance of the class
               requested

Return value:
    SUCCESS if instance of class created, otherwise a failure-specific
     error value from AEEError.h

Comments:  
   For BREW 3.1, only those classes meeting kModule are supported by 
    this function.

Version:
   Introduced BREW PK 3.1

See Also:
    ISHELL_CreateInstance()

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

IKShell_QueryClass()

Description: 
   Tests to see if IKSHELL_CreateInstance() can be expected to succeed.

Prototype:
   int IKSHELL_QueryClass(IkShell *piks, AEECLSID cls);

Parameters:
   piks : pointer to the IkShell interface
   cls : the AEECLSID of the class to test

Return value:
    SUCCESS if instance of class created, otherwise a failure-specific
     error value from AEEError.h

Comments:  
   For BREW 3.1, only those classes meeting kModule are supported by 
    this function.

   A SUCCESS return value from this function does not guarantee that
    IKSHELL_CreateInstance() will also succeed, since a module-specific
    error or resource allocation failure may occur during a 
    "real" creation.

Version:
   Introduced BREW PK 3.1

See Also:
    IKSHELL_CreateInstance()

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

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

#endif /* #ifndef AEEKSHELL_H */
