You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
/// Other variables types can also be set this way but such requests are simply converted to a calculator string and
220
220
/// evaluated via the _Gauge API_ `execute_calculator_code()`. Using `WASimClient::executeCalculatorCode()` directly may be more efficient. \n
221
221
/// The following conditions must be observed:
222
-
/// - The variable type in `VariableRequest::variableType` must be "settable" ('A', 'C', 'H', 'K', 'L', or 'Z'), otherwise an `E_INVALIDARG` result is returned.
222
+
/// - The variable type in `VariableRequest::variableType` must be "settable" ('A', 'B', 'C', 'H', 'K', 'L', or 'Z'), otherwise an `E_INVALIDARG` result is returned.
223
223
/// - Setting an 'A' type variable this way _requires_ the actual variable name in `VariableRequest::variableName` -- using just an ID returns `E_INVALIDARG`. \n
224
224
/// (Other settable variable types don't have any associated ID anyway, so this is not an issue.)
225
225
/// - For any variable type _other than_ 'L', a Unit can only be specified as a string (in `VariableRequest::unitName`), not an ID.
/// This is an overloaded method. This version allows setting an 'A' type (SimVar) variable to a string value. **Only 'A' type variables can be set this way.** \n
235
-
/// Since there is actually no direct way to set string-type values from WASM code, this is just a conveneince method and simply invokes SimConnect to do the work.
235
+
/// Since there is actually no direct way to set string-type values from WASM code, this is just a convenience method and simply invokes SimConnect to do the work.
236
236
/// On first use with a new variable name it will set up a mapping of the name to an internally-assigned ID (calling `SimConnect_AddToDataDefinition()`) and cache that mapping.
237
237
/// Then on subsequent invocations on the same variable the mapped ID will be used directly. The mappings are invalidated when disconnecting from the simulator.
/// which creates the variable if it doesn't exist. The returned ID (new or existing) is then used to set the value. Use the `lookup()` method to check for the existence of a variable name.
249
249
/// Equivalent to `setVariable(VariableRequest(variableName, true, unitName), value)`. See `setVariable()` and `VariableRequest` for details.
250
250
/// \param variableName Name of the local variable.
251
-
/// \param value The value to set. Becomes the intial value if the variable is created.
251
+
/// \param value The value to set. Becomes the initial value if the variable is created.
252
252
/// \param unitName Optional unit specifier to use. Most Local vars do not specify a unit and default to a generic "number" type.
253
253
/// \return `S_OK` on success, `E_INVALIDARG` on parameter validation errors, `E_NOT_CONNECTED` if not connected to server, or `E_FAIL` on general failure (unlikely).
/// Sets a numeric value on an 'A' (aka "SimVar" / "Simulator Variable") type variable. \n
258
258
/// This is a convenience version of `setVariable()`, equivalent to `setVariable(VariableRequest(variableName, unitName), value)`. See `setVariable()` and `VariableRequest` for details.\n
259
259
/// Note that `variableName` can optionally contain an index after a colon (eg. `VAR NAME:1`), or the `setSimVarVariable(const string& name, uint8_t index, const string& unit, double value)`
260
-
/// overload could be used to provide the index separately.
260
+
/// overload could be used to provide the index separately. For MSFS 2024 Sim Vars which use component name suffixes, specify them in the variable name itself.
/// Sets a numeric value on an indexed 'A' (aka "SimVar" / "Simulator Variable") type variable. \n
264
-
/// This is a convenience version of `setVariable()`, equivalent to `setVariable(VariableRequest(variableName, unitName, simVarIndex), value)`. See `setVariable()` and `VariableRequest` for details.
264
+
/// This is a convenience version of `setVariable()`, equivalent to `setVariable(VariableRequest(variableName, unitName, index), value)`. See `setVariable()` and `VariableRequest` for details.
/// Sets a string value on an 'A' (aka "SimVar" / "Simulator Variable") type variable. \n
268
-
/// This is a convenience version of `setVariable()`, equivalent to `setVariable(VariableRequest('A', variableName), stringValue)`. See `setVariable(const VariableRequest &, const std::string &)` for details.
268
+
/// This is a convenience version of `setVariable()`, equivalent to `setVariable(VariableRequest(`'A'`, variableName), stringValue)`. See `setVariable(const VariableRequest &, const std::string &)` for details.
/// Trigger an event previously registered with `registerEvent()`. This is a more direct alternative to triggering events by name via SimConnect.
342
-
/// \param eventId ID of the previously registered event. If the event hasn't been registerd, the server will log a warning but otherwise nothing will happen.
342
+
/// \param eventId ID of the previously registered event. If the event hasn't been registered, the server will log a warning but otherwise nothing will happen.
343
343
/// \return `S_OK` on success, `E_FAIL` on general failure (unlikely), `E_NOT_CONNECTED` if not connected to server.
/// Can be used to trigger standard Simulator "Key Events" as well as "custom" _Gauge API/SimConnect_ events. Up to 5 optional values can be passed onto the event handler.
358
358
/// This provides functionality similar to the _Gauge API_ function `trigger_key_event_EX1()` and `SimConnect_TransmitClientEvent[_EX1()]`. \n\n
359
359
/// *Standard* Key Event IDs can be found in the SimConnect SDK header file 'MSFS/Legacy/gauges.h' in the form of `KEY_*` macro values, and event names can also be
360
-
/// resolved to IDs programmatically using the `lookup()` method. No preliminary setup is required to trigger these events, but a full connection to WASimModule ("Server") is needed.
360
+
/// resolved to IDs programmatically using the `lookup()` method. No preliminary setup is required to trigger these events, but a full connection to WASimModule ("server") is needed.
361
361
/// These are triggered on the simulator side using `trigger_key_event_EX1()` function calls. \n\n
362
362
/// *Custom Events* for which a numeric ID is already known (typically in the _Gauge API_ `THIRD_PARTY_EVENT_ID_MIN`/`THIRD_PARTY_EVENT_ID_MAX` ID range)
363
363
/// can also be triggered directly as with standard events. These types of events are also passed directly to `trigger_key_event_EX1()`. \n\n
/// Register a "Custom Simulator [Key] Event" by providing an event name. The method optionally returns the generated event ID, which can later be used with `sendKeyEvent()` method instead of the event name.
399
399
/// It can also be used to look up a previous registration's ID if the event name has already been registered. \n\n
400
400
/// Custom event names are mapped to internally-generated unique IDs using a standard SimConnect call to
/// which briefly describes custom event usage and name syntax in the `EventName` parameter description. This method serves a similar purpose (and in fact eventually calls that same SimConnect function). \n\n
/// and the documentation briefly describes custom event usage and name syntax in the `EventName` parameter description. This method serves a similar purpose (and in fact eventually calls that same SimConnect function). \n\n
403
403
/// The mappings must be re-established every time a new connection with SimConnect is made, which WASimClient takes care of automatically. If currently connected to the simulator, the event is immediately mapped,
404
404
/// otherwise it will be mapped upon the next connection. An event registration can be removed with `removeCustomKeyEvent()` which will prevent any SimConnect mapping from being created upon the _next_ connection. \n\n
405
-
/// Note that the custom event mapping/triggering feature is actually just a convenience for the WASimClient user and doesn't involve the usual Server interactions (WASimModule) at all. \n
405
+
/// If you're not going to store the ID that will be generated anyway, `sendKeyEvent(customEventName, ...)` can be used directly, which will automatically call this method the first time the event name is used.
406
+
/// The ID can always be looked up later if needed (by calling this method). \n\n
407
+
/// Note that the custom event mapping/triggering feature is actually just a convenience for the WASimClient user and doesn't involve the usual server interactions (WASimModule) at all.
406
408
/// \param customEventName Name of the Event to register. The event name _must_ contain a "." (period) or start with a "#", otherwise an `E_INVALIDARG` result is returned. \n
407
409
/// If an event with the same name has already been registered, the method returns `S_OK` and no further actions are performed (besides setting the optional `puiCustomEventId` pointer value, see below).
408
410
/// \param puiCustomEventId Optional pointer to 32-bit unsigned integer variable to return the generated event ID. This ID can be used to trigger the event later using `sendKeyEvent()` (which is more efficient than using the event name each time).
/// Request server-side lookup of an named item to find the corresponding numeric ID.
443
-
/// \param itemType The type of item to look up. A type of variable or a measurement unit. See the `WASimCommander::LookupItemType` documentation for details.
444
+
/// Request a lookup of a named item to find its corresponding numeric ID. \n
445
+
/// Most lookup types are done on the server side, so an active connection is required. The exception is looking up Key Event IDs (\refwce{LookupItemType::KeyEventId}), which are performed locally.
446
+
/// \param itemType The type of item to look up. A type of variable or a measurement unit. See the \refwce{LookupItemType} documentation for details.
444
447
/// \param itemName The name of the thing to check for.
445
448
/// \param piResult Pointer to 32-bit signed integer variable to hold the result.
446
449
/// \return `S_OK` on success, `E_FAIL` if server returns a Nak response (typically means the item name wasn't found), `E_NOT_CONNECTED` if not connected to server, `E_TIMEOUT` on server communication failure.
447
-
/// \note This method blocks until either the Server responds or the timeout has expired. \sa defaultTimeout(), setDefaultTimeout()
450
+
/// \note Except for Key Event ID type lookups, this method blocks until either the Server responds or the timeout has expired. \sa defaultTimeout(), setDefaultTimeout()
/// \note The remote server logging level for `File` and `Console` facilities is unknown at Client startup. The returned values are only going to be correct if they were set by this instance of the Client (using `setLogLevel()`).
/// Set the current minimum logging severity level for the specified `facility` and `source` to `level`. \sa logLevel(), setLogCallback(), \refwce{CommandId::Log}
477
-
/// \param level The new minimum level. One of `WASimCommander::LogLevel` enum values. Use `LogLevel::None` to disable logging on the given faciliity/source.
480
+
/// \param level The new minimum level. One of `WASimCommander::LogLevel` enum values. Use `LogLevel::None` to disable logging on the given facility/source.
478
481
/// \param facility One or more of `WASimCommander::LogFacility` enum flags. The `LogFacility::Remote` facility is the one delivered via the log callback handler.
479
482
/// \param source One of \refwcc{LogSource} enum values.
0 commit comments