NAME
   DL_DbCreate, CSSM_DL_DbCreate - Create and open new data
                                   store (CDSA)

 SYNOPSIS
   # include <cssm.h>

    API:
        CSSM_RETURN CSSMAPI CSSM_DL_DbCreate
        (CSSM_DL_HANDLE DLHandle,
        const char *DbName,
        const CSSM_NET_ADDRESS *DbLocation,
        const CSSM_DBINFO *DBInfo,
        CSSM_DB_ACCESS_TYPE AccessRequest,
        const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
        const void *OpenParameters,
        CSSM_DB_HANDLE *DbHandle)
    SPI:
        CSSM_RETURN CSSMDLI DL_DbCreate
        (CSSM_DL_HANDLE DLHandle,
        const char *DbName,
        const CSSM_NET_ADDRESS *DbLocation,
        const CSSM_DBINFO *DBInfo,
        CSSM_DB_ACCESS_TYPE AccessRequest,
        const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
        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 used to perform this function.

   DbName (input)
           The logical name for the new 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 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.

   DBInfo (input)
           A pointer to a structure describing the format/schema of
           each record type that will be stored in the new data store.

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

   CredAndAclEntry (input/optional)
           A structure containing one or more credentials authorized for
           creating a data base and the prototype ACL entry that will
           control future use of the newly created key. The credentials
           and ACL entry prototype can be presented as immediate values
           or callback functions can be provided for use by the DL to
           acquire the credentials and/or the ACL entry interactively.
           If the DL provides public access for creating a data base,
           then the credentials can be NULL.  If the DL defines a
           default initial ACL entry for the new data base, then the
           ACL entry prototype can be an empty list.

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

   DbHandle (output)
           The handle to the newly created and open data store. The value
           will be set to CSSM_INVALID_HANDLE if the function fails.

 DESCRIPTION
   This function creates and opens a new data store. The name of the new
   data store is specified by the input parameter DbName.  The record
   schema for the data store is specified in the DBINFO structure.  If
   any RecordType defined in the DBINFO structure does not have an
   associated parsing module, then the ModuleSubserviceUid specified for
   that record type must be zero.

   The newly created data store is opened under the specified access mode.
   If user authentication credentials are required, they must be provided.
   Also, additional open parameters may be required and are supplied in
   OpenParameters. If user authentication credentials are required, they
   must be provided.

   Authorization policy can restrict the set of callers who can create a
   new resource. In this case, the caller must present a set of access
   credentials for authorization. Upon successfully authenticating the
   credentials, the template that verified the presented samples
   identifies the ACL entry that will be used in the authorization
   computation. If the caller is authorized, the new resource is created.

   The caller must provide an initial ACL entry to be associated with the
   newly created resource. This entry is used to control future access to
   the new resource and (since the subject is deemed to be the "Owner")
   exercise control over its associated ACL. The caller can specify the
   following items for initializing an ACL entry:

   Subject A CSSM_LIST structure, containing the type of the subject and
           a template value that can be used to verify samples that are
           presented in credentials when resource access is requested.

   Delegation flag
           A value indicating whether the Subject can delegate the
           permissions recorded in the AuthorizationTag. (This item
           only applies to public key subjects).

   Authorization tag
           The set of permissions that are granted to the Subject.

   Validity period
           The start time and the stop time for which the ACL entry is
           valid.

   ACL entry tag
           A user-defined string value associated with the ACL entry.

           The service provider can modify the caller-provided initial
           ACL entry to conform to any innate resource-access policy
           that the service provider may be required to enforce. If the
           initial ACL entry provided by the caller contains values or
           permissions that are not supported by the service provider,
           then the service provider can modify the initial ACL
           appropriately or can fail the request to create the new
           resource. Service providers list their supported
           AuthorizationTag values in their Module Directory Services
           primary record.

 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_DATASTORE_ALREADY_EXISTS
        CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
        CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
        CSSMERR_DL_INVALID_ACCESS_REQUEST
        CSSMERR_DL_INVALID_DB_LOCATION
        CSSMERR_DL_INVALID_DB_NAME
        CSSMERR_DL_INVALID_FIELD_NAME
        CSSMERR_DL_INVALID_OPEN_PARAMETERS
        CSSMERR_DL_INVALID_PARSING_MODULE
        CSSMERR_DL_INVALID_RECORDTYPE
        CSSMERR_DL_INVALID_RECORD_INDEX
        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

 SEE ALSO
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_DL_DbOpen
       CSSM_DL_DbClose
       CSSM_DL_DbDelete

   Functions for the DL SPI:

       DL_DbOpen
       DL_DbClose
       DL_DbDelete