@iobroker/socket-classes 1.2.0 → 1.3.2

package/README.md

@@ -63,12 +63,66 @@ io.start(server.server, ws, {userKey: 'connect.sid', checkUser, store, secret: a
 io.close();
 ```
 
+## GUI subscribes
+GUI client can send to desired instance the `subscribe` message
+```
+    socket.emit('clientSubscribe', 'cameras.0', 'startCamera', {width: 640, height: 480}, result => console.log('Started: ' + result));
+```
+
+The instance 'cameras.0' will receive message `clientSubscribe` with information who want to receive messages.
+```
+adapter.on('message', obj => {
+    if (obj?.command === 'clientSubscribe') {
+        if (obj?.message.type && obj.message.type.startsWith('startCamera/')) {
+            const [, camera] = obj.message.type.split('/');
+            // start camera with obj.message.data
+            // ...
+            
+            // inform GUI that camera is started
+            adapter.sendTo(obj.from, obj.command, {result: true}, obj.callback);
+            this.subscribes = this.subscribes || [];
+            this.subscribes.push({sid: obj.message.sid, from: obj.from, type: obj.message.type, camera});
+        }
+    } else
+    if (obj?.command === 'clientUnsubscribe' || obj?.command === 'clientSubscribeError') {
+        if (obj?.message.type && obj.message.type.startsWith('startCamera/')) {
+            const [, camera] = obj.message.type.split('/');
+            if (this.subscribes) {
+                const pos = this.subscribes.findIndex(s => s.sid === obj.message.sid && s.from === obj.from && s.type === obj.message.type);
+                if (pos !== -1) {
+                    this.subscribes.splice(pos, 1);
+
+                    // stop camera
+                    // ...
+                }
+            }
+        }
+    }
+});
+```
+
+and after that client will receive messages from instance
+
+```
+function sendImage(camera, data) {
+    this.subscribes.forEach(it => {
+        if (it.camera !== camera) {
+            return;
+        }
+        // send image to GUI
+        adapter.sendTo(it.from, 'im', {m: it.type, s: it.sid, d: data});
+    });
+}
+```
+
+
 ## Web Methods
 <!-- WEB_METHODS_START -->
 ### List of commands
 * [authenticate](#authenticate_w)
 * [error](#error_w)
 * [log](#log_w)
+* [checkFeatureSupported](#checkfeaturesupported_w)
 * [getHistory](#gethistory_w)
 * [httpGet](#httpget_w)
 * [sendTo](#sendto_w)
@@ -86,6 +140,8 @@ io.close();
 * [getObjectView](#getobjectview_w)
 * [setObject](#setobject_w)
 * [delObject](#delobject_w)
+* [clientSubscribe](#clientsubscribe_w)
+* [clientUnsubscribe](#clientunsubscribe_w)
 * [getStates](#getstates_w)
 * [getForeignStates](#getforeignstates_w)
 * [getState](#getstate_w)
@@ -128,6 +184,11 @@ Write log entry into ioBroker log
 * text *(string)*: log text
 * level *(string)*: one of `['silly', 'debug', 'info', 'warn', 'error']`. Default is 'debug'.
 
+### <a name="checkfeaturesupported_w"></a>checkFeatureSupported(feature, callback)
+Checks, if the same feature is supported by the current js-controller
+* feature *(string)*: feature name like `CONTROLLER_LICENSE_MANAGER`
+* callback *(function)*: `function (error, isSupported)`
+
 ### <a name="gethistory_w"></a>getHistory(id, options, callback)
 Get history data from specific instance
 * id *(string)*: object ID
@@ -218,6 +279,19 @@ Delete object. Only deletion of flot objects is allowed
 * options *(string)*: ignored
 * callback *(function)*: `function (error)`
 
+### <a name="clientsubscribe_w"></a>clientSubscribe(targetInstance, messageType, data, callback)
+Client informs specific instance about subscription on its messages. After subscription the socket will receive "im" messages from desired instance
+* targetInstance *(string)*: instance name, e.g. "cameras.0"
+* messageType *(string)*: message type, e.g. "startRecording/cam1"
+* data *(object)*: optional data object, e.g. {width: 640, height: 480}
+* callback *(function)*: `function (error, result)`, target instance MUST acknowledge the subscription and return some object as result
+
+### <a name="clientunsubscribe_w"></a>clientUnsubscribe(targetInstance, messageType, callback)
+Client unsubscribes from specific instance's messages
+* targetInstance *(string)*: instance name, e.g. "cameras.0"
+* messageType *(string)*: message type, e.g. "startRecording/cam1"
+* callback *(function)*: `function (error, wasSubscribed)`, target instance MUST NOT acknowledge the un-subscription
+
 ### <a name="getstates_w"></a>getStates(pattern, callback)
 Read states by pattern
 * pattern *(string)*: optional pattern, like `system.adapter.*` or array of state IDs
@@ -273,19 +347,19 @@ Unsubscribe from state changes by pattern. Same as `unsubscribe`.
 ### <a name="readfile_w"></a>readFile(_adapter, fileName, callback)
 Read file from ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* fileName *(string)*: file name, e.g `main/vis-views.json`
+* fileName *(string)*: file name, e.g. `main/vis-views.json`
 * callback *(function)*: `function (error, data, mimeType)`
 
 ### <a name="readfile64_w"></a>readFile64(_adapter, fileName, callback)
 Read file from ioBroker DB as base64 string
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* fileName *(string)*: file name, e.g `main/vis-views.json`
+* fileName *(string)*: file name, e.g. `main/vis-views.json`
 * callback *(function)*: `function (error, base64, mimeType)`
 
 ### <a name="writefile64_w"></a>writeFile64(_adapter, fileName, data64, options, callback)
 Write file into ioBroker DB as base64 string
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* fileName *(string)*: file name, e.g `main/vis-views.json`
+* fileName *(string)*: file name, e.g. `main/vis-views.json`
 * data64 *(string)*: file content as base64 string
 * options *(object)*: optional `{mode: 0x0644}`
 * callback *(function)*: `function (error)`
@@ -293,7 +367,7 @@ Write file into ioBroker DB as base64 string
 ### <a name="writefile_w"></a>writeFile(_adapter, fileName, data, options, callback)
 Write file into ioBroker DB as text **DEPRECATED**
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* fileName *(string)*: file name, e.g `main/vis-views.json`
+* fileName *(string)*: file name, e.g. `main/vis-views.json`
 * data64 *(string)*: file content as base64 string
 * options *(object)*: optional `{mode: 0x644}`
 * callback *(function)*: `function (error)`
@@ -301,83 +375,83 @@ Write file into ioBroker DB as text **DEPRECATED**
 ### <a name="unlink_w"></a>unlink(_adapter, name, callback)
 Delete file in ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* name *(string)*: file name, e.g `main/vis-views.json`
+* name *(string)*: file name, e.g. `main/vis-views.json`
 * callback *(function)*: `function (error)`
 
 ### <a name="deletefile_w"></a>deleteFile(_adapter, name, callback)
 Delete file in ioBroker DB (same as unlink, but only for files)
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* name *(string)*: file name, e.g `main/vis-views.json`
+* name *(string)*: file name, e.g. `main/vis-views.json`
 * callback *(function)*: `function (error)`
 
 ### <a name="deletefolder_w"></a>deleteFolder(_adapter, name, callback)
 Delete file in ioBroker DB (same as unlink, but only for folders)
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* name *(string)*: folder name, e.g `main`
+* name *(string)*: folder name, e.g. `main`
 * callback *(function)*: `function (error)`
 
 ### <a name="renamefile_w"></a>renameFile(_adapter, oldName, newName, callback)
 Rename file in ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* oldName *(string)*: current file name, e.g `main/vis-views.json`
-* newName *(string)*: new file name, e.g `main/vis-views-new.json`
+* oldName *(string)*: current file name, e.g. `main/vis-views.json`
+* newName *(string)*: new file name, e.g. `main/vis-views-new.json`
 * callback *(function)*: `function (error)`
 
 ### <a name="rename_w"></a>rename(_adapter, oldName, newName, callback)
 Rename file or folder in ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* oldName *(string)*: current file name, e.g `main/vis-views.json`
-* newName *(string)*: new file name, e.g `main/vis-views-new.json`
+* oldName *(string)*: current file name, e.g. `main/vis-views.json`
+* newName *(string)*: new file name, e.g. `main/vis-views-new.json`
 * callback *(function)*: `function (error)`
 
 ### <a name="mkdir_w"></a>mkdir(_adapter, dirName, callback)
 Create folder in ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* dirName *(string)*: desired folder name, e.g `main`
+* dirName *(string)*: desired folder name, e.g. `main`
 * callback *(function)*: `function (error)`
 
 ### <a name="readdir_w"></a>readDir(_adapter, dirName, options, callback)
 Read content of folder in ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* dirName *(string)*: folder name, e.g `main`
+* dirName *(string)*: folder name, e.g. `main`
 * options *(object)*: optional `{filter: '*'}` or `{filter: '*.json'}`
 * callback *(function)*: `function (error, files)` where `files` is an array of objects, like `{file: 'vis-views.json', isDir: false, stats: {size: 123}, modifiedAt: 1661336290090, acl: {owner: 'system.user.admin', ownerGroup: 'system.group.administrator', permissions: 1632, read: true, write: true}`
 
 ### <a name="chmodfile_w"></a>chmodFile(_adapter, fileName, options, callback)
 Change file mode in ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* fileName *(string)*: file name, e.g `main/vis-views.json`
+* fileName *(string)*: file name, e.g. `main/vis-views.json`
 * options *(object)*: `{mode: 0x644}` or 0x644. The first digit is user, second group, third others. Bit 1 is `execute`, bit 2 is `write`, bit 3 is `read`
 * callback *(function)*: `function (error)`
 
 ### <a name="chownfile_w"></a>chownFile(_adapter, fileName, options, callback)
 Change file owner in ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* fileName *(string)*: file name, e.g `main/vis-views.json`
+* fileName *(string)*: file name, e.g. `main/vis-views.json`
 * options *(object)*: `{owner: 'system.user.user', ownerGroup: ''system.group.administrator'}` or 'system.user.user'. If ownerGroup is not defined, it will be taken from owner.
 * callback *(function)*: `function (error)`
 
 ### <a name="fileexists_w"></a>fileExists(_adapter, fileName, callback)
 Check if the file or folder exists in ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* fileName *(string)*: file name, e.g `main/vis-views.json`
+* fileName *(string)*: file name, e.g. `main/vis-views.json`
 * callback *(function)*: `function (error, isExist)`
 
 ### <a name="subscribefiles_w"></a>subscribeFiles(id, pattern, callback)
 Subscribe to file changes in ioBroker DB
 * id *(string)*: instance name, e.g. `vis.0` or any object ID of type `meta`. `id` could have wildcards `*` too.
-* pattern *(string)*: file name pattern, e.g `main/*.json`
+* pattern *(string)*: file name pattern, e.g. `main/*.json`
 * callback *(function)*: `function (error)`
 
 ### <a name="unsubscribefiles_w"></a>unsubscribeFiles(id, pattern, callback)
 Unsubscribe from file changes in ioBroker DB
 * id *(string)*: instance name, e.g. `vis.0` or any object ID of type `meta`. `id` could have wildcards `*` too.
-* pattern *(string)*: file name pattern, e.g `main/*.json`
+* pattern *(string)*: file name pattern, e.g. `main/*.json`
 * callback *(function)*: `function (error)`
 
 ### <a name="getadapterinstances_w"></a>getAdapterInstances(adapterName, callback)
 Read all instances of the given adapter, or all instances of all adapters if adapterName is not defined
-* adapterName *(string)*: optional adapter name, e.g `history`.
+* adapterName *(string)*: optional adapter name, e.g. `history`.
 * callback *(function)*: `function (error, instanceList)`, where instanceList is an array of instance objects, e.g. `{_id: 'system.adapter.history.0', common: {name: 'history', ...}, native: {...}}`
 
 <!-- WEB_METHODS_END -->
@@ -388,6 +462,7 @@ Read all instances of the given adapter, or all instances of all adapters if ada
 * [authenticate](#authenticate_a)
 * [error](#error_a)
 * [log](#log_a)
+* [checkFeatureSupported](#checkfeaturesupported_a)
 * [getHistory](#gethistory_a)
 * [httpGet](#httpget_a)
 * [sendTo](#sendto_a)
@@ -406,7 +481,6 @@ Read all instances of the given adapter, or all instances of all adapters if ada
 * [eventsThreshold](#eventsthreshold_a)
 * [getRatings](#getratings_a)
 * [getCurrentInstance](#getcurrentinstance_a)
-* [checkFeatureSupported](#checkfeaturesupported_a)
 * [decrypt](#decrypt_a)
 * [encrypt](#encrypt_a)
 * [getIsEasyModeStrict](#getiseasymodestrict_a)
@@ -432,6 +506,8 @@ Read all instances of the given adapter, or all instances of all adapters if ada
 * [getObjectView](#getobjectview_a)
 * [setObject](#setobject_a)
 * [delObject](#delobject_a)
+* [clientSubscribe](#clientsubscribe_a)
+* [clientUnsubscribe](#clientunsubscribe_a)
 * [getAllObjects](#getallobjects_a)
 * [extendObject](#extendobject_a)
 * [getForeignObjects](#getforeignobjects_a)
@@ -478,6 +554,11 @@ Write log entry into ioBroker log
 * text *(string)*: log text
 * level *(string)*: one of `['silly', 'debug', 'info', 'warn', 'error']`. Default is 'debug'.
 
+### <a name="checkfeaturesupported_a"></a>checkFeatureSupported(feature, callback)
+Checks, if the same feature is supported by the current js-controller
+* feature *(string)*: feature name like `CONTROLLER_LICENSE_MANAGER`
+* callback *(function)*: `function (error, isSupported)`
+
 ### <a name="gethistory_a"></a>getHistory(id, options, callback)
 Get history data from specific instance
 * id *(string)*: object ID
@@ -568,11 +649,6 @@ Read ratings of adapters
 Return current instance name like `admin.0`
 * callback *(function)*: `function (error, namespace)`
 
-### <a name="checkfeaturesupported_a"></a>checkFeatureSupported(feature, callback)
-Checks, if the same feature is supported by the current js-controller
-* feature *(string)*: feature name like `CONTROLLER_LICENSE_MANAGER`
-* callback *(function)*: `function (error, isSupported)`
-
 ### <a name="decrypt_a"></a>decrypt(encryptedText, callback)
 Decrypts text with the system secret key
 * encryptedText *(string)*: encrypted text
@@ -697,6 +773,19 @@ Delete an object or objects recursively. Objects with `dontDelete` cannot be del
 * options *(string)*: `{recursive: true}`
 * callback *(function)*: `function (error)`
 
+### <a name="clientsubscribe_a"></a>clientSubscribe(targetInstance, messageType, data, callback)
+Client informs specific instance about subscription on its messages. After subscription the socket will receive "im" messages from desired instance
+* targetInstance *(string)*: instance name, e.g. "cameras.0"
+* messageType *(string)*: message type, e.g. "startRecording/cam1"
+* data *(object)*: optional data object, e.g. {width: 640, height: 480}
+* callback *(function)*: `function (error, result)`, target instance MUST acknowledge the subscription and return some object as result
+
+### <a name="clientunsubscribe_a"></a>clientUnsubscribe(targetInstance, messageType, callback)
+Client unsubscribes from specific instance's messages
+* targetInstance *(string)*: instance name, e.g. "cameras.0"
+* messageType *(string)*: message type, e.g. "startRecording/cam1"
+* callback *(function)*: `function (error, wasSubscribed)`, target instance MUST NOT acknowledge the un-subscription
+
 ### <a name="getallobjects_a"></a>getAllObjects(callback)
 Read absolutely all objects
 * callback *(function)*: `function (error, objects)`, where `objects` is an object like `{'system.adapter.admin.0': {...}, 'system.adapter.web.0': {...}}`
@@ -774,19 +863,19 @@ Unsubscribe from state changes by pattern. Same as `unsubscribe`.
 ### <a name="readfile_a"></a>readFile(_adapter, fileName, callback)
 Read file from ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* fileName *(string)*: file name, e.g `main/vis-views.json`
+* fileName *(string)*: file name, e.g. `main/vis-views.json`
 * callback *(function)*: `function (error, data, mimeType)`
 
 ### <a name="readfile64_a"></a>readFile64(_adapter, fileName, callback)
 Read file from ioBroker DB as base64 string
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* fileName *(string)*: file name, e.g `main/vis-views.json`
+* fileName *(string)*: file name, e.g. `main/vis-views.json`
 * callback *(function)*: `function (error, base64, mimeType)`
 
 ### <a name="writefile64_a"></a>writeFile64(_adapter, fileName, data64, options, callback)
 Write file into ioBroker DB as base64 string
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* fileName *(string)*: file name, e.g `main/vis-views.json`
+* fileName *(string)*: file name, e.g. `main/vis-views.json`
 * data64 *(string)*: file content as base64 string
 * options *(object)*: optional `{mode: 0x0644}`
 * callback *(function)*: `function (error)`
@@ -802,83 +891,83 @@ Write file into ioBroker DB as base64 string
 ### <a name="unlink_a"></a>unlink(_adapter, name, callback)
 Delete file in ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* name *(string)*: file name, e.g `main/vis-views.json`
+* name *(string)*: file name, e.g. `main/vis-views.json`
 * callback *(function)*: `function (error)`
 
 ### <a name="deletefile_a"></a>deleteFile(_adapter, name, callback)
 Delete file in ioBroker DB (same as unlink, but only for files)
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* name *(string)*: file name, e.g `main/vis-views.json`
+* name *(string)*: file name, e.g. `main/vis-views.json`
 * callback *(function)*: `function (error)`
 
 ### <a name="deletefolder_a"></a>deleteFolder(_adapter, name, callback)
 Delete file in ioBroker DB (same as unlink, but only for folders)
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* name *(string)*: folder name, e.g `main`
+* name *(string)*: folder name, e.g. `main`
 * callback *(function)*: `function (error)`
 
 ### <a name="renamefile_a"></a>renameFile(_adapter, oldName, newName, callback)
 Rename file in ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* oldName *(string)*: current file name, e.g `main/vis-views.json`
-* newName *(string)*: new file name, e.g `main/vis-views-new.json`
+* oldName *(string)*: current file name, e.g. `main/vis-views.json`
+* newName *(string)*: new file name, e.g. `main/vis-views-new.json`
 * callback *(function)*: `function (error)`
 
 ### <a name="rename_a"></a>rename(_adapter, oldName, newName, callback)
 Rename file or folder in ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* oldName *(string)*: current file name, e.g `main/vis-views.json`
-* newName *(string)*: new file name, e.g `main/vis-views-new.json`
+* oldName *(string)*: current file name, e.g. `main/vis-views.json`
+* newName *(string)*: new file name, e.g. `main/vis-views-new.json`
 * callback *(function)*: `function (error)`
 
 ### <a name="mkdir_a"></a>mkdir(_adapter, dirName, callback)
 Create folder in ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* dirName *(string)*: desired folder name, e.g `main`
+* dirName *(string)*: desired folder name, e.g. `main`
 * callback *(function)*: `function (error)`
 
 ### <a name="readdir_a"></a>readDir(_adapter, dirName, options, callback)
 Read content of folder in ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* dirName *(string)*: folder name, e.g `main`
+* dirName *(string)*: folder name, e.g. `main`
 * options *(object)*: optional `{filter: '*'}` or `{filter: '*.json'}`
 * callback *(function)*: `function (error, files)` where `files` is an array of objects, like `{file: 'vis-views.json', isDir: false, stats: {size: 123}, modifiedAt: 1661336290090, acl: {owner: 'system.user.admin', ownerGroup: 'system.group.administrator', permissions: 1632, read: true, write: true}`
 
 ### <a name="chmodfile_a"></a>chmodFile(_adapter, fileName, options, callback)
 Change file mode in ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* fileName *(string)*: file name, e.g `main/vis-views.json`
+* fileName *(string)*: file name, e.g. `main/vis-views.json`
 * options *(object)*: `{mode: 0x644}` or 0x644. The first digit is user, second group, third others. Bit 1 is `execute`, bit 2 is `write`, bit 3 is `read`
 * callback *(function)*: `function (error)`
 
 ### <a name="chownfile_a"></a>chownFile(_adapter, fileName, options, callback)
 Change file owner in ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* fileName *(string)*: file name, e.g `main/vis-views.json`
+* fileName *(string)*: file name, e.g. `main/vis-views.json`
 * options *(object)*: `{owner: 'system.user.user', ownerGroup: ''system.group.administrator'}` or 'system.user.user'. If ownerGroup is not defined, it will be taken from owner.
 * callback *(function)*: `function (error)`
 
 ### <a name="fileexists_a"></a>fileExists(_adapter, fileName, callback)
 Check if the file or folder exists in ioBroker DB
 * _adapter *(string)*: instance name, e.g. `vis.0`
-* fileName *(string)*: file name, e.g `main/vis-views.json`
+* fileName *(string)*: file name, e.g. `main/vis-views.json`
 * callback *(function)*: `function (error, isExist)`
 
 ### <a name="subscribefiles_a"></a>subscribeFiles(id, pattern, callback)
 Subscribe to file changes in ioBroker DB
 * id *(string)*: instance name, e.g. `vis.0` or any object ID of type `meta`. `id` could have wildcards `*` too.
-* pattern *(string)*: file name pattern, e.g `main/*.json`
+* pattern *(string)*: file name pattern, e.g. `main/*.json`
 * callback *(function)*: `function (error)`
 
 ### <a name="unsubscribefiles_a"></a>unsubscribeFiles(id, pattern, callback)
 Unsubscribe from file changes in ioBroker DB
 * id *(string)*: instance name, e.g. `vis.0` or any object ID of type `meta`. `id` could have wildcards `*` too.
-* pattern *(string)*: file name pattern, e.g `main/*.json`
+* pattern *(string)*: file name pattern, e.g. `main/*.json`
 * callback *(function)*: `function (error)`
 
 ### <a name="getadapterinstances_a"></a>getAdapterInstances(adapterName, callback)
 Read all instances of the given adapter, or all instances of all adapters if adapterName is not defined
-* adapterName *(string)*: optional adapter name, e.g `history`.
+* adapterName *(string)*: optional adapter name, e.g. `history`.
 * callback *(function)*: `function (error, instanceList)`, where instanceList is an array of instance objects, e.g. `{_id: 'system.adapter.history.0', common: {name: 'history', ...}, native: {...}}`
 
 <!-- ADMIN_METHODS_END -->
@@ -889,6 +978,10 @@ Read all instances of the given adapter, or all instances of all adapters if ada
 -->
 
 ## Changelog
+### 1.3.2 (2023-08-01)
+* (bluefox) Implemented subscribes of a client on messages from specific instance
+* (bluefox) Moved checkFeatureSupported to regular connection and not only admin
+
 ### 1.2.0 (2023-07-07)
 * (foxriver76) fixed crash on invalid patterns with js-controller version 5
 * (bluefox) extended the getObjects function with the possibility to read the list of IDs
@@ -943,13 +1036,13 @@ Read all instances of the given adapter, or all instances of all adapters if ada
 * (bluefox) Do not show error with failed authentication
 
 ### 0.4.7 (2022-06-20)
-* (bluefox) Allowed to overload system language
+* (bluefox) Allowed overloading system language
 
 ### 0.4.6 (2022-06-20)
 * (bluefox) updated `passport`
 
 ### 0.4.5 (2022-06-20)
-* (bluefox) allow to run socket.io behind reverse proxy
+* (bluefox) allowed running socket.io behind reverse proxy
 
 ### 0.4.4 (2022-06-09)
 * (bluefox) Do not show requireLog message

package/lib/socketCommands.js

@@ -67,6 +67,7 @@ class SocketCommands {
         this.commands   = {};
         this.subscribes = {};
         this.logEnabled = false;
+        this.clientSubscribes = {};
 
         this._updateSession = updateSession;
 
@@ -230,6 +231,20 @@ class SocketCommands {
         return false;
     }
 
+    publishInstanceMessage(socket, sourceInstance, messageType, data) {
+        if (this.clientSubscribes[socket.id] &&
+            this.clientSubscribes[socket.id][sourceInstance] &&
+            this.clientSubscribes[socket.id][sourceInstance].includes(messageType)
+        ) {
+            socket.emit('im', messageType, sourceInstance, data);
+            return true;
+        } else {
+            // inform instance about missing subscription
+            this.adapter.sendTo(sourceInstance, 'clientSubscribeError', {type: messageType, sid: socket.id});
+            return false;
+        }
+    }
+
     _showSubscribes(socket, type) {
         if (socket && socket.subscribe) {
             const s = socket.subscribe[type] || [];
@@ -364,7 +379,7 @@ class SocketCommands {
                 }
             }
         } else if (key) {
-            // Remove pattern from global list
+            // Remove a pattern from a global list
             if (this.subscribes[type][key] !== undefined) {
                 this.subscribes[type][key]--;
                 if (this.subscribes[type][key] <= 0) {
@@ -451,6 +466,8 @@ class SocketCommands {
         if (!socket || !socket.subscribe) {
             return;
         }
+        // inform all instances about disconnected socket
+        this._informAboutDisconnect(socket.id);
 
         if (!type) {
             // all
@@ -646,6 +663,17 @@ class SocketCommands {
             }
         };
 
+        this.commands['checkFeatureSupported'] = (socket, feature, callback) => {
+            // Checks, if the same feature is supported by the current js-controller
+            // @param {string} feature - feature name like `CONTROLLER_LICENSE_MANAGER`
+            // @param {function} callback - `function (error, isSupported)`
+            if (feature === 'INSTANCE_MESSAGES') {
+                SocketCommands._fixCallback(callback, null, true);
+            } else {
+                SocketCommands._fixCallback(callback, null, this.adapter.supportsFeature && this.adapter.supportsFeature(feature));
+            }
+        };
+
         // new History
         this.commands['getHistory'] = (socket, id, options, callback) => {
             // Get history data from specific instance
@@ -832,7 +860,7 @@ class SocketCommands {
         this.commands['readFile'] = (socket, _adapter, fileName, callback) => {
             // Read file from ioBroker DB
             // @param {string} _adapter - instance name, e.g. `vis.0`
-            // @param {string} fileName - file name, e.g `main/vis-views.json`
+            // @param {string} fileName - file name, e.g. `main/vis-views.json`
             // @param {function} callback - `function (error, data, mimeType)`
             if (this._checkPermissions(socket, 'readFile', callback, fileName)) {
                 try {
@@ -848,7 +876,7 @@ class SocketCommands {
         this.commands['readFile64'] = (socket, _adapter, fileName, callback) => {
             // Read file from ioBroker DB as base64 string
             // @param {string} _adapter - instance name, e.g. `vis.0`
-            // @param {string} fileName - file name, e.g `main/vis-views.json`
+            // @param {string} fileName - file name, e.g. `main/vis-views.json`
             // @param {function} callback - `function (error, base64, mimeType)`
             if (this._checkPermissions(socket, 'readFile64', callback, fileName)) {
                 try {
@@ -887,7 +915,7 @@ class SocketCommands {
         this.commands['writeFile64'] = (socket, _adapter, fileName, data64, options, callback) => {
             // Write file into ioBroker DB as base64 string
             // @param {string} _adapter - instance name, e.g. `vis.0`
-            // @param {string} fileName - file name, e.g `main/vis-views.json`
+            // @param {string} fileName - file name, e.g. `main/vis-views.json`
             // @param {string} data64 - file content as base64 string
             // @param {object} options - optional `{mode: 0x0644}`
             // @param {function} callback - `function (error)`
@@ -920,7 +948,7 @@ class SocketCommands {
         this.commands['writeFile'] = (socket, _adapter, fileName, data, options, callback) => {
             // Write file into ioBroker DB as text **DEPRECATED**
             // @param {string} _adapter - instance name, e.g. `vis.0`
-            // @param {string} fileName - file name, e.g `main/vis-views.json`
+            // @param {string} fileName - file name, e.g. `main/vis-views.json`
             // @param {string} data64 - file content as base64 string
             // @param {object} options - optional `{mode: 0x644}`
             // @param {function} callback - `function (error)`
@@ -946,7 +974,7 @@ class SocketCommands {
         this.commands['unlink'] = (socket, _adapter, name, callback) => {
             // Delete file in ioBroker DB
             // @param {string} _adapter - instance name, e.g. `vis.0`
-            // @param {string} name - file name, e.g `main/vis-views.json`
+            // @param {string} name - file name, e.g. `main/vis-views.json`
             // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'unlink', callback, name)) {
                 try {
@@ -963,7 +991,7 @@ class SocketCommands {
         this.commands['deleteFile'] = (socket, _adapter, name, callback) => {
             // Delete file in ioBroker DB (same as unlink, but only for files)
             // @param {string} _adapter - instance name, e.g. `vis.0`
-            // @param {string} name - file name, e.g `main/vis-views.json`
+            // @param {string} name - file name, e.g. `main/vis-views.json`
             // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'unlink', callback, name)) {
                 try {
@@ -979,7 +1007,7 @@ class SocketCommands {
         this.commands['deleteFolder'] = (socket, _adapter, name, callback) => {
             // Delete file in ioBroker DB (same as unlink, but only for folders)
             // @param {string} _adapter - instance name, e.g. `vis.0`
-            // @param {string} name - folder name, e.g `main`
+            // @param {string} name - folder name, e.g. `main`
             // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'unlink', callback, name)) {
                 try {
@@ -996,8 +1024,8 @@ class SocketCommands {
         this.commands['renameFile'] = (socket, _adapter, oldName, newName, callback) => {
             // Rename file in ioBroker DB
             // @param {string} _adapter - instance name, e.g. `vis.0`
-            // @param {string} oldName - current file name, e.g `main/vis-views.json`
-            // @param {string} newName - new file name, e.g `main/vis-views-new.json`
+            // @param {string} oldName - current file name, e.g. `main/vis-views.json`
+            // @param {string} newName - new file name, e.g. `main/vis-views-new.json`
             // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'rename', callback, oldName)) {
                 try {
@@ -1013,8 +1041,8 @@ class SocketCommands {
         this.commands['rename'] = (socket, _adapter, oldName, newName, callback) => {
             // Rename file or folder in ioBroker DB
             // @param {string} _adapter - instance name, e.g. `vis.0`
-            // @param {string} oldName - current file name, e.g `main/vis-views.json`
-            // @param {string} newName - new file name, e.g `main/vis-views-new.json`
+            // @param {string} oldName - current file name, e.g. `main/vis-views.json`
+            // @param {string} newName - new file name, e.g. `main/vis-views-new.json`
             // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'rename', callback, oldName)) {
                 try {
@@ -1031,7 +1059,7 @@ class SocketCommands {
         this.commands['mkdir'] = (socket, _adapter, dirName, callback) => {
             // Create folder in ioBroker DB
             // @param {string} _adapter - instance name, e.g. `vis.0`
-            // @param {string} dirName - desired folder name, e.g `main`
+            // @param {string} dirName - desired folder name, e.g. `main`
             // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'mkdir', callback, dirName)) {
                 try {
@@ -1047,7 +1075,7 @@ class SocketCommands {
         this.commands['readDir'] = (socket, _adapter, dirName, options, callback) => {
             // Read content of folder in ioBroker DB
             // @param {string} _adapter - instance name, e.g. `vis.0`
-            // @param {string} dirName - folder name, e.g `main`
+            // @param {string} dirName - folder name, e.g. `main`
             // @param {object} options - optional `{filter: '*'}` or `{filter: '*.json'}`
             // @param {function} callback - `function (error, files)` where `files` is an array of objects, like `{file: 'vis-views.json', isDir: false, stats: {size: 123}, modifiedAt: 1661336290090, acl: {owner: 'system.user.admin', ownerGroup: 'system.group.administrator', permissions: 1632, read: true, write: true}`
             if (typeof options === 'function') {
@@ -1075,7 +1103,7 @@ class SocketCommands {
         this.commands['chmodFile'] = (socket, _adapter, fileName, options, callback) => {
             // Change file mode in ioBroker DB
             // @param {string} _adapter - instance name, e.g. `vis.0`
-            // @param {string} fileName - file name, e.g `main/vis-views.json`
+            // @param {string} fileName - file name, e.g. `main/vis-views.json`
             // @param {object} options - `{mode: 0x644}` or 0x644. The first digit is user, second group, third others. Bit 1 is `execute`, bit 2 is `write`, bit 3 is `read`
             // @param {function} callback - `function (error)`
             if (typeof options === 'function') {
@@ -1103,7 +1131,7 @@ class SocketCommands {
         this.commands['chownFile'] = (socket, _adapter, fileName, options, callback) => {
             // Change file owner in ioBroker DB
             // @param {string} _adapter - instance name, e.g. `vis.0`
-            // @param {string} fileName - file name, e.g `main/vis-views.json`
+            // @param {string} fileName - file name, e.g. `main/vis-views.json`
             // @param {object} options - `{owner: 'system.user.user', ownerGroup: ''system.group.administrator'}` or 'system.user.user'. If ownerGroup is not defined, it will be taken from owner.
             // @param {function} callback - `function (error)`
             if (this._checkPermissions(socket, 'chownFile', callback, fileName)) {
@@ -1122,7 +1150,7 @@ class SocketCommands {
         this.commands['fileExists'] = (socket, _adapter, fileName, callback) => {
             // Check if the file or folder exists in ioBroker DB
             // @param {string} _adapter - instance name, e.g. `vis.0`
-            // @param {string} fileName - file name, e.g `main/vis-views.json`
+            // @param {string} fileName - file name, e.g. `main/vis-views.json`
             // @param {function} callback - `function (error, isExist)`
             if (this._checkPermissions(socket, 'fileExists', callback, fileName)) {
                 try {
@@ -1138,7 +1166,7 @@ class SocketCommands {
         this.commands['subscribeFiles'] = (socket, id, pattern, callback) => {
             // Subscribe to file changes in ioBroker DB
             // @param {string} id - instance name, e.g. `vis.0` or any object ID of type `meta`. `id` could have wildcards `*` too.
-            // @param {string} pattern - file name pattern, e.g `main/*.json`
+            // @param {string} pattern - file name pattern, e.g. `main/*.json`
             // @param {function} callback - `function (error)`
             return this._subscribeFiles(socket, id, pattern, callback);
         }
@@ -1146,7 +1174,7 @@ class SocketCommands {
         this.commands['unsubscribeFiles'] = (socket, id, pattern, callback) => {
             // Unsubscribe from file changes in ioBroker DB
             // @param {string} id - instance name, e.g. `vis.0` or any object ID of type `meta`. `id` could have wildcards `*` too.
-            // @param {string} pattern - file name pattern, e.g `main/*.json`
+            // @param {string} pattern - file name pattern, e.g. `main/*.json`
             // @param {function} callback - `function (error)`
 
             return this._unsubscribeFiles(socket, id, pattern, callback);
@@ -1154,7 +1182,7 @@ class SocketCommands {
 
         this.commands['getAdapterInstances'] = (socket, adapterName, callback) => {
             // Read all instances of the given adapter, or all instances of all adapters if adapterName is not defined
-            // @param {string} adapterName - optional adapter name, e.g `history`.
+            // @param {string} adapterName - optional adapter name, e.g. `history`.
             // @param {function} callback - `function (error, instanceList)`, where instanceList is an array of instance objects, e.g. `{_id: 'system.adapter.history.0', common: {name: 'history', ...}, native: {...}}`
             if (typeof callback === 'function') {
                 if (this._checkPermissions(socket, 'getObject', callback)) {
@@ -1565,6 +1593,55 @@ class SocketCommands {
                 SocketCommands._fixCallback(callback, SocketCommands.ERROR_PERMISSION);
             }
         };
+
+        this.commands['clientSubscribe'] = (socket, targetInstance, messageType, data, callback) => {
+            // Client informs specific instance about subscription on its messages. After subscription the socket will receive "im" messages from desired instance
+            // @param {string} targetInstance - instance name, e.g. "cameras.0"
+            // @param {string} messageType - message type, e.g. "startRecording/cam1"
+            // @param {object} data - optional data object, e.g. {width: 640, height: 480}
+            // @param {function} callback - `function (error, result)`, target instance MUST acknowledge the subscription and return some object as result
+            if (typeof data === 'function') {
+                callback = data;
+                data = null;
+            }
+            if (!targetInstance.startsWith('system.adapter.')) {
+                targetInstance = `system.adapter.${targetInstance}`;
+            }
+            const sid = socket.id;
+            // GUI subscribes for messages from targetInstance
+            this.clientSubscribes[sid] = this.clientSubscribes[sid] || {};
+            this.clientSubscribes[sid][targetInstance] = this.clientSubscribes[sid][targetInstance] || [];
+            if (!this.clientSubscribes[sid][targetInstance].includes(messageType)) {
+                this.clientSubscribes[sid][targetInstance].push(messageType);
+            }
+            // inform instance about new subscription
+            this.adapter.sendTo(targetInstance, 'clientSubscribe', {type: messageType, sid, data}, result =>
+                SocketCommands._fixCallback(callback, null, result));
+        };
+
+        this.commands['clientUnsubscribe'] = (socket, targetInstance, messageType, callback) => {
+            // Client unsubscribes from specific instance's messages
+            // @param {string} targetInstance - instance name, e.g. "cameras.0"
+            // @param {string} messageType - message type, e.g. "startRecording/cam1"
+            // @param {function} callback - `function (error, wasSubscribed)`, target instance MUST NOT acknowledge the un-subscription
+            const sid = socket.id;
+            if (!targetInstance.startsWith('system.adapter.')) {
+                targetInstance = `system.adapter.${targetInstance}`;
+            }
+
+            // GUI unsubscribes for messages from targetInstance
+            if (this.clientSubscribes[sid] && this.clientSubscribes[sid][targetInstance]) {
+                const pos = this.clientSubscribes[sid][targetInstance].indexOf(messageType);
+                if (pos !== -1) {
+                    this.clientSubscribes[sid][targetInstance].splice(pos, 1);
+                    // inform instance about unsubscription
+                    this.adapter.sendTo(targetInstance, 'clientUnsubscribe', {type: [messageType], sid});
+                    SocketCommands._fixCallback(callback, null, true);
+                    return;
+                }
+            }
+            SocketCommands._fixCallback(callback, null, false);
+        };
     }
 
     _initCommands() {
@@ -1574,6 +1651,20 @@ class SocketCommands {
         this.__initCommandsFiles();
     }
 
+    _informAboutDisconnect(socketId) {
+        // say to all instances, that this socket was disconnected
+        if (this.clientSubscribes[socketId]) {
+            Object.keys(this.clientSubscribes[socketId]).forEach(targetInstance => {
+                this.adapter.sendTo(targetInstance, 'clientUnsubscribe', {
+                    message: this.clientSubscribes[socketId][targetInstance],
+                    sid: socketId,
+                    provider: this.adapter.namespace
+                });
+            });
+            delete this.clientSubscribes[socketId];
+        }
+    }
+
     applyCommands(socket) {
         Object.keys(this.commands)
             .forEach(command => socket.on(command, (...args) => {

package/lib/socketCommandsAdmin.js

@@ -810,13 +810,6 @@ class SocketCommandsAdmin extends SocketCommands {
             SocketCommands._fixCallback(callback, null, this.adapter.namespace);
         };
 
-        this.commands['checkFeatureSupported'] = (socket, feature, callback) => {
-            // Checks, if the same feature is supported by the current js-controller
-            // @param {string} feature - feature name like `CONTROLLER_LICENSE_MANAGER`
-            // @param {function} callback - `function (error, isSupported)`
-            SocketCommands._fixCallback(callback, null, this.adapter.supportsFeature && this.adapter.supportsFeature(feature));
-        };
-
         this.commands['decrypt'] = (socket, encryptedText, callback) => {
             // Decrypts text with the system secret key
             // @param {string} encryptedText - encrypted text

package/lib/socketCommon.js

@@ -65,7 +65,7 @@ class SocketCommon {
 
         this.settings.ttl = parseInt(this.settings.ttl, 10) || 3600;
 
-        // it can be used as client too for cloud
+        // it can be used as a client too for cloud
         if (socketClass) {
             if (!server.__inited) {
                 if (typeof socketClass.listen === 'function') {
@@ -88,7 +88,7 @@ class SocketCommon {
                 this.__initAuthentication(authOptions);
             }
 
-            // Enable cross domain access
+            // Enable cross-domain access
             // deprecated, because no more used in socket.io@4 only(in @2)
             if (this.settings.crossDomain && this.server.set) {
                 this.server.set('origins', '*:*');
@@ -111,9 +111,9 @@ class SocketCommon {
                 if ((error && error.message && error.message.includes('authentication failed') ||
                     (details && details.toString().includes('authentication failed')))
                 ) {
-                    this.adapter.log.debug(`Error: ${(error && error.message) || JSON.stringify(error)}${details ? ' - ' + details : ''}`);
+                    this.adapter.log.debug(`Error: ${(error && error.message) || JSON.stringify(error)}${details ? ` - ${details}` : ''}`);
                 } else {
-                    this.adapter.log.error(`Error: ${(error && error.message) || JSON.stringify(error)}${details ? ' - ' + details : ''}`);
+                    this.adapter.log.error(`Error: ${(error && error.message) || JSON.stringify(error)}${details ? ` - ${details}` : ''}`);
                 }
             }
         });
@@ -123,9 +123,9 @@ class SocketCommon {
             // ignore "failed connection" as it already shown
             if (!error || !error.message || !error.message.includes('failed connection')) {
                 if (error && error.message && error.message.includes('authentication failed')) {
-                    this.adapter.log.debug(`Error: ${(error && error.message) || JSON.stringify(error)}${details ? ' - ' + details : ''}`);
+                    this.adapter.log.debug(`Error: ${(error && error.message) || JSON.stringify(error)}${details ? ` - ${details}` : ''}`);
                 } else {
-                    this.adapter.log.error(`Error: ${(error && error.message) || JSON.stringify(error)}${details ? ' - ' + details : ''}`);
+                    this.adapter.log.error(`Error: ${(error && error.message) || JSON.stringify(error)}${details ? ` - ${details}` : ''}`);
                 }
             }
         });
@@ -201,17 +201,17 @@ class SocketCommon {
             return address;
         }
 
-        // check if address is IPv4
+        // check if the address is IPv4
         const addressParts = address.split('.');
         if (addressParts.length !== 4) {
             return null;
         }
 
-        // do we have settings for wild carded ips?
+        // do we have settings for wild-carded ips?
         const wildCardIps = Object.keys(whiteList).filter(key => key.includes('*'));
 
         if (!wildCardIps.length) {
-            // no wild carded ips => no ip configured
+            // no wild-carded ips => no ip configured
             return null;
         }
 
@@ -253,7 +253,7 @@ class SocketCommon {
                 });
 
                 if (whiteListAcl.user !== 'auth') {
-                    acl.user = 'system.user.' + whiteListAcl.user;
+                    acl.user = `system.user.${whiteListAcl.user}`;
                 }
             }
         }
@@ -391,6 +391,10 @@ class SocketCommon {
         return this.commands.publish(socket, type, id, obj);
     }
 
+    publishInstanceMessage(socket, sourceInstance, messageType, data) {
+        return this.commands.publishInstanceMessage(socket, sourceInstance, messageType, data);
+    }
+
     publishFile(socket, id, fileName, size) {
         return this.commands.publishFile(socket, id, fileName, size);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iobroker/socket-classes",
-  "version": "1.2.0",
+  "version": "1.3.2",
   "description": "ioBroker server-side web sockets",
   "author": {
     "name": "bluefox",
@@ -21,7 +21,7 @@
     "url": "https://github.com/ioBroker/ioBroker.socket-classes"
   },
   "dependencies": {
-    "@iobroker/adapter-core": "^2.6.8",
+    "@iobroker/adapter-core": "^3.0.3",
     "passport": "^0.6.0",
     "cookie-parser": "^1.4.6",
     "axios": "^1.4.0"