Class TrainzGameObject

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
(→‎IssueSecurityToken)
 
(7 intermediate revisions by one user not shown)
Line 1: Line 1:
 
*[[TrainzScript Library Reference|API Hierarchy]]
 
*[[TrainzScript Library Reference|API Hierarchy]]
−
**[[Class GSObject|GSObject]]
+
**[[Class GSObject]]
−
***[[Class GameObject|GameObject]]
+
***[[Class GameObject]]
−
****Class TrainzGameObject
+
****[[Class TrainzGameObject]]
 
<br>
 
<br>
  
Line 9: Line 9:
  
 
==Init==
 
==Init==
−
{{MethodHeader|public void Init(void)<br>public void Init(Asset asset)}}
+
{{MethodHeader|public void Init(Asset asset)}}
 
;Parameters
 
;Parameters
−
*'''asset''' = Reference to the script's associated asset.
+
*asset - Reference to the script's associated asset.
 
;Returned Value
 
;Returned Value
 
*None
 
*None
Line 36: Line 36:
 
*The returned [[Class Asset|Asset]] reference can be used to retrieve the KUID, StringTable or configuration data of the Asset.
 
*The returned [[Class Asset|Asset]] reference can be used to retrieve the KUID, StringTable or configuration data of the Asset.
 
<br>
 
<br>
−
 
  
 
==IssueSecurityToken==
 
==IssueSecurityToken==
Line 44: Line 43:
 
*rights - Array of string identifiers specifying the operations permitted by this token.
 
*rights - Array of string identifiers specifying the operations permitted by this token.
 
;Returned Value
 
;Returned Value
−
*The issued SecurityToken.
+
*The issued [[Class SecurityToken|SecurityToken]].
−
;Syntax;
+
;Syntax
 
  KUID friendlyAsset = GetAsset().LookupKUIDTable("some-asset");
 
  KUID friendlyAsset = GetAsset().LookupKUIDTable("some-asset");
 
   
 
   
Line 62: Line 61:
 
==IssueSecurityToken==
 
==IssueSecurityToken==
 
{{MethodHeader|native SecurityToken IssueSecurityToken(SecurityToken source, KUID asset, string[] rights))}}
 
{{MethodHeader|native SecurityToken IssueSecurityToken(SecurityToken source, KUID asset, string[] rights))}}
 +
;Parameters
 +
*source - The source security token.
 +
*asset - The asset this token is intended to be used by.
 +
*rights - Array of string identifiers specifying the operations permitted by this token.
 +
;Returned Value
 +
*The issued SecurityToken.
 +
;Syntax
 +
KUID friendlyAsset = GetAsset().LookupKUIDTable("some-asset");
 +
 +
string[] rights = new string[2];
 +
rights[0] = "access-data";
 +
 +
SecurityToken newToken = IssueSecurityToken(m_ourToken, friendlyAsset, rights);
 +
 +
;Notes
 +
*Re-issues a [[Class SecurityToken|SecurityToken]] to another asset.
 +
*The source token must permit duplication by including "duplicate-token" in the rights array.
 +
*It is not be possible to add rights that the calling asset does not already have, only remove existing ones.
 +
<br>
  
 
==MergeSecurityTokens==
 
==MergeSecurityTokens==
 
{{MethodHeader|native SecurityToken MergeSecurityTokens(SecurityToken[] tokens)}}
 
{{MethodHeader|native SecurityToken MergeSecurityTokens(SecurityToken[] tokens)}}
 +
;Parameters
 +
*tokens - The tokens to merge together.
 +
;Returned Value
 +
*A single [[Class SecurityToken|SecurityToken]] with all of the rights of the passed in tokens.
 +
;Syntax;
 +
SecurityToken[] tokens = new SecurityToken[];
 +
tokens[0] = m_securityToken;
 +
tokens[1] = newRightsToken;
 +
 +
m_securityToken = MergeSecurityTokens(tokens);
 +
;Notes
 +
*Can be used to merge multiple tokens together, making things easier to manage.
 +
*Can be used to (essentially) add new rights to an existing token.
 +
*Care should be taken when merging tokens from different owners, to avoid compromising security.
 +
<br>
  
 
==Validate==
 
==Validate==
 
{{MethodHeader|native bool Validate(SecurityToken token, TrainzGameObject owner, string operation)}}
 
{{MethodHeader|native bool Validate(SecurityToken token, TrainzGameObject owner, string operation)}}
 +
;Parameters
 +
*token - The token to validate.
 +
*owner - The owner to search for in the token.
 +
*operation - The operation to perform (must be listed in the 'rights' of the token).
 +
;Returned Value
 +
*Whether the token grants the required access.
 +
;Syntax;
 +
if (!Validate(token, m_friendlyAsset, "edit-settings"))
 +
  return; // Reject the token
 +
;Notes
 +
*Checks if a [[Class SecurityToken|SecurityToken]] is owned by a specific object, and that it has access to perform a specific operation.
 +
<br>
  
 
==Validate==
 
==Validate==
 
{{MethodHeader|native bool Validate(SecurityToken token, KUID owner, string operation)}}
 
{{MethodHeader|native bool Validate(SecurityToken token, KUID owner, string operation)}}
 +
;Parameters
 +
*token - The token to validate.
 +
*owner - The owning asset to search for in the token.
 +
*operation - The operation to perform (must be listed in the 'rights' of the token).
 +
;Returned Value
 +
*Whether the token grants the required access.
 +
;Syntax;
 +
KUID friendlyAsset = GetAsset().LookupKUIDTable("some-asset");
 +
if (!Validate(token, friendlyAsset, "edit-settings"))
 +
  return; // Reject the token
 +
;Notes
 +
*Checks if a [[Class SecurityToken|SecurityToken]] is owned by a specific object, and that it has access to perform a specific operation.
 +
<br>
  
 
==Categories==
 
==Categories==
 
[[Category:Script Class]]
 
[[Category:Script Class]]

Latest revision as of 12:48, 26 February 2024


  • Base class for a GameObject that is an instance of a Trainz asset.


Contents

[edit] Init

public void Init(Asset asset)
Parameters
  • asset - Reference to the script's associated asset.
Returned Value
  • None
Syntax
  • None, method is automatically called by the game.
Notes
  • Initialisation method which is called by Trainz when the object is first created.
  • It is up to the script programmer to do any initialization tasks required here.
  • This may include starting monitor threads, adding message handlers, and so on.
  • Some derived classes have both an Init() and Init(Asset) method. It is recommended that you use the Init(Asset) version whenever you can.
  • Uses the 'mandatory' keyword, meaning you must call inherited() when overriding this function.
  • Since Init() is called from native Trainz code, you cannot use Sleep() or wait(). However, Init() can start threaded methods that are allowed to sleep and process messages.


[edit] GetAsset

public Asset GetAsset(void)
Parameters
  • None
Returned Value
  • A reference to the owning asset.
Syntax 
Asset asset = GetAsset();
Notes
  • The returned Asset reference can be used to retrieve the KUID, StringTable or configuration data of the Asset.


[edit] IssueSecurityToken

native SecurityToken IssueSecurityToken(KUID asset, string[] rights)
Parameters
  • asset - The asset this token is intended to be used by.
  • rights - Array of string identifiers specifying the operations permitted by this token.
Returned Value
Syntax 
KUID friendlyAsset = GetAsset().LookupKUIDTable("some-asset");

string[] rights = new string[2];
rights[0] = "edit-settings";
rights[1] = "access-data";

SecurityToken token = IssueSecurityToken(friendlyAsset, rights);
Notes
  • Creates a SecurityToken object which can be issued to other assets to grant access to certain features.
  • The created SecurityToken can be given to trusted objects, and later passed to the Validate() function when checking permissions.
  • SecurityToken.IsIsOwnerLocallyModified() can be used to check the issued asset hasn't been modified in some form.


[edit] IssueSecurityToken

native SecurityToken IssueSecurityToken(SecurityToken source, KUID asset, string[] rights))
Parameters
  • source - The source security token.
  • asset - The asset this token is intended to be used by.
  • rights - Array of string identifiers specifying the operations permitted by this token.
Returned Value
  • The issued SecurityToken.
Syntax 
KUID friendlyAsset = GetAsset().LookupKUIDTable("some-asset");

string[] rights = new string[2];
rights[0] = "access-data";

SecurityToken newToken = IssueSecurityToken(m_ourToken, friendlyAsset, rights);
Notes
  • Re-issues a SecurityToken to another asset.
  • The source token must permit duplication by including "duplicate-token" in the rights array.
  • It is not be possible to add rights that the calling asset does not already have, only remove existing ones.


[edit] MergeSecurityTokens

native SecurityToken MergeSecurityTokens(SecurityToken[] tokens)
Parameters
  • tokens - The tokens to merge together.
Returned Value
  • A single SecurityToken with all of the rights of the passed in tokens.
Syntax; 
SecurityToken[] tokens = new SecurityToken[];
tokens[0] = m_securityToken;
tokens[1] = newRightsToken;

m_securityToken = MergeSecurityTokens(tokens);
Notes
  • Can be used to merge multiple tokens together, making things easier to manage.
  • Can be used to (essentially) add new rights to an existing token.
  • Care should be taken when merging tokens from different owners, to avoid compromising security.


[edit] Validate

native bool Validate(SecurityToken token, TrainzGameObject owner, string operation)
Parameters
  • token - The token to validate.
  • owner - The owner to search for in the token.
  • operation - The operation to perform (must be listed in the 'rights' of the token).
Returned Value
  • Whether the token grants the required access.
Syntax; 
if (!Validate(token, m_friendlyAsset, "edit-settings"))
  return; // Reject the token
Notes
  • Checks if a SecurityToken is owned by a specific object, and that it has access to perform a specific operation.


[edit] Validate

native bool Validate(SecurityToken token, KUID owner, string operation)
Parameters
  • token - The token to validate.
  • owner - The owning asset to search for in the token.
  • operation - The operation to perform (must be listed in the 'rights' of the token).
Returned Value
  • Whether the token grants the required access.
Syntax; 
KUID friendlyAsset = GetAsset().LookupKUIDTable("some-asset");
if (!Validate(token, friendlyAsset, "edit-settings"))
  return; // Reject the token
Notes
  • Checks if a SecurityToken is owned by a specific object, and that it has access to perform a specific operation.


[edit] Categories

Retrieved from "https://online.ts2009.com/mediaWiki/index.php?title=Class_TrainzGameObject&oldid=40130"
Personal tools