PGET_LOCATION_STRING callback function (ntddk.h)

Article
02/22/2024

The PnpGetLocationString routine provides the device-specific part of the device's SPDRP_LOCATION_PATHS property.

Syntax

PGET_LOCATION_STRING PgetLocationString;

NTSTATUS PgetLocationString(
  [in, out] PVOID Context,
  [out]     PZZWSTR *LocationStrings
)
{...}

Parameters

[in, out] Context

A pointer to interface-specific context information. The caller passes the value that is passed as the Context member of the PNP_LOCATION_INTERFACE structure.

[out] LocationStrings

A pointer to a sequence of null-terminated Unicode strings, that is terminated by another zero. Each string serves as a location string for the device. Drivers typically return a single string.

Return value

The routine returns an NTSTATUS value to indicate the status of the operation.

Remarks

The PNP_LOCATION_INTERFACE structure supplies a pointer to the PnpGetLocationString routine.

The PnpGetLocationString routine provides the device-specific part of the location string for the device. The Plug and Play (PnP) manager assembles the location string for a device by querying the driver for the device, for the device's bus, and any parent buses, and concatenating the provided strings together.

The routine must return a string that is unique to the device relative to its bus. The string must be the same for the device across all versions of the operating system. Once you select a string for this purpose, you must not change it.

By convention, the location string takes the form ServiceName(BusSpecificLocation). For example, PCI devices use PCI(XXYY), where XX is the device number, and YY is the function number.

The PnpGetLocationString routine calls a routine such as ExAllocatePoolWithTag to allocate the memory for the location string. The caller is responsible for calling the ExFreePool routine to free the memory pointed to by LocationStrings when the location string is no longer needed.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows Server 2003.
Target Platform	Desktop
Header	ntddk.h (include Ntddk.h, Ntifs.h)
IRQL	<= PASSIVE_LEVEL