NAME dce_attr_intro - Introduction to the DCE Attribute Interface routines DESCRIPTION The DCE Attribute Interface API allows applications to define and access attributes types (schema entries) in a schema of your choice. It is based on the Extended Registry Attribute (ERA) interface, which defines and accesses attribute types in the registry database schema. Except for the binding methods, the two APIs are similar. Note however, that the Extended Registry Attribute API provides routines to create attribute types in the registry schema, to create and manipulate attribute instances, and to attach those instances to objects. The DCE Attribute Interface in its current state provides calls only to create attribute types. For general usage guidelines for the DCE Attribute Interface refer to the chapter in this manual titled "The Extended Attribute Application Program Interface." The DCE Attribute Interface routine reference pages are supplied in this section. The DCE Attribute Interface Routines The DCE Attribute Interface consists of the following routines: dce_attr_sch_bind Returns an opaque handle of type dce_attr_sch_handle_t to a schema object specified by name and sets authentication and authorization parameters for the handle. dce_attr_sch_bind_free Releases an opaque handle of type dce_attr_sch_handle_t. dce_attr_sch_create_entry Creates a schema entry in a schema bound to with dce_attr_sch_bind. dce_attr_sch_update_entry Updates a schema entry in a schema bound to with dce_attr_sch_bind. dce_attr_sch_delete_entry Deletes a schema entry in a schema bound to with dce_attr_sch_bind. dce_attr_sch_scan Reads a specified number of schema entries. dce_attr_sch_cursor_init Allocates resources to and initializes a cursor used with dce_attr_sch_scan. The dce_attr_sch_cursor_init routine makes a remote call that also returns the current number of schema entries in the schema. dce_attr_sch_cursor_alloc Allocates resources to a cursor used with dce_attr_sch_scan. The dce_attr_sch_cursor_alloc routine is a local operation. dce_attr_sch_cursor_release Releases states associated with a cursor created by dce_attr_sch_cursor_alloc or dce_attr_sch_cursor_init. dce_attr_sch_cursor_reset Reinitializes a cursor used with dce_attr_sch_scan. The reset cursor can then be reused without releasing and re-allocating. dce_attr_sch_lookup_by_id Reads a schema entry identified by attribute type UUID. dce_attr_sch_lookup_by_name Reads a schema entry identified by attribute name. dce_attr_sch_get_acl_mgrs Retrieves the manager types of the ACLs protecting objects dominated by a named schema. dce_attr_sch_aclmgr_strings Returns printable ACL strings associated with an ACL manager protecting a schema object. Data Types and Structures dce_attr_sch_handle_t An opaque handle to a schema object. Use dce_attr_sch_bind to acquire the handle. dce_attr_component_name_t A pointer to a character string used to further specify a schema object. dce_bind_auth_info_t A enumeration that defines whether or not the binding is authenticated. This data type is defined exactly as the sec_attr_bind_auth_info_t data type in the ERA interface. See the sec_intro reference page for more information on sec_attr_bind_auth_info_t. dce_attr_schema_entry_t A structure that defines a complete attribute entry for the schema catalog. This data type is defined exactly as the sec_attr_schema_entry_t data type in the ERA interface. See the sec_intro reference page for more information on sec_attr_schema_entry_t. dce_attr_cursor_t A structure that provides a pointer into a database and is used for multiple database operations. This cursor must minimally represent the object indicated by dce_attr_sch_handle_t. The cursor may additionally represent an entry within that schema. dce_attr_schema_entry_parts_t A 32-bit bitset containing flags that specify the schema entry fields that can be modified on a schema entry update operation. This data type is defined exactly as the sec_attr_schema_entry_parts_t data type in the ERA interface. See the sec_intro reference page for more information on sec_attr_schema_entry_parts_t.
1 – dce_attr_sch_bind
NAME dce_attr_sch_bind - Return an opaque handle to a schema object SYNOPSIS #include <dce/dce_attr_base.h> void dce_attr_sch_bind( dce_attr_component_name_t schema_name, dce_bind_auth_info_t *auth_info, dce_attr_sch_handle_t *h, error_status_t *status ); PARAMETERS Input schema_name A pointer to a value of type dce_attr_component_name_t that specifies the name of the schema object to bind to. auth_info A value of type dce_bind_auth_info_t that defines the authentication and authorization parameters to use with the binding handle. If set to NULL, the default authentication and authorization parameters are used. Output h An opaque handle of type dce_attr_sch_handle_t to the named schema object for use with dce_attr_sch operations. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_bind() routine returns an opaque handle of type dce_attr_sch_handle_t to a named schema object. The returned handle can then be used for subsequent dce_attr_sch operations performed on the object. Permissions Required The dce_attr_sch_update_entry() routine requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_bad_name sec_login_s_no_current_context rpc_s_entry_not_found rpc_s_no_more_bindings dce_attr_s_unknown_auth_info_type dce_attr_s_no_memory error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_bind_free
2 – dce_attr_sch_bind_free
NAME dce_attr_sch_bind_free - Releases an opaque handle of type dce_attr_sch_handle_t to a schema object SYNOPSIS #include <dce/dce_attr_base.h> void dce_attr_sch_bind_free( dce_attr_sch_handle_t *h, error_status_t *status ); PARAMETERS Input h An opaque handle of type dce_attr_sch_handle_t. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_bind_free() routine releases an opaque handle of type dce_attr_sch_handle_t. The handle was returned with the dce_attr_sch_bind() routine and used to perform dce_attr_sch operations. Permissions Required The dce_attr_sch_bind_free() routine requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_SCH.IDL The idl file from which dce/dce_attr_sch.h was derived. ERRORS error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_bind
3 – dce_attr_sch_create_entry
NAME dce_attr_sch_create_entry - Create a schema entry in a schema bound to by a previous dce_attr_sch_bind() routine SYNOPSIS #include <dce/dce_attr_base.h> void dce_attr_sch_create_entry( dce_attr_sch_handle_t h, dce_attr_schema_entry_t *schema_entry, error_status_t *status ); PARAMETERS Input h An opaque handle bound to a schema object. Use dce_attr_sch_bind() to acquire the handle. schema_entry A pointer to a dce_attr_schema_entry_t that contains the schema entry values for the schema in which the entry is to be created. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_create_entry() routine creates schema entries that define attribute types in the schema object bound to by h. Permissions Required The dce_attr_sch_create_entry() routine requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_bad_binding error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_delete_entry dce_attr_sch_update
4 – dce_attr_sch_update_entry
NAME dce_attr_sch_update_entry - Update a schema entry SYNOPSIS #include <dce/dce_attr_sch.h> void dce_attr_sch_update_entry( dce_attr_sch_handle_t h, dce_attr_schema_entry_parts_t modify_parts, dce_attr_schema_entry_t *schema_entry, error_status_t *status ); PARAMETERS Input h An opaque handle bound to a schema object. Use dce_attr_sch_bind() to acquire the handle. modify_parts A value of type dce_attr_schema_entry_parts_t that identifies the fields in the schema bound to by h that can be modified. schema_entry A pointer to a dce_attr_schema_entry_t that contains the schema entry values for the schema entry to be updated. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_update_entry() routine modifies schema entries. Only those schema entry fields set to be modified in the dce_attr_schema_entry_parts_t data type can be modified. Some schema entry components can never be modified. Instead to make any changes to these components, the schema entry must be deleted (which deletes all attribute instances of that type) and recreated. These components are listed below: + Attribute name + Reserved flag + Apply defaults flag + Intercell action flag + Trigger binding + Comment Fields that are arrays of structures (such as acl_mgr_set and trig_binding) are completely replaced by the new input array. This operation cannot be used to add a new element to the existing array. Permissions Required The dce_attr_sch_update_entry() routine requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_bad_binding error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_delete_entry dce_attr_sch_create_entry
5 – dce_attr_sch_delete_entry
NAME dce_attr_sch_delete_entry - Delete a schema entry SYNOPSIS #include <dce/dce_attr_sch.h> void dce_attr_sch_delete_entry( dce_attr_sch_handle_t h, uuid_t *attr_id, error_status_t *status ); PARAMETERS Input h An opaque handle bound to a schema object. Use dce_attr_sch_bind() to acquire the handle. attr_id A pointer to a uuid_t that identifies the schema entry to be deleted in the schema bound to by h. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_delete_entry() routine deletes a schema entry. Because this is a radical operation that invalidates any existing attributes of this type on objects dominated by the schema, access to this operation should be severely limited. Permissions Required The dce_attr_sch_delete_entry() routine requires requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_bad_binding error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_create_entry dce_attr_sch_update_entry
6 – dce_attr_sch_scan
NAME dce_attr_sch_scan - Read a specified number of schema entries SYNOPSIS #include <dce/dce_attr_base.h> void dce_attr_sch_scan( dce_attr_sch_handle_t h, dce_attr_cursor_t *cursor, unsigned32 num_to_read, unsigned32 *num_read, dce_attr_schema_entry_t schema_entries[], error_status_t *status ); PARAMETERS Input h An opaque handle bound to a schema object. Use dce_attr_sch_bind() to acquire the handle. num_to_read An unsigned 32-bit integer specifying the size of the schema_entries[] array and the maximum number of entries to be returned. Input/Output cursor A pointer to a dce_attr_cursor_t. As input cursor must be allocated and can be initialized. If cursor is not initialized, dce_attr_sch_scan will initialize it. As output, cursor is positioned at the first schema entry after the returned entries. Output num_read A pointer to an unsigned 32-bit integer specifying the number of entries returned in schema_entries[]. schema_entries[] A dce_attr_schema_entry_t that contains an array of the returned schema entries. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_scan() routine reads schema entries. The read begins at the entry at which the input cursor is positioned and ends after the number of entries specified in num_to_read. The input cursor must have been allocated by either the dce_attr_sch_cursor_init() or the dce_attr_sch_cursor_alloc() call. If the input cursor is not initialized, dce_attr_sch_scan() initializes it; if cursor is initialized, dce_attr_sch_scan() simply advances it. To read all entries in a schema, make successive dce_attr_sch_scan() calls. When all entries have been read, the call returns the message no_more_entries. This routine is useful as a browser. Permissions Required The dce_attr_sch_scan() routine requires requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_bad_binding dce_attr_s_bad_cursor error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_cursor_init dce_attr_sch_cursor_alloc dce_attr_sch_cursor_release
7 – dce_attr_sch_cursor_init
NAME dce_attr_sch_cursor_init - Initialize and allocate a cursor used with the dce_attr_sch_scan call SYNOPSIS #include <dce/dce_attr_base.h> void dce_rgy_attr_cursor_init( dce_attr_sch_handle_t h, unsigned32 *cur_num_entries, dce_attr_cursor_t *cursor, error_status_t *status ); PARAMETERS Input h An opaque handle bound to a schema object. Use dce_attr_sch_bind() to acquire the handle. Output cur_num_entries A pointer to an unsigned 32-bit integer that specifies the total number of entries contained in the schema at the time of this call. cursor A pointer to a dce_attr_cursor_t that is initialized to the first entry in the the schema. status A pointer to the completion status. On successful completion, the call returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_cursor_init() call initializes and allocates a cursor used with the dce_attr_sch_scan call. This call makes remote calls to initialize the cursor. To limit the number of remote calls, use the dce_attr_sch_cursor_alloc() call to allocate cursor, but not initialize it. If the cursor input to dce_attr_sch_scan has not been initialized, dce_attr_sch_scan call will initialize it; if it has been initialized, dce_attr_sch_scan advances it. Unlike the dce_attr_sch_cursor_alloc() call, the dce_attr_sch_cursor_init() call supplies the total number of entries found in the schema as an output parameter. Permissions Required None. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_bad_binding dce_attr_s_no_memory error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_cursor_release dce_attr_sch_scan dce_attr_sch_cursor_allocate
8 – dce_attr_sch_cursor_alloc
NAME dce_attr_sch_cursor_alloc - Allocates resources to a cursor used with the dce_attr_sch_scan call SYNOPSIS #include <dce/dce_attr_sch.h> void dce_rgy_attr_cursor_alloc( dce_attr_cursor_t *cursor, error_status_t *status ); PARAMETERS Output cursor A pointer to a dce_attr_cursor_t. status A pointer to the completion status. On successful completion, the call returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_cursor_alloc() call allocates resources to a cursor used with the dce_attr_sch_scan call. This routine, which is a local operation, does not initialize cursor. The dce_attr_sch_cursor_init() routine, which makes a remote call, allocates and initializes the cursor. In addition, dce_attr_sch_cursor_init() returns the total number of entries found in the schema as an output parameter; dce_attr_sch_cursor_alloc() does not. Permissions Required The dce_attr_sch_cursor_alloc() call requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_no_memory error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_cursor_init dce_attr_sch_cursor_release dce_attr_sch_scan
9 – dce_attr_sch_cursor_release
NAME dce_attr_sch_cursor_release - Release states associated with a cursor that has been allocated with either dce_attr_sch_cursor_init() or dce_attr_sch_cursor_alloc(). SYNOPSIS #include <dce/dce_attr_base.h> void dce_attr_sch_cursor_init( dce_attr_cursor_t *cursor, error_status_t *status ); PARAMETERS Input/Output cursor A pointer to a dce_attr_cursor_t. As an input parameter, cursor must have been initialized to the first entry in a schema. As an output parameter, cursor is uninitialized with all resources released. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_cursor_init() routine releases the resources allocated to a cursor that has been allocated by either a dce_attr_sch_cursor_init() or dce_attr_sch_cursor_alloc(). This call is a local operation and makes no remote calls. Permissions Required None. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_cursor_init dce_attr_sch_cursor_alloc dce_attr_sch_cursor_reset dce_attr_sch_scan
10 – dce_attr_sch_cursor_reset
NAME dce_attr_sch_cursor_reset - Resets a cursor that has been allocated with either dce_attr_sch_cursor_init() or dce_attr_sch_cursor_alloc(). SYNOPSIS #include <dce/dce_attr_base.h> void dce_attr_cursor_reset( dce_attr_cursor_t *cursor, error_status_t *status ); PARAMETERS Input/Output cursor A pointer to a dce_attr_cursor_t. As an input parameter, an initialized cursor. As an output parameter, cursor is reset to the first attribute in the schema. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_cursor_reset() routine resets a dce_attr_cursor_t that has been allocated by either a dce_attr_sch_cursor_init() or dce_attr_sch_cursor_alloc(). The reset cursor can then be used to process a new dce_attr_sch_scan query by reusing the cursor instead of releasing and re-allocating it. This is a local operation and makes no remote calls. Permissions Required None. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_SCH.IDL The idl file from which dce/dce_attr_sch.h was derived. ERRORS error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_cursor_init dce_attr_sch_cursor_alloc dce_attr_sch_scan
11 – dce_attr_sch_lookup_by_id
NAME dce_attr_sch_lookup_by_id - Read a schema entry identified by UUID SYNOPSIS #include <dce/dce_attr_base.h> void dce_attr_sch_lookup_by_id( dce_attr_sch_handle_t h, uuid_t *attr_id, dce_attr_schema_entry_t *schema_entry, error_status_t *status ); PARAMETERS Input h An opaque handle bound to a schema object. Use dce_attr_sch_bind() to acquire the handle. attr_id A pointer to a uuid_t that identifies a schema entry. Output schema_entry A dce_attr_schema_entry_t that contains an entry identified by attr_id. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_lookup_by_id() routine reads a schema entry identified by attr_id. This routine is useful for programmatic access. Permissions Required The dce_attr_sch_lookup_by_id() routine requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_bad_binding error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_lookup_by_name dce_attr_sch_scan
12 – dce_attr_sch_lookup_by_name
NAME dce_attr_sch_lookup_by_name - Read a schema entry identified by name SYNOPSIS #include <dce/dce_attr_base.h> void dce_attr_sch_lookup_by_name( dce_attr_sch_handle_t h, char *attr_name, dce_attr_schema_entry_t *schema_entry, error_status_t *status ); PARAMETERS Input h An opaque handle bound to a schema object. Use dce_attr_sch_bind() to acquire the handle. attr_name A pointer to a character string that identifies the schema entry. Output schema_entry A dce_attr_schema_entry_t that contains the schema entry identified by attr_name. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_lookup_by_name() routine reads a schema entry identified by name. This routine is useful for use with an interactive editor. Permissions Required The dce_attr_sch_lookup_by_name() routine requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_bad_binding error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_lookup_by_id dce_attr_sch_scan
13 – dce_attr_sch_get_acl_mgrs
NAME dce_attr_sch_get_acl_mgrs - Retrieve the manager types of the ACLs protecting the objects dominated by a named schema SYNOPSIS #include <dce/dce_attr_base.h> void dce_attr_sch_get_acl_mgrs( dce_attr_sch_handle_t h, unsigned32 size_avail, unsigned32 *size_used, unsigned32 *num_acl_mgr_types, uuid_t acl_mgr_types[], error_status_t *status ); PARAMETERS Input h An opaque handle bound to a schema object. Use dce_attr_sch_bind() to acquire the handle. size_avail An unsigned 32-bit integer containing the allocated length of the acl_manager_types[] array. Output size_used An unsigned 32-bit integer containing the number of output entries returned in the acl_mgr_types[] array. num_acl_mgr_types An unsigned 32-bit integer containing the number of types returned in the acl_mgr_types[] array. This may be greater than size_used if there was not enough space allocated by size_avail for all the manager types in the acl_manager_types[] array. acl_mgr_types[] An array of the length specified in size_avail to contain UUIDs (of type uuid_t) identifying the types of ACL managers protecting the target object. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_get_acl_mgrs() routine returns a list of the manager types protecting the schema object identified by h. ACL editors and browsers can use this operation to determine the ACL manager types protecting a selected schema object. Then, using the dce_attr_sch_aclmgr_strings() routine, they can determine how to format for display the permissions supported by that ACL manager type. Permissions Required The dce_attr_sch_get_acl_mgrs() routine requires appropriate permissions on the schema object for which the ACL manager types are to be returned. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_not_implemented error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_aclmgr_strings