NAME

CSSM_ModuleAttach

SYNOPSIS

CSSM_CSP_HANDLE CSSMAPI CSSM_ModuleAttach
    (const CSSM_GUID_PTR GUID,
    const CSSM_VERSION_PTR Version,
    const CSSM_API_MEMORY_FUNCS_PTR MemoryFuncs,
    uint32 SubserviceID,
    uint32 SubserviceFlags,
    uint32 Application,
    const CSSM_NOTIFY_CALLBACK Notification,
    const char *AppFileName,
    const char *AppPathName,
    const void * Reserved)

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 sub-services (as described in the service provider's documentation). The caller can specify a specific sub-service provided by the module. Sub-service flags may be required to set parameters for the service.

PARAMETERS

GUID (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 the service provider module that the application is compatible with.

MemoryFuncs (input)

A structure containing pointers to the memory routines.

SubserviceID (input)

The number of a sub-service provided by the module. This value should always be taken from the CSSM_MODULE_INFO structure to insure that a compatible identifier is used. (Service provider modules that implement only one service can use zero as the sub-service identifier.)

SubserviceFlags (input)

Bitmask of service options defined by a particular sub-service of the module. Legal values are described in module-specific documentation. A default set of flags is specified in the CSSM_MODULE_INFO structure for use by the caller.

Application (input/optional)

Nonce passed to the application when its callback is invoked allowing the application to determine the proper context of operation.

Notification (input/optional)

Callback provided by the application that is used by the add-in module to notify the application of certain events. For example, a CSP may use this callback in the following situations: a parallel operation completes, a token running in serial mode surrenders control to the application or the token is removed (hardware-specific).

AppFileName (input/optional)

The name of the file that implements the application (containing its main entry point). This file name is used to locate the application's credentials for purposes of application authentication by CSSM or by CSSM on behalf of the target add-in module. This input must be provided if the target add-in module defines a usage policy that requires authentication of the application's credentials. The add-in module's declared policy is recorded by the MODULE_FLAGS contained in module's MODULE_INFO structure and in the module's signed credentials. If application authentication is not required by the target add-in module, this parameter should be NULL.

AppPathName (input/optional)

The path to the file that implements the application (containing its main entry point). This path name is used to locate the application's credentials for purposes of application authentication by CSSM or by CSSM on behalf of the target add-in module. This input must be provided if the target add-in module defines a usage policy that requires authentication of the application's credentials. The add-in module's declared policy is recorded by the MODULE_FLAGS contained in the module's MODULE_INFO structure and in the module's signed credentials. If application authentication is not required by the target add-in module, this parameter should be NULL.

Reserved (input)

A reserved input.

RETURN VALUE

A handle is returned for the attached service provider module. If the handle is NULL, an error has occurred. Use CSSM_GetError to obtain the error code.

ERRORS

CSSM_INVALID_POINTER

Invalid pointer.

CSSM_MEMORY_ERROR

Internal memory error.

CSSM_INCOMPATIBLE_VERSION

Incompatible version.

CSSM_EXPIRE

Add-in module has expired.

CSSM_NOT_INITIALIZE

CSSM has not been invoked.

CSSM_ATTACH_FAIL

Unable to load service provider module.

SEE ALSO

CSSM_ModuleDetach