DL_DbOpen

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