NAME

CSSM_DL_DbImport

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_DL_DbImport
    (CSSM_DL_HANDLE DLHandle,
    const char *DbDestinationName,
    const CSSM_NET_ADDRESS_PTR DbDestinationLocation,
    const char *DbSourceName,
    const CSSM_NET_ADDRESS_PTR DbSourceLocation,
    const CSSM_DBINFO_PTR DBInfo,
    const CSSM_BOOL InfoOnly,
    const CSSM_USER_AUTHENTICATION_PTR UserAuthentication)
    const void *DestinationOpenParameters,
    const void *SourceOpenParameters)

DESCRIPTION

This function makes the contents of the source data store available from the destination data source. This may involve registering the source data store with this DL module or the transfer of records from the source to the destination.

If INFO_ONLY is TRUE, information about an existing data store is registered with the DL module but no records are imported. The DL module will update the CSSM registry with the DbDestinationName and DBInfo to inform applications that this data store is available. This method may be used to make existing data stores available via the CSSM DL interface.

If INFO_ONLY is FALSE, this function creates a new data store, or adds to an existing data store, by importing records from the specified data source. It is assumed that the data source contains records exported from a data store using the function CSSM_DL_DbExport.

The DbDestinationName specifies the name of a new or existing data store. If a new data store is being created, the DBInfo structure provides the meta information (schema) for the new data store. This structure describes the record attributes and the index schema for the new data store. If the data store already exists, then the existing meta information (schema) is used. (Dynamic schema evolution is not supported.)

Typically, user authentication is required to create a new data store or to write to an existing data store. An authentication credential is presented to the DL module in the form required by the module. The required form is documented in the capabilities and feature descriptions for this module. The resulting data store is not opened as a result of this operation.

PARAMETERS

DLHandle (input)

The handle that describes the add-in data storage library module to be used to perform this function.

DbDestinationName (input)

The name of the data store which will contain the imported records.

DbDestinationLocation (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 DbDestinationName or can assume a default storage service process location. If the DbDestinationName does not distinguish the storage service process and a default cannot be assumed, the service cannot be performed and the operation fails.

DbSourceName (input)

The name of the data source from which to obtain the records to be imported.

DbSourceLocation (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 DbSourceName or can assume a default storage service process location. If the DbSourceName does not distinguish the storage service process and a default cannot be assumed, the service cannot be performed and the operation fails.

DBInfo (input/optional)

A data structure containing a detailed description of the meta information (schema) for the new data store. If a new data store is being created, then the caller must specify the meta information (schema), or the data source must include the meta information required for proper import of the records. If meta information is supplied by the caller and specified in the data source, then the meta information provided by the caller overrides the meta information recorded in the data source. If the data store exists and records are being added, then this pointer must be NULL. The existing meta information will be used and the schema cannot be evolved.

InfoOnly (input)

A Boolean value indicating what to import. If TRUE, import only the DBInfo, which describes the a data store. If FALSE, import both the DBInfo and all of the records exported from a data store.

UserAuthentication (input/optional)

The caller's credential as required for authorization to create a data store. If the DL module requires no additional credentials to create a new data store, then user authentication can be NULL.

DestinationOpenParameters (input/optional)

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

SourceOpenParameters (input/optional)

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

RETURN VALUE

A CSSM_OK return value signifies that the function completed successfully and the new data store was created. When CSSM_FAIL is returned, an error has occurred. Use CSSM_GetError to obtain the error code.

ERRORS

CSSM_DL_INVALID_DL_HANDLE

Invalid DL handle.

CSSM_DL_INVALID_PTR

NULL source or destination names.

CSSM_REGISTRY_ERROR

Unable to add/update registry entry.

CSSM_DL_DB_IMPORT_FAIL

DB exception doing import function.

CSSM_DL_MEMORY_ERROR

Error in allocating memory.

SEE ALSO

CSSM_DL_DbExport