NAME
sec_rgy_attr_update - Creates and updates attribute instances for a
specified object
SYNOPSIS
#include <dce/sec_rgy_attr.h>
void sec_rgy_attr_update (
sec_rgy_handle_t context,
sec_rgy_domain_t name_domain,
sec_rgy_name_t name,
unsigned32 num_to_write,
unsigned32 space_avail,
sec_attr_t in_attrs[],
unsigned32 *num_returned,
sec_attr_t out_attrs[],
unsigned32 *num_left,
signed32 *failure_index,
error_status_t *status);
PARAMETERS
Input
context
An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.
name_domain
A value of type sec_rgy_domain_t that identifies the registry
domain in which the object specified by name resides. The
valid values are as follows:
sec_rgy_domain_person
The name identifies a principal.
sec_rgy_domain_group
The name identifies a group.
sec_rgy_domain_org
The name identifies an organization.
This parameter is ignored if name is policy or replist.
name A character string of type sec_rgy_name_t specifying the name
of the person, group, or organization to which the attribute
is attached.
num_to_write
A 32-bit unsigned integer that specifies the number of elements
in the in_attrs array. This integer must be greater than 0.
space_avail
A 32-bit unsigned integer that specifies the size of the
out_attrs array. This integer must be greater than 0.
in_attrs[]
An array of values of type sec_attr_t that specifies the
attribute instances to be updated. The size of the array is
determined by num_to_write.
Output
num_returned
A pointer to an unsigned 32-bit integer that specifies the
number of attribute instances returned in the out_attrs[] array.
out_attrs
An array of values of type sec_attr_t that specifies the updated
attribute instances. Not that only if these attributes were
processed by an update attribute trigger server will they differ
from the attributes in the in_attrs[] array. The size of the
array is determined by space_avail and the length by
num_returned.
num_left
A pointer to an unsigned 32-bit integer that supplies the number
of attributes that could not be returned because of space
constraints in the out_attrs[] buffer. To ensure that all the
attributes will be returned, increase the size of the
out_attrs[] array by increasing the size of space_avail and
num_returned.
failure_index
In the event of an error, failure_index is a pointer to the
element in the in_attrs[] array that caused the update to fail.
If the failure cannot be attributed to a specific attribute,
the value of failure_index is -1.
status
A pointer to the completion status. On successful completion,
the routine returns error_status_ok. Otherwise, it returns an
error.
DESCRIPTION
The sec_rgy_attr_update() routine creates new attribute instances and
updates existing attribute instances attached to a object specified by
name and Registry domain. The instances to be created or updated are
passed as an array of sec_attr_t data types. This is an atomic
operation: if the creation of any attribute in the in_attrs[] array
fails, all updates are aborted. The attribute causing the update to
fail is identified in failure_index. If the failure cannot be
attributed to a given attribute, failure_index contains -1.
The in_attrs array, which specifies the attributes to be created,
contains values of type sec_attr_t. These values are:
+ attr_id, a UUID that identifies the attribute type
+ attr_value, values of sec_attr_value_t that specify the attribute's
encoding type and values.
If an attribute instance already exists which is identical in both
attr_id and attr_value to an attribute specified in in_attrs, the
existing attribute information is overwritten by the new information.
For multi-valued attributes, every instance with the same attr_id is
overwritten with the supplied values.
If an attribute instance does not exist, it is created.
For multi-valued attributes, because every instance of the multi-valued
attribute is identified by the same UUID, every instance is overwritten
with the supplied value. To change only one of the values, you must
supply the values that should be unchanged as well as the new value.
To create instances of multi-valued attributes, create individual
sec_attr_t data types to define each multi-valued attribute instance
and then pass all of them in in the input array.
If an input attribute is associated with an update attribute trigger
server, the attribute trigger server is invoked (by the
sec_attr_trig_update() function) and the in_attr[] array is supplied
as input. The output attributes from the update attribute trigger server
are stored in the registry database and returned in the out_attrs[]
array. Note that the update attribute trigger server may modify the
values before they are used to update the registry database. This is
the only circumstance under which the values in the out_attrs[] array
differ from the values in the in_attrs[] array.
Permissions Required
The sec_rgy_attr_update() routine requires the update permission set
for each attribute type identified in the in_attrs[] array. These
permissions are defined as part of the ACL manager set in the schema
entry of each attribute type.
FILES
SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL
The idl file from which dce/sec_rgy_attr.h was derived.
ERRORS
unauthorized
database read only
server unavailable
invalid/unsupported attribute type
invalid encoding type
value not unique
attribute instance already exists
trigger server unavailable
site read only
error_status_ok
RELATED INFORMATION
Functions: sec_intro
sec_rgy_attr_delete
sec_rgy_attr_test_and_update