Studio:AutoScript Messages

STRIDE offers many types of messaging as well as many options on messaging. For ease of understanding, this section describes overall concepts and then describes the precise functionality that STRIDE provides.

Concepts

This section describes overall basic STRIDE concepts related to messaging. Later sections describe how to specifically use STRIDE to facilitate messaging.

Ownership vs. Usage

STRIDE has the concept of a message owner and a message 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.

User

A message user may be any script that is not registered as the message owner or message override owner.

Owner

The message owner is the script that has successfully registered itself as the owner of the message (by calling the Register method). A message 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).

Override Owner

The message override owner of a message 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 message has an override owner registered, message transfers are sent 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 message ownership. Thus the same script may be both registered owner and the registered override owner.

Initiator vs. Handler

For STRIDE, the owner will be the message initiator for all broadcast messages. This means that a user will be the handler for all broadcast messages (that it has subscribed to). Also, the user will be the message intiator for all One-Way or Two-Way messages. The owner will be the message handler for these cases.

Message 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 part of both a message user (ascript.Messages.Item().User.Command and ascript.Messages.Item().User.Response) and a message owner (ascript.Messages.Item().Owner.Command and ascript.Messages.Item().Owner.Response). By being part of both user and owner allows their values can be checked for validity in the event that a message didn't make it from user to owner (or visa-versa).

Synchronous / Asynchronous Messaging

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. When a One-Way Command message is sent from a message user to a message owner (using one of the SendCmd methods), the a message command payload is logged to the message owner script's event queue (and the message user continues processing). When the message owner responds (using SendRsp) with a One-Way Response message, the response payload is logged to the message user script's event queue (and the message user continues processing). The initiator was not blocked from continuing processing.

Synchronous

A synchronous message is also known as a "blocking" message. A message transfer occurs between message owner and message user. If the message user initiates the message, the message is sent to the message owner and the message user waits until it receives a response. If the message owner is initiating the message, it too is blocked until it receives a response from the message user. The initiator of the message is blocked until it receives a response from the handler of the message.

Messaging Types

Broadcast Messaging

Broadcast messaging is the simplest form of asynchronous messaging. All broadcast messages are asynchronous (there is no synchronous form). A message user subscribes to a message. The message owner broadcasts messages. The messages are placed on the message user's event queue. When the message user script is finished listening for messages, the script calls Unsubscribe to cease receiving messages.

Two-Way Messaging

Two-Way Command/Response messaging is synchronous. The message user sends a command payload to the message owner and waits until the message owner sends a response. This is also known as a blocking message because the message user script is blocked from continuing processing until the message owner provides a response.

One-Way Messaging

One-Way Command messaging is asynchronous. For One-Way Command messaging the message user sends any number of one-way command messages to the message owner. These messages are then enqueued to the message owner's event queue. At some point in time, the message owner can respond to these messages with one-way response messages which will then be placed on the message user's event queue.

Broadcast Messages

Broadcast messaging is used to have a message owner broadcast messages. A number of message users will subscribe to a message for a time. The message user will receive messages until the message user's script exits or until it unsubscribes from the message. The exact process for how this is achieved is as follows:

1. A Message User calls Subscribe() to register that it is interested in receiving message events from a given message.
2. When the Message Owner calls Broadcast(), a message event is sent to all Subscribers of the message. The message event received by the Message User is enqueued to its script's event queue. The Message User may then evaluate the messages it has received by making calls to its WaitForEvent() method.
3. When a Message User no longer wishes to receive message events from a given message, it will call Unsubscribe() to unregister its interest in receiving events.

For a broadcast message (a message whose ascript.Messages.Item().Type is "BroadcastMessage"):

• Its owner (ascript.Messages.Item().Owner) will have a Broadcast method.

• Its user object (ascript.Messages.Item().User) will have a Subscribe method and an Unsubscribe method.

• These are the only methods available for this message type. Thus other message methods (e.g. Register/Unregister) will not be available.

Two-Way Command/Response Messaging

Two-Way messaging is as follows:

1. A Message User calls SendAndRead (or SendAndReadBypassOverride) to synchronously connect with the Message Owner. 2. The Message owner sets a response payload and calls SendRsp.

One-Way Command/Response Messaging

One-Way messaging is as follows:

1. A Message User script calls SendCmd (or SendCmdBypassOverride) to log a Command Payload to the event queue of the Message Owner. The Message User script then continues processing. 2. The Message Owner script eventually decides to look in its event queue (using WaitForEvent()) and sees that it has a message Command Payload to be processed. 3. The Message Owner script later decides that it wants to send a Response Payload back to the Message User. It calls SendRsp to send log a Response Payload to the event queue of the Message User. The Message Owner then continues processing. 4. The Message User later makes a call to its WaitForEvent() method and sees that it has a message Response Payload to be processed.