@iobroker/socket-classes 1.1.5 → 1.3.1

package/README.md

@@ -63,6 +63,59 @@ 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
@@ -86,6 +139,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)
@@ -140,22 +195,22 @@ Read content of HTTP(S) page server-side (without CORS and stuff)
 * callback *(function)*: `function (error, {status, statusText}, body)`
 
 ### <a name="sendto_w"></a>sendTo(adapterInstance, command, message, callback)
-Send message to specific instance
+Send the message to specific instance
 * adapterInstance *(string)*: instance name, e.g. `history.0`
 * command *(string)*: command name
-* message *(object)*: message is instance dependent
+* message *(object)*: the message is instance dependent
 * callback *(function)*: `function (result)`
 
 ### <a name="sendtohost_w"></a>sendToHost(host, command, message, callback)
-Send message to specific host.
-Host can answer following commands: `cmdExec, getRepository, getInstalled, getInstalledAdapter, getVersion, getDiagData, getLocationOnDisk, getDevList, getLogs, getHostInfo, delLogs, readDirAsZip, writeDirAsZip, readObjectsAsZip, writeObjectsAsZip, checkLogging, updateMultihost`.
+Send a message to the specific host.
+Host can answer to the following commands: `cmdExec, getRepository, getInstalled, getInstalledAdapter, getVersion, getDiagData, getLocationOnDisk, getDevList, getLogs, getHostInfo, delLogs, readDirAsZip, writeDirAsZip, readObjectsAsZip, writeObjectsAsZip, checkLogging, updateMultihost`.
 * host *(string)*: instance name, e.g. `history.0`
 * command *(string)*: command name
-* message *(object)*: message is command specific
+* message *(object)*: the message is command-specific
 * callback *(function)*: `function (result)`
 
 ### <a name="authenabled_w"></a>authEnabled(callback)
-Ask server is authentication enabled and if the user authenticated
+Ask server is authentication enabled, and if the user authenticated
 * callback *(function)*: `function (isAuthenticationUsed, userName)`
 
 ### <a name="logout_w"></a>logout(callback)
@@ -171,7 +226,7 @@ Get user permissions
 * callback *(function)*: `function (error, permissions)`
 
 ### <a name="getversion_w"></a>getVersion(callback)
-Get adapter version. Not the socket-classes version!
+Get the adapter version. Not the socket-classes version!
 * callback *(function)*: `function (error, adapterVersion, adapterName)`
 
 ### <a name="getadaptername_w"></a>getAdapterName(callback)
@@ -183,18 +238,19 @@ Get one object
 * id *(string)*: object ID.
 * callback *(function)*: `function (error, obj)`
 
-### <a name="getobjects_w"></a>getObjects(callback)
+### <a name="getobjects_w"></a>getObjects(list, callback)
 Get all objects that are relevant for web: all states and enums with rooms
 * id *(string)*: object ID.
+* list *(string[])*: optional list of IDs.
 * callback *(function)*: `function (error, obj)`
 
 ### <a name="subscribeobjects_w"></a>subscribeObjects(pattern, callback)
-Subscribe on object changes by pattern. The events will come as 'objectChange' events to the socket.
+Subscribe to object changes by pattern. The events will come as 'objectChange' events to the socket.
 * pattern *(string)*: pattern like 'system.adapter.*' or array of IDs like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
 * callback *(function)*: `function (error)`
 
 ### <a name="unsubscribeobjects_w"></a>unsubscribeObjects(pattern, callback)
-Unsubscribe on object changes by pattern.
+Unsubscribe from object changes by pattern.
 * pattern *(string)*: pattern like 'system.adapter.*' or array of IDs like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
 * callback *(function)*: `function (error)`
 
@@ -217,6 +273,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
@@ -224,7 +293,7 @@ Read states by pattern
 
 ### <a name="getforeignstates_w"></a>getForeignStates(pattern, callback)
 Read all states (which might not belong to this adapter) which match the given pattern
-* pattern *(string)*: pattern like
+* pattern *(string)*: pattern like `system.adapter.*` or array of state IDs
 * callback *(function)*: `function (error)`
 
 ### <a name="getstate_w"></a>getState(id, callback)
@@ -246,16 +315,16 @@ Read one binary state.
 ### <a name="setbinarystate_w"></a>setBinaryState(id, base64, callback)
 Write one binary state.
 * id *(string)*: State ID like, 'javascript.0.binary'
-* base64 *(string)*: State value as base64 string. Binary states has no acknowledge flag.
+* base64 *(string)*: State value as base64 string. Binary states have no acknowledged flag.
 * callback *(function)*: `function (error)`
 
 ### <a name="subscribe_w"></a>subscribe(pattern, callback)
-Subscribe on state changes by pattern. The events will come as 'stateChange' events to the socket.
+Subscribe to state changes by pattern. The events will come as 'stateChange' events to the socket.
 * pattern *(string)*: pattern like 'system.adapter.*' or array of states like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
 * callback *(function)*: `function (error)`
 
 ### <a name="subscribestates_w"></a>subscribeStates(pattern, callback)
-Subscribe on state changes by pattern. Same as `subscribe`. The events will come as 'stateChange' events to the socket.
+Subscribe to state changes by pattern. Same as `subscribe`. The events will come as 'stateChange' events to the socket.
 * pattern *(string)*: pattern like 'system.adapter.*' or array of states like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
 * callback *(function)*: `function (error)`
 
@@ -272,19 +341,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)`
@@ -292,7 +361,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)`
@@ -300,83 +369,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`
-* options *(object)*: `{mode: 0x644}` or 0x644. First digit is user, second group, third others. Bit 1 is `execute`, bit 2 is `write`, bit 3 is `read`
+* 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)
-Checks if the file or folder exists in ioBroker DB
+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 on file changes in ioBroker DB
+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 on file changes in ioBroker DB
+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 -->
@@ -431,6 +500,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)
@@ -489,22 +560,22 @@ Read content of HTTP(S) page server-side (without CORS and stuff)
 * callback *(function)*: `function (error, {status, statusText}, body)`
 
 ### <a name="sendto_a"></a>sendTo(adapterInstance, command, message, callback)
-Send message to specific instance
+Send the message to specific instance
 * adapterInstance *(string)*: instance name, e.g. `history.0`
 * command *(string)*: command name
-* message *(object)*: message is instance dependent
+* message *(object)*: the message is instance dependent
 * callback *(function)*: `function (result)`
 
 ### <a name="sendtohost_a"></a>sendToHost(host, command, message, callback)
-Send message to specific host.
-Host can answer following commands: `cmdExec, getRepository, getInstalled, getInstalledAdapter, getVersion, getDiagData, getLocationOnDisk, getDevList, getLogs, getHostInfo, delLogs, readDirAsZip, writeDirAsZip, readObjectsAsZip, writeObjectsAsZip, checkLogging, updateMultihost`.
+Send a message to the specific host.
+Host can answer to the following commands: `cmdExec, getRepository, getInstalled, getInstalledAdapter, getVersion, getDiagData, getLocationOnDisk, getDevList, getLogs, getHostInfo, delLogs, readDirAsZip, writeDirAsZip, readObjectsAsZip, writeObjectsAsZip, checkLogging, updateMultihost`.
 * host *(string)*: instance name, e.g. `history.0`
 * command *(string)*: command name
-* message *(object)*: message is command specific
+* message *(object)*: the message is command-specific
 * callback *(function)*: `function (result)`
 
 ### <a name="authenabled_a"></a>authEnabled(callback)
-Ask server is authentication enabled and if the user authenticated
+Ask server is authentication enabled, and if the user authenticated
 * callback *(function)*: `function (isAuthenticationUsed, userName)`
 
 ### <a name="logout_a"></a>logout(callback)
@@ -520,7 +591,7 @@ Get user permissions
 * callback *(function)*: `function (error, permissions)`
 
 ### <a name="getversion_a"></a>getVersion(callback)
-Get adapter version. Not the socket-classes version!
+Get the adapter version. Not the socket-classes version!
 * callback *(function)*: `function (error, adapterVersion, adapterName)`
 
 ### <a name="getadaptername_a"></a>getAdapterName(callback)
@@ -528,9 +599,9 @@ Get adapter name. Not the socket-classes version!
 * callback *(function)*: `function (error, adapterVersion)`
 
 ### <a name="gethostbyip_a"></a>getHostByIp(ip, callback)
-Read host object by IP address
+Read the host object by IP address
 * ip *(string)*: ip address. IPv4 or IPv6
-* callback *(function)*: `function (ip, obj)`. If host not found, obj is null
+* callback *(function)*: `function (ip, obj)`. If host is not found, obj is null
 
 ### <a name="requirelog_a"></a>requireLog(isEnabled, callback)
 Activate or deactivate logging events. Events will be sent to the socket as `log` event. Adapter must have `common.logTransporter = true`
@@ -543,19 +614,19 @@ Get logs file from given host
 * callback *(function)*: `function (error, files)`, where `files` is array of `{fileName: `log/hostname/transport/file`, size: 123}`
 
 ### <a name="delstate_a"></a>delState(id, callback)
-Delete state. Corresponding object will be deleted too.
+Delete state. The corresponding object will be deleted too.
 * id *(string)*: state ID
 * callback *(function)*: `function (error)`
 
 ### <a name="cmdexec_a"></a>cmdExec(host, id, cmd, callback)
-Execute shell command on host/controller. Following response commands are expected: ´cmdStdout, cmdStderr, cmdExit´
+Execute the shell command on host/controller. Following response commands are expected: ´cmdStdout, cmdStderr, cmdExit´
 * host *(string)*: host name, like 'system.host.raspberrypi'
 * id *(string)*: session ID, like `Date.now()´. This session ID will come in events `cmdStdout, cmdStderr, cmdExit`
 * cmd *(string)*: command
 * callback *(function)*: `function (error)`
 
 ### <a name="eventsthreshold_a"></a>eventsThreshold(isActive)
-Used only for admin to limit number of events to front-end.
+Used only for admin to the limited number of events to front-end.
 * isActive *(boolean)*: if true, then events will be limited
 
 ### <a name="getratings_a"></a>getRatings(update, callback)
@@ -568,17 +639,17 @@ Return current instance name like `admin.0`
 * callback *(function)*: `function (error, namespace)`
 
 ### <a name="checkfeaturesupported_a"></a>checkFeatureSupported(feature, callback)
-Checks if same feature is supported by current js-controller
+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 system secret key
+Decrypts text with the system secret key
 * encryptedText *(string)*: encrypted text
 * callback *(function)*: `function (error, decryptedText)`
 
 ### <a name="encrypt_a"></a>encrypt(plainText, callback)
-Encrypts text with system secret key
+Encrypts text with the system secret key
 * plainText *(string)*: normal text
 * callback *(function)*: `function (error, encryptedText)`
 
@@ -641,14 +712,14 @@ Delete existing user. Admin cannot be deleted.
 * callback *(function)*: `function (error)`
 
 ### <a name="addgroup_a"></a>addGroup(group, desc, acl, callback)
-Add new group.
+Add a new group.
 * group *(string)*: user name, like 'benjamin
 * desc *(string)*: optional description
 * acl *(object)*: optional access control list object, like `{"object":{"list":true,"read":true,"write":false,"delete":false},"state":{"list":true,"read":true,"write":true,"create":true,"delete":false},"users":{"list":true,"read":true,"write":false,"create":false,"delete":false},"other":{"execute":false,"http":true,"sendto":false},"file":{"list":true,"read":true,"write":false,"create":false,"delete":false}}`
 * callback *(function)*: `function (error)`
 
 ### <a name="delgroup_a"></a>delGroup(group, callback)
-Delete existing group. Administrator group cannot be deleted.
+Delete the existing group. Administrator group cannot be deleted.
 * group *(string)*: group name, like 'users`
 * callback *(function)*: `function (error)`
 
@@ -668,12 +739,12 @@ Read absolutely all objects. Same as `getAllObjects`.
 * callback *(function)*: `function (error, objects)`, where `objects` is an object like `{'system.adapter.admin.0': {...}, 'system.adapter.web.0': {...}}`
 
 ### <a name="subscribeobjects_a"></a>subscribeObjects(pattern, callback)
-Subscribe on object changes by pattern. The events will come as 'objectChange' events to the socket.
+Subscribe to object changes by pattern. The events will come as 'objectChange' events to the socket.
 * pattern *(string)*: pattern like 'system.adapter.*' or array of IDs like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
 * callback *(function)*: `function (error)`
 
 ### <a name="unsubscribeobjects_a"></a>unsubscribeObjects(pattern, callback)
-Unsubscribe on object changes by pattern.
+Unsubscribe from object changes by pattern.
 * pattern *(string)*: pattern like 'system.adapter.*' or array of IDs like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
 * callback *(function)*: `function (error)`
 
@@ -691,17 +762,30 @@ Set object.
 * callback *(function)*: `function (error)`
 
 ### <a name="delobject_a"></a>delObject(id, options, callback)
-Delete object or objects recursively. Objects with `dontDelete` cannot be deleted.
+Delete an object or objects recursively. Objects with `dontDelete` cannot be deleted.
 * id *(string)*: Object ID like, 'adapterName.0.channel'
 * 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': {...}}`
 
 ### <a name="extendobject_a"></a>extendObject(id, obj, callback)
-Extend existing object
+Extend the existing object
 * id *(string)*: object ID
 * obj *(object)*: new parts of the object, like `{common: {name: 'new name'}}`
 * callback *(function)*: `function (error)`
@@ -725,7 +809,7 @@ Read states by pattern
 
 ### <a name="getforeignstates_a"></a>getForeignStates(pattern, callback)
 Read all states (which might not belong to this adapter) which match the given pattern
-* pattern *(string)*: pattern like
+* pattern *(string)*: pattern like `system.adapter.*` or array of state IDs
 * callback *(function)*: `function (error)`
 
 ### <a name="getstate_a"></a>getState(id, callback)
@@ -747,16 +831,16 @@ Read one binary state.
 ### <a name="setbinarystate_a"></a>setBinaryState(id, base64, callback)
 Write one binary state.
 * id *(string)*: State ID like, 'javascript.0.binary'
-* base64 *(string)*: State value as base64 string. Binary states has no acknowledge flag.
+* base64 *(string)*: State value as base64 string. Binary states have no acknowledged flag.
 * callback *(function)*: `function (error)`
 
 ### <a name="subscribe_a"></a>subscribe(pattern, callback)
-Subscribe on state changes by pattern. The events will come as 'stateChange' events to the socket.
+Subscribe to state changes by pattern. The events will come as 'stateChange' events to the socket.
 * pattern *(string)*: pattern like 'system.adapter.*' or array of states like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
 * callback *(function)*: `function (error)`
 
 ### <a name="subscribestates_a"></a>subscribeStates(pattern, callback)
-Subscribe on state changes by pattern. Same as `subscribe`. The events will come as 'stateChange' events to the socket.
+Subscribe to state changes by pattern. Same as `subscribe`. The events will come as 'stateChange' events to the socket.
 * pattern *(string)*: pattern like 'system.adapter.*' or array of states like ['system.adapter.admin.0.memRss', 'system.adapter.admin.0.memHeapTotal']
 * callback *(function)*: `function (error)`
 
@@ -773,19 +857,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)`
@@ -801,83 +885,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`
-* options *(object)*: `{mode: 0x644}` or 0x644. First digit is user, second group, third others. Bit 1 is `execute`, bit 2 is `write`, bit 3 is `read`
+* 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)
-Checks if the file or folder exists in ioBroker DB
+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 on file changes in ioBroker DB
+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 on file changes in ioBroker DB
+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 -->
@@ -888,6 +972,13 @@ Read all instances of the given adapter, or all instances of all adapters if ada
 -->
 
 ## Changelog
+### 1.3.1 (2023-07-31)
+* (bluefox) Implemented subscribes of a client on messages from specific instance
+
+### 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
+
 ### 1.1.5 (2023-03-13)
 * (bluefox) Added command `name`