NAME
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.
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
Online Help
Functions for the CSSM API:
CSSM_DL_DataInsert, CSSM_DL_DataDelete
Functions for the DL SPI:
DL_DataInsert, DL_DataDelete
