NAME
DL_DataModify, CSSM_DL_DataModify - Modify persistent data
record (CDSA)
SYNOPSIS
# include <cssm.h>
API:
CSSM_RETURN CSSMAPI CSSM_DL_DataModify
(CSSM_DL_DB_HANDLE DLDBHandle,
CSSM_DB_RECORDTYPE RecordType,
CSSM_DB_UNIQUE_RECORD_PTR UniqueRecordIdentifier,
const CSSM_DB_RECORD_ATTRIBUTE_DATA *AttributesToBeModified,
const CSSM_DATA *DataToBeModified,
CSSM_DB_MODIFY_MODE ModifyMode)
SPI:
CSSM_RETURN CSSMDLI DL_DataModify
(CSSM_DL_DB_HANDLE DLDBHandle,
CSSM_DB_RECORDTYPE RecordType,
CSSM_DB_UNIQUE_RECORD_PTR UniqueRecordIdentifier,
const CSSM_DB_RECORD_ATTRIBUTE_DATA *AttributesToBeModified,
const CSSM_DATA *DataToBeModified,
CSSM_DB_MODIFY_MODE ModifyMode)
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 to search for records satisfying the query.
RecordType (input)
Indicates the type of data record being modified.
UniqueRecordIdentifier (input/output)
A pointer to a CSSM_DB_UNIQUE_RECORD containing a unique
identifier associated with the record to modify. If the
modification succeeds, the UniqueRecordIdentifier points to
a CSSM_DB_UNIQUE_RECORD containing a unique identifier
associated with the updated record. If the modification
fails, the UniqueRecordIdentifier is not modified.
AttributesToBeModified (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.) Each attribute specified is modified
according to the value of ModifyMode (see table in the
DESCRIPTION section of this definition). Those attributes
that are not specified as part of this parameter remain
unchanged. If the AttributesToBeModified parameter is NULL,
no attribute modification occurs.
DataToBeModified (input/optional)
A pointer to the CSSM_DATA structure which contains the
opaque data object to be stored in the data record. If
this parameter is NULL, no Data modification occurs.
ModifyMode (input)
A CSSM_DB_MODIFY_MODE value indicating the type of modification
to be performed on the record attributes identified by
AttributesToBeModified. If no attributes are specified, then
this value must be CSSM_DB_MODIFY_ATTRIBUTE_NONE.
DESCRIPTION
This function modifies the persistent data record identified by the
UniqueRecordIdentifier. The modifications are specified by the
Attributes and Data parameters. The ModifyMode indicates how the
attributes are to be updated. The ModifyMode has no affect on
updating the data blob contained in the record. If the data blob is
the only record attribute being updated by this function call, then
the modification mode must be 0. The current modification modes
behave as follows:
ModifyMode Value Function Behavior
---------------- -----------------
CSSM_DB_MODIFY_ATTRIBUTE_NONE No Attributes are being updated.
CSSM_DB_MODIFY_ATTRIBUTE_ADD The specified values are added to
the set of current values for each
attribute. If 0 values are specified
then the error
CSSMERR_DL_INVALID_MODIFY_MODE is
returned. If a DL does not support
multiple values per attribute, the
error CSSMERR_DL_MULTIPLE_VALUES_
UNSUPPORTED is returned.
CSSM_DB_MODIFY_ATTRIBUTE_DELETE The specified values are removed
from the set of current values for
each attribute. If 0 values are
specified then all values are
deleted or the attributes value is
replaced with the default for this
attribute. If a DL does not support
multiple values per attribute, the
error CSSMERR_DL_MULTIPLE_VALUES_
UNSUPPORTED is returned.
CSSM_DB_MODIFY_ATTRIBUTE_REPLACE The values for each attribute are
replaced with the specified set of
values for each attribute. If no
values are specified then all values
are deleted or the attributes value
is replaced with the default for
this attribute. If a DL does not
support multiple values per
attribute, the error
CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED
is returned when more than 1 value is
specified.
If the attribute lists specifies an attribute that is not defined in
the database's meta-information, an error condition is returned. For
each attribute-value pair, the value replaces the corresponding
attribute value in the record. If a data value is specified, the
record's data value is replaced with the specified value. A record's
data value or attribute values can be set to NULL or zero to represent
deletion or the lack of a known value.
If the record referenced by UniqueRecordIdentifier has been modified
since the last time it was updated, the error
CSSMERR_DL_STALE_UNIQUE_RECORD is returned and no modification takes
place.
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_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_FIELD_NAME
CSSMERR_DL_INVALID_MODIFY_MODE
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_RECORD_UID
CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA
CSSMERR_DL_INVALID_VALUE
CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED
CSSMERR_DL_STALE_UNIQUE_RECORD
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA)
Other Help Topics
Functions for the CSSM API:
CSSM_DL_DataInsert
CSSM_DL_DataDelete
Functions for the DL SPI:
DL_DataInsert
DL_DataDelete