sec_rgy_attr_update(3sec)

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
Set this parameter to zero. It is 32-bit unsigned integer that specifies the size of the out_attrs[ ] array. Use of this parameter and its associated out_attrs[ ] array is reserved for future use by update trigger servers.

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[ ]
Reserved for future use by update trigger servers.

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 multivalued 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 multivalued attributes, because every instance of the multivalued 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 multivalued attributes, create individual sec_attr_t data types to define each multivalued attribute instance and then pass all of them in the input 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

/usr/include/dce/sec_rgy_attr.idl
The idl file from which dce/sec_rgy_attr.h was derived.

Errors

The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.

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(3sec)

sec_rgy_attr_delete(3sec)

sec_rgy_attr_test_and_update(3sec)