aes70 1.6.2 → 2.0.0

package/src/controller/ControlClasses/OcaMatrix.d.ts

@@ -1,51 +1,30 @@
+import { OcaCommandResult } from '../../types/OcaCommandResult';
+import { IOcaMatrixCommand } from '../../types/OcaMatrixCommand';
+import { IOcaMatrixCoordinates } from '../../types/OcaMatrixCoordinates';
+import { IOcaMethodID } from '../../types/OcaMethodID';
 import { Arguments } from '../arguments';
 import { PropertyEvent } from '../property_event';
 import { RemoteDevice } from '../remote_device';
 import { OcaWorker } from './OcaWorker';
 
 /**
- * A matrix is a rectangular array of identical objects ("**members**") that is
- * coordinate addressable and has sets of common input and output ports. The
- * matrix host does not instantiate these objects, but instead mediates the
- * coordinate addressing, implements the common input and output ports, and
- * provdes certain other aggregate functions. Matrix members may be workers
- * (including blocks), or agents. All members of a matrix must be of the same
- * class. No object may belong to more than one matrix at a time. No object may
- * appear more than once in a given matrix. The complete model of an OCA matrix
- * consists of: 1. One instance of **OcaMatrix.** 2. **(N x M) members**, where
- * each member is an instance of a worker or agent class. For any given matrix,
- * this class must be the same for all members, and is referred to as the
- * **member class.** Members are sometimes referred to as **cells** of the
- * matrix. 3. One additional instance of the member class, called the **matrix
- * proxy.** Thus, the **OcaMatrix** instance is a container for the
- * two-dimensional collection of its members. Once a matrix is set up, the
- * controller may get and set member properties by the following procedures:
- * **Get** To get a property value of member (x :sub:`1`, y :sub:`1`): 1.
- * Controller calls **OcaMatrix.SetXY(x1, y1)**. This action: - locks the
- * **OcaMatrix** instance, and - posts x :sub:`1` and y :sub:`1` as coordinates
- * of the object whose property value is to be retrieved. 2. Controller calls
- * the matrix proxy's **Get** method for the property value desired. This action
- * causes the **OcaMatrix** instance to: - decode the posted x :sub:`1` and y
- * :sub:`1` values into a member ONo. - call the given **Get** method for the
- * object identified by the decoded ONo. - aggregate the **OcaResult** from each
- * **Get** call into a consolidated **OcaResult**. - unlock the **OcaMatrix**
- * instance. - return the consolidated **OcaResult** to the controller. **Set**
- * ** **To set a property value of member (x :sub:`1`, y :sub:`1`), or of row
- * (0, y :sub:`1`) or column (x :sub:`1`, 0) or whole matrix (0,0) 1. Controller
- * calls **OcaMatrix.SetXY(x1, y1)**. This action: - locks the **OcaMatrix**
- * instance, and - posts x :sub:`1` and y :sub:`1` as coordinates of the object
- * whose property value is to be changed. 2. Controller calls the matrix proxy's
- * **Set** method for the target property. This action causes the **OcaMatrix**
- * instance to: - decode the posted x :sub:`1` and y :sub:`1` values into a list
- * of target member ONos, as follows: If x :sub:`1` ``>`` 0 and y :sub:`1` ``>``
- * 0, the list will be the single ONo of the addressed cell. If x :sub:`1` = 0
- * and y :sub:`1` ``>`` 0, the list will be the list of ONos of the cells in row
- * y :sub:`1` . If x :sub:`1` ``>`` 0 and y :sub:`1` = 0, the list will be the
- * list of ONos of the cells in column x :sub:`1`. If x :sub:`1` = 0 and y
- * :sub:`1` = 0, the list will be the list of ONos of all cells of the matrix. -
- * call the given **Set** method for each target member in the ONo list. -
- * aggregate the **OcaResult** from each **Set** call into a consolidated
- * **OcaResult**. - unlock the **OcaMatrix** instance.
+ * Rectangular array of identical objects (**Matrix Members,** or just****
+ * **Members** in context) that is coordinate addressable and has sets of common
+ * input and output ports. An **OcaMatrix** instance is a container for a
+ * two-dimensional collection of members. Matrix members may be workers
+ * (including blocks or other matrices), or agents. All members of a given
+ * matrix shall be of the same class (*the* **member class**). No object shall
+ * belong to more than one matrix at a time. No object shall appear more than
+ * once in a given matrix. The **OcaMatrix** object shall not instantiate the
+ * Members, but instead shall provide the coordinate addressing, implement the
+ * common input and output ports, and provide certain other aggregate functions.
+ * The term M**atrix** means an **OcaMatrix** object *plus* the ancillary
+ * objects that collectively provide matrixing functionality. Specifically, a
+ * Matrix shall consists of: 1. One instance of the **OcaMatrix** class (the
+ * **matrix object**); and 2. **(N x M) members**, where each member shall be an
+ * instance of the member class; and The normative specification of the
+ * **OcaMatrix** class is here. The normative specification of the overall
+ * Matrix mechanism, with informative examples, is in [AES70-1(Matrices)].
  * @extends OcaWorker
  * @class OcaMatrix
  */
@@ -80,22 +59,12 @@ export declare class OcaMatrix extends OcaWorker {
    */
   OnProxyChanged: PropertyEvent<number>;
 
-  /**
-   * This event is emitted whenever PortsPerRow changes.
-   */
-  OnPortsPerRowChanged: PropertyEvent<number>;
-
-  /**
-   * This event is emitted whenever PortsPerColumn changes.
-   */
-  OnPortsPerColumnChanged: PropertyEvent<number>;
-
   constructor(objectNumber: number, device: RemoteDevice);
 
   /**
    * Gets coordinates of the currently active area (cell, row, column, or whole
-   * matrix). The returned status indicates whether the operation was
-   * successful.
+   * matrix). See the definitions of the properties **X** and **Y** for
+   * specification of X and Y values.
    * The return values of this method are
    *
    * - x of type ``number``
@@ -107,8 +76,12 @@ export declare class OcaMatrix extends OcaWorker {
   GetCurrentXY(): Promise<Arguments<[number, number]>>;
 
   /**
-   * Sets the currently active area (cell, row, column, or whole matrix). The
-   * returned status indicates whether the operation was successful.
+   * Sets the currently active area (cell, row, column, or whole matrix).
+   * Automatically locks the **OcaMatrix** object and the Matrix Proxy object.
+   * Does not lock the addressed matrix Members. Locks shall persist until any
+   * matrix proxy method is called in the same Control Session. See the
+   * definitions of the properties **X** and **Y** for specification of X and Y
+   * values.
    *
    * @method OcaMatrix#SetCurrentXY
    * @param {number} x
@@ -119,8 +92,7 @@ export declare class OcaMatrix extends OcaWorker {
   SetCurrentXY(x: number, y: number): Promise<void>;
 
   /**
-   * Gets the matrix size. The returned status indicates whether the operation
-   * was successful.
+   * Gets the matrix size.
    * The return values of this method are
    *
    * - xSize of type ``number``
@@ -138,8 +110,8 @@ export declare class OcaMatrix extends OcaWorker {
   >;
 
   /**
-   * Sets the matrix size. The returned status indicates whether the operation
-   * was successful. This method will not be available for fixed-size matrices.
+   * Sets the matrix size. This method will not be available for fixed-size
+   * matrices.
    *
    * @method OcaMatrix#SetSize
    * @param {number} xSize
@@ -150,8 +122,8 @@ export declare class OcaMatrix extends OcaWorker {
   SetSize(xSize: number, ySize: number): Promise<void>;
 
   /**
-   * Retrieves the 2D array of member object numbers. Cells for which no member
-   * has been defined will return Zero as the object number.
+   * Retrieves the 2D array of Member ONos. Cells for which no Member has been
+   * provided will contain the value zero.
    *
    * @method OcaMatrix#GetMembers
    * @returns {Promise<number[][]>}
@@ -160,8 +132,10 @@ export declare class OcaMatrix extends OcaWorker {
   GetMembers(): Promise<number[][]>;
 
   /**
-   * Sets the entire 2D array of member object numbers. Row and column size of
-   * the **members** parameter must be equal to the current size of the matrix.
+   * Sets the entire 2D array of Member Object Numbers. Row and column
+   * dimensions of the M**embers** parameter shall be equal to the current row
+   * and column counts of the Matrix. In the list, a Member Object Number value
+   * of zero shall remove any Member at the given position.
    *
    * @method OcaMatrix#SetMembers
    * @param {number[][]} members
@@ -171,8 +145,8 @@ export declare class OcaMatrix extends OcaWorker {
   SetMembers(members: number[][]): Promise<void>;
 
   /**
-   * Retrieves the object number of the member at position (x,y). If no member
-   * is defined at this position, returns an object number value of Zero.
+   * Retrieves the object number of the Member at position (x,y). If no Member
+   * is defined at this position, shall return the value zero.
    *
    * @method OcaMatrix#GetMember
    * @param {number} x
@@ -184,8 +158,10 @@ export declare class OcaMatrix extends OcaWorker {
   GetMember(x: number, y: number): Promise<number>;
 
   /**
-   * Installs a particular object as a member at position (x,y). If another
-   * object was at this position, it is removed.
+   * Installs a particular object as a Member at position (x,y). If another
+   * object is already at this position, it is replaced. If value of the
+   * **memberONo** parameter is zero, any object already at this position is
+   * removed and not replaced.
    *
    * @method OcaMatrix#SetMember
    * @param {number} x
@@ -197,7 +173,7 @@ export declare class OcaMatrix extends OcaWorker {
   SetMember(x: number, y: number, memberONo: number): Promise<void>;
 
   /**
-   * Gets the object number of the matrix proxy.
+   * Gets the object number of the Matrix Proxy.
    *
    * @method OcaMatrix#GetProxy
    * @returns {Promise<number>}
@@ -206,7 +182,7 @@ export declare class OcaMatrix extends OcaWorker {
   GetProxy(): Promise<number>;
 
   /**
-   * Sets the object number of the matrix proxy.
+   * Sets the object number of the Matrix Proxy.
    *
    * @method OcaMatrix#SetProxy
    * @param {number} ONo
@@ -216,7 +192,7 @@ export declare class OcaMatrix extends OcaWorker {
   SetProxy(ONo: number): Promise<void>;
 
   /**
-   * Gets the number of ports per row. These are input ports.
+   * Gets the number of Ports per row. Note: these are Input Ports.
    *
    * @method OcaMatrix#GetPortsPerRow
    * @returns {Promise<number>}
@@ -225,7 +201,7 @@ export declare class OcaMatrix extends OcaWorker {
   GetPortsPerRow(): Promise<number>;
 
   /**
-   * Sets the number of ports per row. These must be input ports.
+   * Sets the number of Ports per row. These shall be Input Ports.
    *
    * @method OcaMatrix#SetPortsPerRow
    * @param {number} Ports
@@ -235,7 +211,7 @@ export declare class OcaMatrix extends OcaWorker {
   SetPortsPerRow(Ports: number): Promise<void>;
 
   /**
-   * Gets the number of ports per output channel. These are output ports.
+   * Gets the number of Ports per column. Note: these are Output Ports.
    *
    * @method OcaMatrix#GetPortsPerColumn
    * @returns {Promise<number>}
@@ -244,7 +220,7 @@ export declare class OcaMatrix extends OcaWorker {
   GetPortsPerColumn(): Promise<number>;
 
   /**
-   * Sets the number of ports per column. These must be output ports.
+   * Sets the number of Ports per column. These shall be Output Ports.
    *
    * @method OcaMatrix#SetPortsPerColumn
    * @param {number} Ports
@@ -254,9 +230,15 @@ export declare class OcaMatrix extends OcaWorker {
   SetPortsPerColumn(Ports: number): Promise<void>;
 
   /**
-   * Sets the currently active area (cell, row, column, or whole matrix) and
-   * locks it. Fails if the referenced members cannot all be locked. The
-   * returned status indicates whether the operation was successful.
+   * Sets the currently active area (cell, row, column, or whole matrix), locks
+   * the **OcaMatrix** object, locks the Matrix Proxy object, and locks all the
+   * Members in the active area. Fails if the referenced members cannot all be
+   * locked. The **OcaMatrix** and Matrix Proxy locks shall persist until any
+   * Matrix Proxy method is called in the same Control Session. The Member locks
+   * shall persist until unlocked by calls to their **Unlock()** methods or by a
+   * call to the **OcaMatrix** method **UnlockCurrent**. The returned status
+   * indicates whether the operation was successful. See the definitions of the
+   * properties **X** and **Y** for specification of X and Y values.
    *
    * @method OcaMatrix#SetCurrentXYLock
    * @param {number} x
@@ -267,14 +249,54 @@ export declare class OcaMatrix extends OcaWorker {
   SetCurrentXYLock(x: number, y: number): Promise<void>;
 
   /**
-   * Unlocks the currently active area of the matrix. Fails if all the members
-   * of the currently active area cannot be unlocked. Failure is not triggered
-   * if one or more members of the currently active area are already unlocked at
-   * the time Unlock() is called. The returned status indicates whether the
-   * operation was successful.
+   * Unlocks the Member objects in the currently active area of the Matrix.
+   * Succeeds only if all the Members of the currently active area can be
+   * unlocked. Failure shall not be**** triggered if one or more Members of the
+   * currently active area are already unlocked. The returned status indicates
+   * whether the operation was successful.
    *
    * @method OcaMatrix#UnlockCurrent
    * @returns {Promise<void>}
    */
   UnlockCurrent(): Promise<void>;
+
+  /**
+   * Execute the same method in various Matrix Members with a common set of
+   * input parameters. Return the status and returned parameter values from each
+   * call. When an addressed Member is a Block, this method shall not be capable
+   * of executing methods of objects inside the Block. The **OcaStatus** value
+   * returned by this** ExecuteMethods(...)** method shall be as follows: **OK
+   * ** Requested methods were called; all, none, or some of them succeeded.
+   * **<anything else>** Problem, no method calls were attempted
+   *
+   * @method OcaMatrix#ExecuteMethod
+   * @param {IOcaMatrixCoordinates[]} TargetMembers
+   * @param {IOcaMethodID} TargetMethod
+   * @param {Uint8Array[]} InData
+   *
+   * @returns {Promise<OcaCommandResult[]>}
+   *   A promise which resolves to a single value of type :class:`OcaCommandResult[]`.
+   */
+  ExecuteMethod(
+    TargetMembers: IOcaMatrixCoordinates[],
+    TargetMethod: IOcaMethodID,
+    InData: Uint8Array[]
+  ): Promise<OcaCommandResult[]>;
+
+  /**
+   * Execute various methods in various Matrix Members with individual parameter
+   * sets for each. Return the status and returned parameter values, if any,
+   * from each call. When an addressed Member is a Block, this method shall not
+   * be capable of executing methods of objects inside the Block. The
+   * **OcaStatus** value returned by this** ExecuteMethods(...)** method shall
+   * be as follows: **OK ** Requested methods were called; all, none, or some of
+   * them succeeded. **<anything else>** Problem, no method calls were attempted
+   *
+   * @method OcaMatrix#ExecuteCommands
+   * @param {IOcaMatrixCommand[]} Commands
+   *
+   * @returns {Promise<OcaCommandResult[]>}
+   *   A promise which resolves to a single value of type :class:`OcaCommandResult[]`.
+   */
+  ExecuteCommands(Commands: IOcaMatrixCommand[]): Promise<OcaCommandResult[]>;
 }