PGET_LOCATION_STRING callback function (ntddk.h)

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

See also

ExAllocatePoolWithTag

ExFreePool

PNP_LOCATION_INTERFACE