Win32 API

https://learn.microsoft.com/en-us/windows/win32/
Admin
The Win32 API provides the native C and C++ programming interface for building high-performance...
Tokens:7,749,761
Snippets:71,009
Trust Score:10
Update:3 days ago
Show doc for...
Tokens:
Raw
### EnumerateTraceGuidsEx example: enumerate registered providers and get provider info

Source: https://learn.microsoft.com/en-us/windows/win32/api/evntrace/nf-evntrace-enumeratetraceguidsex

This example shows how to call EnumerateTraceGuidsEx to get the list of registered provider GUIDs and then retrieve detailed information about each provider. It handles the ERROR_INSUFFICIENT_BUFFER error by reallocating the buffer and looping until the call succeeds. The example prints the provider GUID, the PID of the registering process, registration flags, and enabled sessions.

```C++
#include <windows.h>
#include <stdio.h>
#include <evntcons.h>

DWORD GetProviderInfo(GUID ProviderGuid, PTRACE_GUID_INFO& pInfo);

int wmain(void)
{
    ULONG status = ERROR_SUCCESS;
    GUID* pTemp = NULL;
    GUID* pGuids = NULL;
    DWORD GuidListSize = 0;
    DWORD GuidCount = 0;
    DWORD RequiredListSize = 0;
    WCHAR ProviderGuid[50];
    PTRACE_GUID_INFO pInfo = NULL;
    PTRACE_PROVIDER_INSTANCE_INFO pInstance = NULL;
    PTRACE_ENABLE_INFO pEnable = NULL;


    // Get the required buffer size for the query.

    status = EnumerateTraceGuidsEx(TraceGuidQueryList, NULL, 0, pGuids, GuidListSize, &RequiredListSize);

    // The number of registered providers could change between the
    // time you called to get the buffer size and the time you called
    // to get the actual data, so call EnumerateTraceGuidsEx in a loop
    // until you no longer get ERROR_INSUFFICIENT_BUFFER.

    while (ERROR_INSUFFICIENT_BUFFER == status)
    {
        pTemp = (GUID*)realloc(pGuids, RequiredListSize);

        if (NULL == pTemp)
        {
            printf("Error allocating memory for list of provider GUIDs.\n");
            goto cleanup;
        }

        pGuids = pTemp;
        pTemp = NULL;

        GuidListSize = RequiredListSize;

        ZeroMemory(pGuids, GuidListSize);

        status = EnumerateTraceGuidsEx(TraceGuidQueryList, NULL, 0, pGuids, GuidListSize, &RequiredListSize);
    }

    if (ERROR_SUCCESS == status)
    {
        GuidCount = GuidListSize / sizeof(GUID);

        // For each registered provider on the computer, get information
        // about how it was registered. If a session enabled the
        // provider, get information on how the session enabled the provider.

        for (USHORT i = 0; i < GuidCount; i++)
        {
            StringFromGUID2(pGuids[i], ProviderGuid, sizeof(ProviderGuid));

            printf("Provider: %ls\n", ProviderGuid);

            status = GetProviderInfo(pGuids[i], pInfo);

            if (ERROR_SUCCESS == status)
            {
                pInstance = (PTRACE_PROVIDER_INSTANCE_INFO)((PBYTE)pInfo + sizeof(TRACE_GUID_INFO));

                if (pInfo->InstanceCount > 1)
                {
                    printf("There are %d providers that use the same GUID.\n", pInfo->InstanceCount);
                }

                for (DWORD j = 0; j < pInfo->InstanceCount; j++)
                {
                    printf("\tThe PID of the process that registered the provider is %lu.\n", pInstance->Pid);

                    if ((pInstance->Flags & TRACE_PROVIDER_FLAG_PRE_ENABLE) == TRACE_PROVIDER_FLAG_PRE_ENABLE)
                    {
                        printf("\tThe provider is not registered; however, one or more sessions have enabled the provider.\n");
                    }
                    else
                    {
                        if ((pInstance->Flags & TRACE_PROVIDER_FLAG_LEGACY) == TRACE_PROVIDER_FLAG_LEGACY)
                        {
                            printf("\tThe provider used RegisterTraceGuids to register itself.\n");
                        }
                        else
                        {
                            printf("\tThe provider used EventRegister to register itself.\n");
                        }
                    }

                    if (pInstance->EnableCount > 0)
                    {
                        printf("\tThe provider is enabled to the following sessions.\n");

                        pEnable = (PTRACE_ENABLE_INFO)((PBYTE)pInstance + sizeof(TRACE_PROVIDER_INSTANCE_INFO));

```

--------------------------------

### SetupInstallFileExW

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi/nf-setupapi-setupinstallfileexw

Installs a file, with options to control overwrite, version checking, and reboot behavior. It accepts a callback for notifications and returns a flag indicating if the file was in use.

```APIDOC
## SetupInstallFileExW

### Description
Installs a file, with options to control overwrite, version checking, and reboot behavior. It accepts a callback for notifications and returns a flag indicating if the file was in use.

### Parameters

#### Flags
- **SP_COPY_SOURCEPATH_ABSOLUTE** - _SourcePathRoot_ is the full path part of the source file. Ignore the relative source specified in the SourceDisksNames section of the INF file for the source media where the file is located. This flag is ignored if SP_COPY_SOURCE_ABSOLUTE is specified.
- **SP_COPY_FORCE_IN_USE** - If the target exists, behave as if it is in use and queue the file for copying on the next system reboot.
- **SP_COPY_IN_USE_NEEDS_REBOOT** - If the file was in use during the copy operation, alert the user that the system requires a reboot.
- **SP_COPY_NOSKIP** - Do not give the user the option to skip a file.
- **SP_COPY_FORCE_NOOVERWRITE** - Check whether the target file exists, and if so, the file is not overwritten. The caller is not notified.
- **SP_COPY_FORCE_NEWER** - Examine each file being copied to see if its version resources (or time stamps for non-image files) indicate that it is not newer than an existing copy on the target. If the file being copied is not newer, the file is not copied. The caller is not notified.
- **SP_COPY_WARNIFSKIP** - If the user tries to skip a file, warn them that skipping a file may affect the installation. (Used for system-critical files.)

#### CopyMsgHandler
- **Type**: Optional pointer to a callback function
- **Description**: Called to notify of various conditions that may arise during the file copy.

#### Context
- **Type**: Pointer to a caller-defined value
- **Description**: Passed as the first parameter of the callback function.

#### FileWasInUse
- **Type**: Pointer to a variable
- **Description**: Receives a flag indicating whether the file was in use. This parameter is required.
```

--------------------------------

### SetupDiInstallDevice

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi/nf-setupapi-setupdiinstalldevice

Documentation for the SetupDiInstallDevice function, including syntax, parameters, return value, remarks, and requirements.

```APIDOC
## SetupDiInstallDevice

### Description
Installs a driver from the INF file for a device. This function performs many tasks for device installation, including creating a driver key, processing INF sections, copying files, loading drivers, and starting the device.

### Syntax
```c
WINSETUPAPI BOOL SetupDiInstallDevice(
  _In_ HDEVINFO         DeviceInfoSet,
  _In_ PSP_DEVINFO_DATA DeviceInfoData
);
```

### Parameters
- **DeviceInfoSet** (HDEVINFO) - Required - A handle to the device information set that contains the device to install.
- **DeviceInfoData** (PSP_DEVINFO_DATA) - Required - A pointer to an SP_DEVINFO_DATA structure that specifies the device in the device information set.

### Return Value
Returns **TRUE** if successful. Otherwise, returns **FALSE** and the logged error can be retrieved with a call to GetLastError.

### Remarks
Installs a driver from the INF file. The driver is a "driver node" and includes services, driver files, co-installers, property-page providers, and control-panel applets. Also registers required device interfaces. A successful installation includes creating a driver key, processing INF sections, copying the INF file, performing file operations, loading drivers, calling AddDevice routines, and starting the device. Windows does not start the device if DI_NEEDRESTART, DI_NEEDREBOOT, or DI_DONOTCALLCONFIGMG is set. Only a class installer should call this function, and only when handling a DIF_INSTALLDEVICE request. The caller must be a member of the Administrators group.

### Requirements
- Minimum supported client: Windows 2000 Professional
- Minimum supported server: Windows 2000 Server
- Header: SetupAPI.h
- Library: SetupAPI.lib
- DLL: SetupAPI.dll
- Unicode: Not supported

### See Also
- DIF_INSTALLDEVICE
- GetLastError
- SP_DEVINFO_DATA
- SP_DEVINSTALL_PARAMS
- SetupDiCallClassInstaller
- SetupDiSetDeviceInstallParams
```

--------------------------------

### SetupDiBuildClassInfoList

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi

Returns a list of setup class GUIDs that identify the classes that are installed on a local computer.

```APIDOC
## SetupDiBuildClassInfoList

### Description
Returns a list of setup class GUIDs that identify the classes that are installed on a local computer.

### Function
SetupDiBuildClassInfoList

### Parameters
No parameters are documented in the source.

### Return Value
No return value is documented in the source.

```

--------------------------------

### SetupDiBuildClassInfoListExA

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi/nf-setupapi-setupdibuildclassinfolistexa

Documentation for the SetupDiBuildClassInfoListExA function, which returns a list of setup class GUIDs installed on the local or a remote system.

```APIDOC
## SetupDiBuildClassInfoListExA

### Description
Returns a list of setup class GUIDs that includes every class installed on the local system or a remote system.

### Syntax
```c
WINSETUPAPI BOOL SetupDiBuildClassInfoListExA(
  [in]            DWORD  Flags,
  [out, optional] LPGUID ClassGuidList,
  [in]            DWORD  ClassGuidListSize,
  [out]           PDWORD RequiredSize,
  [in, optional]  PCSTR  MachineName,
                  PVOID  Reserved
);
```

### Parameters
- **Flags** (DWORD) - Required - Flags used to control exclusion of classes from the list. If no flags are specified, all setup classes are included. Can be a combination of the following values:
  - **DIBCI_NOINSTALLCLASS** - Exclude a class if it has the **NoInstallClass** value entry in its registry key.
  - **DIBCI_NODISPLAYCLASS** - Exclude a class if it has the **NoDisplayClass** value entry in its registry key.
- **ClassGuidList** (LPGUID) - Optional - A pointer to a buffer that receives a list of setup class GUIDs.
- **ClassGuidListSize** (DWORD) - Required - Supplies the number of GUIDs in the _ClassGuidList_ array.
- **RequiredSize** (PDWORD) - Required - A pointer to a variable that receives the number of GUIDs returned. If this number is greater than the size of the _ClassGuidList_, the number indicates how large the _ClassGuidList_ array must be in order to contain the list.
- **MachineName** (PCSTR) - Optional - A pointer to a NULL-terminated string that contains the name of a remote computer from which to retrieve installed setup classes. Can be **NULL**. If **NULL**, the function builds a list of classes installed on the local computer. Using this function to access remote machines is not supported beginning with Windows 8 and Windows Server 2012.
- **Reserved** (PVOID) - Required - Must be **NULL**.

### Return Value
Returns **TRUE** if successful. Otherwise, returns **FALSE** and the logged error can be retrieved by calling **GetLastError**.

### Remarks
The setupapi.h header defines **SetupDiBuildClassInfoListEx** as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

### Requirements
- **Minimum supported client**: Available in Microsoft Windows 2000 and later versions of Windows.
- **Target Platform**: Desktop
- **Header**: setupapi.h (include Setupapi.h)
- **Library**: Setupapi.lib

### See Also
- **SetupDiBuildClassInfoList**
- **SetupDiGetClassDescriptionEx**
```

--------------------------------

### SetupInstallFileW

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi/nf-setupapi-setupinstallfilew

Installs a file as specified either by an INFCONTEXT returned by SetupFindXXXLine or explicitly by the file name and path. The caller must have write privileges into the target directory if a file is copied.

```APIDOC
## SetupInstallFileW

### Description
Installs a file as specified either by an INFCONTEXT returned by SetupFindXXXLine or explicitly by the file name and path. If a file is copied, the caller must have write privileges into the target directory.

### Syntax
C++
```cpp
WINSETUPAPI BOOL SetupInstallFileW(
  [in] HINF                InfHandle,
  [in] PINFCONTEXT         InfContext,
  [in] PCWSTR              SourceFile,
  [in] PCWSTR              SourcePathRoot,
  [in] PCWSTR              DestinationName,
  [in] DWORD               CopyStyle,
  [in] PSP_FILE_CALLBACK_W CopyMsgHandler,
  [in] PVOID               Context
);
```

### Parameters
- **InfHandle** (HINF) - Required - Handle to the INF file that contains the **SourceFile** to be installed. This parameter is optional if **InfContext** is specified.
- **InfContext** (PINFCONTEXT) - Required - Optional pointer to the INF context for the file to be installed. If this parameter is NULL, the **SourceFile** and **SourcePathRoot** parameters are used.
- **SourceFile** (PCWSTR) - Required - Optional file name of the file to be installed. This parameter is required if **InfContext** is NULL.
- **SourcePathRoot** (PCWSTR) - Required - Optional root path of the source file. This parameter is required if **InfContext** is NULL.
- **DestinationName** (PCWSTR) - Required - Optional name of the destination file. If NULL, the source file name is used.
- **CopyStyle** (DWORD) - Required - Flags that control the behavior of the file copy operation. See the Remarks section for details.
- **CopyMsgHandler** (PSP_FILE_CALLBACK_W) - Required - Optional pointer to a callback function that receives notifications during the copy operation.
- **Context** (PVOID) - Required - Optional pointer to a caller-defined context that is passed to the callback function.

### Return Value
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.

### Remarks
This function is available for use in the operating systems indicated in the Requirements section. It may be altered or unavailable in subsequent versions. SetupAPI should no longer be used for installing applications; instead, use the Windows Installer for developing application installers. SetupAPI continues to be used for installing device drivers.

### Requirements
- Header: setupapi.h
- Library: Setupapi.lib
- DLL: Setupapi.dll
- Unicode: Implemented as SetupInstallFileW (Unicode) and SetupInstallFileA (ANSI).
```

--------------------------------

### SetupDiBuildClassInfoListExW

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi/nf-setupapi-setupdibuildclassinfolistexw

Documentation for the SetupDiBuildClassInfoListExW function, which returns a list of setup class GUIDs installed on the local or a remote system.

```APIDOC
## SetupDiBuildClassInfoListExW

### Description
Returns a list of setup class GUIDs that includes every class installed on the local system or a remote system.

### Syntax
```cpp
WINSETUPAPI BOOL SetupDiBuildClassInfoListExW(
  [in]            DWORD  Flags,
  [out, optional] LPGUID ClassGuidList,
  [in]            DWORD  ClassGuidListSize,
  [out]           PDWORD RequiredSize,
  [in, optional]  PCWSTR MachineName,
                  PVOID  Reserved
);
```

### Parameters
- **Flags** [in] (DWORD) - Flags used to control exclusion of classes from the list. If no flags are specified, all setup classes are included. Can be a combination of the following values:
  - **DIBCI_NOINSTALLCLASS** - Exclude a class if it has the **NoInstallClass** value entry in its registry key.
  - **DIBCI_NODISPLAYCLASS** - Exclude a class if it has the **NoDisplayClass** value entry in its registry key.
- **ClassGuidList** [out, optional] (LPGUID) - A pointer to a buffer that receives a list of setup class GUIDs.
- **ClassGuidListSize** [in] (DWORD) - Supplies the number of GUIDs in the _ClassGuidList_ array.
- **RequiredSize** [out] (PDWORD) - A pointer to a variable that receives the number of GUIDs returned. If this number is greater than the size of the _ClassGuidList_, the number indicates how large the _ClassGuidList_ array must be in order to contain the list.
- **MachineName** [in, optional] (PCWSTR) - A pointer to a NULL-terminated string that contains the name of a remote computer from which to retrieve installed setup classes. This parameter is optional and can be **NULL**. If _MachineName_ is **NULL**, this function builds a list of classes installed on the local computer.
- **Reserved** (PVOID) - Must be **NULL**.

### Return Value
Returns **TRUE** if successful. Otherwise, returns **FALSE** and the logged error can be retrieved by calling **GetLastError**.

### Remarks
- Using this function to access remote machines is not supported beginning with Windows 8 and Windows Server 2012, as this functionality has been removed.
- The setupapi.h header defines **SetupDiBuildClassInfoListEx** as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors.

### Requirements
- **Minimum supported client**: Available in Microsoft Windows 2000 and later versions of Windows.
- **Target Platform**: Desktop
- **Header**: setupapi.h (include Setupapi.h)
- **Library**: Setupapi.lib
```

--------------------------------

### SetupInstallFileW

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi/nf-setupapi-setupinstallfilew

Installs a file from the source media to the target directory. The function can copy a file, optionally using a callback to handle various conditions, and supports flags like SP_COPY_FORCE_NEWER to control copying behavior.

```APIDOC
## SetupInstallFileW

### Description
Installs a file from the source media to the target directory. The function can copy a file, optionally using a callback to handle various conditions, and supports flags like SP_COPY_FORCE_NEWER to control copying behavior.

### Syntax
```cpp
BOOL SetupInstallFileW(
  [in] HWND                Owner,
  [in] PCWSTR              SourceFile,
  [in] PCWSTR              SourcePath,
  [in] PCWSTR              DestinationName,
  [in] PCWSTR              CopyFlags,
  [in] PSP_FILE_CALLBACK_W CopyMsgHandler,
  [in] PVOID               Context
);
```

### Parameters
#### Owner
- **Type**: HWND
- **Required**: Optional
- **Description**: Handle to the window that owns the dialog box. This parameter can be NULL.

#### SourceFile
- **Type**: PCWSTR
- **Required**: Required
- **Description**: Name of the file to be copied.

#### SourcePath
- **Type**: PCWSTR
- **Required**: Required
- **Description**: Path to the source file. This parameter can be NULL if the file is in the current directory.

#### DestinationName
- **Type**: PCWSTR
- **Required**: Required
- **Description**: Name of the destination file.

#### CopyFlags
- **Type**: PCWSTR
- **Required**: Required
- **Description**: Flags that control the copy operation. The SP_COPY_FORCE_NEWER flag is documented: if the file being copied is not newer than an existing copy on the target, the file is not copied and the function returns FALSE with GetLastError returning NO_ERROR.

#### CopyMsgHandler
- **Type**: PSP_FILE_CALLBACK_W
- **Required**: Optional
- **Description**: Pointer to a callback function to be notified of various conditions that may arise during the file copy operation.

#### Context
- **Type**: PVOID
- **Required**: Optional
- **Description**: Pointer to a caller-defined value that is passed as the first parameter of the callback function.

### Return Value
If the function succeeds, the return value is a nonzero value. If the function fails, the return value is zero. To get extended error information, call GetLastError. If GetLastError returns NO_ERROR, the file copy operation was not completed. The file may not have been copied because the file copy operation was unnecessary or because the file callback function returned FALSE.

### Remarks
If a UNC directory is specified as the target directory of a file installation, you must ensure it exists before you call SetupInstallFile. The setup functions do not check for the existence of nor create UNC directories. If the target UNC directory does not exist, the file installation will fail.

Note: The setupapi.h header defines SetupInstallFile as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
```

--------------------------------

### SetupQuerySourceList

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi

Queries the current list of installation sources. The list is built from the system and user-specific lists, and potentially overridden by a temporary list.

```APIDOC
## SetupQuerySourceList

### Description
Queries the current list of installation sources. The list is built from the system and user-specific lists, and potentially overridden by a temporary list (see SetupSetSourceList).

### Function
SetupQuerySourceList

### Variants
- SetupQuerySourceListA (ANSI)
- SetupQuerySourceListW (Unicode)
```

--------------------------------

### Example: calling EnumerateTraceGuids

Source: https://learn.microsoft.com/en-us/windows/win32/api/evntrace/nf-evntrace-enumeratetraceguids

Example showing how to call EnumerateTraceGuids. It first calls with a small buffer to get the actual count, then retries with a larger buffer if ERROR_MORE_DATA is returned. It prints the GUID and enabled status for each provider.

```cpp
#include <windows.h>
#include <evntrace.h>
#include <vector>
#include <stdio.h>

int
wmain()
{
    ULONG status = 0;

    try
    {
        ULONG guidCount;
        std::vector<TRACE_GUID_PROPERTIES> guidPropValues;
        std::vector<TRACE_GUID_PROPERTIES*> guidPropPointers;

        // First call is just to get the actual count, so allocate a small buffer.
        guidCount = 1;

        // May need to retry multiple times since new providers could be added
        // between calls.
        for (;;)
        {
            ULONG const allocated = guidCount;
            guidPropValues.resize(allocated);
            guidPropPointers.resize(allocated);

            // Initialize the pointers to point at the values.
            for (ULONG i = 0; i != allocated; i += 1)
            {
                guidPropPointers[i] = &guidPropValues[i];
            }

            guidCount = 0;
            status = EnumerateTraceGuids(guidPropPointers.data(), allocated, &guidCount);
            if (status != ERROR_MORE_DATA)
            {
                guidPropValues.resize(guidCount);
                break;
            }

        }

        if (status != ERROR_SUCCESS)
        {
            printf("EnumerateTraceGuids error: %u\n", status);
        }
        else
        {
            printf("GuidCount = %lu\n", guidCount);
            for (auto const& v : guidPropValues)
            {
                printf("%08x-%04x-%04x-%02x%02x-%02x%02x%02x%02x%02x%02x - %hs\n",
                    v.Guid.Data1, v.Guid.Data2, v.Guid.Data3,
                    v.Guid.Data4[0], v.Guid.Data4[1],
                    v.Guid.Data4[2], v.Guid.Data4[3], v.Guid.Data4[4],
                    v.Guid.Data4[5], v.Guid.Data4[6], v.Guid.Data4[7],
                    v.IsEnable ? "Enabled" : "Disabled");
            }
        }
    }
    catch (std::bad_alloc const&)
    {
        printf("Out of memory!\n");
        status = ERROR_OUTOFMEMORY;
    }

    return status;
}
```

--------------------------------

### SetupInstallFileExA

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi/nf-setupapi-setupinstallfileexa

Installs a file with extended options, allowing control over copy behavior and providing a callback for notifications.

```APIDOC
## SetupInstallFileExA

### Description
Installs a file with extended options, allowing control over copy behavior and providing a callback for notifications.

### Parameters

#### Flags
- **SP_COPY_SOURCEPATH_ABSOLUTE** - _SourcePathRoot_ is the full path part of the source file. Ignore the relative source specified in the SourceDisksNames section of the INF file for the source media where the file is located. This flag is ignored if SP_COPY_SOURCE_ABSOLUTE is specified.
- **SP_COPY_FORCE_IN_USE** - If the target exists, behave as if it is in use and queue the file for copying on the next system reboot.
- **SP_COPY_IN_USE_NEEDS_REBOOT** - If the file was in use during the copy operation, alert the user that the system requires a reboot.
- **SP_COPY_NOSKIP** - Do not give the user the option to skip a file.
- **SP_COPY_FORCE_NOOVERWRITE** - Check whether the target file exists, and if so, the file is not overwritten. The caller is not notified.
- **SP_COPY_FORCE_NEWER** - Examine each file being copied to see if its version resources (or time stamps for non-image files) indicate that it is not newer than an existing copy on the target. If the file being copied is not newer, the file is not copied. The caller is not notified.
- **SP_COPY_WARNIFSKIP** - If the user tries to skip a file, warn them that skipping a file may affect the installation. (Used for system-critical files.)

#### CopyMsgHandler
- **Type**: Optional pointer to a callback function
- **Description**: Optional pointer to a callback function to be notified of various conditions that may arise during the file copy.

#### Context
- **Type**: Pointer to a caller-defined value
- **Description**: Pointer to a caller-defined value that is passed as the first parameter of the callback function.

#### FileWasInUse
- **Type**: Pointer to a variable
- **Description**: Pointer to a variable in which this function returns a flag that indicates whether the file was in use. This parameter is required.
```

--------------------------------

### Example 3: Build a list of present network adapter devices

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi/nf-setupapi-setupdigetclassdevsa

Calls SetupDiGetClassDevs with the GUID_DEVCLASS_NET class GUID and DIGCF_PRESENT to retrieve present devices from the network adapter setup class.

```cpp
Handle = SetupDiGetClassDevs(&GUID_DEVCLASS_NET, NULL, NULL, DIGCF_PRESENT);

```

--------------------------------

### Example 3: List present network adapter devices

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi/nf-setupapi-setupdigetclassdevsw

Builds a list of all present devices from the network adapter device setup class. Uses the GUID_DEVCLASS_NET class GUID and the DIGCF_PRESENT flag.

```cpp
Handle = SetupDiGetClassDevs(&GUID_DEVCLASS_NET, NULL, NULL, DIGCF_PRESENT);

```

--------------------------------

### SetupInstallFileA function

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi/nf-setupapi-setupinstallfilea

Documentation for the SetupInstallFileA function, including its syntax, parameters, and return value.

```APIDOC
## SetupInstallFileA function

### Description
Installs a file as specified either by an INFCONTEXT returned by SetupFindXXXLine or explicitly by the file name and path. If a file is copied, the caller must have write privileges into the target directory.

### Syntax
```cpp
WINSETUPAPI BOOL SetupInstallFileA(
  [in] HINF                InfHandle,
  [in] PINFCONTEXT         InfContext,
  [in] PCSTR               SourceFile,
  [in] PCSTR               SourcePathRoot,
  [in] PCSTR               DestinationName,
  [in] DWORD               CopyStyle,
  [in] PSP_FILE_CALLBACK_A CopyMsgHandler,
  [in] PVOID               Context
);
```

### Parameters
- **InfHandle** (HINF) - Required - Handle to the INF file that contains the **SourceFile** information.
- **InfContext** (PINFCONTEXT) - Required - Optional pointer to an INFCONTEXT structure that specifies the source file. If this parameter is NULL, **SourceFile** and **SourcePathRoot** are used.
- **SourceFile** (PCSTR) - Required - Optional file name of the source file. This parameter is used only if **InfContext** is NULL.
- **SourcePathRoot** (PCSTR) - Required - Optional root path for the source file. This parameter is used only if **InfContext** is NULL.
- **DestinationName** (PCSTR) - Required - Optional file name of the destination file. If NULL, the source file name is used.
- **CopyStyle** (DWORD) - Required - Flags that control the behavior of the file copy operation.
- **CopyMsgHandler** (PSP_FILE_CALLBACK_A) - Required - Optional pointer to a callback function that receives notifications during the copy operation.
- **Context** (PVOID) - Required - Optional caller-defined context value passed to the callback function.

### Return Value
Returns a BOOL value. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
```

--------------------------------

### SetupDiGetDeviceInstanceIdA

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi/nf-setupapi-setupdigetdeviceinstanceida

Documentation for the SetupDiGetDeviceInstanceIdA function, including syntax, parameters, return value, remarks, and requirements.

```APIDOC
## SetupDiGetDeviceInstanceIdA

### Description
Retrieves the device instance ID that is associated with a device information element.

### Syntax
```cpp
WINSETUPAPI BOOL SetupDiGetDeviceInstanceIdA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [out, optional] PSTR             DeviceInstanceId,
  [in]            DWORD            DeviceInstanceIdSize,
  [out, optional] PDWORD           RequiredSize
);
```

### Parameters
- **DeviceInfoSet** (HDEVINFO) - [in] - A handle to the device information set that contains the device information element that represents the device for which to retrieve a device instance ID.
- **DeviceInfoData** (PSP_DEVINFO_DATA) - [in] - A pointer to an SP_DEVINFO_DATA structure that specifies the device information element in DeviceInfoSet.
- **DeviceInstanceId** (PSTR) - [out, optional] - A pointer to the character buffer that will receive the NULL-terminated device instance ID for the specified device information element.
- **DeviceInstanceIdSize** (DWORD) - [in] - The size, in characters, of the DeviceInstanceId buffer.
- **RequiredSize** (PDWORD) - [out, optional] - A pointer to the variable that receives the number of characters required to store the device instance ID.

### Return Value
Returns TRUE if successful; otherwise, returns FALSE and the logged error can be retrieved by calling GetLastError.

### Remarks
In Windows Vista and later, the unified device property model uses the DEVPKEY_Device_InstanceId property key to represent the device instance identifier. The setupapi.h header defines SetupDiGetDeviceInstanceId as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant.

### Requirements
- **Minimum supported client**: Available in Microsoft Windows 2000 and later versions of Windows.
- **Target Platform**: Desktop
- **Header**: setupapi.h (include Setupapi.h)
- **Library**: Setupapi.lib
```

--------------------------------

### Call MsiGetFeatureValidStates to get valid states for Feature1

Source: https://learn.microsoft.com/en-us/windows/win32/api/msiquery/nf-msiquery-msigetfeaturevalidstatesa

Calls MsiGetFeatureValidStates with the product handle and feature name 'Feature1', storing the result in dwValidStates. The example is from the Remarks section and is used to illustrate how to retrieve the valid installation states for a feature.

```cpp
MsiGetFeatureValidStates(hProduct, "Feature1", &dwValidStates);

```

--------------------------------

### CreateMediaSourceFromStream example

Source: https://learn.microsoft.com/en-us/windows/win32/api/mfidl/nn-mfidl-imfmediasource

Example showing how to use IMFSourceResolver to get an instance of IMFMediaSource from an IMFByteStream.

```APIDOC
## CreateMediaSourceFromStream example

### Description
Example showing how to use IMFSourceResolver to get an instance of IMFMediaSource from an IMFByteStream.

### Code
```cpp
#include <wil.h>
#include <mfplat.h>
#include <mfidl.h>

HRESULT CreateMediaSourceFromStream(_In_ IMFByteStream* stream, _COM_Outptr_ IMFMediaSource** source)
{
    *source = nullptr;

    wil::com_ptr_nothrow<IMFSourceResolver> sourceResolver;
    RETURN_IF_FAILED(MFCreateSourceResolver(&sourceResolver));

    MF_OBJECT_TYPE objectType;
    wil::com_ptr_nothrow<IUnknown> sourceUnknown;
    RETURN_IF_FAILED(sourceResolver->CreateObjectFromByteStream(stream, nullptr, MF_RESOLUTION_MEDIASOURCE, nullptr, &objectType, &sourceUnknown));

    RETURN_IF_FAILED(sourceUnknown.copy_to(IID_PPV_ARGS(source)));
    return S_OK;
}
```
```

--------------------------------

### SetupInstallFileExW

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi/nf-setupapi-setupinstallfileexw

Installs a file as specified by an INFCONTEXT or by filename and path information, returning a BOOL indicating whether the file was in use.

```APIDOC
## SetupInstallFileExW

### Description
Installs a file as specified either by an INFCONTEXT returned by SetupFindXXXLine or explicitly by the filename and path information. This function is the same as SetupInstallFile, except that a BOOL is returned that indicates whether the file was in use.

### Function Signature
BOOL SetupInstallFileExW(...)

### Parameters
- **InfContext** (INFCONTEXT) - Optional - Context returned by SetupFindXXXLine.
- **SourceFile** (PCTSTR) - Optional - Filename of the source file.
- **SourcePathRoot** (PCTSTR) - Optional - Root path of the source file.
- **DestinationName** (PCTSTR) - Optional - Destination filename.
- **CopyStyle** (DWORD) - Optional - Copy style flags.
- **CopyMsgHandler** (PSP_FILE_CALLBACK) - Optional - Callback for copy messages.
- **Context** (PVOID) - Optional - Context for the callback.
- **FileWasInUse** (PBOOL) - Optional - Pointer to a BOOL that receives whether the file was in use.

### Return Value
Returns a BOOL indicating success or failure. If the file was in use, the BOOL pointed to by FileWasInUse is set to TRUE.

### Remarks
If a file is copied, the caller of this function is required to have privileges to write into the target directory.

### Requirements
- Header: setupapi.h
- Library: Setupapi.lib
- DLL: Setupapi.dll
- Unicode: Implemented as SetupInstallFileExW (Unicode) and SetupInstallFileExA (ANSI).
```

--------------------------------

### SetupDiOpenDeviceInterfaceA

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi/nf-setupapi-setupdiopendeviceinterfacea

Documentation for the SetupDiOpenDeviceInterfaceA function, including its syntax, parameters, and return value.

```APIDOC
## SetupDiOpenDeviceInterfaceA

### Description
Retrieves information about a device interface and adds the interface to the specified device information set for a local system or a remote system.

### Syntax
```cpp
WINSETUPAPI BOOL SetupDiOpenDeviceInterfaceA(
  [in]            HDEVINFO                  DeviceInfoSet,
  [in]            PCSTR                     DevicePath,
  [in]            DWORD                     OpenFlags,
  [out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);
```

### Parameters
- **DeviceInfoSet** (HDEVINFO) - Required - A pointer to a device information set that contains, or will contain, a device information element that represents the device that supports the interface to open.
- **DevicePath** (PCSTR) - Required - A pointer to a NULL-terminated string that supplies the name of the device interface to be opened. This name is a Win32 device path that is typically received in a PnP notification structure or obtained by a previous call to SetupDiEnumDeviceInterfaces and its related functions.
- **OpenFlags** (DWORD) - Required - Flags that determine how the device interface element is to be opened. The only valid flag is DIODI_NO_ADD.
- **DeviceInterfaceData** (PSP_DEVICE_INTERFACE_DATA) - Optional - A pointer to a caller-initialized SP_DEVICE_INTERFACE_DATA structure that receives the requested interface data. This pointer is optional and can be NULL. If a buffer is supplied, the caller must set the cbSize member of the structure to sizeof(SP_DEVICE_INTERFACE_DATA) before calling SetupDiOpenDeviceInterface.

### Return Value
Returns a BOOL value. TRUE if successful, FALSE otherwise.
```

--------------------------------

### SetupDiInstallClassExW

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi/nf-setupapi-setupdiinstallclassexw

Installs a class installer or an interface class. This function is typically called by a class installer to install a new device setup class or a new device interface class.

```APIDOC
## SetupDiInstallClassExW

### Description
Installs a class installer or an interface class.

### Syntax
```
WINSETUPAPI BOOL SetupDiInstallClassExW(
  [in, optional] HWND       hwndParent,
  [in, optional] PCWSTR     InfFileName,
  [in]           DWORD      Flags,
  [in, optional] HSPFILEQ   FileQueue,
  [in, optional] const GUID *InterfaceClassGuid,
                 PVOID      Reserved1,
                 PVOID      Reserved2
);
```

### Parameters
- **hwndParent** (HWND) - Optional - Handle to the parent window for any user interface used to install this class. Can be NULL.
- **InfFileName** (PCWSTR) - Optional - Pointer to a NULL-terminated string containing the name of an INF file. Can be NULL. If installing a class installer, must not be NULL and the INF file must contain an INF ClassInstall32 section. If installing an interface class, the INF file must contain an INF InterfaceInstall32 section.
- **Flags** (DWORD) - Required - Controls the installation process. Can be zero or a bitwise OR of the following values:
  - **DI_NOVCP** - Set if FileQueue is supplied. Instructs SetupInstallFromInfSection not to create its own queue and to use the caller-supplied queue. Files are not copied, only queued.
  - **DI_NOBROWSE** - Disables browsing if a copy operation cannot find a specified file. Ignored if a file queue is supplied.
  - **DI_FORCECOPY** - Always copies files, even if already present. Ignored if a file queue is supplied.
  - **DI_QUIETINSTALL** - Suppresses the user interface unless absolutely necessary. Ignored if a file queue is supplied.
- **FileQueue** (HSPFILEQ) - Optional - If DI_NOVCP is set, supplies a handle to a file queue where file operations should be queued but not committed.
- **InterfaceClassGuid** (const GUID*) - Optional - Pointer to a GUID that identifies the interface class to be installed. If specified, the function installs the interface class represented by the GUID. If NULL, the function installs a class installer.
- **Reserved1** (PVOID) - Required - Reserved. Must be zero.
- **Reserved2** (PVOID) - Required - Reserved. Must be zero.

### Return Value
Returns TRUE if successful. Otherwise, returns FALSE and the logged error can be retrieved with a call to GetLastError.

### Remarks
The caller must be a member of the Administrators group. Typically called by a class installer to install a new device setup class or a new device interface class. An interface class can also be installed automatically by calling SetupDiInstallDeviceInterfaces.

### Requirements
- **Minimum supported client**: Available in Microsoft Windows 2000 and later versions of Windows.
- **Target Platform**: Desktop
- **Header**: setupapi.h (include Setupapi.h)
- **Library**: Setupapi.lib

### See Also
- SetupDiCallClassInstaller
- SetupDiInstallDeviceInterfaces
```

--------------------------------

### Example: Get region data from a path

Source: https://learn.microsoft.com/en-us/windows/win32/api/gdiplusheaders/nf-gdiplusheaders-region-getdatasize

Example that creates a region from a path and then gets the data that describes the region. It uses GetDataSize to determine the buffer size, allocates the buffer, and calls GetData to fill it.

```cpp
VOID Example_GetData(HDC)
{
   Point points[] = 
      Point(110, 20),
      Point(120, 30),
      Point(100, 60),
      Point(120, 70),
      Point(150, 60),
      Point(140, 10)};

   GraphicsPath path;
   path.AddClosedCurve(points, 6);

   // Create a region from a path.
   Region pathRegion(&path); 

   // Get the region data.
   UINT bufferSize = 0;
   UINT sizeFilled = 0;
   BYTE* pData = NULL;

   bufferSize = pathRegion.GetDataSize();
   pData = (BYTE*)malloc(bufferSize*sizeof(BYTE));
   pathRegion.GetData(pData, bufferSize, &sizeFilled);
}
```

--------------------------------

### SetupInstallFileExW

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi/nf-setupapi-setupinstallfileexw

Installs a file with optional callback and reports whether the destination file was in use. This function is part of the Windows Setup API.

```APIDOC
## SetupInstallFileExW

### Description
Installs a file, optionally using an INF file for source information, with a callback for progress and cancellation. Reports whether the destination file was in use.

### Syntax
```cpp
WINSETUPAPI BOOL SetupInstallFileExW(
  [in]  HINF                InfHandle,
  [in]  PINFCONTEXT         InfContext,
  [in]  PCWSTR              SourceFile,
  [in]  PCWSTR              SourcePathRoot,
  [in]  PCWSTR              DestinationName,
  [in]  DWORD               CopyStyle,
  [in]  PSP_FILE_CALLBACK_W CopyMsgHandler,
  [in]  PVOID               Context,
  [out] PBOOL               FileWasInUse
);
```

### Parameters
- **InfHandle** (HINF) - Optional. Handle to an INF file containing SourceDisksNames and SourceDisksFiles sections. If platform-specific sections exist, they are used. Ignored if InfContext is not specified and CopyStyle includes SP_COPY_SOURCE_ABSOLUTE or SP_COPY_SOURCEPATH_ABSOLUTE.
- **InfContext** (PINFCONTEXT) - Optional. Context for a line in a Copy Files section. Used to look up file copy information in SourceDisksFiles. If not specified, SourceFile must be specified.
- **SourceFile** (PCWSTR) - Optional. Filename (no path) of the file to copy. Looked up in SourceDisksFiles. Must be specified if InfContext is not. Ignored if InfContext is specified.
- **SourcePathRoot** (PCWSTR) - Optional. Root path for the source file (e.g., A:\ or F:). Paths in SourceDisksNames are appended. Ignored if CopyStyle includes SP_COPY_SOURCE_ABSOLUTE.
- **DestinationName** (PCWSTR) - Optional. New name for the copied file. If InfContext is specified, supplies filename only (no path). Can be NULL to use the same name as source. If InfContext is not specified, supplies full target path and filename.
- **CopyStyle** (DWORD) - Flags controlling copy behavior. Can be a combination of the following values:
  - **SP_COPY_DELETESOURCE** - Delete source file upon successful copy. Caller not notified if delete fails.
  - **SP_COPY_REPLACEONLY** - Copy only if overwriting a file at destination.
  - **SP_COPY_NEWER_OR_SAME** - Copy if source is same version or newer than existing target. If not, and CopyMsgHandler is specified, caller is notified and may cancel. If not specified, file is not copied.
  - **SP_COPY_NEWER_ONLY** - Copy if source is newer than existing target.
  - **SP_COPY_NOOVERWRITE** - Check if target exists; if so, notify caller who may veto. If CopyMsgHandler not specified, file is not overwritten.
  - **SP_COPY_NODECOMP** - Do not decompress the file. Target file is not given uncompressed form of source name. No language or version information can be checked.
  - **SP_COPY_LANGUAGEAWARE** - Check if source language differs from existing target. If so, and CopyMsgHandler is specified, caller is notified and may cancel. If not specified, file is not copied.
  - **SP_COPY_SOURCE_ABSOLUTE** - SourceFile is a full source path. Do not look it up in SourceDisksNames.
- **CopyMsgHandler** (PSP_FILE_CALLBACK_W) - Optional. Callback function for progress and cancellation.
- **Context** (PVOID) - Optional. Context passed to the callback.
- **FileWasInUse** (PBOOL) - Output. Pointer to a BOOL that receives TRUE if the destination file was in use, FALSE otherwise.

### Return Value
Returns TRUE if the function succeeds, FALSE otherwise. To get extended error information, call GetLastError.

```

--------------------------------

### SetupInstallFile

Source: https://learn.microsoft.com/en-us/windows/win32/api/setupapi

Installs a file as specified either by an INFCONTEXT returned by SetupFindXXXLine or explicitly by the file name and path. Available in ANSI (SetupInstallFileA) and Unicode (SetupInstallFileW) variants.

```APIDOC
## SetupInstallFile

### Description
Installs a file as specified either by an INFCONTEXT returned by SetupFindXXXLine or explicitly by the file name and path.

### Function
SetupInstallFile

### Variants
- SetupInstallFileA (ANSI)
- SetupInstallFileW (Unicode)

```
Tokens:
Raw