MDS_Initialize
CSSM_RETURN MDS_Initialize (const CSSM_GUID *pCallerGuid, const CSSM_DATA *pCallerManifest, const CSSM_MEMORY_FUNCS *pMemoryFunctions, MDS_FUNCS_PTR pDlFunctions, MDS_HANDLE *hMds)
This function initiates a service context with MDS and returns an opaque handle corresponding to that context. The caller provides memory functions that MDS can use to manage memory in the caller's space on behalf of the caller. The caller also provides input/output table pDlFunctions to get access to MDS databases.If the caller is a CDSA service provider that will require write-access to an MDS database, (such as a module that supports dynamic insertion and removal events), then the caller can provide the caller's GUID as input parameter pCallerGuid. When provided as input, the GUID is associated with the MDS handle and is used during DbOpen processing. If write-access is requested during DbOpen, MDS uses the associated GUID to locate the service provider's signed manifest credentials in the DS Common relation. The service provider module and its credentials are verified to ensure that write-access is permitted on this database by this module.
The installers will have to provide the pCallerManifest instead of pCallerGuid, as GUID cannot be used to locate an application unless it is installed. Only one of the two parameters pCallerGuid and pCallerManifest should be non NULL in an
MDS_Initialize() call, otherwise an error will be returned.
- pCallerGuid (input/optional)
The GUID of the module calling MDS.
- pCallerManifest (input/optional)
The Manifest of the module calling MDS.
- pMemoryFunctions (input)
The memory-management routines MDS uses to allocate query results on behalf of the caller.
- pDlFunctions (output)
The function table containing MDS programming interfaces for database access.
- hMds (output)
A new handle that can be used to interact with the MDS. The value will be set to CSSM_INVALID_HANDLE if the function fails.
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.
- CSSMERR_DL_INVALID_POINTER
Invalid input pointer
- CSSMERR_DL_INTERNAL_ERROR
Locking failed
- CSSMERR_DL_MEMORY_ERROR
Memory failure
- CSSMERR_DL_FUNCTION_FAILED
Intialization failed
MDS_Terminate
CSSM_RETURN MDS_Terminate (MDS_HANDLE MdsHandle)
This function terminates the MDS service context identified by the opaque MdsHandle. The MDS handle is invalidated and MDS frees all internal resources associated with the context.
- MdsHandle (input)
The MDS handle corresponding to the context being terminated.
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.
- CSSMERR_DL_INVALID_HANDLE
Handle does not reference a valid MDS context.
MDS_Install
CSSM_RETURN MDS_Install (MDS_HANDLE MdsHandle)
This function creates the Object Directory database containing the Object relation, and the CDSA Directory database containing the set of CDSA-specific relations defined in this specification. The MdsHandle identifies an MDS context created by invokingMDS_Initialize() . The context contains information about the access rights of the caller. Write-access is required to perform this operation.
- MdsHandle (input)
The MDS handle identifying an MDS context.
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.
This API returns CSSM Data Storage Library error codes from the functionCSSM_DL_DbCreate() . These error codes are listed below. See also the Error Codes and Error Values section in the Data Storage Library Services API
CSSMERR_DL_DATASTORE_ALREADY_EXISTS
CSSMERR_DL_INVALID_ACCESS_REQUEST
CSSMERR_DL_INVALID_DB_LOCATION
CSSMERR_DL_INVALID_DB_NAME
CSSMERR_DL_INVALID_OPEN_PARAMETERS
CSSMERR_DL_INVALID_RECORD_INDEX
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_FIELD_NAME
CSSMERR_DL_UNSUPPORTED_FIELD_FORMAT
CSSMERR_DL_UNSUPPORTED_INDEX_INFO
CSSMERR_DL_UNSUPPORTED_LOCALITY
CSSMERR_DL_UNSUPPORTED_NUM_ATTRIBUTES
CSSMERR_DL_UNSUPPORTED_NUM_INDEXES
CSSMERR_DL_UNSUPPORTED_NUM_RECORDTYPES
CSSMERR_DL_UNSUPPORTED_RECORDTYPE
CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_PARSING_MODULE
MDS_Uninstall
CSSM_RETURN MDS_Uninstall (MDS_HANDLE MdsHandle)
This function deletes the Object Directory database containing the Object relation, and the CDSA Directory database containing the set of CDSA-specific relations defined in this specification. The MdsHandle identifies the MDS context created by invokingMDS_Initialize() . The context contains information about the access rights of the caller. Write-access is required to perform this operation.
- MdsHandle (input)
The MDS handle identifying a valid MDS context.
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.
This API returns CSSM Data Storage Library error codes from the functionCSSM_DL_DbDelete() . These error codes are listed below. See also the Error Codes and Error Values section in the Data Storage Library Services API
CSSMERR_DL_DATASTORE_IS_OPEN
CSSMERR_DL_INVALID_DB_LOCATION
CSSMERR_DL_INVALID_DB_NAME
CSSMERR_DL_DATASTORE_DOESNOT_EXIST
For the definitions of these operations, refer to the relevant chapters on Data Storage Library Services API, in this Technical Standard.
Schema can be updated using CreateRelation and DestroyRelation. Schema update operations require special privilege and exclusive access to database files. The mechanisms for enforcing privileged access include:
Exclusive access to database schema requires opening the MDS database with access rights defined by CSSM_DB_ACCESS_PRIVILEGED.
Additional privileges may be needed to open a database with CSSM_DB_ACCESS_WRITE. Privileges may be acquired, and privileged access enforced, by file permissions and manifest based cross-check.
Installation programs and CDSA service providers that support dynamic insert/remove events are the primary software modules that need to update records in MDS databases. MDS requires that these callers provide signed manifest credentials authorizing write access to MDS databases. The signed manifest must contain an MDS access mask authorizing write access for the caller.
An installer provides its signed manifest credential as an explicit
input parameter to the
CDSA service providers that support insert/remove events need write
access to MDS databases.
The signed manifest of a CDSA service provider or any CDSA application is
stored in the MDS database during installation of the service provider or
application. The service provider's record is identified by the provider's
GUID. Similarly application's record is identified by the application's
GUID. When the service provider or application calls the
The integrity and authenticity of the service provider has already been checked when the service provider was loaded into the CDSA environment.
When MDS databases are opened, an access control mask can be applied to the access type requested database open operation.
The value associated with the tag name sets the access permission granted to the module. Valid values are those access flag values defined by the CDSA Data Storage Library service definition of CSSM_DB_ACCESS_TYPE.
CDSA_DB_ACCESS_TYPE is a base64 encodeed, unsigned 32-bit integer in big-endian ordering.
Contents | Next section | Index |