NAME
   CSSM_ModuleAttach - Attach and verify a service provider
                       module (CDSA)

 SYNOPSIS
   # include <cssm.h>

        CSSM_RETURN CSSMAPI CSSM_ModuleAttach
        (const CSSM_GUID *ModuleGuid,
        const CSSM_VERSION *Version,
        const CSSM_API_MEMORY_FUNCS *MemoryFuncs,
        uint32 SubserviceID,
        CSSM_SERVICE_TYPE SubServiceType,
        CSSM_ATTACH_FLAGS AttachFlags,
        CSSM_KEY_HIERARCHY KeyHierarchy,
        CSSM_FUNC_NAME_ADDR *FunctionTable,
        uint32 NumFunctionTable,
        const void *Reserved,
        CSSM_MODULE_HANDLE_PTR NewModuleHandle)

 LIBRARY
   Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE)

 PARAMETERS
   ModuleGuid (input)
           A pointer to the CSSM_GUID structure containing the global
           unique identifier for the CSP module.

   Version (input)
           The major and minor version number of CDSA that the
           application is compatible with.

   MemoryFuncs (input)
           A structure containing pointers to the memory routines.

   SubserviceID (input)
           A SubServiceID identifying a particular subservice within
           the module. Subservice IDs can be obtained from MDS or
           gleaned from insertion events reported through the callback
           function installed through CSSM_ModuleLoad(). Modules that
           provide only one service can use zero as their subservice ID.

   SubServiceType (input)
           A service mask describing the type of service the caller is
           requesting of the service provider module.

   AttachFlags (input)
           A mask representing the caller's request for session-specific
           services.

   KeyHierarchy (input)
           The CSSM_KEY_HIERARCHY option directing CSSM what embedded key
           to use when verifying integrity of the named module.

   FunctionTable (input/output/optional)
           A table of function-name and API function-pointer pairs. The
           caller provides the name of the functions as input. The
           corresponding API function pointers are returned on output.
           The function table allows dynamic linking of CDSA interfaces,
           including interfaces to Elective Module Managers (EMMs),
           which are transparently loaded by CSSM during
           CSSM_ModuleAttach().

   NumFunctionTable (input)
           The number of entries in the FunctionTable parameter. If no
           FunctionTable is provided, this value must be zero.

   Reserved (input)
           This field is reserved for future use. It should always be set
           to zero

   NewModuleHandle (output)
           A new module handle that can be used to interact with the
           requested service provider. The value will be set to
           CSSM_INVALID_HANDLE if the function fails.

 DESCRIPTION
   This function attaches the service provider module and verifies that
   the version of the module expected by the application is compatible
   with the version on the system. The module can implement subservices
   (described in your service provider's documentation). The caller can
   specify a specific subservice provided by the module.

   If the subservice is supported as part of the CSSM framework as well
   as by an EMM, ModuleAttach attaches the Service Provider to the CSSM
   framework.  If the subservice is supported only by an EMM,
   ModuleAttach loads the appropriate EMM. The service provider is given
   an indication of whether it is being attached to the CSSM framework
   or an EMM.

   The caller can provide a function table containing function names for
   the desired services. On output each function name is matched with an
   API function pointer. The caller can use the pointers to invoke
   service module operations through CSSM.

 RETURN VALUE
   A CSSM_RETURN value indicating success or specifying a particular
   error condition. The value CSSM_OK indicates success. All other
   values represent an error condition.

 ERRORS
   Errors are described in the CDSA technical standard.  See CDSA.

        CSSMERR_CSSM_INVALID_ADDIN_FUNCTION_TABLE
        CSSMERR_CSSM_EMM_AUTHENTICATE_FAILED
        CSSMERR_CSSM_ADDIN_AUTHENTICATE_FAILED
        CSSMERR_CSSM_INVALID_SERVICE_MASK
        CSSMERR_CSSM_MODULE_NOT_LOADED
        CSSMERR_CSSM_INVALID_SUBSERVICEID
        CSSMERR_CSSM_INVALID_KEY_HIERARCHY
        CSSMERR_CSSM_INVALID_GUID

 SEE ALSO
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions: CSSM_ModuleDetach