NAME
MDS_Initialize — Initiate service context with MDS (CDSA)
SYNOPSIS
# include <cdsa/mds.h>
CSSM_RETURN CSSMAPI MDS_Initialize
(const CSSM_GUID *pCallerGuid,
const CSSM_DATA *pCallerManifest,
const CSSM_MEMORY_FUNCS *pMemoryFunctions,
MDS_FUNCS_PTR pDlFunctions,
MDS_HANDLE *hMds) |
LIBRARY
Module Directory Services library (cdsa$mds300_shr.exe)
PARAMETERS
| 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. |
DESCRIPTION
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.
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.
CSSMERR_DL_INVALID_POINTER
CSSMERR_DL_INTERNAL_ERROR
CSSMERR_DL_MEMORY_ERROR
CSSMERR_DL_FUNCTION_FAILED |
SEE ALSO
Books
Intel CDSA Application Developer's Guide
