Studio:AutoScript Dynamic Objects
The Dynamic Object Model
The ascript object supports a rich dynamic property model for functions and messages. The dynamic property model depends on the database loaded when the ascript object is initialized.
All dynamic properties are rooted at the following, which are themselves dynamic properties:
- function.User.ParameterList
- function.User.ReturnValue
- function.User.OutPointers
- function.Owner.ParameterList
- function.Owner.ReturnValue
- function.Owner.OutPointers
- message.User.Command
- message.User.Response
- message.Owner.Command
- message.User.Response
These objects are collectively referred to as Dynamic Payload Objects and share a number of common traits as explained in the next section.
Dynamic Payload Objects
A dynamic payload object is used to represent values that are either to be passed as part of a function call/return or message send/receive. The property names, types and values depend on the SCL that was used to describe the interface payload.
Although represented as a variant, each property has an underlying C language type. The types are represented internally according to the host platform, and are unaffected by target platform. The underlying types below are referred to as the ”r;standard set”:
- C language struct. The struct may be ”r;synthesized” under certain conditions. For example a C language struct is synthesized to represent function parameter lists.
- C language union.
- integer scalar types represented as 32 bits or less (char, unsigned char, short, unsigned short, int, unsigned int, long, unsigned long)
- integer scalar types represented as 64 bits. (long long, unsigned long long)
- floating point types float, double, long double
- enumerated type or enumerated-like types synthesized by scl_values()
- pointer to void or unqualified pointer to function (treated as void*) or pointer to incomplete type that is never completed (also treated as void*)
- qualified pointer to function (qualified by scl_fptr_anonymous() or scl_fptr_named())
- Array qualified as string
- qualified single pointer. Qualified as either IN, OUT, INOUT, RETURN or INRETURN
- qualified single pointer and string. Qualified as string and IN, OUT, INOUT, RETURN or INRETURN
- qualified fixed sized pointer. Qualifed as either IN, OUT, INOUT, RETURN or INRETURN
- qualified variable sized pointer. Qualified as either IN, OUT, INOUT, RETURN or INRETURN
- Array of any of the aforementioned types.
Default values are applied to all fields within a dynamic payload when the ascript object is initialized. The default value for all property types of all values is 0; this includes pointed-to values. The default null state of pointers is non-null.
The following sections detail the semantics of each of these types:
Enumerated or enumerated-like types
Bulk unstructured data transfer
C language struct
When the underlying type is a struct, the variant value for the property is an IDispatch object containing one or more named properties. Each named property represents a member of the structure. The property types can be any of the standard set already defined.
C language union
When the underlying type is a union, the variant value for the property is an IDispatch object containing one or more named properties. Each named property represents a member of the union. The property types can be any of the standard set already defined. The script semantics for setting or retrieving the values of the union member do not depend on whether the union is discriminated, or has a fixed active member. Any and all union members may be accessed at any time and they are all treated as independent values — i.e., setting the value of one union member does not overwrite the value of other union members, as in C. In this respect, unions behave like structs.
Note that upon a call or receipt of a call, only the value of the currently active member is transmitted between agents. The values of other members are not communicated to the receiving agent.
Small integer scalar types
Small integer or scalar types are fields whose underlying C type is signed or unsigned versions of char, short, int or long. Versions of char are represented as 8-bit quantities, short as 16-bit quantities, and int and long as 32-bit quantities.
Attempts to set values whose magnitude will not fit in the underlying representation are met by throwing an exception.
Attempts to read the respective values will always yield a value whose magnitude ”r;fits”.
Large integer scalar types
The types long long and unsigned long long are represented by an object whose underlying type is a synthesized structure. The structure for long long is:
struct LongLong { int upper int lower };
The structure synthesized for unsigned long long is:
struct LongLong { unsigned int upper; int lower; };
The value is manipulated by setting (or retrieving) the 64-bit quantity in two 32-bit parts.
Floating point types
The type float is represented as a 4-byte IEEE floating point number. The type double and long double are represented as an 8-byte IEEE floating point number.
Enumerated (or enumerated-like) types
Enumerated and enumerated-like properties stem from fields that were defined to be of some C language enumerated type or were of a small integer scalar type that had scl_values() applied. For the purposes of the rest of this section, we refer to both as enumerated types.
Given a field whose underlying type is an enumerated type, its value can be successfully set in the following ways:
Set an in-range value of the field using the symbolic (string) name of one of the enumerated value pairs.
Set an in-range value of the field using the numeric value of one of the enumerated value pairs.
Set an out-of-range value in the field using a numeric value that does not correspond to one of the enumerated value pairs. The value is out-of-range in the sense that it does not correspond to any of the enumeration constants, but the value's magnitude must still be representable within the bit size of the underlying field, or a out-of-range exception will be thrown.
Given a field whose underlying type is an enumerated type, retrieval of its value will return the enumerated type's symbolic name if the present value is in-range. The retrieval will return an out-of-range integer value if the current value is out of range.
The ascript object always initializes enumerated values to be 0, even when 0 is out of range.
Bulk unstructured data transfer
To provide high performance access to data in an array, special bulk transfer members are dynamically added to payload items that meet the following criteria. For detailed information, click here.
| Member |
Type |
Description |
| Arguments | b | b |