NAME

CSSM_DL_DbOpen

SYNOPSIS

CSSM_DB_HANDLE CSSMAPI CSSM_DL_DbOpen
    (CSSM_DL_HANDLE DLHandle,
    const char *DbName,
    const CSSM_NET_ADDRESS_PTR DbLocation,
    const CSSM_DB_ACCESS_TYPE_PTR AccessRequest,
    const CSSM_USER_AUTHENTICATION_PTR UserAuthentication,
    const void *OpenParameters))

DESCRIPTION

This function opens the data store with the specified logical name under the specified access mode. If no DbName is provided, the default data store will be opened. 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.

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 and a default cannot be assumed, 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.

UserAuthentication (input/optional)

The caller's credential as required for obtaining access to the data store. If no credentials are required for the specified data store, then user authentication must be NULL.

OpenParameters (input/optional)

A pointer to a module-specific set of parameters required to open the data store.

RETURN VALUE

The handle to the opened data store. If the handle is NULL, an error has occurred. Use CSSM_GetError to obtain the error code.

ERRORS

CSSM_DL_INVALID_DL_HANDLE

Invalid DL handle.

CSSM_DL_DATASTORE_NOT_EXISTS

The data store with the logical name does not exist.

CSSM_DL_INVALID_AUTHENTICATION

Caller is not authorized for specified access mode.

CSSM_DL_DB_OPEN_FAIL

Open caused an exception.

CSSM_DL_MEMORY_ERROR

Error in allocating memory.

SEE ALSO

CSSM_DL_DbClose