Knowledge Base

Message Object

by Community Manager on 07-07-2011 08:57 AM - last edited on 09-16-2011 07:58 AM

Represents a Message within the Composition.

Message Properties

  • name (read only – string)

The name of this Message. An item’s name can be changed by setting this property, with the following restrictions:

  • The name can only be changed before any activity has occurred for the given item. The item cannot have started playing yet, cannot have started repeating yet, and no other actions for it can have occurred yet (e.g. no other properties of it can have been set).
  • The name specified by the script must, of course, be a legal item name (255 chars max, no square brackets or slashes), and must not be the same name as another item in the same container.
  • parent (read only – object)

The parent Clip.

  • propertyList (read only – object)
A PropertyList object that allows access to all of the Custom Properties contained in this Message.
  • systempropertyList (read only – object)

A SystemPropertyList object that allows access to all of the System Properties contained in this object.

  • type (read only – string)

The string "Message".

  • children (read only – array of objects)

Always null

  • index (read only – integer)

Returns the position (zero-based index) of this item’s parent’s array of children.

  • nextItem (read only – object)

Returns the next item after this one in this item’s parent’s array of children, or null if this is the last item.  In other words, returns the next sibling in the object hierarchy.  Equivalent to:
item.parent.children(item.index + 1)
where "item" is the current item.

  • previousItem (read only – object)

Returns the previous item before this one in this item’s parent’s array of children, or null of this is the first item.  In other words, returns the next sibling in the object hierarchy. .  Equivalent to:
item.parent.children(item.index - 1)
where "item" is the current item.

  • forEachValue (read only – string, number, date/time, or null)

If this item is repeating due to a “for-each” repeat, this property contains the for-each value associated with this instance of the object. This will be a value in the array used for the for-each.

If this item is not repeating due to a “for-each” repeat, this property will be null.

  • repeatIndex (read only – integer)

An integer value that represents the “repeat index” of this item if it repeats, according to the context in which the current script is executing. The first repeat starts at index zero. The value is -1 if the current item does not repeat or has a repeat count of one (in other words, it is -1 if it doesn’t actually repeat).

  • playNumber (read only – integer)

An integer value that represents the “play ordinal number” of this item. Starting with the number 0, each play is assigned a unique number. The numbers are contiguous (no gaps).

Play number sequences are maintained within the item’s parent only. For example, if a parent item repeats, then the child items inside each repeat of the parent will have their own play number sequence starting at 0.

An item will only have a non-zero play number if it repeats. The play number is equivalent to the repeat index, except that the play number is 0 for items that don’t repeat or have a repeat count of one, whereas the repeat index would be -1 in those cases.

  • playNumberBeforeRenewal (read only – integer)

If this item repeats in parallel with the “Renew parallel repeats” option enabled, this is an integer value that is the “playNumber” value of the original parallel repeat for this item if it has been renewed because a prior parallel repeat ended. If this is the original parallel repeat, the value of playNumberBeforeRenewal will be equal to the value of playNumber. If this item does not repeat in parallel, the value will be zero.

For example, if parallel repeat number 5 of the item ends, but the Renew parallel repeats checkbox is enabled, the ending repeat will be replaced with a new, replacement repeat. The new repeat will have new repeatIndex and playNumber values (according to how many other repeats have already occurred). However, the playNumberBeforeRenewal value will still be 5 in this example.

This property is always 0 for Composition, Checkpoint, Delay, and Target.

  • target (read only – Target object)

The Target object for this Message.  Can be null.

  • REPEAT_TIMING_PARALLEL (read only – int)

 

A constant that can be passed in calls to the "setRepeat"method.  (See the description of the "setRepeat"method.)

  • REPEAT_TIMING_SERIAL (read only – int)

 

A constant that can be passed in calls to the "setRepeat"method.  (See the description of the "setRepeat"method.)

  • REPEAT_TYPE_COUNT_CONSTANT (read only – int)

 

A constant that can be passed in calls to the "setRepeat"method.  (See the description of the "setRepeat"method.)

  • REPEAT_DISTRIBUTION_CONSTANT (read only – int)

 

A constant that can be passed in calls to the "setRepeat"method.  (See the description of the "setRepeat"method.)

  • RESPONSE_TEXT (read only – int)

A constant that can be passed as the "indicator" parameter in calls to the "getResponse"method.  (See the description of the "getResponse"method.)

  • RESPONSE_HTTP_BODY (read only – int)

A constant that can be passed as the "indicator" parameter in calls to the "getResponse"method.  (See the description of the "getResponse"method.)

  • RESPONSE_HTTP_HEADER (read only – int)

A constant that can be passed as the "indicator" parameter in calls to the "getResponse"method.  (See the description of the "getResponse"method.)

  • RESPONSE_HTTP_HEADER_LIST (read only – int)

A constant that can be passed as the “indicator” parameter in calls to the “getResponse” method.

This change affects the “getResponse” method of the “Message” object, which now allows retrieval of all HTTP headers from any response, including when the same header appears multiple times in the response.

  • RESPONSE_HTTP_PROTOCOL (read only – int)

A constant that can be passed as the "indicator" parameter in calls to the "getResponse"method.  (See the description of the "getResponse"method.)

  • RESPONSE_HTTP_STATUSCODE (read only – int)

A constant that can be passed as the "indicator" parameter in calls to the "getResponse"method.  (See the description of the "getResponse"method.)

  • RESPONSE_HTTP_STATUSTEXT (read only – int)

A constant that can be passed as the "indicator" parameter in calls to the "getResponse"method.  (See the description of the "getResponse"method.)

  • RESPONSE_TEXT_AS_XML (read only – int)

A constant that can be passed as the "indicator" parameter in calls to the "getResponse"method.  (See the description of the "getResponse"method.)

    • RESPONSE_TEXT_AS_HTML (read only – int)

 

A constant that can be passed as the “indicator” parameter in calls to the "getResponse" method. (See the description of the "getResponse" method.)

      • RESPONSE_TEXT_AS_JSON (read only – int)

A constant that can be passed as the “indicator” parameter in calls to the "getResponse" method. (See the description of the "getResponse" method.)

      • RESPONSE_HTTP_BODY_AS_XML (read only – int)

A constant that can be passed as the "indicator" parameter in calls to the "getResponse"method.  (See the description of the "getResponse"method.)

      • RESPONSE_HTTP_BODY_AS_HTML (read only – int)

A constant that can be passed as the “indicator” parameter in calls to the "getResponse" method. (See the description of the "getResponse" method.)

      • RESPONSE_HTTP_BODY_AS_JSON (read only – int)

        A constant that can be passed as the “indicator” parameter in calls to the "getResponse" method. (See the description of the "getResponse" method.)

        • MESSAGE_TEXT (read only – int)

        A constant that can be passed as the "indicator" parameter in calls to the "getMessage" and "setMessage" methods.  (See the descriptions of those method.)

        • MESSAGE_HTTP_BODY (read only – int)

        A constant that can be passed as the "indicator" parameter in calls to the "getMessage" and "setMessage" methods.  (See the descriptions of those method.)

        • MESSAGE_HTTP_HEADERS (read only – int)

        A constant that can be passed as the "indicator" parameter in calls to the "getMessage" and "setMessage" methods.  (See the descriptions of those method.)

        • responseTime (read only – long)

        The total amount of time, in milliseconds, that it took to send the message and receive the response.  Will be null if the message has not yet been sent or if in "preview" mode.
        bytesSentCount (read only – long)
        The number of bytes that were sent. Will be null if the message has not yet been sent or if in "preview" mode. 

        Note:  This is currently the number of Unicode characters, which may not be the same as the number of actual bytes.

        • bytesReceivedCount (read only – long)

        The number of bytes that were received. Will be null if the message has not yet been sent or if in "preview" mode. 

        Note:  This is currently the number of Unicode characters, which may not be the same as the number of actual bytes.

        • retryCount (read only – long)

        The number of retries that were required due to unavailable local ports when sending the message.  Will be null if the message has not yet been sent or if in "preview" mode.

        • retryTotalTime (read only – long)

        The total amount of time, in milliseconds, that was spent retrying due to unavailable local ports when sending the message.  Will be null if the message has not yet been sent or if in "preview" mode.
        • o timeToFirstByte (read only – long)

        The “time to first byte” measurement for this message. Will be null if the message has not yet been sent or if in “preview” mode.

        • o timeToLastByte (read only – long)

        The “time to last byte” measurement for this message. Will be null if the message has not yet been sent or if in “preview” mode.

  

Message Methods

getChild

Always returns null.

object getChild(string childName)

  

getItemViaPath

Given a type of item and the path to that item in the Composition object hierarchy, returns the object in the hierarchy that represents that item.

The "itemType" parameter value indicates the type of item (not case sensitive):

  • "Composition"
  • "Band"
  • "Track"
  • "Clip"
  • "Chain"
  • "Message"
  • "Browser Action"
  • "Delay"
  • "Checkpoint"
  • "Target"

The "path" parameter contains a path as specified for In Situ Substitution Specifications. The path can be relative to the current item (for example to specify another item in the same Clip, the Band, Track and Clip portions of the path can be omitted).

object getItemViaPath(string itemType, string path)

clearRepeat

Removes any current repeating specification from this item (so that it will play exactly once).

void clearRepeat()

setRepeat

Sets a new repeating specification for this item.  See the description of this method in the description of the Band object.

void setRepeat(int timingType, intRepeat Type, long control, int distributionType, long distribution)

getResponse

Returns all or the specified portion of the response, if a response has been received.  Can return null.  Depending upon the situation, either null, String or array of String is returned.
The meaning of the "param" parameter depends upon the value of the "indicator" parameter.
The "indicator" parameter must be one of the following:

  • RESPONSE_TEXT

Returns the entire text of the response received as a string.
The "param" parameter is not used.

  • RESPONSE_HTTP_BODY

Returns the body of the HTTP response received as a string.
The "param" parameter is not used.
This indicator value is valid only for responses that are HTTP-based.

  • RESPONSE_HTTP_HEADER

Returns one HTTP header from the response received as a string.
The "param" parameter is the name of the HTTP header to be returned.  If the response contains no HTTP header with the specified name, null is returned.
This indicator value is valid only for responses that are HTTP-based.

  • RESPONSE_HTTP_PROTOCOL

Returns the protocol value from the HTTP response received as a string.
The "param" parameter is not used.
This indicator value is valid only for responses that are HTTP-based.

  • RESPONSE_HTTP_STATUSCODE

Returns the status code from the HTTP response received as a string.
The "param" parameter is not used.
This indicator value is valid only for responses that are HTTP-based.

  • RESPONSE_HTTP_STATUSTEXT

Returns the status text from the HTTP response received as a string.
The "param" parameter is not used.
This indicator value is valid only for responses that are HTTP-based.

  • RESPONSE_TEXT_AS_XML

Parses the entire response text as XML, evaluates an XPath expression for that XML, and returns the result of that XPath expression.
The "param" parameter contains the XPath expression.
This indicator value is valid only for responses that are not HTTP-based.
If no nodes in the XML match, null is returned.  If there are one or more matching nodes, a string array is returned.  (An array is returned even if there is only one match.)

  • RESPONSE_TEXT_AS_HTML

Parses the entire response text as HTML, evaluates an XPath expression for that HTML, and returns the result of that XPath expression.
The "param" parameter contains the XPath expression.
This indicator value is valid only for responses that are not HTTP-based.
If no nodes in the HTML match, null is returned. If there are one or more matching nodes, a string array is returned. (An array is returned even if there is only one match.)

  • RESPONSE_TEXT_AS_JSON

Parses the entire response text as JSON, evaluates an XPath expression for that XML, and returns the result of that XPath expression.
The "param" parameter contains the XPath expression.
This indicator value is valid only for responses that are not HTTP-based.
If no item in the JSON match, null is returned. If there are one or more matching nodes, a string array is returned. (An array is returned even if there is only one match.)

  • RESPONSE_HTTP_BODY_AS_XML

Parses the body of the HTTP response received as XML, evaluates an XPath expression for that XML, and returns the result of that XPath expression.
The "param" parameter contains the XPath expression.
This indicator value is valid only for responses that are HTTP-based.
If no nodes in the XML match, null is returned.  If there are one or more matching nodes, a string array is returned.  (An array is returned even if there is only one match.)

If the "indicator" parameter is omitted, null or undefined, "RESPONSE_TEXT" will be assumed.

String or String[] getResponse(int indicator, string param)

getMessage

  • String getMessage(int indicator)

Returns all or the specified portion of the message that is to be sent.
The "indicator" parameter must be one of the following:

  • MESSAGE_TEXT

Returns the entire text of the message that is to be sent.
This indicator value is valid only for messages that are not HTTP-based.

  • MESSAGE_HTTP_BODY

Returns the body of the HTTP message that is to be sent.
This indicator value is valid only for messages that are HTTP-based.

  • MESSAGE_HTTP_HEADERS

The current value of the (optional) HTTP headers to be sent with the message is returned.  Can be null.  A text string is returned with new-lines between the HTTP headers.
This indicator value is valid only for messages that are HTTP-based.
If the "indicator" parameter is omitted, null or undefined, "MESSAGE_HTTP_BODY" will be assumed for HTTP-based messages, or "MESSAGE_TEXT" will be assumed for non-HTTP-based messages.

  

setMessage Method

Sets all or the specified portion of the message that is to be sent.
The "value" parameter is the value to be placed into the message.
The "indicator" parameter must be one of the following:

  • MESSAGE_TEXT

Sets the entire text of the message that is to be sent from the "value" parameter.
This indicator value is valid only for messages that are not HTTP-based.

  • MESSAGE_HTTP_BODY

Sets the body of the HTTP message that is to be sent from the "value" parameter.
This indicator value is valid only for messages that are HTTP-based.

  • MESSAGE_HTTP_HEADERS

The "value" parameter contains the (optional) HTTP headers to be sent with the message.  Can be null.  The value should be a text string with new-lines between the HTTP headers.
This indicator value is valid only for messages that are HTTP-based.

If the "indicator" parameter is omitted, null or undefined, "MESSAGE_HTTP_BODY" will be assumed for HTTP-based messages, or "MESSAGE_TEXT" will be assumed for non-HTTP-based messages.

String setMessage(string value, int indicator)

endRepeat

Requests that repeating for this Message be ended. If this Message is not currently playing, no action is taken.

Note that this is not an “abort” – repeating will be ended after any current individual repeat play of this Message completes.

This method is permitted for serial repeating only, it is not supported for parallel repeating and an error will be generated if it is attempted to call this method for a parallel repeat.

void endRepeat()

getResourceLinksFromHTMLResponse

This method allows a Script to scan any HTML response for resource URLs.

If the response to this Message is HTML, the HTML is parsed and any links on the HTML page to external resources are extracted and returned as an array of URLs.

If there is no response, or the response is not HTML, null is returned.

String[] getResourceLinksFromHTMLResponse()

0