Skip to content

Latest commit

 

History

History
120 lines (89 loc) · 5.3 KB

nc-ks-pfnkshandler.md

File metadata and controls

120 lines (89 loc) · 5.3 KB
Raw
UID title description old-location tech.root ms.date keywords ms.keywords req.header req.include-header req.target-type req.target-min-winverclnt req.target-min-winversvr req.kmdf-ver req.umdf-ver req.ddi-compliance req.unicode-ansi req.idl req.max-support req.namespace req.assembly req.type-library req.lib req.dll req.irql targetos req.typenames f1_keywords topic_type api_type api_location api_name
NC:ks.PFNKSHANDLER
PFNKSHANDLER (ks.h)
The minidriver-provided routine is called when Kernel Streaming receives an IOCTL_KS_METHOD, get/set property request. Provide a pointer to this handler in the relevant KSMETHOD_ITEM, KSPROPERTY_ITEM structure.
stream\kstrmethodhandler.htm
stream
07/15/2021
PFNKSHANDLER callback function
KStrGetPropertyHandler, KStrHandler, KStrHandler routine [Streaming Media Devices], KStrMethodHandler, KStrSetPropertyHandler, KStrSupportHandler, PFNKSHANDLER, ks/KStrHandler, ksfunc_53b62198-4059-4715-b405-c6f55d736a09.xml, stream.kstrmethodhandler
ks.h
Ks.h
Desktop
Windows
PFNKSHANDLER
ks/PFNKSHANDLER
APIRef
kbSyntax
UserDefined
ks.h
PFNKSHANDLER

PFNKSHANDLER callback function

-description

The minidriver-provided routine is called when Kernel Streaming receives an IOCTL_KS_METHOD, get/set property request. Provide a pointer to this handler in the relevant KSMETHOD_ITEM, KSPROPERTY_ITEM structure.

-parameters

-param Irp [in]

Specifies the IRP that contains the method or property request.

-param Request [in]

Specifies an aligned copy of the method parameter. This is typically a pointer to a KSMETHOD or KSPROPERTY structure.

-param Data [in, out]

Specifies an aligned copy of the method data parameter or the system address of the original data parameter, depending on the flag that was specified in the KSMETHOD_ITEM structure for the method.

-returns

Return STATUS_SUCCESS if the method is handled and the data buffer has been filled per the flag that was specified in KSMETHOD_ITEM. If returning data, your driver should set the Irp->IoStatus.Information field, but should not set the Irp->IoStatus.Status field nor should it complete the IRP. Mark the IRP pending if it is to be completed asynchronously.

Alternatively, return STATUS_SOME_NOT_MAPPED if the method has been handled but the particular request has not been completed and must be completed by the calling helper function. Return any other error message to indicate that the method is not supported or a parameter error has occurred.

-remarks

The minidriver specifies this routine's address in the MethodHandler member of the KSMETHOD_ITEM structure.

The handler declaration used for KStrMethodHandler and KStrSupportHandler is also used for handlers of property and event sets, with the same parameters and return values.

When a helper function such as KsMethodHandler calls a method handler whose data buffer is defined as a write or modify buffer, the method handler must set the Information member of the IO_STATUS_BLOCK structure for the IoStatus member within the IRP (Irp parameter) to the size of that data buffer. The minidriver sets the Flags member of the KSMETHOD_ITEM structure for the method to KSMETHOD_TYPE_WRITE or KSMETHOD_TYPE_MODIFY to define the method handler's data buffer as write or modify respectively.

The following code snippet shows an example of an implementation of a method handler that sets the size of the returning data buffer in the IRP:

NTSTATUS
  MethodHandler(PIRP pIrp, PKSIDENTIFIER Request, PVOID Data) {
    NTSTATUS Status = STATUS_UNSUCCESSFUL;
    // Pointer to hold the position on the Irp stack
    PIO_STACK_LOCATION  pIrpStack  = NULL;
    ASSERT(pIrp);
    if(Data) {
        // Modify data here
    }
    // Find the current Irp stack.
    pIrpStack = IoGetCurrentIrpStackLocation(pIrp);
    if(pIrpStack) {
        // Set the size of the returning Irp data.
        pIrp->IoStatus.Information =
          pIrpStack->Parameters.DeviceIoControl.OutputBufferLength;
        Status = STATUS_SUCCESS;
    }
    return(Status);
}

The minidriver specifies this routine's address in the GetPropertyHandler member of the KSPROPERTY_ITEM structure.

The minidriver specifies this routine's address in the SetPropertyHandler member of the KSPROPERTY_ITEM structure.

The minidriver specifies this routine's address in the SupportHandler member of the KSMETHOD_ITEM structure.

The handler declaration used for KStrMethodHandler and KStrSupportHandler is also used for handlers of property and event sets, with the same parameters and return values.

-see-also

KSMETHOD

KSMETHOD_ITEM

KSMETHOD_SET

KsMethodHandler