docs(ci): Update generated docs - 6160c29 [skip ci]

docs/generated/protocol.md

@@ -20,6 +20,7 @@ obs-websocket provides a feature-rich RPC communication protocol, giving access
 - [Connecting to obs-websocket](#connecting-to-obs-websocket)
   - [Connection steps](#connection-steps)
   - [Creating an authentication string](#creating-an-authentication-string)
+  - [Status and close codes](#status-and-close-codes)
 - [Base message types](#message-types)
   - [Hello](#hello)
   - [Identify](#identify)
@@ -78,8 +79,8 @@ For this guide, we'll be using `supersecretpassword` as the password.
 The `authentication` object in `Hello` looks like this (example):
 ```json
 {
-    "challenge": "ztTBnnuqrqaKDzRM3xcVdbYm",
+    "challenge": "+IxH4CnCiqpX1rM9scsNynZzbOe4KhDeYcTNS3PDaeY=",
-    "salt": "PZVbYpvAnZut2SS6JNJytDm9"
+    "salt": "lM1GncleQOaCu9lT1yeUZhFYnqhsLLP1G5lAGo3ixaI="
 }
 ```
 
@@ -91,44 +92,371 @@ To generate the authentication string, follow these steps:
 
 For more info on how to create the `authentication` string, refer to the obs-websocket client libraries listed on the [README](README.md).
 
+### Status and Close Codes
+These are the enumeration definitions for various codes used by obs-websocket.
+
+#### RequestStatus Enum
+```cpp
+enum RequestStatus: std::uint16_t {
+	Unknown = 0,
+
+	// For internal use to signify a successful parameter check
+	NoError = 10,
+
+	Success = 100,
+
+	// The request is denied because the client is not authenticated
+	AuthenticationMissing = 200,
+	// Connection has already been authenticated (for modules utilizing a request to provide authentication)
+	AlreadyAuthenticated = 201,
+	// Authentication request was denied (for modules utilizing a request to provide authentication)
+	AuthenticationDenied = 202,
+	// The `requestType` field is missing from the request data
+	RequestTypeMissing = 203,
+	// The request type is invalid (does not exist)
+	InvalidRequestType = 204,
+	// Generic error code (comment is expected to be provided)
+	GenericError = 205,
+
+	// A required request parameter is missing
+	MissingRequestParameter = 300,
+
+	// Generic invalid request parameter message
+	InvalidRequestParameter = 400,
+	// A request parameter has the wrong data type
+	InvalidRequestParameterDataType = 401,
+	// A request parameter (float or int) is out of valid range
+	RequestParameterOutOfRange = 402,
+	// A request parameter (string or array) is empty and cannot be
+	RequestParameterEmpty = 403,
+
+	// An output is running and cannot be in order to perform the request (generic)
+	OutputRunning = 500,
+	// An output is not running and should be
+	OutputNotRunning = 501,
+	// Stream is running and cannot be
+	StreamRunning = 502,
+	// Stream is not running and should be
+	StreamNotRunning = 503,
+	// Record is running and cannot be
+	RecordRunning = 504,
+	// Record is not running and should be
+	RecordNotRunning = 505,
+	// Record is paused and cannot be
+	RecordPaused = 506,
+	// Replay buffer is running and cannot be
+	ReplayBufferRunning = 507,
+	// Replay buffer is not running and should be
+	ReplayBufferNotRunning = 508,
+	// Replay buffer is disabled and cannot be
+	ReplayBufferDisabled = 509,
+	// Studio mode is active and cannot be
+	StudioModeActive = 510,
+	// Studio mode is not active and should be
+	StudioModeNotActive = 511,
+
+	// The specified source (obs_source_t) was of the invalid type (Eg. input instead of scene)
+	InvalidSourceType = 600,
+	// The specified source (obs_source_t) was not found (generic for input, filter, transition, scene)
+	SourceNotFound = 601,
+	// The specified source (obs_source_t) already exists. Applicable to inputs, filters, transitions, scenes
+	SourceAlreadyExists = 602,
+	// The specified input (obs_source_t-OBS_SOURCE_TYPE_FILTER) was not found
+	InputNotFound = 603,
+	// The specified input (obs_source_t-OBS_SOURCE_TYPE_INPUT) had the wrong kind
+	InvalidInputKind = 604,
+	// The specified filter (obs_source_t-OBS_SOURCE_TYPE_FILTER) was not found
+	FilterNotFound = 605,
+	// The specified transition (obs_source_t-OBS_SOURCE_TYPE_TRANSITION) was not found
+	TransitionNotFound = 606,
+	// The specified transition (obs_source_t-OBS_SOURCE_TYPE_TRANSITION) does not support setting its position (transition is of fixed type)
+	TransitionDurationFixed = 607,
+	// The specified scene (obs_source_t-OBS_SOURCE_TYPE_SCENE), (obs_scene_t) was not found
+	SceneNotFound = 608,
+	// The specified scene item (obs_sceneitem_t) was not found
+	SceneItemNotFound = 609,
+	// The specified scene collection was not found
+	SceneCollectionNotFound = 610,
+	// The specified profile was not found
+	ProfileNotFound = 611,
+	// The specified output (obs_output_t) was not found
+	OutputNotFound = 612,
+	// The specified encoder (obs_encoder_t) was not found
+	EncoderNotFound = 613,
+	// The specified service (obs_service_t) was not found
+	ServiceNotFound = 614,
+	// The specified hotkey was not found
+	HotkeyNotFound = 615,
+	// The specified directory was not found
+	DirectoryNotFound = 616,
+	// The specified config item (obs_config_t) was not found. Could be section or parameter name.
+	ConfigParameterNotFound = 617,
+	// The specified property (obs_properties_t) was not found
+	PropertyNotFound = 618
+
+	// Processing the request failed unexpectedly
+	RequestProcessingFailed = 700,
+	// Starting the Output failed
+	OutputStartFailed = 701,
+	// Duplicating the scene item failed
+	SceneItemDuplicationFailed = 702,
+	// Rendering the screenshot failed
+	ScreenshotRenderFailed = 703,
+	// Encoding the screenshot failed
+	ScreenshotEncodeFailed = 704,
+	// Saving the screenshot failed
+	ScreenshotSaveFailed = 705,
+	// Creating the directory failed
+	DirectoryCreationFailed = 706,
+};
+```
+
+#### WebsocketCloseCode Enum
+```cpp
+enum WebsocketCloseCode: std::uint16_t {
+	UnknownReason = 4000,
+
+	// The server was unable to decode the incoming websocket message
+	MessageDecodeError = 4001,
+	// The specified `messageType` was invalid
+	UnknownMessageType = 4002,
+	// The client sent a websocket message without first sending `Identify` message
+	NotIdentified = 4003,
+	// The client sent an `Identify` message while already identified
+	AlreadyIdentified = 4004,
+	// The authentication attempt (via `Identify`) failed
+	AuthenticationFailed = 4005,
+	// There was an invalid parameter the client's `Identify` message
+	InvalidIdentifyParameter = 4006,
+	// A `Request` or `RequestBatch` was missing its `requestId`
+	RequestMissingRequestId = 4007,
+	// The websocket session has been invalidated by the obs-websocket server.
+	SessionInvalidated = 4008,
+	// The server detected the usage of an old version of the obs-websocket protocol.
+	UnsupportedProtocolVersion = 4009,
+};
+```
+
 
 ## Message Types
 The following message types are the base message types which may be sent to and from obs-websocket. 
 
+**Every** message sent from the obs-websocket server or client must contain these fields, known as the base object:
+```
+{
+  "messageType": string
+}
+```
+
 ### Hello
 - Sent from: obs-websocket
 - Sent to: Freshly connected websocket client
-- Description:
+- Description: First message sent from the server immediately on client connection. Contains authentication information if auth is required. Also contains RPC version for version negotiation.
+
+**Additional Base Object Fields:**
+```
+{
+  "obsWebsocketVersion": string,
+  "rpcVersion": number,
+  "availableEvents": array<string>,
+  "availableRequests": array<string>,
+  "authentication": object(optional)
+}
+```
+- `rpcVersion` is a version number which gets incremented on each **breaking change** to the obs-websocket protocol. Its usage in this context is to provide the current rpc version that the server would like to use.
+
+**Example Messages:**
+Authentication is required
+```json
+{
+  "messageType": "Hello",
+  "websocketVersion": "5.0.0",
+  "rpcVersion": 3,
+  "availableRequests": ["GetVersion"],
+  "availableEvents": ["Exiting"],
+  "authentication": {
+    "challenge": "+IxH4CnCiqpX1rM9scsNynZzbOe4KhDeYcTNS3PDaeY=",
+    "salt": "lM1GncleQOaCu9lT1yeUZhFYnqhsLLP1G5lAGo3ixaI="
+  }
+}
+```
+
+Authentication is not required
+```json
+{
+  "messageType": "Hello",
+  "websocketVersion": "5.0.0",
+  "rpcVersion": 3,
+  "availableRequests": ["GetVersion"],
+  "availableEvents": ["Exiting"]
+}
+```
 
 ### Identify
 - Sent from: Freshly connected websocket client
 - Sent to: obs-websocket
-- Description: 
+- Description: Response to `Hello` message, should contain authentication string if authentication is required, along with PubSub subscriptions and other session parameters.
+
+**Additional Base Object Fields:**
+```
+{
+  "rpcVersion": number,
+  "authentication": string(optional),
+  "ignoreInvalidMessages": bool(optional) = false,
+  "ignoreNonFatalRequestChecks": bool(optional) = false,
+  "eventWhitelist": array<string>(optional),
+  "eventBlacklist": array<string>(optional)
+}
+```
+- `rpcVersion` is the version number that the client would like the obs-websocket server to use.
+- When `ignoreInvalidMessages` is true, the socket will not be closed for `WebsocketCloseCode` `MessageDecodeError`, `UnknownMessageType`, or `RequestMissingRequestId`. Instead, the message will be logged and dropped.
+- When `ignoreNonFatalRequestChecks` is true, requests will ignore checks which are not critical to the function of the request. Eg calling `DeleteScene` when the target scene does not exist would still return `RequestStatus::Success` if this flag is enabled.
+- When `eventWhitelist` is specified, only the specified events will be sent to the client.
+- When `eventBlacklist` is specified, all events except those specified will be sent to the client.
+- Only `eventWhitelist` or `eventBlacklist` may be provided. If both are provided, the connection will be closed with `WebsocketCloseCode::InvalidIdentifyParameter`.
+
+**Example Message:**
+```json
+{
+  "messageType": "Identify",
+  "rpcVersion": 3,
+  "authentication": "Dj6cLS+jrNA0HpCArRg0Z/Fc+YHdt2FQfAvgD1mip6Y=",
+  "eventWhitelist": ["Exiting"]
+}
+```
 
 ### Identified
 - Sent from: obs-websocket
 - Sent to: Freshly identified client
-- Description: 
+- Description: The identify request was received and validated, and the connection is now ready for normal operation.
+
+**Additional Base Object Fields:**
+```
+{
+  "negotiatedRpcVersion": number
+}
+```
+- If rpc version negotiation succeeds, the server determines the RPC version to be used and gives it to the client as `negotiatedRpcVersion`
+
+**Example Message:**
+```json
+{
+  "messageType": "Identified",
+  "negotiatedRpcVersion": 3
+}
+```
 
 ### Reidentify
 - Sent from: Identified client
 - Sent to: obs-websocket
-- Description:
+- Description: Sent at any time after initial identification to update the provided session parameters.
+
+**Additional Base Object Fields:**
+```
+{
+  "ignoreInvalidMessages": bool(optional),
+  "ignoreNonFatalRequestChecks": bool(optional),
+  "eventWhitelist": array<string>(optional),
+  "eventBlacklist": array<string>(optional)
+}
+```
+- Only the listed parameters may be changed by `Reidentify` after initial identification. To change a parameter not listed, you must reconnect to the obs-websocket server.
 
 ### Event
 - Sent from: obs-websocket
 - Sent to: All subscribed and identified clients
-- Description: 
+- Description: An event coming from OBS has occured. Eg scene switched, source muted.
+
+**Additional Base Object Fields:**
+```
+{
+  "eventType": string,
+  "eventData": object(optional)
+}
+```
 
 ### Request
 - Sent from: Identified client
 - Sent to: obs-websocket
-- Description: 
+- Description: Client is making a request to obs-websocket. Eg get current scene, create source.
+
+**Additional Base Object Fields:**
+```
+{
+  "requestType": string,
+  "requestId": string,
+  "requestData": object(optional),
+  
+}
+```
+
+**Example Message:**
+```json
+{
+  "messageType": "Request",
+  "requestType": "SetCurrentScene",
+  "requestId": "f819dcf0-89cc-11eb-8f0e-382c4ac93b9c",
+  "requestData": {
+    "sceneName": "Scene 12"
+  }
+}
+```
 
 ### RequestResponse
 - Sent from: obs-websocket
 - Sent to: Identified client which made the request
-- Description: 
+- Description: obs-websocket is responding to a request coming from a client.
+
+**Additional Base Object Fields:**
+```
+{
+  "requestType": string,
+  "requestId": string,
+  "requestStatus": object,
+  "responseData": object(optional)
+}
+```
+- The `requestType` and `requestId` are simply mirrors of what was sent by the client.
+
+`requestStatus` object:
+```
+{
+  "result": bool,
+  "code": number,
+  "comment": string(optional)
+}
+```
+- `result` is true if the request resulted in `RequestStatus::Success`. False if otherwise.
+- `code` is a [`RequestStatus`](#requeststatus-enum) code.
+- `comment` may be provided by the server on errors to offer further details on why a request failed.
+
+**Example Messages:**
+Successful Response
+```json
+{
+  "messageType": "RequestResponse",
+  "requestType": "SetCurrentScene",
+  "requestId": "f819dcf0-89cc-11eb-8f0e-382c4ac93b9c",
+  "requestStatus": {
+    "result": true,
+    "code": 100
+  }
+}
+```
+
+Failure Response
+```json
+{
+  "messageType": "RequestResponse",
+  "requestType": "SetCurrentScene",
+  "requestId": "f819dcf0-89cc-11eb-8f0e-382c4ac93b9c",
+  "requestStatus": {
+    "result": false,
+    "code": 608,
+    "comment": "Parameter: sceneName"
+  }
+}
+```
 
 ### RequestBatch
 - Sent from: Identified client