NAME
   MDS_Initialize - Initiate service context with MDS (CDSA)

 SYNOPSIS
   # include <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.  See CDSA.

        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 (see CDSA)

   Other Help Topics