STRIDE Wiki - User contributions [en]

Studio:Test Script Perl Template

2008-11-12T23:53:09Z

Carriez:

The following sample represents a starting point for perl test scripts.

{| class="wikitable"
!Source
|-
| style="background-color: white;" |
<source lang="perl">
=nd

Brief summary...

About: Description
Here is some description text. It can have text that is *bolded* and _underlined_.

About: Tests
test case 1 - description of test case 1
test case 2 - description of test case 2
etc - more cases...

About: Test Plan
See <http://project-portal.s2technologies.com/index.php/MyTestPlan>

About: Copyright
Copyright 2008 S2 Technologies support@s2technologies.com.

=cut

use strict;
use warnings;
use Carp;
use Win32::TieRegistry(Delimiter=>"/");
use File::Spec;
use Win32::OLE;

Win32::OLE->Option(Warn => 3);
use vars qw( $StrideLibDirectory );
BEGIN {
my $strideDir = $Registry->{"LMachine/SOFTWARE/S2 Technologies/STRIDE/InstallDir"} || $ENV{'STRIDE_DIR'};
$StrideLibDirectory = File::Spec->catdir($strideDir, 'lib', 'perl');
}
use lib $StrideLibDirectory;
</source>
|}

This template uses [http://www.naturaldocs.org NaturalDocs] for documentation, which is a utility for documenting diverse codebases (including perl, c++, javascript). The documentation can be generated for your files by invoking the [http://www.naturaldocs.org/running.html NaturalDocs Utility]. The code above produces the following HTML output:

[[Image:NaturalDocs_Out_1.JPG|frame|none|Example NaturalDocs Output]]

[[Category: Document Templates]]

Studio:AutoScript Functions

2008-07-31T00:46:49Z

Carriez: /* CallBypassOverrideNonBlocking */

__FORCETOC__ 

== Overview ==
This section describes basic functionality for ascript function processing. For ease of understanding, this section describes overall concepts and then describes the precise functionality that STRIDE provides. 

== Function Interception ==
A powerful feature of STRIDE is the ability to intercept function calls. While this capability is known to most seasoned STRIDE users, it is not necessarily as known to STRIDE newbies. Comprehension of general STRIDE terms requires a small amount of knowledge as to what function interception means.
 
STRIDE is generally used to debug remote hardware (e.g. a cellphone) from a Windows computer running STRIDE. The remote hardware is refered to as the target. The Windows computer is refered
to as the host. Scripts are used to communicate with STRIDE to pass data between the host and target.
 
While there are several models for how to connect to host and target and to transfer data inbetween them, this wiki page is only to describe how perform this connectability via ascript. The following issues have to be resolved to communicate between host and target using two scripts:
* Which script owns a particular function (e.g. a script on the target)?
* Which script desires access to the function (e.g. a script on the host)?
* What is types of data (i.e. parameters, pointers, and return value payloads) will be passed between them?
* How will the owner and the user communicate to pass payloads?

The how of questions will be answered in the following sections. The why will depend on a particular testing solution to each distinct type of hardware being developed.

== Ownership vs. Usage ==
STRIDE has the concept of a Function Owner and a Function User. In general STRIDE usage the Owner and User imply the owner of a function on the target and the user of a function on the host.
 

=== Function User ===
A [[ascript#ascript.Functions.Item.User|Function User]] may be any script that is not registered as the function owner or function override owner. The [[ascript#ascript.Functions.Item.User|Function User]] may be access via the message as [[ascript#ascript.Functions.Item.User|ascript.Functions.Item.User]].
 

=== Function Owner ===
The [[ascript#ascript.Functions.Item.Owner|Function Owner]] is the script that has successfully registered itself as the owner of the function (by calling the Register method). A function will only have one registered owner. Calls to register a second owner will result in an exception will be thrown. Ownership can be surrendered by calling the Unregister method (or by exiting the script that registered ownership). The [[ascript#ascript.Functions.Item.Owner|Function Owner]] may be accessed via [[ascript#ascript.Functions.Item.Owner|ascript.Functions.Item.Owner]].
 

=== Override Owner ===
The Function Override Owner of a function is the script that successfully registered as the override owner (using the RegisterOverride method). An override owner is used to bypass the registered owner. If a function has an override owner registered, function calls are made to the registered override owner and not the registered owner. This allows the ability to code scripting with the registered owner, but to bypass the registered owner for certain processing for a variety of reasons (i.e. some code not implemented for the registered owner, some exception cases, etc.). It is legal for a script to declare both forms of function ownership. Thus, the same script may be both registered owner and the registered override owner.
 

== Function Payloads ==
Payloads are [[Dynamic Objects|Dynamic Objects]] containing data related to a function's parameters, a function's return value, or pointer values passed for a function. These payloads are defined as properties for both a [[ascript#ascript.Functions.Item.User|Function User]] and a [[ascript#ascript.Functions.Item.Owner|Function Owner]]. By being part of both user and owner allows their values can be checked for validity in the event that a call did not pass correct data from user to owner (or visa-versa).
 

=== OutPointers ===
This payload exists only if a function's payload has at least one pointer that is qualified as OUT or INOUT. In other words, the function returns an object via a pointer through its parameter list.

If this property exists, its members are comprised of all the top-level parameters that are either OUT or INOUT pointers. This can also exist for structured types (structs or unions) that contain members that are OUT or INOUT. It can also exist if a structured type contains a nested structured type that contains members that are OUT or INOUT. In the case of structured type objects appearing in the OutPointers hierarchy, only members that are qualified as OUT or INOUT (or that themselves contain these qualified types) are available.

Upon a function's return, the OutPointers property of the [[ascript#ascript.Functions.Item.User|Function User]] object (ascript.Functions.Item().User.OutPointers) will reflect (contain) the values set by the [[ascript#ascript.Functions.Item.Owner|Function Owner]] object (ascript.Functions.Item().Owner.OutPointers).

=== ParameterList ===
A ParameterList payload only exists if the given [[ascript#ascript.Functions.Item.Owner|Function Owner]] contains one or more parameters. This payload will contain the values of all ParameterList fields at the time the function User called the Owner (on the user side before a call). The ParameterList payload is a [[Dynamic Objects|Dynamic Object]]. This payload will contain all the ParameterList field results after a call (on the owner side after a call).

=== ReturnValue ===
The ReturnValue Payload only exists if the given [[ascript#ascript.Functions.Item.Owner|Function Owner]] returns a value. Functions returning void will not have this property. The ReturnValue payload is a [[Dynamic Objects|Dynamic Object]]. After a call, the ReturnValue payload will contain the return results (on the owner side after a call).

== Synchronous / Asynchronous Interception ==
Function calls that are made between a function [[Ascript#Ascript.Functions.Item.Owner|Owner]] and a function [[Ascript#Ascript.Functions.Item.Owner|User]] will be either asynchronous or synchronous.
 

=== Asynchronous Calls (non-blocking) ===
An asynchronous function call is also known as a "non-blocking" call. This is the type of call that occurs for both CallNonBlocking and CallBypassOverrideNonBlocking.

==== CallBypassOverrideNonBlocking ====
Asynchronously calls the override registered owner of the function (Non-blocking call).
* Invokes call to registered function owner bypassing the registered override owner (if one exists).
* If there is no registered owner but there is a registered override owner, the call is routed to the registered override owner.
* Current values of all fields of the ParameterList property are marshaled to the called function.
* This method returns to the caller immediately. When the function owner (running in a separate thread) returns, an event is placed in this script's queue by the STRIDE Runtime. The event (as a polymorphic object exposing Type and Name properties) is retrieved from the queue using [[Events#WaitForEvent|ascript.WaitForEvent()]].
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].
* The object returned from [[Events#WaitForEvent|WaitForEvent()]] in response to CallByPassOverrideNonBlocking() can be:
{| cellspacing="0" cellpadding="1" width="100%" border="0"
|-
| width="10" |
|  
* The Function User Object corresponding to the function that was called. (Type = "FunctionUser", Name="function name"). The object's ReturnValue property and the OutPointers property (if present) will be populated with the values supplied by the Owner implementation.
* An [[Error Object|Error Object]] containing information about the error that occurred (Type="Error"; Name="error source").
|}

==== CallNonBlocking ====

Asynchronously calls the registered owner of the function (Non-blocking call).
* This call invokes a call to the currently registered owner of the function.
**If there is a registered owner and there is not a registered override owner, the call is routed to the registered owner.
**If there is a registered owner and there is also a registered override owner, the call is routed to the registered override owner.
**If there is no registered owner but there is a registered override owner, the call is routed to the registered override owner.
* The current values of all fields in the ParameterList property are marshaled to the called function.
* This method returns to the caller immediately. When the function owner (running in a separate thread) returns, an event is placed in this script's queue by the STRIDE Runtime. The event (as a polymorphic object exposing Type and Name properties) is retrieved from the queue using ascript.WaitForEvent().
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].
* The object returned from [[Events#WaitForEvent|WaitForEvent()]] in response to CallByPassOverrideNonBlocking() can be:
{| cellspacing="0" cellpadding="1" width="100%" border="0"
|-
| width="10" |
|  
* The Function User Object corresponding to the function that was called. (Type = "FunctionUser", Name="function name"). The object's ReturnValue property and the OutPointers property (if present) will be populated with the values supplied by the Owner implementation.
* An [[Error Object|Error Object]] containing information about the error that occurred (Type="Error"; Name="error source").
|}

=== Synchronous Calls (blocking) ===
A synchronous call is also known as a "blocking" call. Blocking calls a made using the Call or CallBypassOverride methods. These calls are made from the [[Ascript#Ascript.Functions.Item.User|User]].

==== Call ====
Synchronously calls the registered owner of the function (Blocking call).
* All current field values of the ParameterList property are marshaled to the function [[Ascript#Ascript.Functions.Item.Owner|Owner]].
* If there is no registered owner or registered override owner, an exception is thrown.
* If there is no registered owner but there is a registered override owner, the call is routed to the registered override owner.
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].

==== CallBypassOverride ====
Synchronously calls the override registered owner of the function (Blocking call).
* The call is made to the registered owner of the function bypassing any existing registered override owner.
* The current values of all fields in the ParameterList property are marshaled to the called function [[Ascript#Ascript.Functions.Item.Owner|Owner]].
* If there is no registered owner or registered override owner, an exception is thrown.
* If there is no registered owner but there is a registered override owner, the call is routed to the registered override owner.
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].

=== Returns ===
When the callee ([[Ascript#Ascript.Functions.Item.Owner|owner]]) wants to generate a function return, it makes a call to the Return method. This method is used for both synchronous and unsynchronous calls.

Studio:AutoScript Functions

2008-07-31T00:46:01Z

Carriez: /* CallNonBlocking */

__FORCETOC__ 

== Overview ==
This section describes basic functionality for ascript function processing. For ease of understanding, this section describes overall concepts and then describes the precise functionality that STRIDE provides. 

== Function Interception ==
A powerful feature of STRIDE is the ability to intercept function calls. While this capability is known to most seasoned STRIDE users, it is not necessarily as known to STRIDE newbies. Comprehension of general STRIDE terms requires a small amount of knowledge as to what function interception means.
 
STRIDE is generally used to debug remote hardware (e.g. a cellphone) from a Windows computer running STRIDE. The remote hardware is refered to as the target. The Windows computer is refered
to as the host. Scripts are used to communicate with STRIDE to pass data between the host and target.
 
While there are several models for how to connect to host and target and to transfer data inbetween them, this wiki page is only to describe how perform this connectability via ascript. The following issues have to be resolved to communicate between host and target using two scripts:
* Which script owns a particular function (e.g. a script on the target)?
* Which script desires access to the function (e.g. a script on the host)?
* What is types of data (i.e. parameters, pointers, and return value payloads) will be passed between them?
* How will the owner and the user communicate to pass payloads?

The how of questions will be answered in the following sections. The why will depend on a particular testing solution to each distinct type of hardware being developed.

== Ownership vs. Usage ==
STRIDE has the concept of a Function Owner and a Function User. In general STRIDE usage the Owner and User imply the owner of a function on the target and the user of a function on the host.
 

=== Function User ===
A [[ascript#ascript.Functions.Item.User|Function User]] may be any script that is not registered as the function owner or function override owner. The [[ascript#ascript.Functions.Item.User|Function User]] may be access via the message as [[ascript#ascript.Functions.Item.User|ascript.Functions.Item.User]].
 

=== Function Owner ===
The [[ascript#ascript.Functions.Item.Owner|Function Owner]] is the script that has successfully registered itself as the owner of the function (by calling the Register method). A function will only have one registered owner. Calls to register a second owner will result in an exception will be thrown. Ownership can be surrendered by calling the Unregister method (or by exiting the script that registered ownership). The [[ascript#ascript.Functions.Item.Owner|Function Owner]] may be accessed via [[ascript#ascript.Functions.Item.Owner|ascript.Functions.Item.Owner]].
 

=== Override Owner ===
The Function Override Owner of a function is the script that successfully registered as the override owner (using the RegisterOverride method). An override owner is used to bypass the registered owner. If a function has an override owner registered, function calls are made to the registered override owner and not the registered owner. This allows the ability to code scripting with the registered owner, but to bypass the registered owner for certain processing for a variety of reasons (i.e. some code not implemented for the registered owner, some exception cases, etc.). It is legal for a script to declare both forms of function ownership. Thus, the same script may be both registered owner and the registered override owner.
 

== Function Payloads ==
Payloads are [[Dynamic Objects|Dynamic Objects]] containing data related to a function's parameters, a function's return value, or pointer values passed for a function. These payloads are defined as properties for both a [[ascript#ascript.Functions.Item.User|Function User]] and a [[ascript#ascript.Functions.Item.Owner|Function Owner]]. By being part of both user and owner allows their values can be checked for validity in the event that a call did not pass correct data from user to owner (or visa-versa).
 

=== OutPointers ===
This payload exists only if a function's payload has at least one pointer that is qualified as OUT or INOUT. In other words, the function returns an object via a pointer through its parameter list.

If this property exists, its members are comprised of all the top-level parameters that are either OUT or INOUT pointers. This can also exist for structured types (structs or unions) that contain members that are OUT or INOUT. It can also exist if a structured type contains a nested structured type that contains members that are OUT or INOUT. In the case of structured type objects appearing in the OutPointers hierarchy, only members that are qualified as OUT or INOUT (or that themselves contain these qualified types) are available.

Upon a function's return, the OutPointers property of the [[ascript#ascript.Functions.Item.User|Function User]] object (ascript.Functions.Item().User.OutPointers) will reflect (contain) the values set by the [[ascript#ascript.Functions.Item.Owner|Function Owner]] object (ascript.Functions.Item().Owner.OutPointers).

=== ParameterList ===
A ParameterList payload only exists if the given [[ascript#ascript.Functions.Item.Owner|Function Owner]] contains one or more parameters. This payload will contain the values of all ParameterList fields at the time the function User called the Owner (on the user side before a call). The ParameterList payload is a [[Dynamic Objects|Dynamic Object]]. This payload will contain all the ParameterList field results after a call (on the owner side after a call).

=== ReturnValue ===
The ReturnValue Payload only exists if the given [[ascript#ascript.Functions.Item.Owner|Function Owner]] returns a value. Functions returning void will not have this property. The ReturnValue payload is a [[Dynamic Objects|Dynamic Object]]. After a call, the ReturnValue payload will contain the return results (on the owner side after a call).

== Synchronous / Asynchronous Interception ==
Function calls that are made between a function [[Ascript#Ascript.Functions.Item.Owner|Owner]] and a function [[Ascript#Ascript.Functions.Item.Owner|User]] will be either asynchronous or synchronous.
 

=== Asynchronous Calls (non-blocking) ===
An asynchronous function call is also known as a "non-blocking" call. This is the type of call that occurs for both CallNonBlocking and CallBypassOverrideNonBlocking.

==== CallBypassOverrideNonBlocking ====
Asynchronously calls the override registered owner of the function (Non-blocking call).
* Invokes call to registered function owner bypassing the registered override owner (if one exists).
* If there is no registered owner but there is an override registered owner, the call is routed to the override registered owner.
* Current values of all fields of the ParameterList property are marshaled to the called function.
* This method returns to the caller immediately. When the function owner (running in a separate thread) returns, an event is placed in this script's queue by the STRIDE Runtime. The event (as a polymorphic object exposing Type and Name properties) is retrieved from the queue using [[Events#WaitForEvent|ascript.WaitForEvent()]].
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].
* The object returned from [[Events#WaitForEvent|WaitForEvent()]] in response to CallByPassOverrideNonBlocking() can be:
{| cellspacing="0" cellpadding="1" width="100%" border="0"
|-
| width="10" |
|  
* The Function User Object corresponding to the function that was called. (Type = "FunctionUser", Name="function name"). The object's ReturnValue property and the OutPointers property (if present) will be populated with the values supplied by the Owner implementation.
* An [[Error Object|Error Object]] containing information about the error that occurred (Type="Error"; Name="error source").
|}

==== CallNonBlocking ====

Asynchronously calls the registered owner of the function (Non-blocking call).
* This call invokes a call to the currently registered owner of the function.
**If there is a registered owner and there is not a registered override owner, the call is routed to the registered owner.
**If there is a registered owner and there is also a registered override owner, the call is routed to the registered override owner.
**If there is no registered owner but there is a registered override owner, the call is routed to the registered override owner.
* The current values of all fields in the ParameterList property are marshaled to the called function.
* This method returns to the caller immediately. When the function owner (running in a separate thread) returns, an event is placed in this script's queue by the STRIDE Runtime. The event (as a polymorphic object exposing Type and Name properties) is retrieved from the queue using ascript.WaitForEvent().
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].
* The object returned from [[Events#WaitForEvent|WaitForEvent()]] in response to CallByPassOverrideNonBlocking() can be:
{| cellspacing="0" cellpadding="1" width="100%" border="0"
|-
| width="10" |
|  
* The Function User Object corresponding to the function that was called. (Type = "FunctionUser", Name="function name"). The object's ReturnValue property and the OutPointers property (if present) will be populated with the values supplied by the Owner implementation.
* An [[Error Object|Error Object]] containing information about the error that occurred (Type="Error"; Name="error source").
|}

=== Synchronous Calls (blocking) ===
A synchronous call is also known as a "blocking" call. Blocking calls a made using the Call or CallBypassOverride methods. These calls are made from the [[Ascript#Ascript.Functions.Item.User|User]].

==== Call ====
Synchronously calls the registered owner of the function (Blocking call).
* All current field values of the ParameterList property are marshaled to the function [[Ascript#Ascript.Functions.Item.Owner|Owner]].
* If there is no registered owner or registered override owner, an exception is thrown.
* If there is no registered owner but there is a registered override owner, the call is routed to the registered override owner.
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].

==== CallBypassOverride ====
Synchronously calls the override registered owner of the function (Blocking call).
* The call is made to the registered owner of the function bypassing any existing registered override owner.
* The current values of all fields in the ParameterList property are marshaled to the called function [[Ascript#Ascript.Functions.Item.Owner|Owner]].
* If there is no registered owner or registered override owner, an exception is thrown.
* If there is no registered owner but there is a registered override owner, the call is routed to the registered override owner.
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].

=== Returns ===
When the callee ([[Ascript#Ascript.Functions.Item.Owner|owner]]) wants to generate a function return, it makes a call to the Return method. This method is used for both synchronous and unsynchronous calls.

Studio:AutoScript Functions

2008-07-31T00:42:32Z

Carriez: /* Call */

__FORCETOC__ 

== Overview ==
This section describes basic functionality for ascript function processing. For ease of understanding, this section describes overall concepts and then describes the precise functionality that STRIDE provides. 

== Function Interception ==
A powerful feature of STRIDE is the ability to intercept function calls. While this capability is known to most seasoned STRIDE users, it is not necessarily as known to STRIDE newbies. Comprehension of general STRIDE terms requires a small amount of knowledge as to what function interception means.
 
STRIDE is generally used to debug remote hardware (e.g. a cellphone) from a Windows computer running STRIDE. The remote hardware is refered to as the target. The Windows computer is refered
to as the host. Scripts are used to communicate with STRIDE to pass data between the host and target.
 
While there are several models for how to connect to host and target and to transfer data inbetween them, this wiki page is only to describe how perform this connectability via ascript. The following issues have to be resolved to communicate between host and target using two scripts:
* Which script owns a particular function (e.g. a script on the target)?
* Which script desires access to the function (e.g. a script on the host)?
* What is types of data (i.e. parameters, pointers, and return value payloads) will be passed between them?
* How will the owner and the user communicate to pass payloads?

The how of questions will be answered in the following sections. The why will depend on a particular testing solution to each distinct type of hardware being developed.

== Ownership vs. Usage ==
STRIDE has the concept of a Function Owner and a Function User. In general STRIDE usage the Owner and User imply the owner of a function on the target and the user of a function on the host.
 

=== Function User ===
A [[ascript#ascript.Functions.Item.User|Function User]] may be any script that is not registered as the function owner or function override owner. The [[ascript#ascript.Functions.Item.User|Function User]] may be access via the message as [[ascript#ascript.Functions.Item.User|ascript.Functions.Item.User]].
 

=== Function Owner ===
The [[ascript#ascript.Functions.Item.Owner|Function Owner]] is the script that has successfully registered itself as the owner of the function (by calling the Register method). A function will only have one registered owner. Calls to register a second owner will result in an exception will be thrown. Ownership can be surrendered by calling the Unregister method (or by exiting the script that registered ownership). The [[ascript#ascript.Functions.Item.Owner|Function Owner]] may be accessed via [[ascript#ascript.Functions.Item.Owner|ascript.Functions.Item.Owner]].
 

=== Override Owner ===
The Function Override Owner of a function is the script that successfully registered as the override owner (using the RegisterOverride method). An override owner is used to bypass the registered owner. If a function has an override owner registered, function calls are made to the registered override owner and not the registered owner. This allows the ability to code scripting with the registered owner, but to bypass the registered owner for certain processing for a variety of reasons (i.e. some code not implemented for the registered owner, some exception cases, etc.). It is legal for a script to declare both forms of function ownership. Thus, the same script may be both registered owner and the registered override owner.
 

== Function Payloads ==
Payloads are [[Dynamic Objects|Dynamic Objects]] containing data related to a function's parameters, a function's return value, or pointer values passed for a function. These payloads are defined as properties for both a [[ascript#ascript.Functions.Item.User|Function User]] and a [[ascript#ascript.Functions.Item.Owner|Function Owner]]. By being part of both user and owner allows their values can be checked for validity in the event that a call did not pass correct data from user to owner (or visa-versa).
 

=== OutPointers ===
This payload exists only if a function's payload has at least one pointer that is qualified as OUT or INOUT. In other words, the function returns an object via a pointer through its parameter list.

If this property exists, its members are comprised of all the top-level parameters that are either OUT or INOUT pointers. This can also exist for structured types (structs or unions) that contain members that are OUT or INOUT. It can also exist if a structured type contains a nested structured type that contains members that are OUT or INOUT. In the case of structured type objects appearing in the OutPointers hierarchy, only members that are qualified as OUT or INOUT (or that themselves contain these qualified types) are available.

Upon a function's return, the OutPointers property of the [[ascript#ascript.Functions.Item.User|Function User]] object (ascript.Functions.Item().User.OutPointers) will reflect (contain) the values set by the [[ascript#ascript.Functions.Item.Owner|Function Owner]] object (ascript.Functions.Item().Owner.OutPointers).

=== ParameterList ===
A ParameterList payload only exists if the given [[ascript#ascript.Functions.Item.Owner|Function Owner]] contains one or more parameters. This payload will contain the values of all ParameterList fields at the time the function User called the Owner (on the user side before a call). The ParameterList payload is a [[Dynamic Objects|Dynamic Object]]. This payload will contain all the ParameterList field results after a call (on the owner side after a call).

=== ReturnValue ===
The ReturnValue Payload only exists if the given [[ascript#ascript.Functions.Item.Owner|Function Owner]] returns a value. Functions returning void will not have this property. The ReturnValue payload is a [[Dynamic Objects|Dynamic Object]]. After a call, the ReturnValue payload will contain the return results (on the owner side after a call).

== Synchronous / Asynchronous Interception ==
Function calls that are made between a function [[Ascript#Ascript.Functions.Item.Owner|Owner]] and a function [[Ascript#Ascript.Functions.Item.Owner|User]] will be either asynchronous or synchronous.
 

=== Asynchronous Calls (non-blocking) ===
An asynchronous function call is also known as a "non-blocking" call. This is the type of call that occurs for both CallNonBlocking and CallBypassOverrideNonBlocking.

==== CallBypassOverrideNonBlocking ====
Asynchronously calls the override registered owner of the function (Non-blocking call).
* Invokes call to registered function owner bypassing the registered override owner (if one exists).
* If there is no registered owner but there is an override registered owner, the call is routed to the override registered owner.
* Current values of all fields of the ParameterList property are marshaled to the called function.
* This method returns to the caller immediately. When the function owner (running in a separate thread) returns, an event is placed in this script's queue by the STRIDE Runtime. The event (as a polymorphic object exposing Type and Name properties) is retrieved from the queue using [[Events#WaitForEvent|ascript.WaitForEvent()]].
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].
* The object returned from [[Events#WaitForEvent|WaitForEvent()]] in response to CallByPassOverrideNonBlocking() can be:
{| cellspacing="0" cellpadding="1" width="100%" border="0"
|-
| width="10" |
|  
* The Function User Object corresponding to the function that was called. (Type = "FunctionUser", Name="function name"). The object's ReturnValue property and the OutPointers property (if present) will be populated with the values supplied by the Owner implementation.
* An [[Error Object|Error Object]] containing information about the error that occurred (Type="Error"; Name="error source").
|}

==== CallNonBlocking ====

Asynchronously calls the registered owner of the function (Non-blocking call).
* This call invokes a call to the currently registered owner of the function.
**If there is a registered owner and there is not an override registered owner, the call is routed to the registered owner.
**If there is a registered owner and there is also an override registered owner, the call is routed to the override registered owner.
**If there is no registered owner but there is an override registered owner, the call is routed to the override registered owner.
* The current values of all fields in the ParameterList property are marshaled to the called function.
* This method returns to the caller immediately. When the function owner (running in a separate thread) returns, an event is placed in this script's queue by the STRIDE Runtime. The event (as a polymorphic object exposing Type and Name properties) is retrieved from the queue using ascript.WaitForEvent().
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].
* The object returned from [[Events#WaitForEvent|WaitForEvent()]] in response to CallByPassOverrideNonBlocking() can be:
{| cellspacing="0" cellpadding="1" width="100%" border="0"
|-
| width="10" |
|  
* The Function User Object corresponding to the function that was called. (Type = "FunctionUser", Name="function name"). The object's ReturnValue property and the OutPointers property (if present) will be populated with the values supplied by the Owner implementation.
* An [[Error Object|Error Object]] containing information about the error that occurred (Type="Error"; Name="error source").
|}

=== Synchronous Calls (blocking) ===
A synchronous call is also known as a "blocking" call. Blocking calls a made using the Call or CallBypassOverride methods. These calls are made from the [[Ascript#Ascript.Functions.Item.User|User]].

==== Call ====
Synchronously calls the registered owner of the function (Blocking call).
* All current field values of the ParameterList property are marshaled to the function [[Ascript#Ascript.Functions.Item.Owner|Owner]].
* If there is no registered owner or registered override owner, an exception is thrown.
* If there is no registered owner but there is a registered override owner, the call is routed to the registered override owner.
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].

==== CallBypassOverride ====
Synchronously calls the override registered owner of the function (Blocking call).
* The call is made to the registered owner of the function bypassing any existing registered override owner.
* The current values of all fields in the ParameterList property are marshaled to the called function [[Ascript#Ascript.Functions.Item.Owner|Owner]].
* If there is no registered owner or registered override owner, an exception is thrown.
* If there is no registered owner but there is a registered override owner, the call is routed to the registered override owner.
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].

=== Returns ===
When the callee ([[Ascript#Ascript.Functions.Item.Owner|owner]]) wants to generate a function return, it makes a call to the Return method. This method is used for both synchronous and unsynchronous calls.

Studio:AutoScript

2008-07-31T00:14:58Z

Carriez: /* ascript.Functions.Item.Owner */

__FORCETOC__ 

= Introduction  =

Ascript is the definitive hierarchy of methods, objects, and properties provided by Autosense. While Autosense helps the user find the script methods/data desired in a script, Ascript is the definitive source of what is available from STRIDE when using Autosense.

The ascript object provides functionality that allows host-based scripts to interact with target-based binaries through the STRIDE Runtime. Through ascript, you can:

*call target-based functions and messages (synchronously or asynchronously)
*set and read parameter values of these functions and messages
*transparently emulate (mock) target-based functions

= Ascript Wiki Pages =
* [[Ascript#Introduction|Ascript]]
* [[Dynamic Objects|Dynamic Objects]]
* [[Events|Events]]
* [[Functions|Functions]]
* [[Messaging|Messaging]]
* [[Timeout Considerations|Timeout Considerations]]

= Ascript Automation Usage =

Ascript is used to access STRIDE functionality within JScript or Perl. When creating a script, the user types in 'ascript' followed by dot '.' to get Autosense to display (see below).

[[Image:Ascriptpopup.jpg]]

The user may select methods to be used within his script. The user may access property data within his script. Other data elements may be accessed using the Ascript API.

= Ascript API =
The ascript object is the top-most object when accessing methods and properties related to Ascript. The following table describes what is available from the ascript object. Other nested properties and methods may be found under the ascript object.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="250" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| [[#ascript.Arguments|Arguments]]
| Collection
| Collection of arguments.
|-
| [[#ascript.Constants|Constants]]
| Collection
| Collection of constants.
|-
| [[#ascript.Database|Database]]
| valign="top" align="left" width="150" | Object 
| Database settings.
|-
| [[#ascript.Functions|Functions]]
| Collection
| Collection of functions.
|-
| void '''Initialize ('''    String STIDName,    String databaseFile,    int MessageBoxTimeout [optional] ''')'''
| Method
| Initializes and ascript object instance that has been created outside of the STRIDE Studio environment. This call is needed only on an explicitly-created ascript instance. This call should not be made on an ascript instance automatically created and injected into a script by STRIDE Studio.
|-
| IsEventPending
| Property, '''Read-only''', boolean
| Contains true if there is at least one event in this script's message queue. Events are retrieved from the queue using the [[Events#WaitForEvent|WaitForEvent]] method (ascript.WaitForEvent()).
|-
| LogicalPath
| Property, '''Read-only''', String
| Contains the script's path in the STRIDE Studio workspace tree.
|-
| String '''MessageBox('''     String Message,    String Title [optional],     String Type ''')'''
| Method
| Displays a model message box dialog.
 
Acceptable strings for type include:
* "OK"
* "OKCANCEL"
* "RETRYCANCEL"
* "YESNO"
* "YESNOCANCEL"
 
Returns a string indicating the action used to dismiss the message box. Strings returned include:
* "ABORT"
* "CANCEL"
* "IGNORE"
* "YES"
* "NO"
* "OK"
|-
| [[ascript.Messages|Messages]]
| Collection
| Collection of messages.
|-
| Output
| Property, (String, Integer, or Object)
| This is the return value from a RunBlocking() call that invoked this script. This works only when the script is invoked using RunBlocking() in the studio object model.
|-
| RspTimeoutPeriod
| Property, int
| This value controls the timeout threshold for synchronous function and two-way message calls (in milliseconds). A zero value indicates no timeout. For interactively run scripts the timeout behavior may be different. Specific calls affected by this value are:
* Call
* CallBypassOverride
* SendAndRead
* SendAndReadBypassOverride
|-
| ScriptName
| Property, '''Read-only''', String
| Contains the name of the currently running script with extension and without path. If the current ascript instance was instantiated and initialized outside of STRIDE Studio, this value will reflect the STIDName passed to ascript.Initialize().
|-
| void '''Sleep('''    int Period ''')'''
| Method
| Time to pause (in milliseconds). Allowable range is 0 -1440000 (24 hours).
|-
| [[#ascript.TestUnits|Test Units]]
| Collection
| Collection of test units.
|-
| [[#ascript.Timers|Timers]]
| Collection
| Collection of timers.
|-
| [[Events#WaitForEvent|Event]] '''WaitForEvent ( void )'''
| Method
| Pauses script execution until an event is detected in this script's event queue. See [[Events#WaitForEvent|WaitForEvent]] for more information on this method.
|-
| WaitTimeoutPeriod
| Property, String
| The timeout threshold (in milliseconds) for asynchronous function and message calls. A zero value indicates no timeout.
|}

 

== ascript.Arguments ==

The Arguments collection manages a list of [[#ascript.Arguments.Item|Arguments]] passed to a script which has been invoked via one of the following methods of the Studio Object Model's File object:
 
* RunBlocking([arg1], [arg2], ...)
* RunNonBlocking([arg1], [arg2], ...)
 
The default sort order of the member argument objects is the order in which the arguments were given in the call where the script was invoked.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" | Count
| valign="top" | Property, '''Read-only''', int
| valign="top" | Returns the number of Arguments in this collection. 
|-
| valign="top" align="left" width="150" |
[[#ascript.Arguments.Item|Argument]] '''Item''' (     int Index ''')'''

| valign="top" | Method 
| valign="top" | Retrieves the argument at the given index. An exception is thrown if the index is out of range. 
|-
| valign="top" align="left" width="150" |
[[#ascript.Arguments.Item|Argument]] '''Item''' (     String Name ''')'''

| valign="top" | Method 
| valign="top" | Retrieves the argument with the given name. If a named argument doesn't exist, null is returned. 
 

|}

=== ascript.Arguments.Item ===

The ascript [[#ascript.Arguments|Arguments]] Collection's Item() method returns an Argument Object.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" align="left" width="150" | Name
| valign="top" align="left" | Property, '''Read-only''', String
| valign="top" align="left" |
The argument name. The name may have been specified in the studio automation RunBlocking() or RunNonBlocking() call that launched the script or if not specified the name is synthesized by the ascript object.

When synthesized, the name is of the form "Unnamed_N" where 'N' is a monotonically incremented number starting from 0.

|-
| valign="top" align="left" width="150" | Value 
| valign="top" align="left" | Property, '''Read-only''', String, Integer, or Object
| valign="top" align="left" | The argument value.
|}

 

== ascript.Constants ==

The Constants collection contains [[#ascript.Constants.Item|Constants]] objects that represent all constants in C/C++ source code compiled by the STRIDE compiler. Constants include all #define symbols and enumerated constants.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" | '''void ArrangeBy ('''    String By [optional],    String Order [optional] ''')'''
| valign="top" | Method
| valign="top" | Sorts the Constants collection so that indexing by position yields predictable results. The 'By' parameter may only be "Name". If not specified, the default is "Name". This represents how Constants should be sorted in the collection. The 'Order' parameter may be either "Ascending" or "Descending". If not specified, the default is "Ascending". Exception thrown if either argument is outside legal values.
|-
| valign="top" | Count
| valign="top" | Property, '''Read-only''', int
| valign="top" | Returns the number of Constants in this collection. 
|-
| valign="top" align="left" width="150" |
[[#ascript.Constants.Item|Constant]] '''Item''' (     int Index ''')'''

| valign="top" | Method 
| valign="top" | Retrieves the constant at the given index. An exception is thrown if the index is out of range. 
|-
| valign="top" align="left" width="150" |
[[#ascript.Constants.Item|Constant]] '''Item''' (     String Name ''')'''

| valign="top" | Method 
| valign="top" | Retrieves the constant with the given name. If a named constant doesn't exist, null is returned. 
 

|}

 

=== ascript.Constants.Item ===

The ascript [[#ascript.Constants|Constants]] Collection's Item() method returns a Constant object.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" align="left" width="150" | Name
| valign="top" align="left" | Property, '''Read-only''', String
| valign="top" align="left" | The name of the constant.
|-
| valign="top" align="left" width="150" | Value
| valign="top" align="left" | Property, '''Read-only''', String
| valign="top" align="left" | The value of the constant.
|}

 

== ascript.Database ==

The Database object represents the currently-loaded STRIDE database managed by ascript. You can combine the values of the database path and name to construct a fully-qualified filename. For example:

var dbFullPath = ascript.Database.Path + "\\" + ascript.Database.Name;

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" | Name
| valign="top" | Property, '''Read-only''', String
| valign="top" | The name of the database in use. The database name includes the ".sidb" extension.
|-
| valign="top" | Path 
| valign="top" | Property, '''Read-only''', String
| valign="top" | The path to the STRIDE database in use. The path does not contain a trailing backslash. 
|}

 

== ascript.Functions ==

The Functions collection represents all captured [[#ascript.Functions.Item|Function]] interfaces in the active database.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" | '''void ArrangeBy ('''    String By [optional],    String Order [optional] ''')'''
| valign="top" | Method
| valign="top" | Sorts the Functions collection so that indexing by position yields predictable results. The 'By' parameter may be either "Name" or "SUID". If not specified, the default is "Name". This represents how Functions should be sorted in the collection. The 'Order' parameter may be either "Ascending" or "Descending". If not specified, the default is "Ascending". Exception thrown if either argument is outside legal values.
|-
| valign="top" | Count
| valign="top" | Property, '''Read-only''', int
| valign="top" | Returns the number of Functions in this collection. 
|-
| valign="top" align="left" width="150" |
[[#ascript.Functions.Item|Function]] '''Item''' (     int Index ''')'''
| valign="top" | Method 
| valign="top" | Retrieves the function at the given index. An exception is thrown if the index is out of range. 
|-
| valign="top" align="left" width="150" |
[[#ascript.Functions.Item|Function]] '''Item''' (   String Name ''')'''
| valign="top" | Method 
| valign="top" | Retrieves the function with the given name. A null value is returned if there is no function with the given name. 
|}

=== ascript.Functions.Item ===

The Function object represents a captured function interface in the currently active STRIDE database. A Function object always exists as a member of the [[#ascript.Functions|Functions]] collection.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| Name
| Property, '''Read-only''', boolean
| Function's name.
|-
| [[#ascript.Functions.Item.Owner|Owner]]
| Property, '''Read-only''', Object
| Function's owner object. The owner object provides access to properties and methods used by the owner-side of the function interface. The owner-side of the interface is used by the implementor of the function.
|-
| SUID
| Property, '''Read-Only''', int
| STRIDE Unique IDentifier assigned by compiler.
|-
| Type
| Property, '''Read-Only''', String
| Contains the string "Function".
|-
| [[#ascript.Functions.Item.User|User]]
| Property '''Read-Only''', Object
| Function's user object. The user object provides access to properties and methods used by the user-side of the function interface. The user-side of the interface is used by the caller of the function.
|}

 

==== ascript.Functions.Item.Owner ====
The Function Owner object represents the Owner (callee) side of a function. The Owner object is used to implement a function in script that can be called through the STRIDE Runtime. The Function Owner object is reachable from a [[#ascript.Functions.Item|Function]] object's owner property.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="200" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| IsOverrideRegistered
| Property, '''Read-Only''', boolean
| Contains true if there is a registered override owner. See [[Functions#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| IsRegistered
| Property, '''Read-only''', boolean
| Contains true if there is a registered owner, a registered override owner, or both. See [[Functions#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| Name
| Property, '''Read-only''', String
| Owner name.
|-
| [[Functions#OutPointers|OutPointers]]
| Property, '''Read-only''', Object
| Contains the [[Functions#OutPointers|OutPointers]] payload of the Function User object. See [[Functions#Function Payloads|Function Payloads]] for more information.
|-
| [[Functions#ParameterList|ParameterList]]
| Property, '''Read-only''', Object
| Contains the object representing the [[Functions#ParameterList|ParameterList]] payload of the Function Owner. Functions without parameters will not have this property. Before calling the function, all relevent fields in the ParameterList property must be set (includeing the fields of any child objects). These values are marshaled to the currently registered Owner of the function when it is called. This property is a [[Dynamic Objects|Dynamic Object]]. See [[Functions#Function Payloads|Function Payloads]] for more information.
|-
| '''void Register (void)'''
| Method
| Registers the script from which it is called as the active owner of the function. If there is a currently registered owner or another registration failure, an exception is thrown. See [[Functions#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| '''void RegisterOverride (void)'''
| Method
| Registers the script as the override registered owner. If the function already has an override registered owner or if there is another registration error, an exception is thrown. See [[Functions#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| '''void Return ()'''
| Method
| Causes a return from a function call made from another script. See [[Functions#Returns|Return]] for more information. The values of OutPointers and ReturnValue will be reflected to the caller (as long as they are consistent with the input values).
|-
| [[Functions#ReturnValue|ReturnValue]]
| Property, '''Read-only''', Integer
| Contains the object representing the [[Functions#ReturnValue|ReturnValue]] payload of the Function Owner. Functions returning void will not have this property. Upon return this property will reflect the ReturnValue set by the function Owner. This property is a [[Dynamic Objects|Dynamic Object]]. See [[Functions#Function Payloads|Function Payloads]] for more information.
|-
| SUID
| Property, '''Read-only''', int
| STRIDE-unique identifier assigned by compiler.
|-
| Type
| Property, '''Read-only''', String
| Contains "FunctionOwner".
|-
| '''void Unregister (void)'''
| Method
| Unregisters the script that was registered as the owner of the function from a prior Register call. If the current script is not the owner or if unregistration fails, an exception is thrown. See [[Functions#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| '''void UnregisterOverride (void)'''
| Method
| Unregisters the script that was registered as the override owner of the function from a prior RegisterOverride call. If the current script is not the registered override owner or if unregistration fails, an exception is thrown. See [[Functions#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|}

 

==== ascript.Functions.Item.User ====
The Function User object represents the User (caller) side of a function. The User object is used to call a function through the STRIDE Runtime. The Function User object is reachable from a [[#ascript.Functions.Item|Function]] object's User property.
{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="280" bgcolor="#66ff99" | '''Member''' 
| width="90" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| '''void Call (void)'''
| Method
| Synchronously calls the registered owner of the function (Blocking call). See [[Functions#Synchronous Calls (blocking)|Synchronous Calls]] for more information.
|-
| '''void CallBypassOverride (void)'''
| Method
| Synchronously calls the registered owner bypassing the registered override owner of the function (Blocking call). See [[Functions#Synchronous Calls (blocking)|Synchronous Calls]] for more information.
|-
| '''void CallBypassOverrideNonBlocking (void)'''
| Method
| Asynchronously calls the registered owner bypassing the registered override owner of the function (Non-blocking call). See [[Functions#Asynchronous Calls (non-blocking)|Asynchronous Calls]] for more information.
|-
| '''void CallNonBlocking (void)'''
| Method
| Asynchronously calls the registered owner of the function (Non-blocking call). See [[Functions#Asynchronous Calls (non-blocking)|Asynchronous Calls]] for more information.
|-
| IsOverrideRegistered
| Property, '''Read-only''', boolean
| Contains true if there is a registered override owner. See [[Functions#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| IsRegistered
| Property, '''Read-only''', boolean
| Contains true if there is a registered owner, a registered override owner, or both. See [[Functions#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| Name
| Property, '''Read-only''', String
| User function name.
|-
| [[Functions#OutPointers|OutPointers]]
| Property, '''Read-only''', Object
| Contains the [[Functions#OutPointers|OutPointers]] payload of the Function User object. See [[Functions#Function Payloads|Function Payloads]] for more information.
|-
| [[Functions#ParameterList|ParameterList]]
| Property, '''Read-only''', Object
| Contains the object representing the [[Functions#ParameterList|ParameterList]] payload of the Function Owner. Functions without parameters will not have this property. Before calling the function, all relevent fields in the ParameterList property must be set (includeing the fields of any child objects). These values are marshaled to the currently registered Owner of the function when it is called. This property is a [[Dynamic Objects|Dynamic Object]]. See [[Functions#Function Payloads|Function Payloads]] for more information.
|-
| [[Functions#ReturnValue|ReturnValue]]
| Property, '''Read-only''', Object
| Contains the object representing the [[Functions#ReturnValue|ReturnValue]] payload of the Function Owner. Functions returning void will not have this property. Upon return this property will reflect the ReturnValue set by the function Owner. This property is a [[Dynamic Objects|Dynamic Object]]. See [[Functions#Function Payloads|Function Payloads]] for more information.
|-
| SUID
| Property, '''Read-only''', ,int
| STRIDE-unique identifier assigned by compiler.
|-
| Type
| Property, '''Read-only''', String
| Contains "FunctionUser". This property is typically used to classify an object that is returned from [[Events#WaitForEvent|WaitForEvent]].
|}

 

== ascript.Messages ==

The Messages Collection is a collection of captured [[#ascript.Messages.Item|Message]] objects. 

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" | '''void ArrangeBy ('''    String By [optional],    String Order [optional] ''')'''
| valign="top" | Method
| valign="top" | Sorts the Messages collection so that indexing by position yields predictable results. The 'By' parameter may one of the following: "Name", "SMID", "SUID", "Type". The default sorting order is by "Name". This represents how Timers should be sorted in the collection. A runtime exception is thrown if an invalid value is passed The 'Order' parameter may be either "Ascending" or "Descending" and is not case sensitive. If not specified, the default is "Ascending". A runtime exception is thrown if a invalid value is passed.
|-
| valign="top" | Count
| valign="top" | Property, '''Read-only''', int
| valign="top" | Returns the number of Messages in this collection. 
|-
| valign="top" align="left" width="150" |
[[#ascript.Messages.Item|Message]] '''Item '''(     int Index )

| valign="top" | Method 
| valign="top" | Retrieves the message at the given index. 
|-
| valign="top" align="left" width="150" |
[[#ascript.Messages.Item|Message]] '''Item '''(     String Name )

| valign="top" | Method 
| valign="top" | Retrieves the message with the given name. 
|}

 

=== ascript.Messages.Item ===

The Message object represents a captured message interface in the currently active STRIDE database. A Message object is always a member of the [[#ascript.Messages|Messages]] collection.
{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="120" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| Name
| Property, '''Read-only''', String
| Message name.
|-
| [[#ascript.Messages.Item.Owner|Owner]]
| Property, '''Read-only''', Object
| Message's owner object.
|-
| SUID
| Property, '''Read-only''', int
| STRIDE Unique Identifier assigned by compiler.
|-
| Type
| Property, '''Read-only''', String
| Contains message type defined by the SCL declaration. Legal values include:
* "OneWayMessage"
* "OneWayResponse"
* "TwoWayMessage"
* "BroadcastMessage"
|-
| [[#ascript.Messages.Item.User|User]]
| Property, '''Read-only''', Object
| Message's user object.
|}

 

==== ascript.Messages.Item.Owner ====

The Message Owner object represents the Owner-side of a [[#ascript.Messages.Item|Message]]. This may be a receiver of a one-way or two-way message. It may also be the broadcaster of a broadcast message. The Owner object may be used to implement the message owner in a script that can be called through the STRIDE Runtime. 
This object allows access to the message destination. The message can be routed to any of the following:
 
* the original on-target receiver
* a window in STRIDE Studio
* a script running in Studio
 
{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="210" bgcolor="#66ff99" | '''Member''' 
| width="80" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| '''void Broadcast (void)'''
| Method
| Broadcast method exists only for Broadcast Messages. This method broadcasts this message to all message users that have subscribed to this message. The Response payload values are marshaled to all subscribed message users. See [[Messaging#Broadcast Messaging|Broadcast Messaging]] for more information.
|-
| [[Dynamic Objects|Command]]
| Property, '''Read-only''', Object
| This property is a [[Dynamic Objects|Dynamic Object]] representing the Command payload of the Message Owner. The property exists only if the captured message took one or more parameters. The property contains all the values of the Message User Command fields at the time that the message User called the Owner. See [[Messaging#Message Payloads|Message Payloads]] for more information.
|-
| IsOverrideRegistered
| Property, '''Read-only''', boolean
| Contains the override Owner registration state of the message. True only if there is a registered override owner. See [[Messaging#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| IsRegistered
| Property, '''Read-only''', boolean
| Contains the Owner registration state of the message. True only if there is a registered owner, a registered override owner, or both. See [[Messaging#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| Name
| Property, '''Read-only''', String
| Contains Message name.
|-
| '''void Register (void)'''
| Method
| This method only exists for One-Way Command or Two-Way Messages. The calling script is registered as the active owner of the message. If there is already a registered owner or if there is some other registration failure, an exception is thrown. See [[Messaging#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| '''void RegisterOverride (void)'''
| Method
| This method only for One-Way Command or Two-Way Messages. The calling script is registered as the registered override owner (such that all future messages are routed to this owner over and above the registered owner). If there is already an override owner or if there is another registration failure, an exception is thrown. See [[Messaging#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| [[Dynamic Objects|Response]]
| Property, '''Read-only''', Object
| This property is a [[Dynamic Objects|Dynamic Object]] representing the Response payload of the Message Owner. The property exists only if the message is defined with a response payload. See [[Messaging#Message Payloads|Message Payloads]] for more information.
|-
| '''void SendRsp (void)'''
| Method
| Send response method exists only for One-Way Response or Two-Way Messages. The method sends the message as a response to a prior message command from a message user. If there is not pending message response expected an exception is thrown. After setting values of the response payload, a script that implements an Owner message calls SendRsp() to reply to an earlier two-way message (or one-way response). The effect of this call on the calling (User) script depends on how the earlier user message was sent. See [[Messaging#Point-to-Point Messaging|Point-to-Point Messaging]] for more information.
|-
| SUID
| Property, '''Read-only''', int
| STRIDE Unique Identifier assigned by compiler.
|-
| Type
| Property, '''Read-only''', String
| Contains message type defined by the SCL declaration. Legal values include:
* "OneWayMessage"
* "OneWayResponse"
* "TwoWayMessage"
* "BroadcastMessage"
|-
| '''void Unregister (void)'''
| Method
| This method only exists for One-Way Command or Two-Way Messages. This method unregisters the current script as the owner of the message. If the current script is not the registered owner or if unregistration fails, an exception is thrown. See [[Messaging#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| '''void UnregisterOverride (void)'''
| Method
| This method exists only for One-Way Command or Two-Way Messages. This method unregisters the current script as registered override owner. If the current script is not the registered override owner or if registration fails, an exception is thrown. See [[Messaging#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|}

 

==== ascript.Messages.Item.User ====
The Message User object represents the User-side of a [[#ascript.Messages.Item|Message]]. This may be a sender of a one-way or two-way message. It may also be the receiver of a broadcast message. The User object may be used to send a message from a script to the registered message owner through the STRIDE Runtime. 

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="240" bgcolor="#66ff99" | '''Member''' 
| width="90" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| [[Dynamic Objects|Command]]
| Property, '''Read-only''', Object
| This property is a [[Dynamic Objects|Dynamic Object]] representing the Command payload of the Message User. The property exists only if the captured message took one or more parameters. The values of all Message User Command payload fields should be set before the Message Owner is called. See [[Messaging#Message Payloads|Message Payloads]] for more information.
|-
| IsOverrideRegistered
| Property, '''Read-only''', boolean
| Contains the override Owner registration state of the message. True only if there is a registered override owner. See [[Messaging#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| IsRegistered
| Property, '''Read-only''', boolean
| Contains the Owner registration state of the message. True only if there is a registered owner, a registered override owner, or both. See [[Messaging#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| Name
| Property, '''Read-only''', String
| Contains Message name.
|-
| [[Dynamic Objects|Response]]
| Property, '''Read-only''', Object
| This property is a [[Dynamic Objects|Dynamic Object]] representing the Response payload of the Message User. The property exists only if the message is defined with a response payload. See [[Messaging#Message Payloads|Message Payloads]] for more information.
|-
| '''void SendAndRead ('''   boolean Value ''')'''
| Method
| This method exists only for Two-Way Messages. See [[Messaging#Two-Way Messaging|Two-Way Messaging]] for more information.
|-
| '''void SendAndReadBypassOverride ('''   boolean Value ''')'''
| Method
| This method exists only for Two-Way Messages. See [[Messaging#Two-Way Messaging|Two-Way Messaging]] for more information.
|-
| '''void SendCmd (void)'''
| Method
| This method exists only for Two-Way and One-Way Command Messages. See [[Messaging#Two-Way Messaging|Two-Way Messaging]] and [[Messaging#One-Way Messaging|One-Way Messaging]] for more information.
|-
| '''void SendCmdBypassOverride ('''    boolean Value ''')'''
| Method
| This method exists only for Two-Way and One-Way Command Messages. See [[Messaging#Two-Way Messaging|Two-Way Messaging]] and [[Messaging#One-Way Messaging|One-Way Messaging]] for more information.
|-
| '''void Subscribe (void)'''
| Method
| This method exists only for Broadcast Messages. This method subscribes this message owner to receive message broadcasts from the given message. See [[Messaging#Broadcast Messaging|Broadcast Messaging]] for more information.
|-
| SUID
| Property, '''Read-only''', int
| STRIDE Unique Identifier assigned by compiler.
|-
| Type
| Property, '''Read-only''', String
| Contains message type defined by the SCL declaration. Legal values include:
* "OneWayMessage"
* "OneWayResponse"
* "TwoWayMessage"
* "BroadcastMessage"
|-
| '''void Unsubscribe (void)'''
| Method
| Unsubscribe method exists only for Broadcast Messages. This method unsubscribes this message owner from given message's broadcasts. See [[Messaging#Broadcast Messaging|Broadcast Messaging]] for more information.

|}

== ascript.TestUnits ==

TestUnits is a collection of [[#ascript.TestUnits.Item|TestUnit]] Objects contained and managed through ascript.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" | '''void ArrangeBy ('''    String By [optional],    String Order [optional] ''')'''
| valign="top" | Method
| valign="top" | Sorts the Test Units collection so that indexing by position yields predictable results. The 'By' parameter may be either "Name" or "SUID". If not specified, the default is "Name". This represents how Test Units should be sorted in the collection. The 'Order' parameter may be either "Ascending" or "Descending". If not specified, the default is "Ascending". Exception thrown if either argument is outside legal values.
|-
| valign="top" | Count
| valign="top" | Property, '''Read-only''', int
| valign="top" | Returns the number of Test Units in this collection. 
|-
| valign="top" align="left" width="150" |
[[#ascript.TestUnits.Item|TestUnit]] '''Item '''(     int Index ''')'''

| valign="top" | Method 
| valign="top" | Retrieves the test unit at the given index. 
|}

 

=== ascript.TestUnits.Item ===

The TestUnit Object represents a captured Test Unit interface in the currently active STRIDE database. A Test Unit object always exists as a member of the [[#ascript.TestUnits|TestUnits]] collection and is accessed from the collection using the item(#) interface.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" align="left" width="150" | Arguments
| valign="top" align="left" | Object
| valign="top" align="left" | Contains the Test Unit's parameter list payload.
|-
| valign="top" align="left" width="150" | IsRegistered
| valign="top" align="left" | Property, '''Read-only''', boolean
| valign="top" align="left" | Contains true if the Test Unit owner has registered on the target side.
|-
| valign="top" align="left" width="150" | Name
| valign="top" align="left" | Property, '''Read-only''', String
| valign="top" align="left" | Test Unit name.
|-
| valign="top" align="left" width="150" | '''void Run (void)''' 
| valign="top" align="left" | Method
| valign="top" align="left" | Method to run the test unit. Calling this method will run the test unit in a blocking call until the test unit completes processing.
|-
| valign="top" align="left" width="150" | [[Reporter#reporter.Suites.Item|Suite]]
| valign="top" align="left" | Property, Object
| valign="top" align="left" | An object of type Reporter's [[Reporter#reporter.Suites.Item|Suite]]. By default after a run this object is a sub-Suite of ascript.TestSuite with the same name as the Test Unit (null if no reporting performed). Setting Suite to a concrete external TestSuite prior to execution will override default creation behavior (set to null to revert to default behavior).
|-
| valign="top" align="left" width="150" | Summary
| valign="top" align="left" | Property, int
| valign="top" align="left" | Contains static payload object of type srTestCaseTotals_t with one of the following:
* srTEST_PASS
* srTEST_FAIL
* srTEST_NOTINUSE
* srTEST_INPROGRESS
|-
| valign="top" align="left" width="150" | Type
| valign="top" align="left" | Property, '''Read-only''', String
| valign="top" align="left" | Contains test unit type:
* "TestClass"
* "TestCClass"
* "TestFList"
|}

 

== ascript.Timers ==

The Timers collection manages a set of [[#ascript.Timers.Item|Timer]] Objects. The Timers allow scripts to generate periodic or 'one-shot' timed events. Upon creation, the Timers collection is empty. The Timers collection is the only read/write collection in STRIDE; member Timer objects can be added (implicitly created) and removed by scripts. From the collection's point of view, member Timers have two states: dead and alive. Timers are alive upon creation and remain so as long as they exist in the collection. A Timer object that is removed from the collection is considered dead. Any operation on a dead timer will cause an exception to be thrown. 

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" align="left" width="150" | [[#ascript.Timers.Item|Timer]] '''Add''' (     String Name ''')'''
| valign="top" align="left" | Method 
| valign="top" align="left" | Creates and adds a new timer object with the given name. Returns the new Timer object. An exception is thrown if a Timer was already created with the given name.
|-
| valign="top" | '''void ArrangeBy ('''    String By [optional],    String Order [optional] ''')'''
| valign="top" | Method
| valign="top" | Sorts the Timers collection so that indexing by position yields predictable results. The 'By' parameter may only be "Name". If not specified, the default is "Name". This represents how Timers should be sorted in the collection. The 'Order' parameter may be either "Ascending" or "Descending". If not specified, the default is "Ascending". An exception is thrown if either argument is outside legal values.
|-
| valign="top" | Count
| valign="top" | Property, '''Read-only''', int
| valign="top" | Returns the number of Timers in this collection. 
|-
| valign="top" align="left" width="150" | [[#ascript.Timers.Item|Timer]] '''Item ( '''    int Index ''')'''
| valign="top" align="left" | Method 
| valign="top" align="left" | Retrieves the Timer object for the given index.
|-
| valign="top" align="left" width="150" | [[#ascript.Timers.Item|Timer]] '''Remove ('''     int Index ''')'''
| valign="top" | Method 
| valign="top" | Removes the timer at the given index. A timer object that is removed from the collection is automatically stopped before removal if it is active. No event is generated in this case.
|}

 

=== ascript.Timers.Item ===

The ascript [[#ascript.Timers|Timers]] Collection's Item() method returns a Timer Object. The Timer object enables scripting clients to synthesize and receive timer-based periodic or one-shot events. 

When a timer expires and rires its event, the event is queued and can be accessed by the [[Events#WaitForEvent|WaitForEvent]] method. The expired timer object will be returned by WaitForEvent. 

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" align="left" width="150" | Active
| valign="top" align="left" | Property, '''Read-only,''' boolean
| valign="top" align="left" | Contains timer operation state. True if timer is in operation (i.e. it will generate an event at some time in the future). A newly created timer is inactive by default.
|-
| valign="top" align="left" width="150" | Duration
| valign="top" align="left" | Property, int
| valign="top" align="left" | Timer duration in milliseconds.
|-
| valign="top" align="left" width="150" | Id
| valign="top" align="left" | Property, '''Read-only,''' int
| valign="top" align="left" | Contains timer identifier.
|-
| valign="top" align="left" width="150" | Name
| valign="top" align="left" | Property, '''Read-only''', String
| valign="top" align="left" | Name assigned when the timer was created. Default names are "Timer_n" where 'n' is the nth named time created by this ascript object.
|-
| valign="top" align="left" width="150" | Periodic
| valign="top" align="left" | Property, boolean 
| valign="top" align="left" | When false, the time will fire only once (one-shot mode). When true, the time automatically restarts after each event is fired. This property can be changed regardless of the state of the timer. This field is false by default when a timer is created. 
|-
| valign="top" align="left" width="150" | '''void Start (void)'''
| valign="top" align="left" | Method 
| valign="top" align="left" | Transitions an inactive timer to active. Once started, the timer will run for the length of time specified by its Duration property. Calling Start on a timer with a zero/negative duration will cause an exception to be thrown. Calling Start on a timer that has already started will also cause an exception to be thrown.
|-
| valign="top" align="left" width="150" | '''void Stop (void)'''
| valign="top" align="left" | Method 
| valign="top" align="left" | Transitions an active timer to inactive. Calling Stop on a timer that is not active will cause an exception to be thrown.
|-
| valign="top" align="left" width="150" | Type
| valign="top" align="left" | Property, '''Read-only''', String
| valign="top" align="left" | Contains the string "Timer". This property is typically used to classify an object that is returned from the [[Events#WaitForEvent|WaitForEvent]] method.
|}

Studio:AutoScript Functions

2008-07-30T23:46:14Z

Carriez: /* CallNonBlocking */

__FORCETOC__ 

== Overview ==
This section describes basic functionality for ascript function processing. For ease of understanding, this section describes overall concepts and then describes the precise functionality that STRIDE provides. 

== Function Interception ==
A powerful feature of STRIDE is the ability to intercept function calls. While this capability is known to most seasoned STRIDE users, it is not necessarily as known to STRIDE newbies. Comprehension of general STRIDE terms requires a small amount of knowledge as to what function interception means.
 
STRIDE is generally used to debug remote hardware (e.g. a cellphone) from a Windows computer running STRIDE. The remote hardware is refered to as the target. The Windows computer is refered
to as the host. Scripts are used to communicate with STRIDE to pass data between the host and target.
 
While there are several models for how to connect to host and target and to transfer data inbetween them, this wiki page is only to describe how perform this connectability via ascript. The following issues have to be resolved to communicate between host and target using two scripts:
* Which script owns a particular function (e.g. a script on the target)?
* Which script desires access to the function (e.g. a script on the host)?
* What is types of data (i.e. parameters, pointers, and return value payloads) will be passed between them?
* How will the owner and the user communicate to pass payloads?

The how of questions will be answered in the following sections. The why will depend on a particular testing solution to each distinct type of hardware being developed.

== Ownership vs. Usage ==
STRIDE has the concept of a Function Owner and a Function User. In general STRIDE usage the Owner and User imply the owner of a function on the target and the user of a function on the host.
 

=== Function User ===
A [[ascript#ascript.Functions.Item.User|Function User]] may be any script that is not registered as the function owner or function override owner. The [[ascript#ascript.Functions.Item.User|Function User]] may be access via the message as [[ascript#ascript.Functions.Item.User|ascript.Functions.Item.User]].
 

=== Function Owner ===
The [[ascript#ascript.Functions.Item.Owner|Function Owner]] is the script that has successfully registered itself as the owner of the function (by calling the Register method). A function will only have one registered owner. Calls to register a second owner will result in an exception will be thrown. Ownership can be surrendered by calling the Unregister method (or by exiting the script that registered ownership). The [[ascript#ascript.Functions.Item.Owner|Function Owner]] may be accessed via [[ascript#ascript.Functions.Item.Owner|ascript.Functions.Item.Owner]].
 

=== Override Owner ===
The Function Override Owner of a function is the script that successfully registered as the override owner (using the RegisterOverride method). An override owner is used to bypass the registered owner. If a function has an override owner registered, function calls are made to the registered override owner and not the registered owner. This allows the ability to code scripting with the registered owner, but to bypass the registered owner for certain processing for a variety of reasons (i.e. some code not implemented for the registered owner, some exception cases, etc.). It is legal for a script to declare both forms of function ownership. Thus, the same script may be both registered owner and the registered override owner.
 

== Function Payloads ==
Payloads are [[Dynamic Objects|Dynamic Objects]] containing data related to a function's parameters, a function's return value, or pointer values passed for a function. These payloads are defined as properties for both a [[ascript#ascript.Functions.Item.User|Function User]] and a [[ascript#ascript.Functions.Item.Owner|Function Owner]]. By being part of both user and owner allows their values can be checked for validity in the event that a call did not pass correct data from user to owner (or visa-versa).
 

=== OutPointers ===
This payload exists only if a function's payload has at least one pointer that is qualified as OUT or INOUT. In other words, the function returns an object via a pointer through its parameter list.

If this property exists, its members are comprised of all the top-level parameters that are either OUT or INOUT pointers. This can also exist for structured types (structs or unions) that contain members that are OUT or INOUT. It can also exist if a structured type contains a nested structured type that contains members that are OUT or INOUT. In the case of structured type objects appearing in the OutPointers hierarchy, only members that are qualified as OUT or INOUT (or that themselves contain these qualified types) are available.

Upon a function's return, the OutPointers property of the [[ascript#ascript.Functions.Item.User|Function User]] object (ascript.Functions.Item().User.OutPointers) will reflect (contain) the values set by the [[ascript#ascript.Functions.Item.Owner|Function Owner]] object (ascript.Functions.Item().Owner.OutPointers).

=== ParameterList ===
A ParameterList payload only exists if the given [[ascript#ascript.Functions.Item.Owner|Function Owner]] contains one or more parameters. This payload will contain the values of all ParameterList fields at the time the function User called the Owner (on the user side before a call). The ParameterList payload is a [[Dynamic Objects|Dynamic Object]]. This payload will contain all the ParameterList field results after a call (on the owner side after a call).

=== ReturnValue ===
The ReturnValue Payload only exists if the given [[ascript#ascript.Functions.Item.Owner|Function Owner]] returns a value. Functions returning void will not have this property. The ReturnValue payload is a [[Dynamic Objects|Dynamic Object]]. After a call, the ReturnValue payload will contain the return results (on the owner side after a call).

== Synchronous / Asynchronous Interception ==
Function calls that are made between a function [[Ascript#Ascript.Functions.Item.Owner|Owner]] and a function [[Ascript#Ascript.Functions.Item.Owner|User]] will be either asynchronous or synchronous.
 

=== Asynchronous Calls (non-blocking) ===
An asynchronous function call is also known as a "non-blocking" call. This is the type of call that occurs for both CallNonBlocking and CallBypassOverrideNonBlocking.

==== CallBypassOverrideNonBlocking ====
Asynchronously calls the override registered owner of the function (Non-blocking call).
* Invokes call to registered function owner bypassing the registered override owner (if one exists).
* If there is no registered owner but there is an override registered owner, the call is routed to the override registered owner.
* Current values of all fields of the ParameterList property are marshaled to the called function.
* This method returns to the caller immediately. When the function owner (running in a separate thread) returns, an event is placed in this script's queue by the STRIDE Runtime. The event (as a polymorphic object exposing Type and Name properties) is retrieved from the queue using [[Events#WaitForEvent|ascript.WaitForEvent()]].
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].
* The object returned from [[Events#WaitForEvent|WaitForEvent()]] in response to CallByPassOverrideNonBlocking() can be:
{| cellspacing="0" cellpadding="1" width="100%" border="0"
|-
| width="10" |
|  
* The Function User Object corresponding to the function that was called. (Type = "FunctionUser", Name="function name"). The object's ReturnValue property and the OutPointers property (if present) will be populated with the values supplied by the Owner implementation.
* An [[Error Object|Error Object]] containing information about the error that occurred (Type="Error"; Name="error source").
|}

==== CallNonBlocking ====

Asynchronously calls the registered owner of the function (Non-blocking call).
* This call invokes a call to the currently registered owner of the function.
**If there is a registered owner and there is not an override registered owner, the call is routed to the registered owner.
**If there is a registered owner and there is also an override registered owner, the call is routed to the override registered owner.
**If there is no registered owner but there is an override registered owner, the call is routed to the override registered owner.
* The current values of all fields in the ParameterList property are marshaled to the called function.
* This method returns to the caller immediately. When the function owner (running in a separate thread) returns, an event is placed in this script's queue by the STRIDE Runtime. The event (as a polymorphic object exposing Type and Name properties) is retrieved from the queue using ascript.WaitForEvent().
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].
* The object returned from [[Events#WaitForEvent|WaitForEvent()]] in response to CallByPassOverrideNonBlocking() can be:
{| cellspacing="0" cellpadding="1" width="100%" border="0"
|-
| width="10" |
|  
* The Function User Object corresponding to the function that was called. (Type = "FunctionUser", Name="function name"). The object's ReturnValue property and the OutPointers property (if present) will be populated with the values supplied by the Owner implementation.
* An [[Error Object|Error Object]] containing information about the error that occurred (Type="Error"; Name="error source").
|}

=== Synchronous Calls (blocking) ===
A synchronous call is also known as a "blocking" call. Blocking calls a made using the Call or CallBypassOverride methods. These calls are made from the [[Ascript#Ascript.Functions.Item.User|User]].

==== Call ====
Synchronously calls the registered owner of the function (Blocking call).
* All current field values of the ParameterList property are marshaled to the function [[Ascript#Ascript.Functions.Item.Owner|Owner]].
* If there is no registered owner or registered override owner, an exception is thrown.
* If there is no registered owner but there is an override registered owner, the call is routed to the override registered owner.
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].

==== CallBypassOverride ====
Synchronously calls the override registered owner of the function (Blocking call).
* The call is made to the registered owner of the function bypassing any existing registered override owner.
* The current values of all fields in the ParameterList property are marshaled to the called function [[Ascript#Ascript.Functions.Item.Owner|Owner]].
* If there is no registered owner or registered override owner, an exception is thrown.
* If there is no registered owner but there is a registered override owner, the call is routed to the registered override owner.
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].

=== Returns ===
When the callee ([[Ascript#Ascript.Functions.Item.Owner|owner]]) wants to generate a function return, it makes a call to the Return method. This method is used for both synchronous and unsynchronous calls.

Studio:AutoScript Functions

2008-07-30T23:22:15Z

Carriez: /* CallBypassOverride */

__FORCETOC__ 

== Overview ==
This section describes basic functionality for ascript function processing. For ease of understanding, this section describes overall concepts and then describes the precise functionality that STRIDE provides. 

== Function Interception ==
A powerful feature of STRIDE is the ability to intercept function calls. While this capability is known to most seasoned STRIDE users, it is not necessarily as known to STRIDE newbies. Comprehension of general STRIDE terms requires a small amount of knowledge as to what function interception means.
 
STRIDE is generally used to debug remote hardware (e.g. a cellphone) from a Windows computer running STRIDE. The remote hardware is refered to as the target. The Windows computer is refered
to as the host. Scripts are used to communicate with STRIDE to pass data between the host and target.
 
While there are several models for how to connect to host and target and to transfer data inbetween them, this wiki page is only to describe how perform this connectability via ascript. The following issues have to be resolved to communicate between host and target using two scripts:
* Which script owns a particular function (e.g. a script on the target)?
* Which script desires access to the function (e.g. a script on the host)?
* What is types of data (i.e. parameters, pointers, and return value payloads) will be passed between them?
* How will the owner and the user communicate to pass payloads?

The how of questions will be answered in the following sections. The why will depend on a particular testing solution to each distinct type of hardware being developed.

== Ownership vs. Usage ==
STRIDE has the concept of a Function Owner and a Function User. In general STRIDE usage the Owner and User imply the owner of a function on the target and the user of a function on the host.
 

=== Function User ===
A [[ascript#ascript.Functions.Item.User|Function User]] may be any script that is not registered as the function owner or function override owner. The [[ascript#ascript.Functions.Item.User|Function User]] may be access via the message as [[ascript#ascript.Functions.Item.User|ascript.Functions.Item.User]].
 

=== Function Owner ===
The [[ascript#ascript.Functions.Item.Owner|Function Owner]] is the script that has successfully registered itself as the owner of the function (by calling the Register method). A function will only have one registered owner. Calls to register a second owner will result in an exception will be thrown. Ownership can be surrendered by calling the Unregister method (or by exiting the script that registered ownership). The [[ascript#ascript.Functions.Item.Owner|Function Owner]] may be accessed via [[ascript#ascript.Functions.Item.Owner|ascript.Functions.Item.Owner]].
 

=== Override Owner ===
The Function Override Owner of a function is the script that successfully registered as the override owner (using the RegisterOverride method). An override owner is used to bypass the registered owner. If a function has an override owner registered, function calls are made to the registered override owner and not the registered owner. This allows the ability to code scripting with the registered owner, but to bypass the registered owner for certain processing for a variety of reasons (i.e. some code not implemented for the registered owner, some exception cases, etc.). It is legal for a script to declare both forms of function ownership. Thus, the same script may be both registered owner and the registered override owner.
 

== Function Payloads ==
Payloads are [[Dynamic Objects|Dynamic Objects]] containing data related to a function's parameters, a function's return value, or pointer values passed for a function. These payloads are defined as properties for both a [[ascript#ascript.Functions.Item.User|Function User]] and a [[ascript#ascript.Functions.Item.Owner|Function Owner]]. By being part of both user and owner allows their values can be checked for validity in the event that a call did not pass correct data from user to owner (or visa-versa).
 

=== OutPointers ===
This payload exists only if a function's payload has at least one pointer that is qualified as OUT or INOUT. In other words, the function returns an object via a pointer through its parameter list.

If this property exists, its members are comprised of all the top-level parameters that are either OUT or INOUT pointers. This can also exist for structured types (structs or unions) that contain members that are OUT or INOUT. It can also exist if a structured type contains a nested structured type that contains members that are OUT or INOUT. In the case of structured type objects appearing in the OutPointers hierarchy, only members that are qualified as OUT or INOUT (or that themselves contain these qualified types) are available.

Upon a function's return, the OutPointers property of the [[ascript#ascript.Functions.Item.User|Function User]] object (ascript.Functions.Item().User.OutPointers) will reflect (contain) the values set by the [[ascript#ascript.Functions.Item.Owner|Function Owner]] object (ascript.Functions.Item().Owner.OutPointers).

=== ParameterList ===
A ParameterList payload only exists if the given [[ascript#ascript.Functions.Item.Owner|Function Owner]] contains one or more parameters. This payload will contain the values of all ParameterList fields at the time the function User called the Owner (on the user side before a call). The ParameterList payload is a [[Dynamic Objects|Dynamic Object]]. This payload will contain all the ParameterList field results after a call (on the owner side after a call).

=== ReturnValue ===
The ReturnValue Payload only exists if the given [[ascript#ascript.Functions.Item.Owner|Function Owner]] returns a value. Functions returning void will not have this property. The ReturnValue payload is a [[Dynamic Objects|Dynamic Object]]. After a call, the ReturnValue payload will contain the return results (on the owner side after a call).

== Synchronous / Asynchronous Interception ==
Function calls that are made between a function [[Ascript#Ascript.Functions.Item.Owner|Owner]] and a function [[Ascript#Ascript.Functions.Item.Owner|User]] will be either asynchronous or synchronous.
 

=== Asynchronous Calls (non-blocking) ===
An asynchronous function call is also known as a "non-blocking" call. This is the type of call that occurs for both CallNonBlocking and CallBypassOverrideNonBlocking.

==== CallBypassOverrideNonBlocking ====
Asynchronously calls the override registered owner of the function (Non-blocking call).
* Invokes call to registered function owner bypassing the registered override owner (if one exists).
* If there is no registered owner but there is an override registered owner, the call is routed to the override registered owner.
* Current values of all fields of the ParameterList property are marshaled to the called function.
* This method returns to the caller immediately. When the function owner (running in a separate thread) returns, an event is placed in this script's queue by the STRIDE Runtime. The event (as a polymorphic object exposing Type and Name properties) is retrieved from the queue using [[Events#WaitForEvent|ascript.WaitForEvent()]].
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].
* The object returned from [[Events#WaitForEvent|WaitForEvent()]] in response to CallByPassOverrideNonBlocking() can be:
{| cellspacing="0" cellpadding="1" width="100%" border="0"
|-
| width="10" |
|  
* The Function User Object corresponding to the function that was called. (Type = "FunctionUser", Name="function name"). The object's ReturnValue property and the OutPointers property (if present) will be populated with the values supplied by the Owner implementation.
* An [[Error Object|Error Object]] containing information about the error that occurred (Type="Error"; Name="error source").
|}

==== CallNonBlocking ====

Asynchronously calls the registered owner of the function (Non-blocking call).
* This call invokes a call to the currently registered owner of the function. If there is an override registered owner, it is called. If there is no override registered owner, but there is a registered owner, the registered owner is called.
* The current values of all fields in the ParameterList property are marshaled to the called function.
* This method returns to the caller immediately. When the function owner (running in a separate thread) returns, an event is placed in this script's queue by the STRIDE Runtime. The event (as a polymorphic object exposing Type and Name properties) is retrieved from the queue using ascript.WaitForEvent().
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].
* The object returned from [[Events#WaitForEvent|WaitForEvent()]] in response to CallByPassOverrideNonBlocking() can be:
{| cellspacing="0" cellpadding="1" width="100%" border="0"
|-
| width="10" |
|  
* The Function User Object corresponding to the function that was called. (Type = "FunctionUser", Name="function name"). The object's ReturnValue property and the OutPointers property (if present) will be populated with the values supplied by the Owner implementation.
* An [[Error Object|Error Object]] containing information about the error that occurred (Type="Error"; Name="error source").
|}

=== Synchronous Calls (blocking) ===
A synchronous call is also known as a "blocking" call. Blocking calls a made using the Call or CallBypassOverride methods. These calls are made from the [[Ascript#Ascript.Functions.Item.User|User]].

==== Call ====
Synchronously calls the registered owner of the function (Blocking call).
* All current field values of the ParameterList property are marshaled to the function [[Ascript#Ascript.Functions.Item.Owner|Owner]].
* If there is no registered owner or registered override owner, an exception is thrown.
* If there is no registered owner but there is an override registered owner, the call is routed to the override registered owner.
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].

==== CallBypassOverride ====
Synchronously calls the override registered owner of the function (Blocking call).
* The call is made to the registered owner of the function bypassing any existing registered override owner.
* The current values of all fields in the ParameterList property are marshaled to the called function [[Ascript#Ascript.Functions.Item.Owner|Owner]].
* If there is no registered owner or registered override owner, an exception is thrown.
* If there is no registered owner but there is a registered override owner, the call is routed to the registered override owner.
* If the [[Ascript#Ascript API|RspTimeoutPeriod]] is non-zero and the call does not complete in the specified time, an exception is thrown. For interactively run scripts the timeout behavior differ; see [[Timeout Considerations|Timeout Considerations]].

=== Returns ===
When the callee ([[Ascript#Ascript.Functions.Item.Owner|owner]]) wants to generate a function return, it makes a call to the Return method. This method is used for both synchronous and unsynchronous calls.

Studio:AutoScript

2008-07-30T23:00:29Z

Carriez: /* Introduction  */

__FORCETOC__ 

= Introduction  =

Ascript is the definitive hierarchy of methods, objects, and properties provided by Autosense. While Autosense helps the user find the script methods/data desired in a script, Ascript is the definitive source of what is available from STRIDE when using Autosense.

The ascript object provides functionality that allows host-based scripts to interact with target-based binaries through the STRIDE Runtime. Through ascript, you can:

*call target-based functions and messages (synchronously or asynchronously)
*set and read parameter values of these functions and messages
*transparently emulate (mock) target-based functions

= Ascript Wiki Pages =
* [[Ascript#Introduction|Ascript]]
* [[Dynamic Objects|Dynamic Objects]]
* [[Events|Events]]
* [[Functions|Functions]]
* [[Messaging|Messaging]]
* [[Timeout Considerations|Timeout Considerations]]

= Ascript Automation Usage =

Ascript is used to access STRIDE functionality within JScript or Perl. When creating a script, the user types in 'ascript' followed by dot '.' to get Autosense to display (see below).

[[Image:Ascriptpopup.jpg]]

The user may select methods to be used within his script. The user may access property data within his script. Other data elements may be accessed using the Ascript API.

= Ascript API =
The ascript object is the top-most object when accessing methods and properties related to Ascript. The following table describes what is available from the ascript object. Other nested properties and methods may be found under the ascript object.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="250" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| [[#ascript.Arguments|Arguments]]
| Collection
| Collection of arguments.
|-
| [[#ascript.Constants|Constants]]
| Collection
| Collection of constants.
|-
| [[#ascript.Database|Database]]
| valign="top" align="left" width="150" | Object 
| Database settings.
|-
| [[#ascript.Functions|Functions]]
| Collection
| Collection of functions.
|-
| void '''Initialize ('''    String STIDName,    String databaseFile,    int MessageBoxTimeout [optional] ''')'''
| Method
| Initializes and ascript object instance that has been created outside of the STRIDE Studio environment. This call is needed only on an explicitly-created ascript instance. This call should not be made on an ascript instance automatically created and injected into a script by STRIDE Studio.
|-
| IsEventPending
| Property, '''Read-only''', boolean
| Contains true if there is at least one event in this script's message queue. Events are retrieved from the queue using the [[Events#WaitForEvent|WaitForEvent]] method (ascript.WaitForEvent()).
|-
| LogicalPath
| Property, '''Read-only''', String
| Contains the script's path in the STRIDE Studio workspace tree.
|-
| String '''MessageBox('''     String Message,    String Title [optional],     String Type ''')'''
| Method
| Displays a model message box dialog.
 
Acceptable strings for type include:
* "OK"
* "OKCANCEL"
* "RETRYCANCEL"
* "YESNO"
* "YESNOCANCEL"
 
Returns a string indicating the action used to dismiss the message box. Strings returned include:
* "ABORT"
* "CANCEL"
* "IGNORE"
* "YES"
* "NO"
* "OK"
|-
| [[ascript.Messages|Messages]]
| Collection
| Collection of messages.
|-
| Output
| Property, (String, Integer, or Object)
| This is the return value from a RunBlocking() call that invoked this script. This works only when the script is invoked using RunBlocking() in the studio object model.
|-
| RspTimeoutPeriod
| Property, int
| This value controls the timeout threshold for synchronous function and two-way message calls (in milliseconds). A zero value indicates no timeout. For interactively run scripts the timeout behavior may be different. Specific calls affected by this value are:
* Call
* CallBypassOverride
* SendAndRead
* SendAndReadBypassOverride
|-
| ScriptName
| Property, '''Read-only''', String
| Contains the name of the currently running script with extension and without path. If the current ascript instance was instantiated and initialized outside of STRIDE Studio, this value will reflect the STIDName passed to ascript.Initialize().
|-
| void '''Sleep('''    int Period ''')'''
| Method
| Time to pause (in milliseconds). Allowable range is 0 -1440000 (24 hours).
|-
| [[#ascript.TestUnits|Test Units]]
| Collection
| Collection of test units.
|-
| [[#ascript.Timers|Timers]]
| Collection
| Collection of timers.
|-
| [[Events#WaitForEvent|Event]] '''WaitForEvent ( void )'''
| Method
| Pauses script execution until an event is detected in this script's event queue. See [[Events#WaitForEvent|WaitForEvent]] for more information on this method.
|-
| WaitTimeoutPeriod
| Property, String
| The timeout threshold (in milliseconds) for asynchronous function and message calls. A zero value indicates no timeout.
|}

 

== ascript.Arguments ==

The Arguments collection manages a list of [[#ascript.Arguments.Item|Arguments]] passed to a script which has been invoked via one of the following methods of the Studio Object Model's File object:
 
* RunBlocking([arg1], [arg2], ...)
* RunNonBlocking([arg1], [arg2], ...)
 
The default sort order of the member argument objects is the order in which the arguments were given in the call where the script was invoked.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" | Count
| valign="top" | Property, '''Read-only''', int
| valign="top" | Returns the number of Arguments in this collection. 
|-
| valign="top" align="left" width="150" |
[[#ascript.Arguments.Item|Argument]] '''Item''' (     int Index ''')'''

| valign="top" | Method 
| valign="top" | Retrieves the argument at the given index. An exception is thrown if the index is out of range. 
|-
| valign="top" align="left" width="150" |
[[#ascript.Arguments.Item|Argument]] '''Item''' (     String Name ''')'''

| valign="top" | Method 
| valign="top" | Retrieves the argument with the given name. If a named argument doesn't exist, null is returned. 
 

|}

=== ascript.Arguments.Item ===

The ascript [[#ascript.Arguments|Arguments]] Collection's Item() method returns an Argument Object.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" align="left" width="150" | Name
| valign="top" align="left" | Property, '''Read-only''', String
| valign="top" align="left" |
The argument name. The name may have been specified in the studio automation RunBlocking() or RunNonBlocking() call that launched the script or if not specified the name is synthesized by the ascript object.

When synthesized, the name is of the form "Unnamed_N" where 'N' is a monotonically incremented number starting from 0.

|-
| valign="top" align="left" width="150" | Value 
| valign="top" align="left" | Property, '''Read-only''', String, Integer, or Object
| valign="top" align="left" | The argument value.
|}

 

== ascript.Constants ==

The Constants collection contains [[#ascript.Constants.Item|Constants]] objects that represent all constants in C/C++ source code compiled by the STRIDE compiler. Constants include all #define symbols and enumerated constants.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" | '''void ArrangeBy ('''    String By [optional],    String Order [optional] ''')'''
| valign="top" | Method
| valign="top" | Sorts the Constants collection so that indexing by position yields predictable results. The 'By' parameter may only be "Name". If not specified, the default is "Name". This represents how Constants should be sorted in the collection. The 'Order' parameter may be either "Ascending" or "Descending". If not specified, the default is "Ascending". Exception thrown if either argument is outside legal values.
|-
| valign="top" | Count
| valign="top" | Property, '''Read-only''', int
| valign="top" | Returns the number of Constants in this collection. 
|-
| valign="top" align="left" width="150" |
[[#ascript.Constants.Item|Constant]] '''Item''' (     int Index ''')'''

| valign="top" | Method 
| valign="top" | Retrieves the constant at the given index. An exception is thrown if the index is out of range. 
|-
| valign="top" align="left" width="150" |
[[#ascript.Constants.Item|Constant]] '''Item''' (     String Name ''')'''

| valign="top" | Method 
| valign="top" | Retrieves the constant with the given name. If a named constant doesn't exist, null is returned. 
 

|}

 

=== ascript.Constants.Item ===

The ascript [[#ascript.Constants|Constants]] Collection's Item() method returns a Constant object.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" align="left" width="150" | Name
| valign="top" align="left" | Property, '''Read-only''', String
| valign="top" align="left" | The name of the constant.
|-
| valign="top" align="left" width="150" | Value
| valign="top" align="left" | Property, '''Read-only''', String
| valign="top" align="left" | The value of the constant.
|}

 

== ascript.Database ==

The Database object represents the currently-loaded STRIDE database managed by ascript. You can combine the values of the database path and name to construct a fully-qualified filename. For example:

var dbFullPath = ascript.Database.Path + "\\" + ascript.Database.Name;

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" | Name
| valign="top" | Property, '''Read-only''', String
| valign="top" | The name of the database in use. The database name includes the ".sidb" extension.
|-
| valign="top" | Path 
| valign="top" | Property, '''Read-only''', String
| valign="top" | The path to the STRIDE database in use. The path does not contain a trailing backslash. 
|}

 

== ascript.Functions ==

The Functions collection represents all captured [[#ascript.Functions.Item|Function]] interfaces in the active database.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" | '''void ArrangeBy ('''    String By [optional],    String Order [optional] ''')'''
| valign="top" | Method
| valign="top" | Sorts the Functions collection so that indexing by position yields predictable results. The 'By' parameter may be either "Name" or "SUID". If not specified, the default is "Name". This represents how Functions should be sorted in the collection. The 'Order' parameter may be either "Ascending" or "Descending". If not specified, the default is "Ascending". Exception thrown if either argument is outside legal values.
|-
| valign="top" | Count
| valign="top" | Property, '''Read-only''', int
| valign="top" | Returns the number of Functions in this collection. 
|-
| valign="top" align="left" width="150" |
[[#ascript.Functions.Item|Function]] '''Item''' (     int Index ''')'''
| valign="top" | Method 
| valign="top" | Retrieves the function at the given index. An exception is thrown if the index is out of range. 
|-
| valign="top" align="left" width="150" |
[[#ascript.Functions.Item|Function]] '''Item''' (   String Name ''')'''
| valign="top" | Method 
| valign="top" | Retrieves the function with the given name. A null value is returned if there is no function with the given name. 
|}

=== ascript.Functions.Item ===

The Function object represents a captured function interface in the currently active STRIDE database. A Function object always exists as a member of the [[#ascript.Functions|Functions]] collection.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| Name
| Property, '''Read-only''', boolean
| Function's name.
|-
| [[#ascript.Functions.Item.Owner|Owner]]
| Property, '''Read-only''', Object
| Function's owner object. The owner object provides access to properties and methods used by the owner-side of the function interface. The owner-side of the interface is used by the implementor of the function.
|-
| SUID
| Property, '''Read-Only''', int
| STRIDE Unique IDentifier assigned by compiler.
|-
| Type
| Property, '''Read-Only''', String
| Contains the string "Function".
|-
| [[#ascript.Functions.Item.User|User]]
| Property '''Read-Only''', Object
| Function's user object. The user object provides access to properties and methods used by the user-side of the function interface. The user-side of the interface is used by the caller of the function.
|}

 

==== ascript.Functions.Item.Owner ====
The Function Owner object represents the Owner (callee) side of a function. The Owner object is used to implement a function in script that can be called through the STRIDE Runtime. The Function Owner object is reachable from a [[#ascript.Functions.Item|Function]] object's owner property.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="200" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| IsOverrideRegistered
| Property, '''Read-Only''', boolean
| Contains true if there is a registered override owner. See [[Functions#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| IsRegistered
| Property, '''Read-only''', boolean
| Contains true if there is a registered owner, a registered override owner, or both. See [[Functions#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| Name
| Property, '''Read-only''', String
| Owner name.
|-
| [[Functions#OutPointers|OutPointers]]
| Property, '''Read-only''', Object
| Contains the [[Functions#OutPointers|OutPointers]] payload of the Function User object. See [[Functions#Function Payloads|Function Payloads]] for more information.
|-
| [[Functions#ParameterList|ParameterList]]
| Property, '''Read-only''', Object
| Contains the object representing the [[Functions#ParameterList|ParameterList]] payload of the Function Owner. Functions without parameters will not have this property. Before calling the function, all relevent fields in the ParameterList property must be set (includeing the fields of any child objects). These values are marshaled to the currently registered Owner of the function when it is called. This property is a [[Dynamic Objects|Dynamic Object]]. See [[Functions#Function Payloads|Function Payloads]] for more information.
|-
| '''void Register (void)'''
| Method
| Registers the script from which it is called as the active owner of the function. If there is a currently registered owner or another registration failure, an exception is thrown. See [[Functions#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| '''void RegisterOverride (void)'''
| Method
| Registers the script as the override registered owner. If the function already has an override registered owner or if there is another registration error, an exception is thrown. See [[Functions#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| '''void Return ()'''
| Method
| Causes a return from a function call made from another script. See [[Functions#Returns|Return]] for more information. The values of OutPointers and ReturnValue will be reflected to the caller (as long as they are consistent with the input values).
|-
| [[Functions#ReturnValue|ReturnValue]]
| Property, '''Read-only''', Integer
| Contains the object representing the [[Functions#ReturnValue|ReturnValue]] payload of the Function Owner. Functions returning void will not have this property. Upon return this property will reflect the ReturnValue set by the function Owner. This property is a [[Dynamic Objects|Dynamic Object]]. See [[Functions#Function Payloads|Function Payloads]] for more information.
|-
| SUID
| Property, '''Read-only''', int
| STRIDE-unique identifier assigned by compiler.
|-
| Type
| Property, '''Read-only''', String
| Contains "Function".
|-
| '''void Unregister (void)'''
| Method
| Unregisters the script that was registered as the owner of the function from a prior Register call. If the current script is not the owner or if unregistration fails, an exception is thrown. See [[Functions#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| '''void UnregisterOverride (void)'''
| Method
| Unregisters the script that was registered as the override owner of the function from a prior RegisterOverride call. If the current script is not the registered override owner or if unregistration fails, an exception is thrown. See [[Functions#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|}

 

==== ascript.Functions.Item.User ====
The Function User object represents the User (caller) side of a function. The User object is used to call a function through the STRIDE Runtime. The Function User object is reachable from a [[#ascript.Functions.Item|Function]] object's User property.
{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="280" bgcolor="#66ff99" | '''Member''' 
| width="90" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| '''void Call (void)'''
| Method
| Synchronously calls the registered owner of the function (Blocking call). See [[Functions#Synchronous Calls (blocking)|Synchronous Calls]] for more information.
|-
| '''void CallBypassOverride (void)'''
| Method
| Synchronously calls the registered owner bypassing the registered override owner of the function (Blocking call). See [[Functions#Synchronous Calls (blocking)|Synchronous Calls]] for more information.
|-
| '''void CallBypassOverrideNonBlocking (void)'''
| Method
| Asynchronously calls the registered owner bypassing the registered override owner of the function (Non-blocking call). See [[Functions#Asynchronous Calls (non-blocking)|Asynchronous Calls]] for more information.
|-
| '''void CallNonBlocking (void)'''
| Method
| Asynchronously calls the registered owner of the function (Non-blocking call). See [[Functions#Asynchronous Calls (non-blocking)|Asynchronous Calls]] for more information.
|-
| IsOverrideRegistered
| Property, '''Read-only''', boolean
| Contains true if there is a registered override owner. See [[Functions#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| IsRegistered
| Property, '''Read-only''', boolean
| Contains true if there is a registered owner, a registered override owner, or both. See [[Functions#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| Name
| Property, '''Read-only''', String
| User function name.
|-
| [[Functions#OutPointers|OutPointers]]
| Property, '''Read-only''', Object
| Contains the [[Functions#OutPointers|OutPointers]] payload of the Function User object. See [[Functions#Function Payloads|Function Payloads]] for more information.
|-
| [[Functions#ParameterList|ParameterList]]
| Property, '''Read-only''', Object
| Contains the object representing the [[Functions#ParameterList|ParameterList]] payload of the Function Owner. Functions without parameters will not have this property. Before calling the function, all relevent fields in the ParameterList property must be set (includeing the fields of any child objects). These values are marshaled to the currently registered Owner of the function when it is called. This property is a [[Dynamic Objects|Dynamic Object]]. See [[Functions#Function Payloads|Function Payloads]] for more information.
|-
| [[Functions#ReturnValue|ReturnValue]]
| Property, '''Read-only''', Object
| Contains the object representing the [[Functions#ReturnValue|ReturnValue]] payload of the Function Owner. Functions returning void will not have this property. Upon return this property will reflect the ReturnValue set by the function Owner. This property is a [[Dynamic Objects|Dynamic Object]]. See [[Functions#Function Payloads|Function Payloads]] for more information.
|-
| SUID
| Property, '''Read-only''', ,int
| STRIDE-unique identifier assigned by compiler.
|-
| Type
| Property, '''Read-only''', String
| Contains "FunctionUser". This property is typically used to classify an object that is returned from [[Events#WaitForEvent|WaitForEvent]].
|}

 

== ascript.Messages ==

The Messages Collection is a collection of captured [[#ascript.Messages.Item|Message]] objects. 

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" | '''void ArrangeBy ('''    String By [optional],    String Order [optional] ''')'''
| valign="top" | Method
| valign="top" | Sorts the Messages collection so that indexing by position yields predictable results. The 'By' parameter may one of the following: "Name", "SMID", "SUID", "Type". The default sorting order is by "Name". This represents how Timers should be sorted in the collection. A runtime exception is thrown if an invalid value is passed The 'Order' parameter may be either "Ascending" or "Descending" and is not case sensitive. If not specified, the default is "Ascending". A runtime exception is thrown if a invalid value is passed.
|-
| valign="top" | Count
| valign="top" | Property, '''Read-only''', int
| valign="top" | Returns the number of Messages in this collection. 
|-
| valign="top" align="left" width="150" |
[[#ascript.Messages.Item|Message]] '''Item '''(     int Index )

| valign="top" | Method 
| valign="top" | Retrieves the message at the given index. 
|-
| valign="top" align="left" width="150" |
[[#ascript.Messages.Item|Message]] '''Item '''(     String Name )

| valign="top" | Method 
| valign="top" | Retrieves the message with the given name. 
|}

 

=== ascript.Messages.Item ===

The Message object represents a captured message interface in the currently active STRIDE database. A Message object is always a member of the [[#ascript.Messages|Messages]] collection.
{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="120" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| Name
| Property, '''Read-only''', String
| Message name.
|-
| [[#ascript.Messages.Item.Owner|Owner]]
| Property, '''Read-only''', Object
| Message's owner object.
|-
| SUID
| Property, '''Read-only''', int
| STRIDE Unique Identifier assigned by compiler.
|-
| Type
| Property, '''Read-only''', String
| Contains message type defined by the SCL declaration. Legal values include:
* "OneWayMessage"
* "OneWayResponse"
* "TwoWayMessage"
* "BroadcastMessage"
|-
| [[#ascript.Messages.Item.User|User]]
| Property, '''Read-only''', Object
| Message's user object.
|}

 

==== ascript.Messages.Item.Owner ====

The Message Owner object represents the Owner-side of a [[#ascript.Messages.Item|Message]]. This may be a receiver of a one-way or two-way message. It may also be the broadcaster of a broadcast message. The Owner object may be used to implement the message owner in a script that can be called through the STRIDE Runtime. 
This object allows access to the message destination. The message can be routed to any of the following:
 
* the original on-target receiver
* a window in STRIDE Studio
* a script running in Studio
 
{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="210" bgcolor="#66ff99" | '''Member''' 
| width="80" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| '''void Broadcast (void)'''
| Method
| Broadcast method exists only for Broadcast Messages. This method broadcasts this message to all message users that have subscribed to this message. The Response payload values are marshaled to all subscribed message users. See [[Messaging#Broadcast Messaging|Broadcast Messaging]] for more information.
|-
| [[Dynamic Objects|Command]]
| Property, '''Read-only''', Object
| This property is a [[Dynamic Objects|Dynamic Object]] representing the Command payload of the Message Owner. The property exists only if the captured message took one or more parameters. The property contains all the values of the Message User Command fields at the time that the message User called the Owner. See [[Messaging#Message Payloads|Message Payloads]] for more information.
|-
| IsOverrideRegistered
| Property, '''Read-only''', boolean
| Contains the override Owner registration state of the message. True only if there is a registered override owner. See [[Messaging#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| IsRegistered
| Property, '''Read-only''', boolean
| Contains the Owner registration state of the message. True only if there is a registered owner, a registered override owner, or both. See [[Messaging#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| Name
| Property, '''Read-only''', String
| Contains Message name.
|-
| '''void Register (void)'''
| Method
| This method only exists for One-Way Command or Two-Way Messages. The calling script is registered as the active owner of the message. If there is already a registered owner or if there is some other registration failure, an exception is thrown. See [[Messaging#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| '''void RegisterOverride (void)'''
| Method
| This method only for One-Way Command or Two-Way Messages. The calling script is registered as the registered override owner (such that all future messages are routed to this owner over and above the registered owner). If there is already an override owner or if there is another registration failure, an exception is thrown. See [[Messaging#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| [[Dynamic Objects|Response]]
| Property, '''Read-only''', Object
| This property is a [[Dynamic Objects|Dynamic Object]] representing the Response payload of the Message Owner. The property exists only if the message is defined with a response payload. See [[Messaging#Message Payloads|Message Payloads]] for more information.
|-
| '''void SendRsp (void)'''
| Method
| Send response method exists only for One-Way Response or Two-Way Messages. The method sends the message as a response to a prior message command from a message user. If there is not pending message response expected an exception is thrown. After setting values of the response payload, a script that implements an Owner message calls SendRsp() to reply to an earlier two-way message (or one-way response). The effect of this call on the calling (User) script depends on how the earlier user message was sent. See [[Messaging#Point-to-Point Messaging|Point-to-Point Messaging]] for more information.
|-
| SUID
| Property, '''Read-only''', int
| STRIDE Unique Identifier assigned by compiler.
|-
| Type
| Property, '''Read-only''', String
| Contains message type defined by the SCL declaration. Legal values include:
* "OneWayMessage"
* "OneWayResponse"
* "TwoWayMessage"
* "BroadcastMessage"
|-
| '''void Unregister (void)'''
| Method
| This method only exists for One-Way Command or Two-Way Messages. This method unregisters the current script as the owner of the message. If the current script is not the registered owner or if unregistration fails, an exception is thrown. See [[Messaging#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| '''void UnregisterOverride (void)'''
| Method
| This method exists only for One-Way Command or Two-Way Messages. This method unregisters the current script as registered override owner. If the current script is not the registered override owner or if registration fails, an exception is thrown. See [[Messaging#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|}

 

==== ascript.Messages.Item.User ====
The Message User object represents the User-side of a [[#ascript.Messages.Item|Message]]. This may be a sender of a one-way or two-way message. It may also be the receiver of a broadcast message. The User object may be used to send a message from a script to the registered message owner through the STRIDE Runtime. 

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="240" bgcolor="#66ff99" | '''Member''' 
| width="90" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| [[Dynamic Objects|Command]]
| Property, '''Read-only''', Object
| This property is a [[Dynamic Objects|Dynamic Object]] representing the Command payload of the Message User. The property exists only if the captured message took one or more parameters. The values of all Message User Command payload fields should be set before the Message Owner is called. See [[Messaging#Message Payloads|Message Payloads]] for more information.
|-
| IsOverrideRegistered
| Property, '''Read-only''', boolean
| Contains the override Owner registration state of the message. True only if there is a registered override owner. See [[Messaging#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| IsRegistered
| Property, '''Read-only''', boolean
| Contains the Owner registration state of the message. True only if there is a registered owner, a registered override owner, or both. See [[Messaging#Ownership vs. Usage|Ownership vs. Usage]] for more information.
|-
| Name
| Property, '''Read-only''', String
| Contains Message name.
|-
| [[Dynamic Objects|Response]]
| Property, '''Read-only''', Object
| This property is a [[Dynamic Objects|Dynamic Object]] representing the Response payload of the Message User. The property exists only if the message is defined with a response payload. See [[Messaging#Message Payloads|Message Payloads]] for more information.
|-
| '''void SendAndRead ('''   boolean Value ''')'''
| Method
| This method exists only for Two-Way Messages. See [[Messaging#Two-Way Messaging|Two-Way Messaging]] for more information.
|-
| '''void SendAndReadBypassOverride ('''   boolean Value ''')'''
| Method
| This method exists only for Two-Way Messages. See [[Messaging#Two-Way Messaging|Two-Way Messaging]] for more information.
|-
| '''void SendCmd (void)'''
| Method
| This method exists only for Two-Way and One-Way Command Messages. See [[Messaging#Two-Way Messaging|Two-Way Messaging]] and [[Messaging#One-Way Messaging|One-Way Messaging]] for more information.
|-
| '''void SendCmdBypassOverride ('''    boolean Value ''')'''
| Method
| This method exists only for Two-Way and One-Way Command Messages. See [[Messaging#Two-Way Messaging|Two-Way Messaging]] and [[Messaging#One-Way Messaging|One-Way Messaging]] for more information.
|-
| '''void Subscribe (void)'''
| Method
| This method exists only for Broadcast Messages. This method subscribes this message owner to receive message broadcasts from the given message. See [[Messaging#Broadcast Messaging|Broadcast Messaging]] for more information.
|-
| SUID
| Property, '''Read-only''', int
| STRIDE Unique Identifier assigned by compiler.
|-
| Type
| Property, '''Read-only''', String
| Contains message type defined by the SCL declaration. Legal values include:
* "OneWayMessage"
* "OneWayResponse"
* "TwoWayMessage"
* "BroadcastMessage"
|-
| '''void Unsubscribe (void)'''
| Method
| Unsubscribe method exists only for Broadcast Messages. This method unsubscribes this message owner from given message's broadcasts. See [[Messaging#Broadcast Messaging|Broadcast Messaging]] for more information.

|}

== ascript.TestUnits ==

TestUnits is a collection of [[#ascript.TestUnits.Item|TestUnit]] Objects contained and managed through ascript.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" | '''void ArrangeBy ('''    String By [optional],    String Order [optional] ''')'''
| valign="top" | Method
| valign="top" | Sorts the Test Units collection so that indexing by position yields predictable results. The 'By' parameter may be either "Name" or "SUID". If not specified, the default is "Name". This represents how Test Units should be sorted in the collection. The 'Order' parameter may be either "Ascending" or "Descending". If not specified, the default is "Ascending". Exception thrown if either argument is outside legal values.
|-
| valign="top" | Count
| valign="top" | Property, '''Read-only''', int
| valign="top" | Returns the number of Test Units in this collection. 
|-
| valign="top" align="left" width="150" |
[[#ascript.TestUnits.Item|TestUnit]] '''Item '''(     int Index ''')'''

| valign="top" | Method 
| valign="top" | Retrieves the test unit at the given index. 
|}

 

=== ascript.TestUnits.Item ===

The TestUnit Object represents a captured Test Unit interface in the currently active STRIDE database. A Test Unit object always exists as a member of the [[#ascript.TestUnits|TestUnits]] collection and is accessed from the collection using the item(#) interface.

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" align="left" width="150" | Arguments
| valign="top" align="left" | Object
| valign="top" align="left" | Contains the Test Unit's parameter list payload.
|-
| valign="top" align="left" width="150" | IsRegistered
| valign="top" align="left" | Property, '''Read-only''', boolean
| valign="top" align="left" | Contains true if the Test Unit owner has registered on the target side.
|-
| valign="top" align="left" width="150" | Name
| valign="top" align="left" | Property, '''Read-only''', String
| valign="top" align="left" | Test Unit name.
|-
| valign="top" align="left" width="150" | '''void Run (void)''' 
| valign="top" align="left" | Method
| valign="top" align="left" | Method to run the test unit. Calling this method will run the test unit in a blocking call until the test unit completes processing.
|-
| valign="top" align="left" width="150" | [[Reporter#reporter.Suites.Item|Suite]]
| valign="top" align="left" | Property, Object
| valign="top" align="left" | An object of type Reporter's [[Reporter#reporter.Suites.Item|Suite]]. By default after a run this object is a sub-Suite of ascript.TestSuite with the same name as the Test Unit (null if no reporting performed). Setting Suite to a concrete external TestSuite prior to execution will override default creation behavior (set to null to revert to default behavior).
|-
| valign="top" align="left" width="150" | Summary
| valign="top" align="left" | Property, int
| valign="top" align="left" | Contains static payload object of type srTestCaseTotals_t with one of the following:
* srTEST_PASS
* srTEST_FAIL
* srTEST_NOTINUSE
* srTEST_INPROGRESS
|-
| valign="top" align="left" width="150" | Type
| valign="top" align="left" | Property, '''Read-only''', String
| valign="top" align="left" | Contains test unit type:
* "TestClass"
* "TestCClass"
* "TestFList"
|}

 

== ascript.Timers ==

The Timers collection manages a set of [[#ascript.Timers.Item|Timer]] Objects. The Timers allow scripts to generate periodic or 'one-shot' timed events. Upon creation, the Timers collection is empty. The Timers collection is the only read/write collection in STRIDE; member Timer objects can be added (implicitly created) and removed by scripts. From the collection's point of view, member Timers have two states: dead and alive. Timers are alive upon creation and remain so as long as they exist in the collection. A Timer object that is removed from the collection is considered dead. Any operation on a dead timer will cause an exception to be thrown. 

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" align="left" width="150" | [[#ascript.Timers.Item|Timer]] '''Add''' (     String Name ''')'''
| valign="top" align="left" | Method 
| valign="top" align="left" | Creates and adds a new timer object with the given name. Returns the new Timer object. An exception is thrown if a Timer was already created with the given name.
|-
| valign="top" | '''void ArrangeBy ('''    String By [optional],    String Order [optional] ''')'''
| valign="top" | Method
| valign="top" | Sorts the Timers collection so that indexing by position yields predictable results. The 'By' parameter may only be "Name". If not specified, the default is "Name". This represents how Timers should be sorted in the collection. The 'Order' parameter may be either "Ascending" or "Descending". If not specified, the default is "Ascending". An exception is thrown if either argument is outside legal values.
|-
| valign="top" | Count
| valign="top" | Property, '''Read-only''', int
| valign="top" | Returns the number of Timers in this collection. 
|-
| valign="top" align="left" width="150" | [[#ascript.Timers.Item|Timer]] '''Item ( '''    int Index ''')'''
| valign="top" align="left" | Method 
| valign="top" align="left" | Retrieves the Timer object for the given index.
|-
| valign="top" align="left" width="150" | [[#ascript.Timers.Item|Timer]] '''Remove ('''     int Index ''')'''
| valign="top" | Method 
| valign="top" | Removes the timer at the given index. A timer object that is removed from the collection is automatically stopped before removal if it is active. No event is generated in this case.
|}

 

=== ascript.Timers.Item ===

The ascript [[#ascript.Timers|Timers]] Collection's Item() method returns a Timer Object. The Timer object enables scripting clients to synthesize and receive timer-based periodic or one-shot events. 

When a timer expires and rires its event, the event is queued and can be accessed by the [[Events#WaitForEvent|WaitForEvent]] method. The expired timer object will be returned by WaitForEvent. 

{| cellspacing="0" cellpadding="10" width="100%" border="1"
|-
| width="150" bgcolor="#66ff99" | '''Member''' 
| width="100" bgcolor="#66ff99" | '''Type''' 
| bgcolor="#66ff99" | '''Description''' 
|-
| valign="top" align="left" width="150" | Active
| valign="top" align="left" | Property, '''Read-only,''' boolean
| valign="top" align="left" | Contains timer operation state. True if timer is in operation (i.e. it will generate an event at some time in the future). A newly created timer is inactive by default.
|-
| valign="top" align="left" width="150" | Duration
| valign="top" align="left" | Property, int
| valign="top" align="left" | Timer duration in milliseconds.
|-
| valign="top" align="left" width="150" | Id
| valign="top" align="left" | Property, '''Read-only,''' int
| valign="top" align="left" | Contains timer identifier.
|-
| valign="top" align="left" width="150" | Name
| valign="top" align="left" | Property, '''Read-only''', String
| valign="top" align="left" | Name assigned when the timer was created. Default names are "Timer_n" where 'n' is the nth named time created by this ascript object.
|-
| valign="top" align="left" width="150" | Periodic
| valign="top" align="left" | Property, boolean 
| valign="top" align="left" | When false, the time will fire only once (one-shot mode). When true, the time automatically restarts after each event is fired. This property can be changed regardless of the state of the timer. This field is false by default when a timer is created. 
|-
| valign="top" align="left" width="150" | '''void Start (void)'''
| valign="top" align="left" | Method 
| valign="top" align="left" | Transitions an inactive timer to active. Once started, the timer will run for the length of time specified by its Duration property. Calling Start on a timer with a zero/negative duration will cause an exception to be thrown. Calling Start on a timer that has already started will also cause an exception to be thrown.
|-
| valign="top" align="left" width="150" | '''void Stop (void)'''
| valign="top" align="left" | Method 
| valign="top" align="left" | Transitions an active timer to inactive. Calling Stop on a timer that is not active will cause an exception to be thrown.
|-
| valign="top" align="left" width="150" | Type
| valign="top" align="left" | Property, '''Read-only''', String
| valign="top" align="left" | Contains the string "Timer". This property is typically used to classify an object that is returned from the [[Events#WaitForEvent|WaitForEvent]] method.
|}