NAME

sec_rgy_attr_test_and_update-Updates specified attribute instances for a specified object only if a set of control attribute instances match the object's existing attribute instances

SYNOPSIS

#include <dce/sec_rgy_attr.h>

void sec_rgy_attr_test_and_update (
    sec_rgy_handle_t context,
    sec_rgy_domain_t name_domain,
    sec_rgy_name_t name,
    unsigned32 num_to_test,
    sec_attr_t test_attrs[],
    unsigned32 num_to_write,
    sec_attr_t update_attrs[],
    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_test

An unsigned 32-bit integer that specifies the number of elements in the test_attrs array. This integer must be greater than 0.

test_attrs[]

An array of values of type sec_attr_t that specifies the control attributes. The update takes place only if the types and values of the control attributes exactly match those of the attribute instances on the named registry object. The size of the array is determined by num_to_test.

num_to_write

A 32-bit integer that specifies the number of attribute instances returned in the update_attrs array.

update_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

failure_index

In the event of an error, failure_index is a pointer to the element in the update_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_test_and_update() routine updates an attribute only if the set of control attributes specified in the test_attrs match attributes that already exist for the object.

This update is an atomic operation: if any of the control attributes do not match existing attributes, none of the updates are performed, and if an update should be performed, but the write cannot occur for whatever reason to any member of the update_attrs array, 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.

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.

If you specify an attribute set for updating, the update applies to the set instance, the set itself, not the members of the set. To update a member of an attribute set, supply the UUID of the set member.

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_test_and_update() routine requires the test permission and the update permission set for each attribute type identified in the test_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

error_status_ok

The call was successful.

sec_attr_bad_encoding_type

Invalid encoding type specified.

sec_attr_bad_type

Invalid or unsupported attribute type.

sec_attr_not_unique

Attribute value is not unique.

sec_rgy_read_only

Registry is read only.

sec_attr_svr_read_only

Server is read only.

sec_attr_svr_unavailable

Server is unavailable.

sec_attr_trig_svr_unavailable

Trigger server is unavailable.

sec_attr_unauthorized

Unauthorized to perform this operation.

SEE ALSO

Functions: sec_rgy_attr_update(), sec_rgy_attr_delete().