Rework events and add proper support for client events

Added

- Client events are now implemented through `SimConnect::subscribe_to_client_event`, `SimConnect::unsubscribe_from_client_event` and `SimConnect::unsubscribe_from_all_client_events`.
- `subscribe_to_client_events.rs` example has been added.
- `SimConnectError::EventAlreadySubscribedTo` and `SimConnectError::EventNotSubscribedTo` error variants have been added.

Changed

- A second call to `SimConnect::subscribe_to_system_event` for the same event will now return an error of type `SimConnectError::EventAlreadySubscribedTo` instead of `SimConnectError::SimConnectException`.
- The call to `SimConnect::unsubscribe_from_system_event` is now a NOOP when the system event is not subscribed to.
- `SimConnectError::UnimplementedMessageType` has been renamed to `SimConnectError::UnimplementedNotification`.

Removed

- `SimConnect::register_event` has been replaced by the new client event functions.
- `NotificationGroup` has been removed in favor of an internally managed notification group.

examples/Cargo.toml

@@ -30,8 +30,12 @@ name = "facilities"
 path = "src/facilities.rs"
 
 [[bin]]
-name = "system_events"
-path = "src/system_events.rs"
+name = "subscribe_to_client_events"
+path = "src/subscribe_to_client_events.rs"
+
+[[bin]]
+name = "subscribe_to_system_events"
+path = "src/subscribe_to_system_events.rs"
 
 [dependencies]
 tracing = "0.1"

examples/README.md

@@ -45,8 +45,14 @@ cargo run --bin data_multiple_objects
 cargo run --bin facilities
 ```
 
-## Receiving system events
+## Subscribe to client events
 
 ```bash
-cargo run --bin system_events
+cargo run --bin subscribe_to_client_events
+```
+
+## Subscribe to system events
+
+```bash
+cargo run --bin subscribe_to_system_events
 ```

examples/src/subscribe_to_client_events.rs

@@ -0,0 +1,62 @@
+use simconnect_sdk::{ClientEvent, ClientEventRequest, Notification, SimConnect};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let client = SimConnect::new("Client Events example");
+
+    let mut throttle_events_received = 0;
+    let mut elevator_events_received = 0;
+
+    match client {
+        Ok(mut client) => loop {
+            let notification = client.get_next_dispatch()?;
+
+            match notification {
+                Some(Notification::Open) => {
+                    println!("Connection opened.");
+
+                    // After the connection is successfully open
+                    // We subscribe to the client events we're interested in
+                    client.subscribe_to_client_event(ClientEventRequest::Throttle1Set)?;
+                    client.subscribe_to_client_event(ClientEventRequest::AxisElevatorSet)?;
+                }
+                Some(Notification::ClientEvent(event)) => match event {
+                    ClientEvent::Throttle1Set { value } => {
+                        println!("Throttle1Set: {value}");
+
+                        throttle_events_received += 1;
+                        if throttle_events_received >= 9 {
+                            // We unsubscribe from the client event after we receive 10 of them
+                            // This might run multiple times if there are more events queued up
+                            println!("Unsubscribing from Throttle1Set...");
+                            client
+                                .unsubscribe_from_client_event(ClientEventRequest::Throttle1Set)?;
+                        }
+                    }
+                    ClientEvent::AxisElevatorSet { value } => {
+                        println!("AxisElevatorSet: {value}");
+
+                        elevator_events_received += 1;
+                        if elevator_events_received >= 9 {
+                            // We unsubscribe from the client event after we receive 10 of them
+                            // This might run multiple times if there are more events queued up
+                            println!("Unsubscribing from AxisElevatorSet...");
+                            client.unsubscribe_from_client_event(
+                                ClientEventRequest::AxisElevatorSet,
+                            )?;
+                        }
+                    }
+                    _ => {}
+                },
+                _ => (),
+            }
+
+            // sleep for about a frame to reduce CPU usage
+            std::thread::sleep(std::time::Duration::from_millis(16));
+        },
+        Err(e) => {
+            println!("Error: {e:?}")
+        }
+    }
+
+    Ok(())
+}

examples/src/subscribe_to_system_events.rs

@@ -1,7 +1,7 @@
 use simconnect_sdk::{Notification, SimConnect, SystemEvent, SystemEventRequest};
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let client = SimConnect::new("System events example");
+    let client = SimConnect::new("System Events example");
 
     match client {
         Ok(mut client) => loop {