Studio:AutoScript Messages

From STRIDE Wiki
Revision as of 18:13, 31 July 2008 by Chrisj (talk | contribs) (→‎Message Owner Methods)
Jump to: navigation, search

 

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.

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.

Message User

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

Message 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). The Message Owner may be accessed via ascript.Messages.Item.Owner.

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.

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 properties for both a Message User and a Message Owner. 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. 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.

Messaging Types

Broadcast Messaging

Broadcast Messaging Process

Broadcast messaging is the simplest form of asynchronous messaging. All broadcast messages are asynchronous (there is no synchronous form). The process for broadcast messages is as follows:

1. A Message User script makes a call to Subscribe() to listen for messages.
2. The Message Owner script constructs a Response Payload.
3. The Message Owner script makes a call to Broadcast() to broadcast its Response Payload.
4. The Response Payload is placed on the event queue of each of its subscribers.
5. The Message User script may retrieve messages from its event queue by calling WaitForEvent().
6. When the Message User script is finished listening for messages, a call to Unsubscribe() is made to cease receiving messages.

Broadcast Messaging Methods

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

  • Its Message Owner (ascript.Messages.Item().Owner) will have a Broadcast method.
  • Its Message 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.

Point-To-Point Messaging

Point-to-Point messaging refers to messaging where there is a single sender and a single receiver for a message (as opposed to broadcast messaging with multiple receivers). Point-to-Point messages are either Two-Way or One-Way.

Two-Way Messaging

Two-Way Messaging Process

Two-Way Command/Response messaging is synchronous. The process for two-way messages is as follows:
1. The Message User script constructs a Command Payload Dynamic Object.
2. The Message User script makes a call (SendAndRead or SendCmd) to send the Command Payload to the Message Owner script.
3. The Message User script blocks (in case of SendAndRead) or explicitly would need to read an event from its event queue using WaitForEvent().
4. The Message Owner script processes the Command Payload.
5. The Message Owner script performs some processing.
6. The Message Owner script constructs a Response Payload.
7. The Message Owner script makes a SendRsp call to return its Response Payload.
8. The Message User script receives the Response Payload and processes it.

Two-Way Messaging Methods

For a two-way message (a message whose ascript.Messages.Item().Type is "TwoWayMessage"):

  • Its Message Owner (ascript.Messages.Item().Owner) will have a SendRsp method.
  • Its Message User object (ascript.Messages.Item().User) will have a SendCmd and SendAndRead methods as well as SendCmdBypassOverride and SendAndReadBypassOverride methods.
  • These are the only methods available for this message type. Thus other message methods (e.g. Subscribe) will not be available.

One-Way Messaging

One-Way Messaging Process

One-Way Command messaging is asynchronous. The process for One-Way messages is as follows:
1. The Message User script constructs a Command Payload Dynamic Object.
2. The Message User script makes a call (SendCmd or SendCmdBypass) to send the Command Payload to the Message Owner.
3. The Command Payload is logged onto the event queue for the Message Owner script.
4. The Message User script continues processing.
5. The Message Owner script eventually reads an event from its event queue using WaitForEvent().
6. The Message Owner script formulates a Response Payload.
7. The Message Owner makes a call (SendRsp) to send its Response Payload to the Message User script.
8. The Response Payload is logged onto the event queue for the Message User script.
9. The Message User eventually reads an event from its event queue using WaitForEvent().

One-Way Messaging Methods

For a One-Way Command message (a message whose ascript.Messages.Item().Type is "OneWayMessage"):

  • Its Message User (ascript.Messages.Item().User) will have a SendCmd method as well as a SendCmdBypassOverride method.
  • These are the only methods available for this message type. Thus other message methods (e.g. Subscribe/SendCmd) will not be available.


For a One-Way Response message (a message whose ascript.Messages.Item().Type is "OneWayResponse"):

  • Its Message Owner (ascript.Messages.Item().Owner) will have a SendRsp method.
  • These are the only methods available for this message type. Thus other message methods (e.g. Subscribe/SendCmd) will not be available.


ascript.Messages

The Messages Collection is a collection of captured Message objects.

Member
 Type
 Description
void ArrangeBy (
   String By [optional],
   String Order [optional]
) 		Method Sorts the Messages collection so that indexing by position yields predictable results.

The 'By' parameter may one of the following: "Name", "SUID", or "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.
Count Property,
Read-only,
int 		Returns the number of Messages in this collection.

Message Item (
    int Index
)

Method
 Retrieves the message at the given index.

Message Item (
    String Name
)

Method
 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 Messages collection.

Member
 Type
 Description
Name Property,
Read-only,
String 		Message name.
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"
User Property,
Read-only,
Object 		Message's user object.


ascript.Messages.Item.Owner

The Message Owner object represents the Owner-side of a 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


Member
 Type
 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 Broadcast Messaging for more information.
Command Property,
Read-only,
Object 		This property is a 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 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 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 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 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 Ownership vs. Usage for more information.
Response Property,
Read-only,
Object 		This property is a Dynamic Object representing the Response payload of the Message Owner. The property exists only if the message is defined with a response payload. See 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 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 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 Ownership vs. Usage for more information.


Message Methods

The message methods available to a message owner or a message user are based upon the message type. This section describes the methods available for the given message types.

Message Owner Methods

Method
 Message Type
Method \ Message Type
 One-Way Command
 One-Way Response
 Two-Way
 Broadcast
Broadcast()       X
SendRsp()   X X  
Register() X   X  
RegisterOverride() X   X  
Unregister() X   X  
UnregisterOverride() X   X  
Retrieved from "https://www.stridewiki.com/index.php?title=Studio:AutoScript_Messages&oldid=6797"