docs: Document plugin api event

2024-08-30 18:12:16 +00:00 · 2021-12-14 18:33:50 -08:00 · 2021-12-14 18:33:50 -08:00 · 2e7262fe11
commit 2e7262fe11
parent 5f261de143
4 changed files with 152 additions and 12 deletions
--- a/docs/generated/protocol.json
+++ b/docs/generated/protocol.json
@ -1171,6 +1171,48 @@
      ],
      "responseFields": []
    },
+    {
+      "description": "Call a request registered to a vendor.\n\nA vendor is a unique name registered by a third-party plugin or script, which allows for custom requests and events to be added to obs-websocket.\nIf a plugin or script implements vendor requests or events, documentation is expected to be provided with them.",
+      "requestType": "CallVendorRequest",
+      "complexity": 3,
+      "rpcVersion": "1",
+      "deprecated": false,
+      "initialVersion": "5.0.0",
+      "category": "general",
+      "requestFields": [
+        {
+          "valueName": "vendorName",
+          "valueType": "String",
+          "valueDescription": "Name of the vendor to use",
+          "valueRestrictions": null,
+          "valueOptional": false,
+          "valueOptionalBehavior": null
+        },
+        {
+          "valueName": "requestType",
+          "valueType": "String",
+          "valueDescription": "The request type to call",
+          "valueRestrictions": null,
+          "valueOptional": false,
+          "valueOptionalBehavior": null
+        },
+        {
+          "valueName": "requestData",
+          "valueType": "Object",
+          "valueDescription": "Object containing appropriate request data",
+          "valueRestrictions": null,
+          "valueOptional": true,
+          "valueOptionalBehavior": "{}"
+        }
+      ],
+      "responseFields": [
+        {
+          "valueName": "responseData",
+          "valueType": "Object",
+          "valueDescription": "Object containing appropriate response data. {} if request does not provide any response data"
+        }
+      ]
+    },
    {
      "description": "Gets an array of all hotkey names in OBS",
      "requestType": "GetHotkeyList",
@ -2348,6 +2390,33 @@
          "valueDescription": "True == Enabled, False == Disabled"
        }
      ]
+    },
+    {
+      "description": "An event has been emitted from a vendor.\n\nA vendor is a unique name registered by a third-party plugin or script, which allows for custom requests and events to be added to obs-websocket.\nIf a plugin or script implements vendor requests or events, documentation is expected to be provided with them.",
+      "eventType": "VendorEvent",
+      "eventSubscription": "ExternalPlugins",
+      "complexity": 3,
+      "rpcVersion": "1",
+      "deprecated": false,
+      "initialVersion": "5.0.0",
+      "category": "general",
+      "dataFields": [
+        {
+          "valueName": "vendorName",
+          "valueType": "String",
+          "valueDescription": "Name of the vendor emitting the event"
+        },
+        {
+          "valueName": "eventType",
+          "valueType": "String",
+          "valueDescription": "Vendor-provided event typedef"
+        },
+        {
+          "valueName": "eventData",
+          "valueType": "Object",
+          "valueDescription": "Vendor-provided event data. {} if event does not provide any data"
+        }
+      ]
    }
  ]
 }
--- a/docs/generated/protocol.md
+++ b/docs/generated/protocol.md
@ -1220,6 +1220,7 @@ Subscription value to receive the `SceneItemTransformChanged` high-volume event.
 - [General](#general)
  - [ExitStarted](#exitstarted)
  - [StudioModeStateChanged](#studiomodestatechanged)
+  - [VendorEvent](#vendorevent)
 - [Config](#config)
  - [CurrentSceneCollectionChanging](#currentscenecollectionchanging)
  - [CurrentSceneCollectionChanged](#currentscenecollectionchanged)
@ -1255,6 +1256,28 @@ Studio mode has been enabled or disabled.
 | Name | Type  | Description |
 | ---- | :---: | ----------- |
 | studioModeEnabled | Boolean | True == Enabled, False == Disabled |
+
+---
+
+### VendorEvent
+
+An event has been emitted from a vendor.
+
+A vendor is a unique name registered by a third-party plugin or script, which allows for custom requests and events to be added to obs-websocket.
+If a plugin or script implements vendor requests or events, documentation is expected to be provided with them.
+
+- Complexity Rating: `3/5`
+- Latest Supported RPC Version: `1`
+- Added in v5.0.0
+
+
+**Data Fields:**
+
+| Name | Type  | Description |
+| ---- | :---: | ----------- |
+| vendorName | String | Name of the vendor emitting the event |
+| eventType | String | Vendor-provided event typedef |
+| eventData | Object | Vendor-provided event data. {} if event does not provide any data |
 ## Config

 ### CurrentSceneCollectionChanging
@ -1370,6 +1393,7 @@ The profile list has changed.
  - [GetVersion](#getversion)
  - [GetStats](#getstats)
  - [BroadcastCustomEvent](#broadcastcustomevent)
+  - [CallVendorRequest](#callvendorrequest)
  - [GetHotkeyList](#gethotkeylist)
  - [TriggerHotkeyByName](#triggerhotkeybyname)
  - [TriggerHotkeyByKeySequence](#triggerhotkeybykeysequence)
@ -1494,6 +1518,35 @@ Broadcasts a `CustomEvent` to all WebSocket clients. Receivers are clients which

 ---

+### CallVendorRequest
+
+Call a request registered to a vendor.
+
+A vendor is a unique name registered by a third-party plugin or script, which allows for custom requests and events to be added to obs-websocket.
+If a plugin or script implements vendor requests or events, documentation is expected to be provided with them.
+
+- Complexity Rating: `3/5`
+- Latest Supported RPC Version: `1`
+- Added in v5.0.0
+
+
+**Request Fields:**
+
+| Name | Type  | Description | Value Restrictions | ?Default Behavior |
+| ---- | :---: | ----------- | :----------------: | ----------------- |
+| vendorName | String | Name of the vendor to use | None | N/A |
+| requestType | String | The request type to call | None | N/A |
+| ?requestData | Object | Object containing appropriate request data | None | {} |
+
+
+**Response Fields:**
+
+| Name | Type  | Description |
+| ---- | :---: | ----------- |
+| responseData | Object | Object containing appropriate response data. {} if request does not provide any response data |
+
+---
+
 ### GetHotkeyList

 Gets an array of all hotkey names in OBS
--- a/src/obs-websocket.cpp
+++ b/src/obs-websocket.cpp
@ -129,6 +129,35 @@ bool IsDebugEnabled()
 	return !_config || _config->DebugEnabled;
 }

+void ___source_dummy_addref(obs_source_t*) {}
+void ___weak_source_dummy_addref(obs_weak_source_t*) {}
+void ___scene_dummy_addref(obs_scene_t*) {}
+void ___sceneitem_dummy_addref(obs_sceneitem_t*) {}
+void ___data_dummy_addref(obs_data_t*) {}
+void ___data_array_dummy_addref(obs_data_array_t*) {}
+void ___output_dummy_addref(obs_output_t*) {}
+void ___data_item_dummy_addref(obs_data_item_t*) {}
+void ___data_item_release(obs_data_item_t* dataItem){ obs_data_item_release(&dataItem); }
+void ___properties_dummy_addref(obs_properties_t*) {}
+
+/**
+ * An event has been emitted from a vendor. 
+ *
+ * A vendor is a unique name registered by a third-party plugin or script, which allows for custom requests and events to be added to obs-websocket.
+ * If a plugin or script implements vendor requests or events, documentation is expected to be provided with them.
+ *
+ * @dataField vendorName | String | Name of the vendor emitting the event
+ * @dataField eventType  | String | Vendor-provided event typedef
+ * @dataField eventData  | Object | Vendor-provided event data. {} if event does not provide any data
+ *
+ * @eventSubscription ExternalPlugins
+ * @eventType VendorEvent
+ * @complexity 3
+ * @rpcVersion -1
+ * @initialVersion 5.0.0
+ * @api events
+ * @category general
+ */
 void WebSocketApiEventCallback(std::string vendorName, std::string eventType, obs_data_t *obsEventData)
 {
 	json eventData = Utils::Json::ObsDataToJson(obsEventData);
@ -141,17 +170,6 @@ void WebSocketApiEventCallback(std::string vendorName, std::string eventType, ob
 	_webSocketServer->BroadcastEvent(EventSubscription::ExternalPlugins, "VendorEvent", broadcastEventData);
 }

-void ___source_dummy_addref(obs_source_t*) {}
-void ___weak_source_dummy_addref(obs_weak_source_t*) {}
-void ___scene_dummy_addref(obs_scene_t*) {}
-void ___sceneitem_dummy_addref(obs_sceneitem_t*) {}
-void ___data_dummy_addref(obs_data_t*) {}
-void ___data_array_dummy_addref(obs_data_array_t*) {}
-void ___output_dummy_addref(obs_output_t*) {}
-void ___data_item_dummy_addref(obs_data_item_t*) {}
-void ___data_item_release(obs_data_item_t* dataItem){ obs_data_item_release(&dataItem); }
-void ___properties_dummy_addref(obs_properties_t*) {}
-

 #define PLUGIN_API_TEST
 #ifdef PLUGIN_API_TEST
--- a/src/requesthandler/RequestHandler_General.cpp
+++ b/src/requesthandler/RequestHandler_General.cpp
@ -129,7 +129,7 @@ RequestResult RequestHandler::BroadcastCustomEvent(const Request& request)
 * @requestField requestType  | String | The request type to call
 * @requestField ?requestData | Object | Object containing appropriate request data | {}
 *
- * @responseField responseData | Object | Object containing appropriate response data. May be null if vendor request does not implement responses
+ * @responseField responseData | Object | Object containing appropriate response data. {} if request does not provide any response data
 *
 * @requestType CallVendorRequest
 * @complexity 3