NAME
CSSM_DL_DataInsert — Create new persistent data record (CDSA)
SYNOPSIS
# include <cssm.h>
API:
CSSM_RETURN CSSMAPI CSSM_DL_DataInsert
(CSSM_DL_DB_HANDLE DLDBHandle,
CSSM_DB_RECORDTYPE RecordType,
const CSSM_DB_RECORD_ATTRIBUTE_DATA *Attributes,
const CSSM_DATA *Data,
CSSM_DB_UNIQUE_RECORD_PTR *UniqueId)
SPI:
CSSM_RETURN CSSMDLI DL_DataInsert
(CSSM_DL_DB_HANDLE DLDBHandle,
CSSM_DB_RECORDTYPE RecordType,
const CSSM_DB_RECORD_ATTRIBUTE_DATA *Attributes,
const CSSM_DATA *Data,
CSSM_DB_UNIQUE_RECORD_PTR *UniqueId) |
LIBRARY
Common Security Services Manager library (cdsa$incssm300_shr.exe)
PARAMETERS
| DLDBHandle (input) |
| | | The handle pair that describes the add-in data storage
library module to be used to perform this function and the open
data store in which to insert the new data record. |
| RecordType (input) |
| | | Indicates the type of data record being added to
the data store. |
| Attributes (input/optional) |
| | | A list of structures containing the attribute values
to be stored in that attribute, and the meta information (schema)
describing those attributes. The list contains at most one entry per
attribute in the specified record type. The specified AttributeFormat for
each attribute must match that of the database schema, otherwise
the error CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT is returned. If an
attribute is of type CSSM_DB_ATTRIBUTE_FORMAT_STRING and the value
specified for that string includes a null-terminator, then the length
count in the CSSM_DATA structure containing the input string should
include the terminating character. (If null-terminators are used, they
should be used consistently when storing, searching, and retrieving
the string value, otherwise selection predicates will not locate
expected matches.) For those attributes that are not assigned values
by the caller, the DL module may assume the values to be the empty set,
or assume default values, or return an error. If the specified record
type does not contain any attributes, this parameter must be NULL. |
| Data (input/optional) |
| | | A pointer to the CSSM_DATA structure which contains
the opaque data object to be stored in the new data record. If the
specified record type does not contain an opaque data object, this
parameter must be NULL. |
| UniqueId (output) |
| | | A pointer to a CSSM_DB_UNIQUE_RECORD_PTR containing
a unique identifier associated with the new record. This unique
identifier structure can be used in future references to this record
during the current open data base session. The pointer will be set to
NULL if the function fails. The CSSM_DL_FreeUniqueRecord() function must be used to deallocate this structure. |
DESCRIPTION
This function creates a new persistent data record of the
specified type by inserting it into the specified data store. The
values contained in the new data record are specified by the Attributes and
the Data. The attribute value list contains zero
or more attribute values. The Attributes parameter
also specifies a record type. This type must be the same as the
type specified by the RecordType input parameter.
The DL module may require initial values for the CSSM pre-defined
attributes. The DL module can assume default values for any unspecified
attribute values or can return an error condition when DLM-required
attribute values are not specified by the caller. The Data is an
opaque object to be stored in the new data record.
If a primary key (concatination of all unique indexes in the
relation) exists, the error CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA
is returned. The client should call CSSM_DL_DataGetFirst(), followed by CSSM_DL_DataModify() to change an existing 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.
CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_FIELD_NAME
CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_PARSING_MODULE
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_RECORD_UID
CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA
CSSMERR_DL_INVALID_VALUE
CSSMERR_DL_MISSING_VALUE |
SEE ALSO
Books
Intel CDSA Application Developer's Guide
Online Help
Functions for the CSSM API:
CSSM_DL_DataDelete
Functions for the DL SPI:
DL_DataDelete
