atomicshop 2.21.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

atomicshop/wrappers/pywin32w/wmis/win32_networkadapterconfiguration.py

@@ -0,0 +1,262 @@
+from typing import Union
+import socket
+import time
+
+from win32com.client import CDispatch
+
+from . import wmi_helpers, win32networkadapter
+from ...psutilw import psutil_networks
+from .... import ip_addresses
+
+
+def get_network_configuration_by_adapter(
+        adapter: CDispatch,
+        wmi_instance: CDispatch = None
+) -> Union[CDispatch, None]:
+    """
+    Get the network configuration for a specific adapter index.
+
+    :param adapter: CDispatch, Win32_NetworkAdapter object.
+    :param wmi_instance: WMI instance. You can get it from:
+        wmi_helpers.get_wmi_instance()
+    :return: Win32_NetworkAdapterConfiguration object.
+    """
+
+    network_config: CDispatch = wmi_instance.ExecQuery(
+        f"SELECT * FROM Win32_NetworkAdapterConfiguration WHERE Index={adapter.Index}")[0]
+
+    return network_config
+
+
+def get_adapter_network_configuration(
+        use_default_interface: bool = False,
+        connection_name: str = None,
+        mac_address: str = None,
+        wmi_instance: CDispatch = None
+) -> tuple:
+    """
+    Get the WMI network configuration for a network adapter.
+    :param use_default_interface: bool, if True, the default network interface will be used.
+        This is the adapter that your internet is being used from.
+    :param connection_name: string, adapter name as shown in the network settings.
+    :param mac_address: string, MAC address of the adapter. Format: '00:00:00:00:00:00'.
+    :param wmi_instance: WMI instance. You can get it from:
+        wrappers.pywin32s.wmis.wmi_helpers.get_wmi_instance()
+        or default will be used.
+    :return: tuple(Win32_NetworkAdapterConfiguration, Win32_NetworkAdapter)
+    """
+
+    if use_default_interface and connection_name:
+        raise ValueError("Only one of 'use_default_interface' or 'connection_name' must be provided.")
+    elif not use_default_interface and not connection_name:
+        raise ValueError("Either 'use_default_interface' or 'connection_name' must be provided.")
+
+    if not wmi_instance:
+        wmi_instance, _ = wmi_helpers.get_wmi_instance()
+
+    adapters = win32networkadapter.list_network_adapters(wmi_instance)
+
+    current_adapter = None
+    if use_default_interface:
+        default_connection_name_dict: dict = psutil_networks.get_default_connection_name()
+        if not default_connection_name_dict:
+            raise wmi_helpers.WMINetworkAdapterNotFoundError("Default network adapter not found.")
+        # Get the first key from the dictionary.
+        connection_name: str = list(default_connection_name_dict.keys())[0]
+
+    if connection_name is None and mac_address is None:
+        raise ValueError("Either 'connection_name' or 'mac_address' must be provided.")
+    elif connection_name and mac_address:
+        raise ValueError("Only one of 'connection_name' or 'mac_address' must be provided.")
+
+    if connection_name:
+        for adapter in adapters:
+            if connection_name == adapter.NetConnectionID:
+                current_adapter = adapter
+                break
+
+        if not current_adapter:
+            raise wmi_helpers.WMINetworkAdapterNotFoundError(f"Adapter with connection name '{connection_name}' not found.")
+    elif mac_address:
+        for adapter in adapters:
+            if mac_address == adapter.MACAddress:
+                current_adapter = adapter
+                break
+
+        if current_adapter is None:
+            raise wmi_helpers.WMINetworkAdapterNotFoundError(f"Adapter with MAC address '{mac_address}' not found.")
+
+    # Query the network adapter configurations
+    query = f"SELECT * FROM Win32_NetworkAdapterConfiguration WHERE Index='{current_adapter.DeviceID}'"
+    adapter_configs = wmi_instance.ExecQuery(query)
+
+    # Check if the adapter exists
+    if len(adapter_configs) == 0:
+        raise wmi_helpers.WMINetworkAdapterNotFoundError(f"Adapter with connection name '{connection_name}' not found.")
+
+    return adapter_configs[0], current_adapter
+
+
+def set_static_ips(
+        network_config: CDispatch,                               # Win32_NetworkAdapterConfiguration (CDispatch)
+        ips: list[str],    # ["192.168.157.3", ...]
+        masks: list[str],    # ["255.255.255.0", ...]
+        gateways: list[str] = None,
+        dns_gateways: list[str] = None,
+        availability_wait_seconds: int = 0
+) -> None:
+    """
+    • network_config      – Win32_NetworkAdapterConfiguration instance for the target NIC
+                 (you already have it from GetObject / WMI query).
+    • ips     – list of IPv4 strings.
+    • masks    – matching subnet‑mask list (same length as ipv4).
+    • gateways – list of default gateways (optional).
+    • dns_gateways – list of DNS servers (optional).
+    • availability_wait_seconds – seconds to wait for the adapter to become available.
+        0 means no wait.
+
+    Raises RuntimeError if Windows reports anything other than success (0 / 1)
+    or "object already exists" (22) for each operation.
+
+    ==========
+
+    Example:
+        cfg = wmi_instance.Get("Win32_NetworkAdapterConfiguration.Index=12")  # your adapter
+        set_static_ips(
+            cfg,
+            ipv4=["192.168.157.129", "192.168.157.3", "192.168.157.4"],
+            masks=["255.255.255.0"] * 3,
+            # gateways=["192.168.157.2"],
+            # dns_gateways=["8.8.8.8", "1.1.1.1"]
+        )
+    """
+
+    initial_default_ipv4: str = socket.gethostbyname(socket.gethostname())
+
+    # -------------------- IPv4 via EnableStatic ----------------------------
+    if not masks or len(ips) != len(masks):
+        raise ValueError("ipv4 and masks must be lists of equal length")
+
+    in_params = network_config.Methods_("EnableStatic").InParameters.SpawnInstance_()
+    in_params.IPAddress  = ips
+    in_params.SubnetMask = masks
+
+    rc = network_config.ExecMethod_("EnableStatic", in_params).Properties_('ReturnValue').Value
+    if rc not in (0, 1):     # 0 = reboot required, 1 = OK
+        raise RuntimeError(f"EnableStatic (IPv4) failed, code {rc}")
+
+    # -------------------- Default Gateway via SetGateways -------------------
+    if gateways:
+        gateway_metrics = [1] * len(gateways)
+        in_params = network_config.Methods_("SetGateways").InParameters.SpawnInstance_()
+        in_params.DefaultIPGateway = gateways
+        in_params.GatewayCostMetric = [int(m) for m in gateway_metrics]
+
+        rc = network_config.ExecMethod_("SetGateways", in_params) \
+            .Properties_('ReturnValue').Value
+        if rc not in (0, 1):
+            raise RuntimeError(f"SetGateways failed, code {rc}")
+
+    # -------------------- DNS via SetDNSServerSearchOrder ------------------
+    if dns_gateways:
+        in_params = network_config.Methods_("SetDNSServerSearchOrder").InParameters.SpawnInstance_()
+        in_params.DNSServerSearchOrder = dns_gateways
+
+        rc = network_config.ExecMethod_("SetDNSServerSearchOrder", in_params).Properties_('ReturnValue').Value
+        if rc not in (0, 1):
+            raise RuntimeError(f"SetDNSServerSearchOrder failed, code {rc}")
+
+    # -------------------- Wait for the adapter to become available -----------
+    if availability_wait_seconds > 0:
+        count = 0
+        while count < 15:
+            current_default_ipv4: str = socket.gethostbyname(socket.gethostname())
+            if current_default_ipv4 == initial_default_ipv4:
+                # print(f"[+] Adapter is available: {current_default_ipv4}")
+                break
+            else:
+                # print(f"[!] Adapter is not available yet: [{current_default_ipv4}]")
+                count += 1
+
+            time.sleep(1)
+
+
+def set_dynamic_ip(
+        nic_cfg,
+        reset_dns: bool = True,
+        reset_wins: bool = True
+) -> None:
+    """
+    Switch the adapter represented by *nic_cfg* (a Win32_NetworkAdapterConfiguration
+    COM object) to DHCP.
+
+    Parameters
+    ----------
+    nic_cfg : CDispatch
+        The adapter’s Win32_NetworkAdapterConfiguration instance (IPEnabled = TRUE).
+    reset_dns : bool, default True
+        Also clear any static DNS servers (calls SetDNSServerSearchOrder(None)).
+    reset_wins : bool, default True
+        Also clear any static WINS servers (calls SetWINSServer(None, None)).
+
+    Raises
+    ------
+    RuntimeError
+        If any WMI call returns a status other than 0 (“Success”) or 1 (“Restart required”).
+    """
+
+    # 1) Turn on DHCP for IPv4
+    wmi_helpers.call_method(nic_cfg, 'EnableDHCP')
+
+    # 2) Clear static gateways (otherwise Windows keeps using them)
+    wmi_helpers.call_method(nic_cfg, 'SetGateways', ([], []))    # empty SAFEARRAY → remove gateways
+
+    # 3) Optional: reset DNS
+    if reset_dns:
+        wmi_helpers.call_method(nic_cfg, 'SetDNSServerSearchOrder', None)  # None = DHCP-provided DNS
+
+    # 4) Optional: reset WINS
+    if reset_wins:
+        wmi_helpers.call_method(nic_cfg, 'SetWINSServer', ("", ""))
+
+
+def get_info_from_network_config(
+        network_config: CDispatch
+) -> dict:
+    """
+    Collect information about adapter that currently carries the default route.
+
+    :param network_config: CDispatch, Win32_NetworkAdapterConfiguration object.
+    :return: dict of the default adapter.
+    """
+
+    def _split_ips(config):
+        """Split IPAddress[] into separate v4 / v6 lists."""
+        current_ipv4s: list[str] = []
+        current_ipv4_masks: list[str] = []
+        current_ipv6s: list[str] = []
+        current_ipv6_prefixes: list[int] = []
+        for address_index, ip_address in enumerate(config.IPAddress):
+            if ip_addresses.is_ip_address(ip_address, 'ipv4'):
+                current_ipv4s.append(ip_address)
+                current_ipv4_masks.append(config.IPSubnet[address_index])
+            elif ip_addresses.is_ip_address(ip_address, 'ipv6'):
+                current_ipv6s.append(ip_address)
+                current_ipv6_prefixes.append(int(config.IPSubnet[address_index]))
+
+        return current_ipv4s, current_ipv6s, current_ipv4_masks, current_ipv6_prefixes
+
+    ipv4s, ipv6s, ipv4subnets, ipv6prefixes = _split_ips(network_config)
+    adapter = {
+            "description": network_config.Description,
+            "interface_index": network_config.InterfaceIndex,
+            "is_dynamic": bool(network_config.DHCPEnabled),
+            "ipv4s": ipv4s,
+            "ipv6s": ipv6s,
+            "ipv4_subnet_masks": ipv4subnets,
+            "ipv6_prefixes": ipv6prefixes,
+            "default_gateways": list(network_config.DefaultIPGateway or []),
+            "dns_gateways": list(network_config.DNSServerSearchOrder or []),
+        }
+
+    return adapter

atomicshop/wrappers/pywin32w/wmis/win32networkadapter.py

@@ -1,112 +1,81 @@
 from typing import Union
 
-import win32com.client
+from win32com.client import CDispatch
 
-from . import helpers
-from ...psutilw import networks
+from . import wmi_helpers, win32_networkadapterconfiguration
+from ...psutilw import psutil_networks
 from ....print_api import print_api
 
 
-class NetworkAdapterNotFoundError(Exception):
-    pass
+def list_network_adapters(wmi_instance: CDispatch = None) -> list[CDispatch]:
+    """
+    List all network adapters on the system, from the Win32_NetworkAdapter class.
 
+    :param wmi_instance: WMI instance. You can get it from:
+        wmi_helpers.get_wmi_instance()
+    :return: list of Win32_NetworkAdapter objects.
+    """
 
-def list_network_adapters() -> list:
-    # Initialize the WMI client
-    wmi = win32com.client.Dispatch('WbemScripting.SWbemLocator')
-    wmi_service = wmi.ConnectServer('.', 'root\\cimv2')
+    if not wmi_instance:
+        wmi_instance, _ = wmi_helpers.get_wmi_instance()
 
     # Query all network adapters
-    adapters = wmi_service.ExecQuery("SELECT * FROM Win32_NetworkAdapter")
+    adapters: list[CDispatch] = list(wmi_instance.ExecQuery("SELECT * FROM Win32_NetworkAdapter"))
 
     # Print adapter descriptions
     # for adapter in adapters:
     #     print(f"Description: {adapter.Description}, IPEnabled: {adapter.IPEnabled}")
-    return list(adapters)
+    return adapters
 
 
-def get_default_network_adapter():
-    """
-    Get the default network adapter.
-    :return:
+def get_network_adapter_by_device_name(
+        device_name: str,
+        wmi_instance: CDispatch = None
+) -> Union[CDispatch, None]:
     """
+    Get a network adapter by its name.
 
-    default_connection_name_dict: dict = networks.get_default_connection_name()
-    # Get the first key from the dictionary.
-    default_connection_name: str = list(default_connection_name_dict.keys())[0]
-    adapters = list_network_adapters()
-
-    for adapter in adapters:
-        if default_connection_name == adapter.NetConnectionID:
-            return adapter
-
-    raise NetworkAdapterNotFoundError("Default network adapter not found.")
-
-
-def get_wmi_network_configuration(
-        use_default_interface: bool = False,
-        connection_name: str = None,
-        mac_address: str = None
-) -> tuple:
-    """
-    Get the WMI network configuration for a network adapter.
-    :param use_default_interface: bool, if True, the default network interface will be used.
-        This is the adapter that your internet is being used from.
-    :param connection_name: string, adapter name as shown in the network settings.
-    :param mac_address: string, MAC address of the adapter. Format: '00:00:00:00:00:00'.
-    :return: tuple(Win32_NetworkAdapterConfiguration, Win32_NetworkAdapter)
+    :param device_name: string, adapter name as shown in the network settings.
+    :param wmi_instance: WMI instance. You can get it from:
+        wmi_helpers.get_wmi_instance()
+    :return: Win32_NetworkAdapter object.
     """
 
-    if use_default_interface and connection_name:
-        raise ValueError("Only one of 'use_default_interface' or 'connection_name' must be provided.")
-    elif not use_default_interface and not connection_name:
-        raise ValueError("Either 'use_default_interface' or 'connection_name' must be provided.")
+    if not wmi_instance:
+        wmi_instance, _ = wmi_helpers.get_wmi_instance()
 
-    adapters = list_network_adapters()
+    query: str = (
+        "SELECT * FROM Win32_NetworkAdapter "
+        f"WHERE Name LIKE '{device_name}'")
+    adapters: list[CDispatch] = list(wmi_instance.ExecQuery(query))
+    if not adapters:
+        return None
 
-    current_adapter = None
-    if use_default_interface:
-        default_connection_name_dict: dict = networks.get_default_connection_name()
-        if not default_connection_name_dict:
-            raise NetworkAdapterNotFoundError("Default network adapter not found.")
-        # Get the first key from the dictionary.
-        connection_name: str = list(default_connection_name_dict.keys())[0]
+    return adapters[0]
 
-    if connection_name is None and mac_address is None:
-        raise ValueError("Either 'connection_name' or 'mac_address' must be provided.")
-    elif connection_name and mac_address:
-        raise ValueError("Only one of 'connection_name' or 'mac_address' must be provided.")
 
-    if connection_name:
-        for adapter in adapters:
-            if connection_name == adapter.NetConnectionID:
-                current_adapter = adapter
-                break
-
-        if not current_adapter:
-            raise NetworkAdapterNotFoundError(f"Adapter with connection name '{connection_name}' not found.")
-    elif mac_address:
-        for adapter in adapters:
-            if mac_address == adapter.MACAddress:
-                current_adapter = adapter
-                break
+def get_default_network_adapter(wmi_instance: CDispatch = None):
+    """
+    Get the default network adapter.
 
-        if current_adapter is None:
-            raise NetworkAdapterNotFoundError(f"Adapter with MAC address '{mac_address}' not found.")
+    :param wmi_instance: WMI instance. You can get it from:
+        wmi_helpers.get_wmi_instance()
+    :return:
+    """
 
-    # Initialize the WMI client
-    wmi = win32com.client.Dispatch('WbemScripting.SWbemLocator')
-    wmi_service = wmi.ConnectServer('.', 'root\\cimv2')
+    if not wmi_instance:
+        wmi_instance, _ = wmi_helpers.get_wmi_instance()
 
-    # Query the network adapter configurations
-    query = f"SELECT * FROM Win32_NetworkAdapterConfiguration WHERE Index='{current_adapter.DeviceID}'"
-    adapter_configs = wmi_service.ExecQuery(query)
+    default_connection_name_dict: dict = psutil_networks.get_default_connection_name()
+    # Get the first key from the dictionary.
+    default_connection_name: str = list(default_connection_name_dict.keys())[0]
+    adapters: list[CDispatch] = list_network_adapters(wmi_instance)
 
-    # Check if the adapter exists
-    if len(adapter_configs) == 0:
-        raise NetworkAdapterNotFoundError(f"Adapter with connection name '{connection_name}' not found.")
+    for adapter in adapters:
+        if default_connection_name == adapter.NetConnectionID:
+            return adapter
 
-    return adapter_configs[0], current_adapter
+    raise wmi_helpers.WMINetworkAdapterNotFoundError("Default network adapter not found.")
 
 
 def set_dns_server(
@@ -127,11 +96,11 @@ def set_dns_server(
     :return:
     """
 
-    adapter_config, current_adapter = get_wmi_network_configuration(
+    adapter_config, current_adapter = win32_networkadapterconfiguration.get_adapter_network_configuration(
         use_default_interface=use_default_interface, connection_name=connection_name, mac_address=mac_address)
 
     print_api(f"Adapter [{current_adapter.Description}], Connection name [{current_adapter.NetConnectionID}]\n"
               f"Setting DNS servers to {dns_servers}", color='blue')
 
     # Set DNS servers
-    helpers.call_method(adapter_config, 'SetDNSServerSearchOrder', dns_servers)
+    wmi_helpers.call_method(adapter_config, 'SetDNSServerSearchOrder', dns_servers)

atomicshop/wrappers/pywin32w/wmis/wmi_helpers.py

@@ -0,0 +1,235 @@
+import os
+from typing import Union
+
+import win32com.client
+from win32com.client import CDispatch
+
+
+class WmiMethodExecutionError(Exception):
+    pass
+
+
+class WmiMethodParameterError(Exception):
+    pass
+
+
+class EmptyValue:
+    pass
+_EMPTY_VALUE = EmptyValue()
+
+
+class WMINetworkAdapterNotFoundError(Exception):
+    pass
+
+
+LOCAL_SERVER: str = '.'
+
+
+def get_wmi_instance(
+        server: str = LOCAL_SERVER,
+        namespace: str = 'root\\cimv2',
+        wmi_instance: CDispatch = None,
+        locator: CDispatch = None
+) -> tuple[CDispatch, CDispatch]:
+    """
+    Get the WMI instance.
+
+    :param server: str, The server you want to connect to. Default is '.' (local machine).
+    :param namespace: str, WMI namespace. Default is 'root\\cimv2'.
+        Other examples:
+            'root\\StandardCimv2'
+    :param wmi_instance: WMI connected instance.
+    :param locator: WMI locator instance. If not provided, a new one will be created.
+    :return: WMI instance.
+
+    ===================
+
+    If you want to connect directly to a WMI namespace, you can use the following code:
+    return win32com.client.GetObject(f"winmgmts:\\\\{location}\\{namespace}")
+    """
+
+    if not locator:
+        # This is a better way to get the WMI instance, since you have more control over the WMI object.
+        locator: CDispatch = win32com.client.Dispatch('WbemScripting.SWbemLocator')
+
+    if wmi_instance:
+        server_from_instance, namespace_from_instance = get_connection_details(wmi_instance)
+
+        # If current server name of the wmi connection is not the same as was passed to the function,
+        # then create a new connection to the server.
+        if server_from_instance.lower() != server.lower():
+            if not (server_from_instance.lower() == os.environ["COMPUTERNAME"].lower() and server.lower() == LOCAL_SERVER):
+                wmi_instance = locator.ConnectServer(server, namespace)
+        # If the namespace is not the same as was passed to the function.
+        if namespace_from_instance != namespace:
+            wmi_instance = locator.ConnectServer(server, namespace)
+
+    else:
+        wmi_instance: CDispatch = locator.ConnectServer(server, namespace)
+
+    return wmi_instance, locator
+
+
+def get_connection_details(wmi_instance: CDispatch) -> tuple[str, str]:
+    """
+    Get the connection details: connected server and namespace.
+
+    :param wmi_instance: WMI instance.
+    :return: tuple of server and namespace.
+    """
+
+    # Get the current connection details.
+    # Get the security object for the WMI instance.
+    security_object: CDispatch = wmi_instance.Get("__SystemSecurity=@")
+    # Get the Paths.
+    path: CDispatch = security_object.Path_
+
+    server_from_instance: str = path.Server
+    namespace_from_instance: str = path.Namespace
+
+    return server_from_instance, namespace_from_instance
+
+
+def get_method(
+        wmi_object: win32com.client.CDispatch,
+        method_name: str
+):
+    """
+    Get the WMI method.
+
+    :param wmi_object: WMI object.
+    :param method_name: str, name of the method.
+    :return: WMI method object.
+    """
+
+    return wmi_object.Methods_(method_name)
+
+
+def get_method_parameter_instance(
+        method: win32com.client.CDispatch
+):
+    """
+    Get the WMI method parameter.
+
+    :param method: WMI method object.
+    :return: WMI method parameter object.
+    """
+
+    return method.inParameters.SpawnInstance_()
+
+
+def call_method(
+        wmi_object: win32com.client.CDispatch,
+        method_name: str,
+        value: Union[
+            Union[tuple, dict],
+            Union[bool, str, list]] = _EMPTY_VALUE
+):
+    """
+    Call the WMI method.
+
+    :param wmi_object: WMI object.
+    :param method_name: str, name of the method.
+    :param value: tuple, value to pass to the method.
+        tuple: If ou pass a tuple, it will be unpacked and passed as positional arguments.
+            Dor example if a method requires 2 parameters, you can pass a tuple with 2 values.
+        dict: If you pass a dictionary, it will be unpacked and passed as keyword arguments.
+
+        If you pass a single value, which is not a dict or tuple, it will be passed as a single parameter.
+
+        Methods can receive a None value if they don't require any parameters.
+        If the method doesn't require any parameters, leave it as 'EmptyValue' class.
+    :return: WMI method object.
+    """
+
+    if not (isinstance(value, EmptyValue) and isinstance(value, tuple) and isinstance(value, dict)):
+        value = (value,)
+
+    # Get the method instance out of the WMI object.
+    method = get_method(wmi_object, method_name)
+
+    # ── discover the method’s IN parameters up-front ─────────────────────────────
+    if method.InParameters:
+        input_properties: list = [(in_property.Name, in_property.IsArray) for in_property in method.InParameters.Properties_]
+    else:
+        input_properties: list = []  # no inputs expected
+
+    expected = len(input_properties)  # how many inputs the method wants
+
+    got_tuple = isinstance(value, tuple)
+    got_dict = isinstance(value, dict)
+    got_empty = isinstance(value, EmptyValue)
+
+    # ── validate the caller’s intent ─────────────────────────────────────────────
+    if expected == 0 and not got_empty:
+        raise WmiMethodParameterError(
+            f"Method '{method_name}' takes no parameters, got: {value!r}"
+        )
+    if expected > 0 and got_empty:
+        raise WmiMethodParameterError(
+            f"Method '{method_name}' expects {expected} parameter(s); none given."
+        )
+    if got_tuple and len(value) != expected:
+        raise WmiMethodParameterError(
+            f"Method '{method_name}' expects {expected} parameter(s); "
+            f"{len(value)} positional value(s) given."
+        )
+
+    # ── prepare the parameter object if needed ──────────────────────────────────
+    if expected == 0:  # simple – no inputs
+        result = wmi_object.ExecMethod_(method_name)
+
+    else:
+        param_obj = get_method_parameter_instance(method)
+
+        if got_tuple:  # positional list / tuple
+            for (name, is_array), val in zip(input_properties, value):
+                setattr(param_obj, name, val)
+
+        elif got_dict:  # mapping by name
+            for name, _ in input_properties:
+                if name in value:
+                    setattr(param_obj, name, value[name])
+
+        else:  # single scalar for one-input method
+            name, is_array = input_properties[0]
+            if is_array and not (isinstance(value, list) or value is None):
+                raise WmiMethodParameterError(
+                    f"Parameter '{name}' must be a list.\nValue: {value!r}"
+                )
+            setattr(param_obj, name, value)
+
+        result = wmi_object.ExecMethod_(method_name, param_obj)
+
+    # ── collect OUT parameters & check return code ──────────────────────────────
+    out_vals = []
+    if method.OutParameters:
+        for parameter in method.OutParameters.Properties_:
+            out_vals.append(result.Properties_(parameter.Name).Value)
+
+    # return-code conventions: 0 = OK, 1 = OK-needs-reboot
+    if out_vals and out_vals[0] not in (0, 1):
+        result_code: int = out_vals[0]
+        if result_code == 91:
+            raise PermissionError(
+                f"Method '{method_name}' failed (code {result_code}) – try with admin rights."
+            )
+        if result_code == 68:
+            raise WmiMethodExecutionError(
+                f"Method '{method_name}' failed (code {result_code}) – Invalid input parameter"
+            )
+        raise WmiMethodExecutionError(
+            f"Method '{method_name}' failed with error code {result_code}"
+        )
+
+    return out_vals or None
+
+
+"""
+# Setting SeDebugPrivilege
+import win32security, ntsecuritycon, win32con, win32api
+privs = ((win32security.LookupPrivilegeValue('',ntsecuritycon.SE_DEBUG_NAME), win32con.SE_PRIVILEGE_ENABLED),)
+hToken = win32security.OpenProcessToken(win32api.GetCurrentProcess(), win32security.TOKEN_ALL_ACCESS)
+win32security.AdjustTokenPrivileges(hToken, False, privs)
+win32api.CloseHandle(hToken)
+"""