Brows.Sys 1.0.0

Brows.Sys

Message contracts and immutable device-change models for the Brows system notification libraries. This package targets net10.0 and contains no native window-hook implementation.

Installation

dotnet add package Brows.Sys

Use this package when consuming typed messages or implementing a messenger. For the supplied Windows implementation, use Brows.Sys.Win32.Windows, which references these contracts transitively.

Contracts

Contracts are in Brows.Sys. Device models are under Brows.Sys.Messages and Brows.Sys.Messages.DeviceMessages. Concrete change records are in Brows.Sys.Messages.DeviceMessages.DeviceChanges; the volume model is in Brows.Sys.Messages.DeviceMessages.Devices.

The current SystemMessageKind is Device. DeviceMessageKind.TreeChange identifies DeviceTreeChange, whose inherited Device is null because no individual device is identified. Consumers should enumerate devices initially and refresh their inventory when this notification arrives; notifications do not provide an initial snapshot.

DeviceKind preserves None=0 and Volume=1, and adds Port=2 and Interface=3. DeviceMessageKind.Change=0 is preserved and TreeChange=1 is appended.

Device changes are represented by DeviceArrival, DeviceRemovalRequest, DeviceRemovalFailed, DeviceRemovalPending, and DeviceRemovalComplete records.

Example

using Brows.Sys.Messages.DeviceMessages.DeviceChanges;
using Brows.Sys.Messages.DeviceMessages.Devices;
using System;

var message = new DeviceArrival {
    Device = new VolumeDevice {
        VolumeName = "E",
        VolumeFlag = VolumeFlag.Media,
    },
};

Console.WriteLine($"{message.DeviceChangeKind}: {message.Device.DeviceKind}");

The Windows decoder supplies VolumeName as a drive letter, such as E, without a colon or trailing backslash. VolumeFlag is a flags enum: None = 0, Media = 1, and Network = 2. Test individual bits when a combination is possible.

Consumers should inspect the payload before assuming it is a volume:

using Brows.Sys;
using Brows.Sys.Messages.DeviceMessages;
using Brows.Sys.Messages.DeviceMessages.Devices;
using System;

static void PrintMessage(ISystemMessage message) {
    if (message is DeviceChange { Device: VolumeDevice volume } change) {
        Console.WriteLine($"{change.DeviceChangeKind}: {volume.VolumeName} ({volume.VolumeFlag})");
    }
}

The supplied decoder can emit a recognized device-change event with a null Device when its native device type has no corresponding model; payloads whose native device type is outside the platform's enumeration produce no message. The device kind is available through Device.DeviceKind; there is no separate kind property on DeviceChange.

Named devices and topology

using Brows.Sys;
using Brows.Sys.Messages.DeviceMessages;
using Brows.Sys.Messages.DeviceMessages.Devices;
using System;

static void PrintDeviceNotification(ISystemMessage message) {
    switch (message) {
        case DeviceTreeChange:
            Console.WriteLine("Device inventory changed; re-enumerate devices.");
            break;
        case DeviceChange { Device: PortDevice port } change:
            Console.WriteLine($"{change.DeviceChangeKind}: {port.PortName}");
            break;
        case DeviceChange { Device: InterfaceDevice deviceInterface } change:
            Console.WriteLine($"{change.DeviceChangeKind}: {deviceInterface.InterfaceClassGuid}");
            Console.WriteLine(deviceInterface.InterfaceName);
            break;
    }
}

Interface names are copied native symbolic identifiers. Resolving friendly names, device properties, and mounted paths belongs to the application. Port names are the names supplied by the broadcast and are not restricted to COM-number syntax.

Lifetime

Dispose an ISystemMessenger when subscribing directly. When reading through ISystemMessengerSet from Brows.Sys.Composition, the enumerator owns the messengers it creates and cleans them up when reading ends.

License and source

MIT license. Source repository.