Custom Ownership Mode for Control Tokens

Ownership of Control Tokens is defined by the application property ControlTokenOwnerMode as one of:

Session ID
Account ID
Machine ID
or, Custom

When in Custom owner mode, the ownership of a token is determined by custom logic defined by the application as an alternative to SessionID, AccountID and MachineID. Whenever a check is made to see who owns a token, a ControlTokenIsOwnerHook module defined by the application is called. The application's special ownership logic must be defined within this module. Furthermore, the tokens themselves can be made to store a custom identifier that can assist in determining who it is owned by. The custom identifier can be added by a ControlTokenCustomFieldHook module defined by the application.

The ControlTokenIsOwnerHook module must be both script and steady-state compatible. When VTScada tests to see if a token belongs to the current user, this hook will be invoked if it exists. It must return TRUE if the token owner (as defined by the hook) matches the token record and FALSE otherwise.

The ControlTokenCustomFieldHook module must be script compatible. It must return a string that helps identify the owner of a token. When VTScada generates a token record, if this module exists it will be called to generate the custom identifier which then gets stored in the token record.

For example, suppose you have two control rooms (Main and Backup) with several workstations in each (thick clients). The owner grouping goes by control room, so when a workstation from the Main control room requests a token, all the workstations at Main should get access. ControlTokenCustomFieldHook should return "Main" or "Backup" depending on where the workstation is. Once this token has been granted and any user from any workstation attempts to control a tag, the ControlTokenIsOwnerHook checks to see who owns the token based on whether both the token and the user are in Main or Backup.

Writing a custom hook module may require a high degree of proficiency with VTScada scripting.

VTScada will call ControlTokenIsOwnerHook with the following supplied parameters. Your module may make use any of these as appropriate for your definition of ownership.

\ControlTokenIsOwnerHook(Record       { As returned by AlarmManager.GetRecord() },
                         SessID       { The current security session            },
                         MachineID    { Identifies the current machine          },
                         MachID       { The current machine ID                  }, 
                         Custom       { A custom value that can be any of:
                                          - Invalid (default set by ControlTokenCustomFieldHook)
                                          - a parameter that you pass to the Control Token Manager,
                                          - the value you set for Custom in any of RequestToken, ReleaseToken, DenyTokenRequest and GrantTokenRequest,
                                          - the first valid value of SessionID, AccountID or MachineID });
\ControlTokenIsOwnerHook(Record       { an AlarmRecord structure that contains the token information },
                         SessionID    { the user's current session ID },
                         AccountID    { the user's account ID as returned by \SecurityManager.GetAccountID() },
                         MachineID    { the user's workstation ID as returned by WkStaInfo(3) }, 
                         Custom       { A custom value that can be any of:
                                          - Invalid (default set by ControlTokenCustomFieldHook)
                                          - the value you set for Custom in any of RequestToken, ReleaseToken, DenyTokenRequest and GrantTokenRequest });

The Custom parameter can be used as another identifier of the user but can also be used to compare against the Custom field of a Record or Token. The default value of Custom is set by , "ControlTokenCustomFieldHook".

 ControlTokenCustomFieldHook(SessionID, AccountID, MachineID)

The purpose of ControlTokenCustomFieldHook is to provide more flexibility when creating custom ownership rules. The return value of ControlTokenCustomFieldHook is used as the default value of the Custom parameter of ControlTokenIsOwnerHook, RequestToken, ReleaseToken, DenyTokenRequest and GrantTokenRequest.