Studio:AutoScript Functions

 

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

Must of the functionality that STRIDE offers centers around the ability to intercept function calls between a host and a target.

Ownership vs. Usage

STRIDE has the concept of a Function Owner and a Function User. In general STRIDE usage the Owner and User imply target and host, but for messaging this meaning is transparent. A Message Owner may be on the host or the target. A Message User may be on the host or target.

Function User

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

Function Owner

The 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 Function Owner may be accessed via 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 containing data related to a message. A One-Way Command message may have a Command Payload. A One-Way Response message may have a Response Payload. A Two-Way Message may have both a Command Payload and a Response Payload. The word 'may' is used here because these are the legal conditions of what payloads may exist. For a Command Payload to exist, the captured message must take one or more parameters. For a Response Payload to exist, the captured message must be defined with a response payload.

These payloads are defined as properties for both a Function User and a 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 Function User object (ascript.Functions.Item().User.OutPointers) will reflect (contain) the values set by the Function Owner object (ascript.Functions.Item().Owner.OutPointers).

ParameterList

A ParameterList payload only exists if the given 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 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 Function Owner returns a value. Functions returning void will not have this property. The ReturnValue payload is a Dynamic Object. After a call, the ReturnValue payload will contain the return results (on the owner side after a call).

Synchronous / Asynchronous Interception

Messages that are sent between a Message Owner and a Message User will be either asynchronous or synchronous.

Asynchronous

An asynchronous message is also known as a "non-blocking" message. This is the type of messaging that occurs for Broadcast messaging, One-Way Command messaging, and One-Way Response messaging. For asynchronous messaging:
1. The initiator script of the action makes a call to transfer a payload (either a command or response).
2. The payload is logged onto the receiving script's event queue.
3. The initiator script continues processing.
4. Later the receiving script makes a call to WaitForEvent to processing the payload.

The initiator script was not blocked from continuing processing.

Synchronous

A synchronous message is also known as a "blocking" message. Only a Two-Way message is synchronous for STRIDE. For synchronous messaging:
1. The initiator script makes a call to transfer a command payload.
2. The initiator script then waits until the receiving script provides a response (perhaps with a response payload).

The initiator script was blocked from continuing processing until the receiving script responded.