/*-----------------------------------------------------------------------
 * File: MAF_INTERFACE.H
 *
 * Copyright (c) 1995-2000 Intel Corporation. All rights reserved.
 *-----------------------------------------------------------------------
 */

/*
 * OpenVMS History
 *
 * 13-Sep-2002 Carol Kelly
 *        o Merge in V3_14 changes
 *
 */

#ifndef MAF_INTERFACE_H
#define MAF_INTERFACE_H

#ifndef MAF_CONFIG_H
#error maf_config.h must be included before this file
#endif
#ifndef _CSSMTYPE_H
#error $/inc/cssmtype.h must be included before this file
#endif
#ifndef __MAF_INTEG_H__
#error maf_integ.h must be included before this file
#endif
#if ADDIN_NEED_ADDIN_ATTACH_STRUCT
# ifndef __COLLECTN_H__
# error maf_collectn.h must be included before this file
# endif
#endif

#ifdef __cplusplus
extern "C" {
#endif

/*-----------------------------------------------------------------------------
 * Name: MAF_MODULE_LOAD_TRACKER
 *
 * Description:
 * An instance of this structure is created for every CSSM that loads the
 * module. This structure holds state that is global to a CSSM, and tracks
 * the number of times a module has been loaded
 *---------------------------------------------------------------------------*/
typedef struct _maf_module_load_tracker
{
#ifdef _DEBUG
    /* Magic Number that is used to verify the integrity of the structure */
    unsigned long debug_MagicNumber;
#endif

    /* GUID of the CSSM to which this load belongs */
    CSSM_GUID CssmGuid;

    /* Module event callback and context for this CSSM */
    CSSM_SPI_ModuleEventHandler ModuleEventHandler;
    const void *ModuleEventHandlerCtx;

    /* Number of times that this CSSM has loaded this module */
    uint32 NumLoads;

    /* Verified handle of the CSSM */
    ADDIN_MODULE_HANDLE hCssm;

#if ADDIN_NEED_ADDIN_LOAD_STRUCT
    /* Custom data for every addin module, customized through maf_config.h */
    ADDIN_LOAD_DATA AddinLoadData;
#endif
}
MAF_MODULE_LOAD_TRACKER, *MAF_MODULE_LOAD_TRACKER_PTR;

/*-----------------------------------------------------------------------------
 * Name: CSSM_MODULE_ATTACH_TRACKER
 *
 * Description:
 * An instance of this structure is created for every attach to the addin. This 
 * structure holds state that is global to an attach.
 *---------------------------------------------------------------------------*/
typedef struct _maf_module_attach_tracker
{
#ifdef _DEBUG
    /* Magic Number that is used to verify the integrity of the structure */
    unsigned long debug_MagicNumber;
#endif

    /* Parameter values passed by CSSM during attach */
    uint32 SubServiceID;
    CSSM_SERVICE_TYPE SubServiceType;
    CSSM_MODULE_HANDLE ModuleHandle;
    CSSM_KEY_HIERARCHY KeyHierarchy;

    /* Memory functs to use when returning memory to the application through
     * protected SPIs.
     */
    CSSM_UPCALLS AppUpcalls;

    /* Reference to the CSSM that made this attach.
     */
    ADDIN_MODULE_HANDLE hCssm;
    ADDIN_MODULE_HANDLE hModuleManager;
    ADDIN_MODULE_HANDLE hCaller;

    /* Reference to a CSSM_MODULE_LOAD_TRACKER node */
    MLC_LOCK_REF LoadLockRef;

#if ADDIN_NEED_ADDIN_ATTACH_STRUCT
    /* Custom data for every addin module, customized through maf_config.h */
    ADDIN_ATTACH_DATA AddinAttachData;
#endif
}
MAF_MODULE_ATTACH_TRACKER, *MAF_MODULE_ATTACH_TRACKER_PTR;

#if ADDIN_NEED_ADDIN_LOAD_STRUCT
/*-----------------------------------------------------------------------------
 * Name: Addin_GetLoadData
 *
 * Description:
 * Function that returns the ADDIN_LOAD_DATA structure inside the load
 * tracker for the current thread. Addin must call Addin_SPIBegin before calling
 * this function. This data should not be modified unless ADDIN_NEED_LOAD_WRITER_LOCK
 * is true.
 *
 * Parameters: 
 * None.
 * 
 * Return Code:
 * On success, a pointer to a ADDIN_LOAD_DATA, otherwise NULL
 *---------------------------------------------------------------------------*/
#if (ADDIN_NEED_LOAD_WRITER_LOCK == 0)
const
#endif
ADDIN_LOAD_DATA * Addin_GetLoadData();
#endif

#if ADDIN_NEED_ADDIN_ATTACH_STRUCT
/*-----------------------------------------------------------------------------
 * Name: Addin_GetAttachData
 *
 * Description:
 * Function that returns the ADDIN_ATTACH_DATA structure inside the attach
 * tracker for the current thread. Addin must call Addin_SPIBegin before calling
 * this function. This data should not be modified unless ADDIN_NEED_ATTACH_WRITER_LOCK
 * is true.
 *
 * Parameters: 
 * None.
 * 
 * Return Code:
 * On success, a pointer to a ADDIN_ATTACH_DATA, otherwise NULL
 *---------------------------------------------------------------------------*/
#if (ADDIN_NEED_ATTACH_WRITER_LOCK == 0)
const
#endif
ADDIN_ATTACH_DATA * Addin_GetAttachData();

/*-----------------------------------------------------------------------------
 * Name: Addin_GetAttachTrackerFromLock
 *
 * Description:
 * Returns the CSSM_MODULE_ATTACH_TRACKER structure from a lock reference.
 * Caller must insure that the lock reference is appropriately locked.
 *
 * Parameters: 
 * LockRef (input) : Lock reference to query.
 * ppAttachTracker (ouput) : Pointer that will receive the address of the
 *                           attach tracker record.
 * 
 * Return Code:
 * CSSM_OK : Attach tracker returned.
 * CSSM_INVALID_HANDLE : LockRef does not protect an attach tracker record.
 *---------------------------------------------------------------------------*/
CSSM_RETURN Addin_GetAttachTrackerFromLock(
                            MLC_LOCK_REF LockRef,
                            const MAF_MODULE_ATTACH_TRACKER **ppAttachTracker );

/*-----------------------------------------------------------------------------
 * Name: Addin_GetAttachDataFromLock
 *
 * Description:
 * Returns the ADDIN_ATTACH_DATA structure from a lock reference. Caller must
 * insure that the lock reference is appropriately locked.
 *
 * Parameters: 
 * LockRef (input) : Lock reference to query.
 * ppAttachData (ouput) : Pointer that will receive the address of the
 *                        attach data record.
 * 
 * Return Code:
 * CSSM_OK : Attach tracker returned.
 * CSSM_INVALID_HANDLE : LockRef does not protect an attach tracker record.
 *---------------------------------------------------------------------------*/
CSSM_RETURN Addin_GetAttachDataFromLock(
                            MLC_LOCK_REF LockRef,
                            ADDIN_ATTACH_DATA **ppAttachData );
#endif

/*-----------------------------------------------------------------------------
 * Name: Addin_GetLoadTracker
 *
 * Description:
 * Function that returns the CSSM_MODULE_LOAD_TRACKER structure for the current 
 * thread. Addin must call Addin_SPIBegin before calling this function. The 
 * structure returned should not be modified.
 *
 * Parameters: 
 * None.
 * 
 * Return Code:
 * On success, a pointer to a CSSM_MODULE_LOAD_TRACKER, otherwise NULL
 *---------------------------------------------------------------------------*/
const MAF_MODULE_LOAD_TRACKER * Addin_GetLoadTracker();

/*-----------------------------------------------------------------------------
 * Name: Addin_GetAttachTracker
 *
 * Description:
 * Function that returns the CSSM_MODULE_ATTACH_TRACKER structure for the current 
 * thread. Addin must call Addin_SPIBegin before calling this function. The 
 * structure returned should not be modified.
 *
 * Parameters: 
 * None.
 * 
 * Return Code:
 * On success, a pointer to a CSSM_MODULE_ATTACH_TRACKER, otherwise NULL
 *---------------------------------------------------------------------------*/
const MAF_MODULE_ATTACH_TRACKER * Addin_GetAttachTracker();

#ifdef __cplusplus
}
#endif

#endif