Main Page | Modules | Files | Functions | Code Elements | Data Structures | Deprecated

Access Manager

Detailed Description

For security reasons, each persistent object manipulated by an object manager should have an associated Access Control List (ACL). The Access Manager (AM) module is designed to manipulate such lists and has been generalized so that it can deal with objects from different modules without incurring too great a performance cost. An access control list is a sequenced list of accessor/permission pairings.

The ITK programmer should avoid using the AM functions to alter the protection of an object directly. For example, when you change the protection of a dataset, if it is rev0, both rev0 and the latest version need to be updated. If you use the AM call, you must know which version of the dataset needs to be changed.

The valid accessor types that can appear within an ACL are:

These compound accessors are represented by the tag of a "compound accessor" through the AM tag based ITK. POM_delete_accessor and POM_ask_accessor_instances are provided to manipulate these.

Note:
The creation of accessors is demand driven by find. The only supported generic accessor at present is role in group. The AM regards any role possessed by the current user within the current group to be combined with current group to provide a list of current "role in group" accessors.
The importance of these accessor types within an ACL is ordered based upon how discriminating that type is. A "user" entry, since it affects a single Teamcenter Engineering user, has a higher "priority" than an entry specifying a role or a group. The actual priority ordering is:

  1. user (highest)
  2. role + group
  3. role, group
  4. world (lowest)

The access allowed on an object is determined by finding the entry (or entries) in the ACL with the highest priority that correspond to the current Teamcenter Engineering user. All entries for the same priority are added together to obtain total access allowed to this user. Access specified at lower priorities are ignored. If there are no entries that correspond to the current user (current group or users roles within that group) then no access is assumed.

Modules

Named ACL Functions

Access Control Entry Functions

Utility Functions

Privilege Functions

Named Tag Functions

Rule Tree Functions

Statistics Functions

Defines

Functions

Define Documentation

#define AM_acl_name_len   128

Definition at line 80 of file am.h.

#define AM_acl_selector_failed   AM_ERROR_BASE + 175

Cause: The ACL selector function failed - caught by error handler.

Action: check for evidence as to where the error originated in the journal and trace files.

Definition at line 535 of file am_errors.h.

#define AM_ACLClassName   "AM_ACL"

Definition at line 90 of file am.h.

#define AM_ambiguous_name   AM_ERROR_BASE + 179

Cause: The attempted find returned more than one instance.

Action: Change the name, and re-find.

Definition at line 566 of file am_errors.h.

#define AM_cannot_edit_node   AM_ERROR_BASE + 178

Cause: An attempt has been made to edit/cut/reorder the children of a rule tree node that is not editable.

Action: You cannot edit the children of the node.

Definition at line 559 of file am_errors.h.

#define AM_error_null_argument_value   AM_ERROR_BASE + 184

Definition at line 605 of file am_errors.h.

#define AM_invalid_rule_arg   AM_ERROR_BASE + 168

Specified rule argument is too long.

Definition at line 493 of file am_errors.h.

#define AM_invalid_rule_name   AM_ERROR_BASE + 163

Specified rule name is too long.

Definition at line 468 of file am_errors.h.

#define AM_list_rule_args_failed   AM_ERROR_BASE + 173

Argument listing function for this rule failed.

Definition at line 522 of file am_errors.h.

#define AM_load_not_allowed_outside_rule   AM_ERROR_BASE + 183

Cause: A special load/refresh function was called from outside a rule or accessor implementation function.

Action: Rewrite code to use normal load/refresh functions instead of the special ones reserved for rule/accessor implementations.

Definition at line 603 of file am_errors.h.

#define AM_load_not_allowed_within_rule   AM_ERROR_BASE + 182

Cause: A normal load/refresh function was called from within a rule or accessor function. This is probably the result of using cxpom objects from within a rule or accessor implementation, which is not allowed.

Action: Rewrite the rule or accessor function to not use cxpom objects.

Definition at line 594 of file am_errors.h.

#define AM_max_err_code   AM_ERROR_BASE + 184

Definition at line 607 of file am_errors.h.

#define AM_MODE_ALL_GROUPS   (1 << 0)

Definition at line 87 of file am.h.

#define AM_MODE_RULES   (1 << 1)

Definition at line 88 of file am.h.

#define AM_MODE_UNSET   0

Definition at line 86 of file am.h.

#define AM_named_tag_name_len   32

Definition at line 84 of file am.h.

#define AM_no_check_fn_for_data_manager   AM_ERROR_BASE + 181

Cause: The AM accessor type has no implementation for your object's data manager.

Action: check for evidence as to where the error originated in the journal and trace files.

Definition at line 583 of file am_errors.h.

#define AM_no_rule_for_data_manager   AM_ERROR_BASE + 180

Cause: The AM rule has no implementation for your object's data manager.

Action: check for evidence as to where the error originated in the journal and trace files.

Definition at line 574 of file am_errors.h.

#define AM_node_cut_error   AM_ERROR_BASE + 165

Specified node has already been cut from the rule tree.

Definition at line 478 of file am_errors.h.

#define AM_node_inconsistent_paste   AM_ERROR_BASE + 167

Specified "previous" node is not a child of the specified "parent" node.

Definition at line 488 of file am_errors.h.

#define AM_node_not_cut   AM_ERROR_BASE + 164

Specified node was not previously cut from the rule tree.

Definition at line 473 of file am_errors.h.

#define AM_node_root_exists   AM_ERROR_BASE + 166

A root node for the rule tree already exists.

Definition at line 483 of file am_errors.h.

#define AM_non_exclusive_login   AM_ERROR_BASE + 162

There are other users logged into the database.

Definition at line 463 of file am_errors.h.

#define AM_not_installed   AM_ERROR_BASE + 160

AM is not installed.

Definition at line 453 of file am_errors.h.

#define AM_not_loaded   AM_ERROR_BASE + 161

Specified ACL is not loaded.

Definition at line 458 of file am_errors.h.

#define AM_object_acl_on_non_pao   AM_ERROR_BASE + 176

Cause: Object ACLs are only permitted on POM Application Objects.

Action: Use a POM Application Object in cases where an Object ACL is required.

Definition at line 543 of file am_errors.h.

#define AM_old_am_function   AM_ERROR_BASE + 177

Cause: An obsolete old AM function is being used.

Action: Use the rules tree and new AM functions to replace the use of the old AM function.

Definition at line 551 of file am_errors.h.

#define AM_priv_name_len   32

Definition at line 83 of file am.h.

#define AM_REASONPropertyName   "reason"

Definition at line 91 of file am.h.

#define AM_reserved_id   AM_ERROR_BASE + 172

Cause: Attempt to register a rule or name an ACL using a reserved id.

Action: choose another id, that is distinct from the reserved id's, and from any other used id's.

Definition at line 517 of file am_errors.h.

#define AM_rule_arg_len   128

Definition at line 82 of file am.h.

#define AM_rule_failed   AM_ERROR_BASE + 169

There was an error during evaluation of a rule.

Definition at line 498 of file am_errors.h.

#define AM_rule_name_len   32

Definition at line 81 of file am.h.

#define AM_rule_not_found   AM_ERROR_BASE + 170

No rule with specified name exists.

Definition at line 503 of file am_errors.h.

#define AM_rule_not_registered   AM_ERROR_BASE + 171

There was an attempt to evaluate a rule before it was registered.

Definition at line 508 of file am_errors.h.

#define AM_validate_rule_arg_failed   AM_ERROR_BASE + 174

Argument validation function for this rule failed.

Definition at line 527 of file am_errors.h.

Function Documentation

SA_API int AM_accessor_info ( tag_t  accessor,
char **  type,
char **  name 
)

Returns the type and name of the specified accessor. Examples of accessor types are User, Group, etc.

Parameters:
accessor  (I) Tag of the accessor.
type  (OF) Type of the accessor.
name  (OF) Name of the accessor.

SA_API int AM_ask_acl_display_name ( tag_t  acl_id,
char **  acl_display_name 
)

Finds the display name of the specified Named ACL.

Parameters:
acl_id  (I)
acl_display_name  (OF) Display Name of ACL.

SA_API int AM_ask_acl_flag ( tag_t  acl_id,
char **  acl_flag 
)

Parameters:
acl_id  (I)
acl_flag  (OF)

SA_API int AM_ask_acl_name ( tag_t  acl_id,
char **  acl_name 
)

Finds the name of the specified Named ACL.

Parameters:
acl_id  (I)
acl_name  (OF) Name of ACL.

SA_API int AM_ask_mode ( int *  mode  ) 

Gives the current mode of operation for the AM.

In order to decode the mode, use a bitwise comparison with AM_MODE_ALL_GROUPS.

Parameters:
mode  (O) Current mode.

SA_API int AM_ask_named_tag_name ( tag_t  named_tag_id,
char **  named_tag_name 
)

Finds the name of the specified named tag.

Parameters:
named_tag_id  (I) Tag of the named tag.
named_tag_name  (OF) Name of the named tag.

SA_API int AM_ask_priv_name ( tag_t  privilege_id,
char **  privilege_name 
)

Finds the name of the specified privilege.

Parameters:
privilege_id  (I) Tag of the privilege.
privilege_name  (OF) Name of the privilege.

SA_API int AM_ask_priv_offset ( tag_t  privilege_id,
int *  offset 
)

Finds the offset of the specified privilege.

Parameters:
privilege_id  (I) Tag of the privilege.
offset  (O) Offset of the privilege.

SA_API int AM_check_accessors_privilege ( int  n_accessors,
tag_t *  accessors,
tag_t  object,
const char *  privilege,
logical *  verdict 
)

Checks if the given set of accessors (combination of user, groups, roles, etc.) has the specified privilege on the specified object. The rule tree is traversed to determine whether the privilege is granted or not. The verdict is set to true if the privilege is granted and to false if the privilege is revoked.

Parameters:
n_accessors  (I) Number of accessors.
accessors  (I) n_accessors Array containing the tags of the accessors.
object  (I) Tag of object instance to be checked.
privilege  (I) Choices are READ, WRITE, DELETE, CHANGE, PROMOTE, DEMOTE, COPY, IMPORT, EXPORT, TRANSFER_IN and TRANSFER_OUT.
verdict  (O) Logical flag specifying whether the privilege is granted or revoked.

SA_API int AM_check_privilege ( tag_t  object,
const char *  privilege,
logical *  verdict 
)

Checks if the current user has the specified privilege on the specified object. The rule tree is traversed to determine whether the privilege is granted or not. The verdict is set to true if the privilege is granted and to false if the privilege is revoked.

This function also works on objects with embedded ACLs.

Parameters:
object  (I) Tag of object instance to be checked.
privilege  (I) Choices are READ, WRITE, DELETE, CHANGE, PROMOTE, DEMOTE, COPY, IMPORT, EXPORT, TRANSFER_IN and TRANSFER_OUT.
verdict  (O) Logical flag specifying whether the privilege is granted or revoked.

SA_API int AM_check_sites_privilege ( tag_t  site,
tag_t  object,
const char *  privilege,
logical *  verdict 
)

Checks if the specified Teamcenter Engineering site has the specified privilege on the specified object. The rule tree is traversed to determine whether the privilege is granted or not. The verdict is set to true if the privilege is granted and to false if the privilege is revoked.

Parameters:
site  (I) Tag of site.
object  (I) Tag of object instance to be checked.
privilege  (I) Choices are READ, WRITE, DELETE, CHANGE, PROMOTE, DEMOTE, COPY, IMPORT, EXPORT, TRANSFER_IN and TRANSFER_OUT.
verdict  (O) Logical flag specifying whether the privilege is granted or revoked.

SA_API int AM_check_users_privilege ( tag_t  user,
tag_t  object,
const char *  privilege,
logical *  verdict 
)

Checks if the specified user has the specified privilege on the specified object. The rule tree is traversed to determine whether the privilege is granted or not. The verdict is set to true if the privilege is granted and to false if the privilege is revoked.

Note that the union of all the user's groups and roles is used and if the user is granted the privilege via any of these groups or roles, the verdict is specified as true.

Parameters:
user  (I) Tag of user.
object  (I) Tag of object instance to be checked.
privilege  (I) Choices are READ, WRITE, DELETE, CHANGE, PROMOTE, DEMOTE, COPY, IMPORT, EXPORT, TRANSFER_IN and TRANSFER_OUT.
verdict  (O) Logical flag specifying whether the privilege is granted or revoked.

SA_API int AM_clear_acl ( tag_t  acl_id  ) 

Removes all entries from a named ACL.

Parameters:
acl_id  (I) Tag of ACL.

SA_API int AM_create_acl ( const char *  acl_name,
tag_t *  acl_id 
)

Creates a Named ACL using the specified name.

Note:
The current user must be a Teamcenter Engineering system administrator.
Parameters:
acl_name  (I) Name specified to created ACL.
acl_id  (O) Tag of ACL to be created.

SA_API int AM_create_named_tag ( const char *  named_tag_name,
tag_t *  named_tag_id 
)

Creates a named tag using the specified name.

Parameters:
named_tag_name  (I) Name given to created named tag.
named_tag_id  (O) Tag of created named tag.

SA_API int AM_create_node ( const char *  rule_name,
const char *  rule_arg,
tag_t  parent,
tag_t  prev,
tag_t  acl,
tag_t *  node 
)

Creates a new node in the rules tree, as a child of the specified parent node and using the specified previous node to define its position among its sibling nodes.

The rule name and argument must be specified. The ACL for the node can also be specified if required. If the ACL is specified as NULLTAG, no ACL will be placed on the node.

If the parent node is specified as NULLTAG, an attempt is made to create a new root node. This will fail if a root node already exists.

If the previous node is specified as NULLTAG, the new node is created as the first child of the specified parent.

Note:
The current user must be a Teamcenter Engineering system administrator.
Parameters:
rule_name  (I) Name of the rule for the new node.
rule_arg  (I) Rule argument for the new node.
parent  (I) Parent node for the new node.
prev  (I) Previous sibling node for the new node.
acl  (I) ACL on the new node.
node  (O) Tag of the newly created node.

SA_API int AM_create_privilege ( const char *  privilege_name,
tag_t *  privilege_id 
)

Creates a privilege using the specified name.

Note:
The current user must be a Teamcenter Engineering system administrator.
Parameters:
privilege_name  (I) Name for the privilege.
privilege_id  (O) Tag of the created privilege.

SA_API int AM_delete_accessor ( tag_t  accessor_id  ) 

Removes an accessor from all Named ACLs in which it appears.

Note:
Exclusive login is required for this operation.
Parameters:
accessor_id  (I) Tag of accessor.

SA_API int AM_delete_acl ( tag_t  acl_id  ) 

Deletes the specified Named ACL.

Note:
The current user must be a Teamcenter Engineering system administrator.
Parameters:
acl_id  (I) Tag of ACL to be deleted.

SA_API int AM_delete_named_tag ( tag_t  named_tag_id  ) 

Deletes the specified named tag.

Parameters:
named_tag_id  (I) Tag of named tag to be deleted.

SA_API int AM_delete_privilege ( tag_t  privilege_id  ) 

Deletes the specified privilege.

Note:
The current user must be a Teamcenter Engineering system administrator.

Exclusive login is required for this operation.

Parameters:
privilege_id  (I) Tag of the privilege.

SA_API int AM_effective_acl_line ( tag_t  eff_acl_tag,
int  index,
tag_t *  source_acl,
tag_t *  accessor,
int *  n_granted,
tag_t **  granted,
int *  n_revoked,
tag_t **  revoked 
)

Returns details of an entry in the specified effective ACL. Both the tag of the accessor and lists of granted and revoked privileges are found for the entry with specified index.

Parameters:
eff_acl_tag  (I) Tag of the effective ACL.
index  (I) Index of the required ACL entry.
source_acl  (O)
accessor  (O) Tag of the accessor.
n_granted  (O) Number of granted privileges.
granted  (OF) n_granted Tags of granted privileges.
n_revoked  (O) Number of revoked privileges.
revoked  (OF) n_revoked Tags of revoked privileges.

SA_API int AM_evaluate_privilege ( tag_t  object,
const char *  privilege,
logical *  verdict,
int *  n_rules,
char ***  rules,
char ***  args,
tag_t *  acl,
tag_t *  accessor 
)

Checks if the current user has the specified privilege on the specified object and also evaluates the reason why the privilege is granted or revoked. The rule tree is traversed to determine whether the privilege is granted or not. The verdict is set to true if the privilege is granted, and to false if the privilege is revoked.

The path through the rule tree to the node that resulted in the verdict, is presented in the form of an array of rules and their arguments. Also provided is the Named ACL that resulted in the verdict and the accessor that applied within that ACL.

The acl and accessor tags are then null and there is one rule/argument returned with value of rule = "A.M." and argument = "Object ACL".

Parameters:
object  (I) Tag of object instance to be checked.
privilege  (I) Choices are READ, WRITE, DELETE, CHANGE, PROMOTE, DEMOTE, COPY, IMPORT, EXPORT, TRANSFER_IN and TRANSFER_OUT.
verdict  (O) Logical flag specifying whether the privilege is granted or revoked.
n_rules  (O) Number of rules and arguments.
rules  (OF) n_rules Array containing the names of all rules evaluated to arrive at the verdict.
args  (OF) n_rules Array of arguments for the rules.
acl  (O) Tag of the ACL used to arrive at the verdict.
accessor  (O) Tag of the accessor that applied within the ACL.

SA_API int AM_evaluate_users_privilege ( tag_t  user,
tag_t  object,
const char *  privilege,
logical *  verdict,
int *  n_rules,
char ***  rules,
char ***  args,
tag_t *  acl,
tag_t *  accessor 
)

Checks if the specified user has the specified privilege on the specified object. The rule tree is traversed to determine whether the privilege is granted or not. The verdict is set to true if the privilege is granted and to false if the privilege is revoked.

Note that the union of all the user's groups and roles is used and if the user is granted the privilege via any of these groups or roles, the verdict is specified as true.

Parameters:
user  (I) Tag of user.
object  (I) Tag of object instance to be checked.
privilege  (I) Choices are READ, WRITE, DELETE, CHANGE, PROMOTE, DEMOTE, COPY, IMPORT, EXPORT, TRANSFER_IN and TRANSFER_OUT.
verdict  (O) Logical flag specifying whether the privilege is granted or revoked.
n_rules  (O) Number of rules and arguments.
rules  (OF) n_rules Array containing the names of all rules evaluated to arrive at the verdict.
args  (OF) n_rules Array of arguments for the rules.
acl  (O) Tag of the ACL used to arrive at the verdict.
accessor  (O) Tag of the accessor that applied within the ACL.

SA_API int AM_exit_module ( void   ) 

Exits the AM module. This function should not be called more times than AM_init_module.

SA_API int AM_find_accessor ( const char *  type,
const char *  name,
tag_t *  acc 
)

Finds the tag of the accessor using the specified accessor type and name.

Parameters:
type  (I) Type of the accessor.
name  (I) Name of the accessor.
acc  (O) Tag of the accessor.

SA_API int AM_find_acl ( const char *  acl_name,
tag_t *  acl_id 
)

Finds the Named ACL with the specified name.

Parameters:
acl_name  (I) Name of ACL.
acl_id  (O) Tag of ACL.

SA_API int AM_find_named_tag ( const char *  named_tag_name,
tag_t *  named_tag_id 
)

Finds the named tag with the specified name.

Parameters:
named_tag_name  (I) Name of the named tag.
named_tag_id  (O) Tag of the named tag.

SA_API int AM_find_privilege ( const char *  name,
tag_t *  privilege_id 
)

Finds the privilege with the specified name.

Parameters:
name  (I) Privilege name.
privilege_id  (O) Tag of privilege found.

SA_API int AM_free_effective_acl ( tag_t  eff_acl_tag  ) 

Frees the information stored for an effective ACL.

Any call to AM_get_effective_acl should be followed eventually with a call to this routine, as the memory is then freed.

Parameters:
eff_acl_tag  (I) Tag of the object's effective ACL.

SA_API int AM_get_effective_acl ( tag_t  object,
tag_t *  eff_acl_tag,
int *  length 
)

Evaluates and returns the effective ACL on the specified object.

In effect this function uses the rule tree to build up a compound ACL that describes the combined effect on the object of the ACLs in the rule tree.

Parameters:
object  (I) Tag of the object.
eff_acl_tag  (O) Tag of the object's effective ACL.
length  (O) Number of entries in the effective ACL.

SA_API int AM_grant_privilege ( tag_t  acl_id,
tag_t  accessor_id,
tag_t  privilege 
)

Edits the specified Named ACL or object ACL, granting the specified privilege to the specified accessor. If the accessor previously had no privileges granted or revoked within the ACL, the accessor is added to the list of accessors within the ACL.

Note:
You should save any edits to an ACL by calling AM_save_acl as follows:
If you are editing an object ACL, call AM_save_acl on the object whose ACL has been edited.

If you are editing a named ACL, call AM_save_acl on the named ACL itself.

Parameters:
acl_id  (I) Tag of ACL.
accessor_id  (I) Tag of accessor.
privilege  (I) Tag of privilege.

SA_API int AM_init_module ( void   ) 

Initializes the AM module.

Note:
The initialization of the module does not install the AM, nor does it perform any checks to see if installation is necessary.
No AM function works if the AM module has not previously been initialized. Calls to AM_init_module can be nested.

SA_API int AM_list_accessor_privileges ( tag_t  acl_id,
tag_t  accessor_id,
int *  n_granted,
tag_t **  granted,
int *  n_revoked,
tag_t **  revoked 
)

Lists each privilege that is granted or revoked for the specified accessor in the specified Named ACL. Any privilege that is neither listed as granted nor as revoked is thus known to be unset.

Parameters:
acl_id  (I) Tag of ACL.
accessor_id  (I) Tag of accessor.
n_granted  (O) Number of granted privileges.
granted  (OF) n_granted Tags of granted privileges.
n_revoked  (O) Number of revoked privileges.
revoked  (OF) n_revoked Tags of revoked privileges.

SA_API int AM_list_accessor_types ( int *  n_types,
char ***  types 
)

Lists the names of all accessor types.

Parameters:
n_types  (O) Number of accessor types found.
types  (OF) n_types Names of the accessor types found.

SA_API int AM_list_accessors ( tag_t  acl_id,
int *  n_accessors,
tag_t **  accessors 
)

List all accessors that have one or more privileges granted or revoked within the specified Named ACL.

Parameters:
acl_id  (I) Tag of ACL.
n_accessors  (O) Number of accessors in ACL.
accessors  (OF) n_accessors Tags of accessors.

SA_API int AM_list_accessors_by_type ( const char *  type,
int *  n_accs,
tag_t **  accs 
)

Lists all accessors of the specified accessor type.

Parameters:
type  (I) Type of accessor to find.
n_accs  (O) Number of accessors found.
accs  (OF) n_accs Tags of the accessor found.

SA_API int AM_list_acls ( int *  n_acls,
tag_t **  acl_ids 
)

Lists the names of all Named ACLs.

Parameters:
n_acls  (O) Number of ACLs found.
acl_ids  (OF) n_acls Tags of ACLs found.

SA_API int AM_list_acls_by_type ( int *  n_acls,
tag_t **  acl_ids,
const char *  acl_flag 
)

Parameters:
n_acls  (O)
acl_ids  (OF) n_acls
acl_flag  (I)

SA_API int AM_list_named_tags ( int *  n_named_tags,
tag_t **  named_tags 
)

Lists the names of all named tags.

Parameters:
n_named_tags  (O) Number of named tags found.
named_tags  (OF) n_named_tags Tags of named tags found.

SA_API int AM_list_privileges ( int *  n_privileges,
tag_t **  privilege_ids 
)

Lists all defined privileges.

Parameters:
n_privileges  (O) Number of privileges.
privilege_ids  (OF) n_privileges Tags of the privileges.

SA_API int AM_list_rule_args ( const char *  rule_name,
int *  no_args,
char ***  args 
)

Lists the valid arguments of the specified rule.

Parameters:
rule_name  (I) Name of the rule.
no_args  (O) Number of arguments found.
args  (OF) no_args Names of the arguments found.

SA_API int AM_list_rules ( int *  no_rules,
char ***  rules 
)

Lists the names of all registered rules.

Parameters:
no_rules  (O) Number of rules found.
rules  (OF) no_rules Names of the rules found.

SA_API int AM_list_session_accessors ( int *  n_accessors,
tag_t **  accessors 
)

Lists all accessors in the current POM session context. This usually contains the login user plus all his/her groups and roles.

Parameters:
n_accessors  (O) Number of accessors found.
accessors  (OF) n_accessors Tags of the accessor found.

SA_API int AM_log_statistics ( logical  clear  ) 

Log Access Manager statistics to the syslog and optionally clear them.

Note:
Accumulation and logging of statistics is enabled by setting the AM_PERFORMANCE_STATISTICS environment variable to any value.
Parameters:
clear  (I) If true, clear statistics after logging them.

SA_API int AM_lookup_delegation_class ( const char *  class_name,
int *  cid 
)

SA_API int AM_node_ask_acl ( tag_t  node,
tag_t *  acl 
)

Finds the Named ACL on the specified node in the rules tree.

Parameters:
node  (I) Tag of the rule node.
acl  (O) Tag of the Named ACL.

SA_API int AM_node_ask_children ( tag_t  node,
int *  no_children,
tag_t **  children 
)

Finds the children of the specified node in the rules tree.

Parameters:
node  (I) Tag of the parent node.
no_children  (O) Number of children found.
children  (OF) no_children Tags of the children found.

SA_API int AM_node_ask_children_editable ( tag_t  node,
logical *  editable 
)

Parameters:
node  (I)
editable  (O)

SA_API int AM_node_ask_expanded ( tag_t  node,
logical *  expanded 
)

Parameters:
node  (I)
expanded  (O)

SA_API int AM_node_ask_parent ( tag_t  node,
tag_t *  parent 
)

Finds the parent of the specified node in the rules tree.

Parameters:
node  (I) Tag of the child rule node.
parent  (O) Tag of the parent rule node.

SA_API int AM_node_ask_root ( tag_t *  root  ) 

Finds the root of the rules tree. If the rules tree is empty, NULLTAG is returned for the root.

Parameters:
root  (O) Tag of the root node of the rules tree.

SA_API int AM_node_ask_rule_arg ( tag_t  node,
char **  rule_arg 
)

Finds the rule argument on the specified node in the rules tree.

Parameters:
node  (I) Tag of the rule node.
rule_arg  (OF) Argument for the rule.

SA_API int AM_node_ask_rule_name ( tag_t  node,
char **  rule_name 
)

Finds the name of the rule on the specified node in the rules tree.

Parameters:
node  (I) Tag of the rule node.
rule_name  (OF) Name of the rule.

SA_API int AM_node_cut ( tag_t  node  ) 

Cuts the specified node from the rules tree. This node can then be pasted somewhere else in the tree.

Note:
The current user must be a Teamcenter Engineering system administrator.
Parameters:
node  (I) Tag of the rule node to be cut.

SA_API int AM_node_move_down ( tag_t  node  ) 

Moves the specified node in the rules tree down its list of siblings. It has no effect if the node is already the last sibling in the list.

Note:
The current user must be a Teamcenter Engineering system administrator.
Parameters:
node  (I) Tag of the rule node to be moved.

SA_API int AM_node_move_up ( tag_t  node  ) 

Moves the specified node in the rules tree up its list of siblings. It has no effect if the node is already the first sibling in the list.

Note:
The current user must be a Teamcenter Engineering system administrator.
Parameters:
node  (I) Tag of the rule node to be moved.

SA_API int AM_node_paste ( tag_t  node,
tag_t  parent,
tag_t  prev 
)

Pastes the specified node into the rules tree, using the specified parent and previous nodes to define its position in the tree.

The paste will only work if the specified node has previously been cut from the rules tree.

If the parent node is specified as NULLTAG, the specified node becomes the root node in the tree. This will fail if a root node already exists.

If the previous node is specified as NULLTAG, the node is pasted as the first child of the specified parent.

Note:
The current user must be a Teamcenter Engineering system administrator.
Parameters:
node  (I) Tag of the rule node to be pasted.
parent  (I) Parent node for the pasted node.
prev  (I) Previous sibling node for the pasted node.

SA_API int AM_node_set_acl ( tag_t  node,
tag_t  acl 
)

Sets the Named ACL on the specified node in the rules tree.

Note:
The current user must be a Teamcenter Engineering system administrator.
Parameters:
node  (I) Tag of the rule node.
acl  (I) Tag of the new Named ACL.

SA_API int AM_node_set_children_editable ( tag_t  node,
logical  editable 
)

Parameters:
node  (I)
editable  (I)

SA_API int AM_node_set_expanded ( tag_t  node,
logical  expanded 
)

Parameters:
node  (I)
expanded  (I)

SA_API int AM_node_set_rule_arg ( tag_t  node,
const char *  rule_arg 
)

Sets the argument for the rule on the specified node in the rules tree.

Note:
The current user must be a Teamcenter Engineering system administrator.
Parameters:
node  (I) Tag of the rule node.
rule_arg  (I) New argument. for the rule.

SA_API int AM_node_set_rule_name ( tag_t  node,
const char *  rule_name 
)

Sets the rule on the specified node in the rules tree.

Note:
The current user must be a Teamcenter Engineering system administrator.
Parameters:
node  (I) Tag of the rule node.
rule_name  (I) Name of the new rule.

SA_API void AM_preload_rule_tree ( void   ) 

May make the first check_priv call go faster

SA_API int AM_privilege_of_offset ( int  offset,
tag_t *  privilege_id 
)

Finds the privilege with the specified offset.

Parameters:
offset  (I) Privilege offset.
privilege_id  (O) Tag of privilege found.

SA_API int AM_record_delegation_classes ( int  n_strings,
const char **  class_names,
const char *  parent_class 
)

SA_API int AM_record_object_parent ( int  n_tags,
tag_t *  ref_tag,
tag_t  parent_tag 
)

SA_API int AM_refresh_tree ( void   ) 

SA_API int AM_remove_accessor ( tag_t  acl_id,
tag_t  accessor_id 
)

Removes the specified accessor entry from a Named ACL, meaning that all that accessor privileges are now unset within the ACL.

Parameters:
acl_id  (I) Tag of ACL.
accessor_id  (I) Tag of accessor.

SA_API int AM_remove_parent_from_cache ( int  n_tags,
tag_t *  ref_tag,
tag_t  parent_tag 
)

SA_API int AM_revoke_privilege ( tag_t  acl_id,
tag_t  accessor_id,
tag_t  privilege 
)

Edits the specified Named ACL or object ACL, revoking the specified privilege for the specified accessor. If the accessor previously had no privileges granted or revoked within the ACL, the accessor is added to the list of accessors within the ACL.

Note:
You should save any edits to an ACL by calling AM_save_acl as follows:
If you are editing an object ACL, call AM_save_acl on the object whose ACL has been edited.

If you are editing a named ACL, call AM_save_acl on the named ACL itself.

Parameters:
acl_id  (I) Tag of ACL.
accessor_id  (I) Tag of accessor.
privilege  (I) Tag of privilege.

SA_API int AM_save_acl ( tag_t  acl_id  ) 

This function can be used to save either a named ACL or an objects ACL. When called on a named ACL, it saves any changes made to that ACL. When called on an object, it saves any edits to the ACL on the object, and also saves the object itself.

Note:
The current user must be a Teamcenter Engineering system administrator to save a named ACL; any user can save an object ACL.
Parameters:
acl_id  (I) Tag of ACL to be saved.

SA_API int AM_save_tree ( void   ) 

Saves all changes to the rules tree.

SA_API int AM_set_acl_flag ( tag_t  acl_id,
const char *  acl_flag 
)

Parameters:
acl_id  (I)
acl_flag  (I)

SA_API int AM_set_acl_name ( tag_t  acl_id,
const char *  acl_name 
)

Sets the name of the specified Named ACL.

Note:
The current user must be a Teamcenter Engineering system administrator.
Parameters:
acl_id  (I) Tag of ACL.
acl_name  (I) New name for ACL.

SA_API int AM_set_default_acl_flag ( tag_t  acl_id  ) 

Parameters:
acl_id  (I)

SA_API int AM_set_journalling ( logical  flag  ) 

Sets AM journalling on/off.

Parameters:
flag  (I) If true, set AM journalling on; if false, set AM journalling off.

SA_API int AM_set_mode ( int  mode  ) 

Sets the mode of operation for the AM.

The following modes are available:

AM_MODE_ALL_GROUPS - The user gains the benefit of access granted by all groups of which he/she is a member and not just the current group.

AM_MODE_UNSET - Neither of the above.

Note:
In order to achieve a combination of modes, use the '|' separator (e.g., AM_MODE_ALL_GROUPS | AM_MODE_UNSET).
Parameters:
mode  (I) Mode of operation for AM.

SA_API int AM_set_named_tag_name ( tag_t  named_tag_id,
const char *  named_tag_name 
)

Sets the name of the specified named tag.

Parameters:
named_tag_id  (I) Tag of the named tag.
named_tag_name  (I) New name of the named tag.

SA_API int AM_set_priv_name ( tag_t  privilege_id,
const char *  privilege_name 
)

Sets the name of the specified privilege.

Parameters:
privilege_id  (I) Tag of the privilege.
privilege_name  (I) New name of the privilege.

SA_API int AM_tree_discard_changes ( void   ) 

SA_API int AM_tree_find_nodes ( tag_t  parent,
char *  ruleName,
char *  ruleArg,
int *  count,
tag_t **  nodes 
)

Parameters:
parent  (I)
ruleName  (I)
ruleArg  (I)
count  (O)
nodes  (OF) count

SA_API int AM_unload_acl ( tag_t  acl_id  ) 

Unloads the specified Named ACL.

Parameters:
acl_id  (I) Tag of ACL to be unloaded.

SA_API int AM_unload_tree ( void   ) 

Unloads the rules tree from memory. All changes since the last time the tree was saved are lost.

SA_API int AM_unset_privilege ( tag_t  acl_id,
tag_t  accessor_id,
tag_t  privilege 
)

Edits the specified Named ACL or object ACL, un-setting the specified privilege for the specified accessor. If the accessor has no remaining privileges granted or revoked within the ACL, the accessor is removed from the list of accessors within the ACL.

Note:
You should save any edits to an ACL by calling AM_save_acl as follows:
If you are editing an object ACL, call AM_save_acl on the object whose ACL has been edited.

If you are editing a named ACL, call AM_save_acl on the named ACL itself.

Parameters:
acl_id  (I) Tag of ACL.
accessor_id  (I) Tag of accessor.
privilege  (I) Tag of privilege.

SA_API int AM_validate_rule_arg ( const char *  rule_name,
const char *  rule_arg,
logical *  is_valid 
)

Checks whether the specified argument is valid for the specified rule, using the validate function registered for the rule.

Parameters:
rule_name  (I) Name of the rule.
rule_arg  (I) Name of the argument.
is_valid  (O) True if the argument is valid.