aes70 1.6.1 → 2.0.0

package/src/controller/notification_error.js

@@ -0,0 +1,62 @@
+import { Enum } from '../types/Enum.js';
+import { Enum8 } from '../OCP1/Enum8.js';
+import { OcaBoolean } from '../OCP1/OcaBoolean.js';
+import { OcaBlob } from '../OCP1/OcaBlob.js';
+
+export class OcaNotificationExceptionType extends Enum({
+  Unspecified: 0,
+  // Device canceled subscription
+  CanceledByDevice: 1,
+  // Object was deleted
+  ObjectDeleted: 2,
+  // Something went wrong in the Device.
+  DeviceError: 3,
+}) {}
+
+const OcaNotificationExceptionTypeDecoder = Enum8(OcaNotificationExceptionType);
+
+function parseNotificationExceptionData(buffer) {
+  const view = new DataView(buffer);
+  let pos = 0;
+
+  let type, try_again, data;
+
+  [pos, type] = OcaNotificationExceptionTypeDecoder.decodeFrom(view, pos);
+  [pos, try_again] = OcaBoolean.decodeFrom(view, pos);
+  [pos, data] = OcaBlob.decodeFrom(view, pos);
+
+  return [type, try_again, view];
+}
+
+/**
+ * Error raised by remove events via a notification
+ * exception.
+ *
+ * @property {Notification2} notification - The notification object.
+ * @property {OcaNotificationExceptionType} type - The notification exception type.
+ */
+export class NotificationError extends Error {
+  constructor(notification) {
+    super(`Notification failed with an exception.`);
+    this.name = 'aes70.NotificationError';
+    this.notification = notification;
+
+    try {
+      const [type, try_again, data] = parseNotificationExceptionData(
+        notification.parameters
+      );
+      this.type = type;
+      this.try_again = try_again;
+      this.data = data;
+    } catch (error) {
+      console.error('Failed to decode notification exception data.');
+      this.type = OcaNotificationExceptionType.Unspecified;
+      this.try_again = false;
+      this.data = null;
+    }
+  }
+
+  is_object_deleted() {
+    this.type === OcaNotificationExceptionType.ObjectDeleted;
+  }
+}

package/src/controller/observeProperty.js

@@ -94,6 +94,10 @@ export function observeProperty(o, property, callback) {
     console.warn('Unhandled event', value, changeType, eventId);
   };
 
+  const errorCallback = (error) => {
+    callback(false, error);
+  };
+
   let active = true;
   const event = property.event(o);
   const getter = property.getter(o);
@@ -102,14 +106,10 @@ export function observeProperty(o, property, callback) {
     throw new Error(`Not getter found for ${propertyName} in ${o.ClassName}`);
   }
 
+  let unsubscribe = null;
+
   if (event) {
-    const p = event.subscribe(eventCallback);
-    if (p) {
-      p.catch((error) => {
-        if (!active) return;
-        callback(false, error);
-      });
-    }
+    unsubscribe = event.subscribe(eventCallback, errorCallback);
   }
 
   getter((ok, result) => {
@@ -124,6 +124,6 @@ export function observeProperty(o, property, callback) {
 
   return () => {
     active = false;
-    if (event) event.unsubscribe(eventCallback);
+    if (unsubscribe) unsubscribe();
   };
 }

package/src/controller/property_event.js

@@ -21,21 +21,29 @@ export class PropertyEvent extends BaseEvent {
 
       const value = propertyType[0].decodeFrom(dataView, 0)[1];
 
-      this.handlers.forEach(function (callback) {
-        try {
-          callback.call(object, value, changeType, id);
-        } catch (e) {
-          error(e);
-        }
-      });
+      this.emit([value, changeType, id]);
     };
+    this.error_callback = (error) => {
+      this.emit_error(error);
+    };
+    this._unsubscribe = null;
   }
 
   do_subscribe() {
-    return this.object.OnPropertyChanged.subscribe(this.callback);
+    this._unsubscribe = this.object.OnPropertyChanged.subscribe(
+      this.callback,
+      this.error_callback
+    );
   }
 
-  do_unsubscribe(callback) {
-    return this.object.OnPropertyChanged.unsubscribe(this.callback);
+  do_unsubscribe() {
+    const unsubscribe = this._unsubscribe;
+    if (!unsubscribe) return;
+    this._unsubscribe = null;
+    try {
+      unsubscribe();
+    } catch (error) {
+      console.error('Unsubscribing PropertyChanged event failed: ', error);
+    }
   }
 }

package/src/controller/remote_device.js

@@ -16,6 +16,8 @@ import { OcaTaskManager } from './ControlClasses/OcaTaskManager.js';
 import { OcaCodingManager } from './ControlClasses/OcaCodingManager.js';
 import { OcaDiagnosticManager } from './ControlClasses/OcaDiagnosticManager.js';
 import { OcaBlock } from './ControlClasses/OcaBlock.js';
+import { RemoteError } from './remote_error.js';
+import { OcaStatus } from '../types/OcaStatus.js';
 import tree_to_rolemap from './tree_to_rolemap.js';
 
 import * as RemoteControlClasses from './ControlClasses.js';
@@ -23,6 +25,8 @@ import * as RemoteControlClasses from './ControlClasses.js';
 import { OcaManagerDefaultObjectNumbers } from '../types/OcaManagerDefaultObjectNumbers.js';
 import { OcaNotificationDeliveryMode } from '../types/OcaNotificationDeliveryMode.js';
 
+const emptyUint8Array = new Uint8Array(0);
+
 function eventToKey(event) {
   const ono = event.EmitterONo;
   const id = event.EventID;
@@ -38,6 +42,42 @@ const subscriberMethod = {
   },
 };
 
+class EventSubscription {
+  constructor(event, cb) {
+    this.event = event;
+    this.callbacks = [];
+    this.cb = cb;
+    this.subscribing = null;
+    this.version = 0;
+  }
+
+  add_callback(cb) {
+    this.callbacks.push(cb);
+  }
+
+  delete_callback(cb) {
+    this.callbacks = this.callbacks.filter((entry) => entry !== cb);
+  }
+
+  emit(ok, notification) {
+    this.callbacks.forEach((cb) => {
+      try {
+        cb(ok, notification);
+      } catch (error) {
+        console.log('Event handler threw an exception', error);
+      }
+    });
+  }
+
+  emit_error(error) {
+    this.emit(false, error);
+  }
+
+  has_subscribers() {
+    return this.callbacks.length !== 0;
+  }
+}
+
 /**
  * Controller class for a remote OCA device.
  *
@@ -54,13 +94,15 @@ export class RemoteDevice extends Events {
     this.objects = new Map();
     this.connection = connection;
     this._stackDebug = false;
+    this._supportsEV2 = undefined;
+    this._checkEV2Promise = undefined;
 
     connection.on('error', (e) => {
       this.emit('error', e);
     });
 
-    connection.on('close', (e) => {
-      this.emit('close', e);
+    connection.on('close', () => {
+      this.emit('close');
     });
 
     this.modules = [];
@@ -173,69 +215,128 @@ export class RemoteDevice extends Events {
     this.connection.close();
   }
 
-  send_command(cmd, returnType, callback) {
+  send_command(cmd, returnType, callback, name) {
     const stack = this._stackDebug ? new Error().stack : null;
-    return this.connection.send_command(cmd, returnType, callback, stack);
+    return this.connection.send_command(cmd, returnType, callback, stack, name);
   }
 
-  _doSubscribe(event) {
-    return this.SubscriptionManager.AddSubscription(
+  async _doSubscribe(event) {
+    const { _checkEV2Promise } = this;
+
+    if (_checkEV2Promise) await _checkEV2Promise;
+
+    const { _supportsEV2, SubscriptionManager } = this;
+
+    if (_supportsEV2 === undefined || _supportsEV2) {
+      const p = SubscriptionManager.AddSubscription2(
+        event,
+        OcaNotificationDeliveryMode.Normal,
+        emptyUint8Array
+      );
+
+      try {
+        if (_supportsEV2 === undefined) this._checkEV2Promise = p;
+        await p;
+        if (_supportsEV2 === undefined) {
+          this._supportsEV2 = true;
+        }
+        return 2;
+      } catch (err) {
+        if (!RemoteError.check_status(err, OcaStatus.NotImplemented)) {
+          throw err;
+        }
+        this._supportsEV2 = false;
+      } finally {
+        if (_supportsEV2 === undefined) {
+          this._checkEV2Promise = undefined;
+        }
+      }
+    }
+
+    await SubscriptionManager.AddSubscription(
       event,
       subscriberMethod,
-      new Uint8Array(0),
-      OcaNotificationDeliveryMode.Reliable,
-      new Uint8Array(0)
+      emptyUint8Array,
+      OcaNotificationDeliveryMode.Normal,
+      emptyUint8Array
     );
+    return 1;
+  }
+
+  _doUnsubscribe(info, event) {
+    if (info.version === 2) {
+      return this.SubscriptionManager.RemoveSubscription2(
+        event,
+        OcaNotificationDeliveryMode.Normal,
+        emptyUint8Array
+      );
+    } else if (info.version === 1) {
+      return this.SubscriptionManager.RemoveSubscription(
+        event,
+        subscriberMethod
+      );
+    } else {
+      // If this happens, the subscription failed. In this case
+      // there is also nothing to do here.
+    }
   }
 
-  async add_subscription(event, callback) {
+  add_subscription(event, callback) {
     if (this.connection.is_closed()) throw new Error('Connection was closed.');
 
     const key = eventToKey(event);
     const subscriptions = this.subscriptions;
 
-    {
-      const info = subscriptions.get(key);
+    let info = subscriptions.get(key);
 
-      if (info) {
-        info.callbacks.add(callback);
-        return true;
-      }
+    if (info) {
+      info.add_callback(callback);
+      return;
     }
 
     /* do the actual subscription */
 
-    const cb = (o) => {
+    const dropSubscribers = () => {
+      this.subscriptions.delete(key);
+      this.connection._removeSubscriber(event);
+    };
+
+    const cb = (ok, notification) => {
       const S = this.subscriptions.get(key);
       if (!S) {
         warn('Subscription lost.');
         return;
       }
-      const a = S.callbacks;
-      a.forEach(function (cb) {
-        try {
-          cb(o);
-        } catch (e) {
-          error(e);
-        }
-      });
+      S.emit(ok, notification);
+
+      if (!ok || notification.exception) {
+        dropSubscribers();
+      } else if (S.version > 0 && !S.has_subscribers()) {
+        dropSubscribers();
+        this._doUnsubscribe(S, event).catch((error) => {
+          console.error('Unsubscribe failed: ', error);
+        });
+      }
     };
 
     this.connection._addSubscriber(event, cb);
 
-    const info = {
-      callbacks: new Set([callback]),
-      callback: cb,
-    };
+    info = new EventSubscription(event, cb);
+
+    info.add_callback(callback);
 
     subscriptions.set(key, info);
 
-    try {
-      await this._doSubscribe(event);
-    } catch (err) {
-      subscriptions.delete(key);
-      throw err;
-    }
+    const p = this._doSubscribe(event);
+    p.then(
+      (version) => {
+        info.version = version;
+      },
+      (error) => {
+        info.emit_error(error);
+        dropSubscribers();
+      }
+    );
   }
 
   remove_subscription(event, callback) {
@@ -245,20 +346,7 @@ export class RemoteDevice extends Events {
 
     if (!info) return Promise.reject('Callback not registered.');
 
-    const a = info.callbacks;
-
-    a.delete(callback);
-
-    if (!a.size) {
-      this.connection._removeSubscriber(event);
-      this.subscriptions.delete(key);
-      return this.SubscriptionManager.RemoveSubscription(
-        event,
-        subscriberMethod
-      );
-    }
-
-    return Promise.resolve(true);
+    info.delete_callback(callback);
   }
 
   find_best_class(id) {

package/src/controller/tcp_connection.d.ts

@@ -2,13 +2,15 @@ import {
   ClientConnection,
   IClientConnectionOptions,
 } from './client_connection.js';
-import { Socket, NetConnectOpts } from 'net';
+import { Socket, NetConnectOpts } from 'node:net';
 
-export interface ITCPConnectionOptions
-  extends IClientConnectionOptions,
-    NetConnectOpts {
-  connectSignal?: AbortSignal;
-}
+export type ITCPConnectionOptions = IClientConnectionOptions &
+  NetConnectOpts & {
+    /**
+     * This AbortSignal can be used to abort a connection attempt.
+     */
+    connectSignal?: AbortSignal;
+  };
 
 /**
  * :class:`ClientConnection` subclass which implements OCP.1 with TCP

package/src/index.default.d.ts

@@ -15,6 +15,7 @@ export * from './controller/define_custom_class';
 export * from './controller/abstract_udp_connection';
 export * from './controller/fetch_device_content';
 export * from './controller/remote_error';
+export * from './controller/notification_error';
 
 import * as RemoteControlClasses from './controller/ControlClasses';
 import * as Types from './types';

package/src/index.default.js

@@ -17,6 +17,7 @@ export * from './controller/observeProperty.js';
 export * from './controller/PropertyObserver.js';
 export * from './controller/fetch_device_content.js';
 export * from './controller/remote_error.js';
+export * from './controller/notification_error.js';
 
 import * as RemoteControlClasses from './controller/ControlClasses.js';
 import * as Types from './types.js';

package/src/types/Enum.js

@@ -89,6 +89,10 @@ export function Enum(values) {
       return name;
     }
 
+    static hasValue(value) {
+      return getName(value) !== void 0;
+    }
+
     static getValue(name) {
       const value = getValue(name);
 
@@ -97,6 +101,10 @@ export function Enum(values) {
       return value;
     }
 
+    static hasName(name) {
+      return getValue(name) !== void 0;
+    }
+
     static values() {
       return values;
     }

package/src/types/OcaActionObjectSearchResult.d.ts

@@ -0,0 +1,73 @@
+/*
+ * This file has been generated.
+ */
+import {
+  IOcaObjectIdentification,
+  OcaObjectIdentification,
+} from './OcaObjectIdentification';
+
+export declare interface IOcaActionObjectSearchResult {
+  /**
+   * ONo & class identification of Action Object found
+   * @type OcaObjectIdentification
+   */
+  Identification: IOcaObjectIdentification;
+
+  /**
+   * Array of ONos leading from root to this Action Object's Owner
+   * @type number[]
+   */
+  ContainerPath: number[];
+
+  /**
+   * **Role** property of Action Object found
+   * @type string
+   */
+  Role: string;
+
+  /**
+   * **Label** property of Action Object found
+   * @type string
+   */
+  Label: string;
+}
+
+export declare class OcaActionObjectSearchResult
+  implements IOcaActionObjectSearchResult {
+  /**
+   * Result of Action Object search via the **FindActionObject...()** methods of
+   * **OcaBlock**. Dynamic format, form used depends on type of search and
+   * options.
+   * @class OcaActionObjectSearchResult
+   */
+  constructor(
+    Identification: OcaObjectIdentification,
+    ContainerPath: number[],
+    Role: string,
+    Label: string
+  );
+
+  /**
+   * ONo & class identification of Action Object found
+   * @type OcaObjectIdentification
+   */
+  Identification: OcaObjectIdentification;
+
+  /**
+   * Array of ONos leading from root to this Action Object's Owner
+   * @type number[]
+   */
+  ContainerPath: number[];
+
+  /**
+   * **Role** property of Action Object found
+   * @type string
+   */
+  Role: string;
+
+  /**
+   * **Label** property of Action Object found
+   * @type string
+   */
+  Label: string;
+}

package/src/types/OcaActionObjectSearchResult.js

@@ -0,0 +1,34 @@
+/*
+ * This file has been generated.
+ */
+
+export class OcaActionObjectSearchResult {
+  /**
+   * Result of Action Object search via the **FindActionObject...()** methods of
+   * **OcaBlock**. Dynamic format, form used depends on type of search and
+   * options.
+   * @class OcaActionObjectSearchResult
+   */
+  constructor(Identification, ContainerPath, Role, Label) {
+    /**
+     * ONo & class identification of Action Object found
+     * @type OcaObjectIdentification
+     */
+    this.Identification = Identification;
+    /**
+     * Array of ONos leading from root to this Action Object's Owner
+     * @type number[]
+     */
+    this.ContainerPath = ContainerPath;
+    /**
+     * **Role** property of Action Object found
+     * @type string
+     */
+    this.Role = Role;
+    /**
+     * **Label** property of Action Object found
+     * @type string
+     */
+    this.Label = Label;
+  }
+}

package/src/types/OcaActionObjectSearchResultFlags.d.ts

@@ -0,0 +1,37 @@
+/*
+ * This file has been generated.
+ */
+/**
+ * Bitset that specifies the fields to be returned by a search for Action
+ * Objects in a Block
+ * @enum {number}
+ * @readonly
+ */
+export declare const OcaActionObjectSearchResultFlags: {
+  /**
+   * Entry with value ``1``.
+   */
+  ONo: number;
+
+  /**
+   * Entry with value ``2``.
+   */
+  ClassIdentification: number;
+
+  /**
+   * Entry with value ``4``.
+   */
+  ContainerPath: number;
+
+  /**
+   * Entry with value ``8``.
+   */
+  Role: number;
+
+  /**
+   * Entry with value ``16``.
+   */
+  Label: number;
+};
+
+export declare type IOcaActionObjectSearchResultFlags = number;

package/src/types/OcaActionObjectSearchResultFlags.js

@@ -0,0 +1,52 @@
+/*
+ * This file has been generated.
+ */
+/**
+ * Bitset that specifies the fields to be returned by a search for Action
+ * Objects in a Block
+ * @enum {number}
+ * @readonly
+ */
+export const OcaActionObjectSearchResultFlags = {
+  ONo: 1,
+  ClassIdentification: 2,
+  ContainerPath: 4,
+  Role: 8,
+  Label: 16,
+};
+
+/**
+ * Entry with value ``1``.
+ * @type {number}
+ * @member ONo
+ * @memberof OcaActionObjectSearchResultFlags
+ * @static
+ */
+/**
+ * Entry with value ``2``.
+ * @type {number}
+ * @member ClassIdentification
+ * @memberof OcaActionObjectSearchResultFlags
+ * @static
+ */
+/**
+ * Entry with value ``4``.
+ * @type {number}
+ * @member ContainerPath
+ * @memberof OcaActionObjectSearchResultFlags
+ * @static
+ */
+/**
+ * Entry with value ``8``.
+ * @type {number}
+ * @member Role
+ * @memberof OcaActionObjectSearchResultFlags
+ * @static
+ */
+/**
+ * Entry with value ``16``.
+ * @type {number}
+ * @member Label
+ * @memberof OcaActionObjectSearchResultFlags
+ * @static
+ */

package/src/types/OcaApplicationNetworkCommand.d.ts

@@ -18,18 +18,6 @@ export class OcaApplicationNetworkCommand {
    * Singleton object corresponding to the entry with value ``2``.
    */
   static Start: OcaApplicationNetworkCommand;
-  /**
-   * Singleton object corresponding to the entry with value ``3``.
-   */
-  static Pause: OcaApplicationNetworkCommand;
-  /**
-   * Singleton object corresponding to the entry with value ``4``.
-   */
-  static Stop: OcaApplicationNetworkCommand;
-  /**
-   * Singleton object corresponding to the entry with value ``5``.
-   */
-  static Reset: OcaApplicationNetworkCommand;
 
   /**
    * Returns the numeric value of this enum entry.
@@ -57,12 +45,6 @@ export type IOcaApplicationNetworkCommand =
   | 'None'
   | 'Prepare'
   | 'Start'
-  | 'Pause'
-  | 'Stop'
-  | 'Reset'
   | 0
   | 1
-  | 2
-  | 3
-  | 4
-  | 5;
+  | 2;