DL_DataModify(3)DL_DataModify(3)NAME
DL_DataModify, CSSM_DL_DataModify - Modify persistent data record
(CDSA)
SYNOPSIS
# include <cdsa/cssm.h>
API: CSSM_RETURN CSSMAPI CSSM_DL_DataModify (CSSM_DL_DB_HANDLE DLDBHan‐
dle, CSSM_DB_RECORDTYPE RecordType, CSSM_DB_UNIQUE_RECORD_PTR UniqueRe‐
cordIdentifier, const CSSM_DB_RECORD_ATTRIBUTE_DATA *AttributesToBeMod‐
ified, const CSSM_DATA *DataToBeModified, CSSM_DB_MODIFY_MODE Modify‐
Mode) SPI: CSSM_RETURN CSSMDLI DL_DataModify (CSSM_DL_DB_HANDLE DLDB‐
Handle, CSSM_DB_RECORDTYPE RecordType, CSSM_DB_UNIQUE_RECORD_PTR Uni‐
queRecordIdentifier, const CSSM_DB_RECORD_ATTRIBUTE_DATA
*AttributesToBeModified, const CSSM_DATA *DataToBeModified,
CSSM_DB_MODIFY_MODE ModifyMode)
LIBRARY
Common Security Services Manager library (libcssm.so)
PARAMETERS
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. Indicates the type of data record
being modified. A pointer to a CSSM_DB_UNIQUE_RECORD containing a
unique identifier associated with the record to modify. If the modifi‐
cation succeeds, the UniqueRecordIdentifier points to a
CSSM_DB_UNIQUE_RECORD containing a unique identifier associated with
the updated record. If the modification fails, the UniqueRecordIdenti‐
fier is not modified. 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 defini‐
tion). Those attributes that are not specified as part of this parame‐
ter remain unchanged. If the AttributesToBeModified parameter is NULL,
no attribute modification occurs. 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. A CSSM_DB_MOD‐
IFY_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_MOD‐
IFY_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 modifi‐
cation mode must be 0. The current modification modes behave as fol‐
lows:
ModifyMode Value Function Behavior
CSSM_DB_MOD‐ No Attributes are being updated.
IFY_ATTRIBUTE_NONE
CSSM_DB_MOD‐ The specified values are added to the set of
IFY_ATTRIBUTE_ADD current values for each attribute. If 0 values
are specified then the error CSS‐
MERR_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_MOD‐ The specified values are removed from the set of
IFY_ATTRIBUTE_DELETE 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 CSS‐
MERR_DL_MULTIPLE_VALUES_UNSUPPORTED is returned.
CSSM_DB_MOD‐ The values for each attribute are replaced with
IFY_ATTRIBUTE_REPLACE 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 CSS‐
MERR_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 repre‐
sent an error condition.
ERRORS
Errors are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE CSSMERR_DL_INCOM‐
PATIBLE_FIELD_FORMAT CSSMERR_DL_INVALID_DB_HANDLE CSS‐
MERR_DL_INVALID_FIELD_NAME CSSMERR_DL_INVALID_MODIFY_MODE CSS‐
MERR_DL_INVALID_RECORDTYPE CSSMERR_DL_INVALID_RECORD_UID CSS‐
MERR_DL_INVALID_UNIQUE_INDEX_DATA CSSMERR_DL_INVALID_VALUE CSS‐
MERR_DL_MULTIPLE_VALUES_UNSUPPORTED CSSMERR_DL_STALE_UNIQUE_RECORD
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA_intro(3))
Reference Pages
Functions for the CSSM API:
CSSM_DL_DataInsert(3), CSSM_DL_DataDelete(3)
Functions for the DL SPI:
DL_DataInsert(3), DL_DataDelete(3)DL_DataModify(3)