General Elements of Actions

Introduction

This document describes the building elements of HTTP actions in general.

General XML Formats

• Action element:

  • Each command is a single root  <action>  element.
  • The  type  attribute selects which action class to execute (for example  ComposerSetPinValueAction ).
  • Additional attributes (and, for some actions, child elements) carry the action's parameters.

  <action type="ActionTypeName"
          Param1="value1"
          Param2="value2">
      <!-- Optional nested parameter content -->
  </action>
  

• Response element:

  • Every action returns a single  <response>  element.
  •  Code="0"  indicates success; any non-zero  Code  indicates an error.
  •  Message  contains a human-readable description (for example  "OK"  or an error explanation).
  • For read actions and write actions that return data, an optional  <ReturnValue>  element carries the payload.

  <response Code="0" Message="OK">
      <ReturnValue><!-- action-specific data --></ReturnValue>
  </response>
  

Document selector

Document-scoped actions accept an optional  Document  attribute:

• Omitted or empty: the currently running compound document.
•  @ : the currently active document in the Composer UI.
• Explicit file path: must match the file path of a compound document that is already open in Composer; otherwise the action fails with a document-not-found style error.

In the request XML examples below,  Document="doc_selector"  is a placeholder: use  @ , the full path of an open document, or omit the attribute.

Module paths

Actions that take a  Module  parameter (and other attributes that refer to a module path in the same way) accept absolute or relative paths:

• Absolute path: if the path starts with  Root&#92; , it is resolved from the document root.
•  Root  (exact): if the path equals  Root  (no trailing segment), it designates the root compound of the document.
• Relative path: if the path is not exactly  Root , and does not start with  Root&#92; , it is resolved relative to the context compound (the compound currently in focus in the editor for that document).
• Empty path: designates the context compound itself.
•  .  and  .. : may appear in paths to mean the current compound and the parent compound, respectively.

Pin value string formats ( Value )

The  Value  attribute used by  ComposerSetPinValueAction  and  ComposerSetCtrBoardPropertyValueAction  accepts the following user-facing string formats.

• Numeric separator: use  .  as decimal separator.
• Whitespace around comma-separated components is accepted.
• Enums ( type  shown as  baseType, EnumType ):
  • Use the enum element internal name ( name  from  ComposerGetEnumInfoAction ).
  • Numeric values can also work for enum-backed pins.
  • Empty string selects the enum's first element.

Accepted formats by pin value type name:

Special cases used by actions in this contract:

•  byte[]  values are represented as Base64 text.
• Arrays of simple types ( string[] ,  int[] , etc.) are represented as comma-separated lists, where each list element must use that element type's normal string format.

For any other/custom pin type, use the format expected by that pin type.

Action Categories

• Read actions only query information from the current Composer state and do not modify documents, modules, pins, MOS objects, or runtime state.
• Write actions modify Composer state, such as:
  • opening / closing / restarting documents or the application,
  • changing pin or sequence values,
  • pressing or changing control board buttons,
  • starting / stopping MOS object runners,
  • or performing any other side-effect on the running compound or engine.

Undo behavior for graph modifications

• Graph modification actions (module, pin, and control board modifications) are executed in an undoable manner and appear in Composer's Undo History.
• The exceptions are  ComposerSetPinValueAction  and  ComposerSetCtrBoardPropertyValueAction  for backward compatibility:
  • each has an  Undoable  parameter,
  •  Undoable  defaults to  false ,
• Composite means a series of operations that appears as a single item in Composer's Undo History, so the whole series can be undone in one step.
• To make multiple graph-modifying actions appear as one undo item, call  ComposerBeginCompositeAction  before the first action and call  ComposerFinishCompositeAction  after the last on the same document (or  ComposerFinishAllCompositesAction  to close several documents at once).

Pin Actions

Control board panels: When reading or writing values exposed on a control board panel (user-facing "properties" of the panel module), do not use the pin actions in this section. Use  ComposerEnumCtrBoardPropertiesAction ,  ComposerSetCtrBoardPropertyValueAction , and  ComposerGetCtrBoardPropertyValueAction  instead of  ComposerEnumPinsAction ,  ComposerGetModuleInfoAction  (for that purpose),  ComposerSetPinValueAction , and  ComposerGetPinValueAction , respectively.

Control Board Actions

For control board panels, prefer the CtrBoard property actions ( ComposerEnumCtrBoardPropertiesAction ,  ComposerSetCtrBoardPropertyValueAction ,  ComposerGetCtrBoardPropertyValueAction ) over generic pin enumeration and pin value actions ( ComposerEnumPinsAction ,  ComposerGetModuleInfoAction ,  ComposerSetPinValueAction ,  ComposerGetPinValueAction ). The property actions understand exposer pin descriptors,  $SelSub  /  $SelSubSeq  associated pins, and  $Redir  redirection (see below).