NAME

CSSM_GetModuleInfo

SYNOPSIS

CSSM_MODULE_INFO_PTR CSSMAPI CSSM_GetModuleInfo
    (const CSSM_GUID_PTR ModuleGUID,
    CSSM_SERVICE_MASK ServiceMask,
    sint32 SubserviceID,
    CSSM_INFO_LEVEL InfoLevel);

DESCRIPTION

This function returns descriptive information about the module identified by the GUID. The information returned can include all of the capability information, for each subservices for each of the service types implemented by the selected module. The request for information can be limited to a particular set of services, as specified by the service bit mask. The request may be further limited to one or all of the sub-services implemented in one or all of the service categories. Finally the detail level of the information returned can be controlled by the InfoLevel input parameter. This is particularly important for modules with dynamic capabilities. InfoLevel can be used to request static attribute values only or dynamic values.

PARAMETERS

ModuleGUID (input)

A pointer to the CSSM_GUID structure containing the global unique identifier for the service provider module.

ServiceMask (input)

A bit mask specifying the module usage types used to restrict the capabilities information returned by this function. An input value of zero specifies all usages for the specified module.

SubserviceID (input)

A single sub-service ID or the value CSSM_ALL_SUBSERVICES must be provided. If a sub-service ID is provided the get operation is limited to the specified sub-service. Note that the operation may already be limited by a service mask. If so, the sub-service ID applies to all service categories selected by the service mask. If CSSM_ALL_SUBSERVICES is specified, information for all sub-services (as limited by the service mask) are returned by this function.

InfoLevel (input)

Indicates the level of detail returned by this function. Information retrieval can be restricted as follows:

• CSSM_INFO_LEVEL_MODULE-returns only the information contained in the CSSM_SERVICE_INFO structure.

• CSSM_INFO_LEVEL_SUBSERVICE-returns the information returned by CSSM_INFO_LEVEL_MODULE and the information contained in the XXsubservice structure, where XX corresponds to the module type, such as tpsubservice, clsubservice, dlsubservice, cpsubservice.

• CSSM_INFO_LEVEL_STATIC_ATTR-returns the information returned by CSSM_INFO_LEVEL_SUBSERVICE and the attribute and capability values that are statically defined for the module.

• CSSM_INFO_LEVEL_ALL_ATTR-returns the information returned by CSSM_INFO_LEVEL_SUBSERVICE and the attribute and capability values that are statically or dynamically defined for the module. Dynamic modules, whose capabilities change over time, support a query function used by CSSM to interrogate the module's current capability status.

RETURN VALUE

A pointer to a module info structure containing a pointer to an array of zero or more service information structures. Each structure contains type information identifying the service description as representing certificate library services, data storage library services, and so on. The service descriptions are sub-classed into sub-service descriptions which describe the attributes and capabilities of a sub-service.

ERRORS

CSSM_INVALID_POINTER

Invalid pointer.

CSSM_INVALID_USAGE_MASK

Invalid bit mask.

CSSM_INVALID_SUBSERVICEID

Invalid sub-service ID.

CSSM_INVALID_INFO_LEVEL

Invalid info level indicator.

CSSM_MEMORY_ERROR

Internal memory error.

CSSM_INVALID_GUID

Unknown GUID.

CSSM_NOT_INITIALIZE

CSSM_Init has not been invoked.

CSSM_MEMORY_ERROR

Internal Memory Error.

CSSM_REGISTRY_ERROR

A registry error occurred.

SEE ALSO

CSSM_SetModuleInfo, CSSM_FreeModuleInfo