NAME
   DL_DbOpen, CSSM_DL_DbOpen - Open a data store (CDSA)

 SYNOPSIS
   # include <cssm.h>

    API:
        CSSM_RETURN CSSMAPI CSSM_DL_DbOpen
        (CSSM_DL_HANDLE DLHandle,
        const char *DbName,
        const CSSM_NET_ADDRESS *DbLocation,
        CSSM_DB_ACCESS_TYPE AccessRequest,
        const CSSM_ACCESS_CREDENTIALS *AccessCred,
        const void *OpenParameters,
        CSSM_DB_HANDLE *DbHandle)
    SPI:
        CSSM_RETURN CSSMDLI DL_DbOpen
        (CSSM_DL_HANDLE DLHandle,
        const char *DbName,
        const CSSM_NET_ADDRESS *DbLocation,
        CSSM_DB_ACCESS_TYPE AccessRequest,
        const CSSM_ACCESS_CREDENTIALS *AccessCred,
        const void *OpenParameters,
        CSSM_DB_HANDLE *DbHandle)

 LIBRARY
   Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE)

 PARAMETERS
   DLHandle (input)
           The handle that describes the add-in data storage library
           module to be used to perform this function.

   DbName (input)
           A pointer to the string containing the logical name of the
           data store.

   DbLocation (input/optional)
           A pointer to a network address directly or indirectly
           identifying the location of the storage service process. If
           the input is NULL, the module can determine a storage service
           process and its location based on the DbName (for existing
           data stores) or can assume a default storage service process
           location. If the DbName does not distinguish the storage
           service process, the service cannot be performed and the
           operation fails.

   AccessRequest (input)
           An indicator of the requested access mode for the data store,
           such as read-only or read-write.

   AccessCred (input/optional)
           A pointer to the set of one or more credentials being presented
           for authentication by the caller. These credentials are
           required to obtain access to the specified data store. The
           credentials structure can contain multiple types of credentials,
           as required for multi-factor authentication. The credential
           data can be an immediate value, such as a passphrase, PIN,
           certificate, or template of user-specific data, or the caller
           can specify a callback function the DL can use to obtain one
           or more credentials.  The required set of credentials to
           access a particular data store is defined by the DbInfo record
           containing meta-data for the specified data store. If
           credentials are not required to access the specified data
           store, then this field can be NULL.

   OpenParameters (input/optional)
           A pointer to a module-specific set of parameters required to
           open the data store.

   DbHandle (output)
           The handle to the opened data store. The value will be set to
           CSSM_INVALID_HANDLE if the function fails.

 DESCRIPTION
   This function opens the data store with the specified logical name
   under the specified access mode. If user authentication credentials
   are required, they must be provided. Also, additional open parameters
   may be required to open a given data store, and are supplied in the
   OpenParameters.

 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_DB_LOCKED
        CSSMERR_DL_INVALID_ACCESS_REQUEST
        CSSMERR_DL_INVALID_DB_LOCATION
        CSSMERR_DL_INVALID_DB_NAME
        CSSMERR_DL_DATASTORE_DOESNOT_EXIST
        CSSMERR_DL_INVALID_PARSING_MODULE
        CSSMERR_DL_INVALID_OPEN_PARAMETERS

 SEE ALSO
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_DL_DbClose

   Functions for the DL SPI:

       DL_DbClose