EVT_SERCX_APPLY_CONFIG 콜백 함수(sercx.h)

EvtSerCxApplyConfig 이벤트 콜백 함수는 직렬 컨트롤러 드라이버에 직렬 컨트롤러 하드웨어에 구성 설정 목록을 적용하도록 지시합니다.

구문

EVT_SERCX_APPLY_CONFIG EvtSercxApplyConfig;

NTSTATUS EvtSercxApplyConfig(
  [in] WDFDEVICE Device,
  [in] PVOID ConnectionParameters
)
{...}

매개 변수

[in] Device

직렬 컨트롤러를 나타내는 프레임워크 디바이스 개체에 대한 WDFDEVICE 핸들입니다.

[in] ConnectionParameters

연결 매개 변수 구조에 대한 포인터입니다. 이 함수는 이 매개 변수를 적절한 포인터 형식으로 캐스팅하고, 데이터 구조를 구문 분석하여 구성 설정을 가져오고, 이러한 설정을 직렬 컨트롤러 하드웨어에 적용해야 합니다. 연결 매개 변수 구조는 하드웨어 플랫폼 공급업체에 의해 정의되며 SerCx(직렬 프레임워크 확장)와 운영 체제 모두에 불투명합니다.

반환 값

EvtSerCxApplyConfig 함수는 호출이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 적절한 오류 상태 코드를 반환합니다.

설명

SerCx는 직렬 컨트롤러를 초기화하는 동안 이 함수를 호출하여 하드웨어가 유효한 초기 상태인지 확인합니다. 또한 이 함수는 클라이언트가 컨트롤러에 IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION I/O 제어 요청을 보낼 때마다 호출됩니다.

SerCx는 직렬 컨트롤러 디바이스에 대한 ACPI 리소스 설명자에서 이러한 구성 매개 변수를 가져옵니다. ACPI 펌웨어가 이러한 구성 설정을 저장하는 데 사용하는 데이터 형식은 직렬 컨트롤러 드라이버에서 예상한 것과 동일한 데이터 형식이어야 합니다.

클라이언트가 SerCx에서 관리하는 직렬 포트에 IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION 요청을 보내면 SerCx는 직렬 포트의 직렬 컨트롤러 드라이버가 EvtSerCxApplyConfig 콜백을 지원하는지 여부와 직렬 포트에 대한 ACPI 리소스 설명자가 기본 연결 설정을 제공하는지 여부를 결정합니다. 그렇지 않은 경우 SerCx는 오류 상태 코드 STATUS_NOT_SUPPORTED 사용하여 요청을 완료합니다. 그렇지 않으면 SerCx는 연결 매개 변수를 드라이버의 EvtSerCxApplyConfig 콜백 함수에 전달합니다. 이 콜백이 반환되면 SerCx는 요청을 완료하고 콜백의 반환 값을 요청에 대한 상태 코드로 사용합니다.

직렬 컨트롤러 드라이버가 EvtSerCxApplyConfig 콜백 중 이외의 시간에 기본 연결 매개 변수를 가져와야 하는 경우 드라이버는 SerCxGetConnectionParameters 메서드를 호출할 수 있습니다.

EvtSerCxApplyConfig 콜백 함수를 등록하려면 드라이버가 SerCxInitialize 메서드를 호출해야 합니다.

예제

이 콜백에 대한 함수 형식은 다음과 같이 Sercx.h에서 선언됩니다.

typedef NTSTATUS
  EVT_SERCX_APPLY_CONFIG(
    __in WDFDEVICE Device
    );

라는 MyEvtSerCxApplyConfigEvtSerCxApplyConfig 콜백 함수를 정의하려면 먼저 다음과 같이 SDV(정적 드라이버 검증 도구) 및 기타 확인 도구에 필요한 함수 선언을 제공해야 합니다.

EVT_SERCX_APPLY_CONFIG MyEvtSerCxApplyConfig;

그런 다음, 다음과 같이 콜백 함수를 구현합니다.

NTSTATUS
  MyEvtSerCxApplyConfig(
    __in WDFDEVICE Device
    )
{ ... }

함수 선언에 대한 SDV 요구 사항에 대한 자세한 내용은 KMDF 드라이버에 함수 역할 형식을 사용하여 함수 선언을 참조하세요.

//
// Define the UART ACPI descriptor, plus any vendor-specific
// data that is needed by the serial controller (UART) driver.
//

#define ANYSIZE_ARRAY 1


//
// Common resource name descriptor
//
typedef struct _PNP_IO_DESCRIPTOR_RESOURCE_NAME {
    UCHAR ResourceIndex;
    UCHAR ResourceName[ANYSIZE_ARRAY];
} PNP_IO_DESCRIPTOR_RESOURCE_NAME, *PPNP_IO_DESCRIPTOR_RESOURCE_NAME;

//
// Bus descriptor for a UART
//
typedef struct _PNP_UART_SERIAL_BUS_DESCRIPTOR {
    PNP_SERIAL_BUS_DESCRIPTOR SerialBusDescriptor;
    ULONG BaudRate;
    USHORT RxBufferSize;
    USHORT TxBufferSize;
    UCHAR Parity;
    // Include any optional vendor data here:
    ...
    // Append the PNP_IO_DESCRIPTOR_RESOURCE_NAME here:
    ....
} PNP_UART_SERIAL_BUS_DESCRIPTOR, *PPNP_UART_SERIAL_BUS_DESCRIPTOR;

EVT_SERCX_APPLY_CONFIG UartEvtApplyConfig;

//
// Implementation of an EvtSerCxApplyConfig callback function
//
NTSTATUS
  UartEvtApplyConfig(
    __in WDFDEVICE Device,
    __in PVOID ConnectionParameters
    )
{
    NTSTATUS status = STATUS_SUCCESS; 
    PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER connection;
    PPNP_SERIAL_BUS_DESCRIPTOR descriptor;
    PPNP_UART_SERIAL_BUS_DESCRIPTOR uartDescriptor;

    if (ConnectionParameters == NULL)
    {
        status = STATUS_INVALID_PARAMETER; 
    }

    if (NT_SUCCESS(status))
    {
        connection = (PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER)ConnectionParameters;

        if (connection->PropertiesLength < sizeof(PNP_SERIAL_BUS_DESCRIPTOR))
        {
            status = STATUS_INVALID_PARAMETER;
        }
    }

    if (NT_SUCCESS(status))
    {
        descriptor = (PPNP_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties;

        if (descriptor->SerialBusType != UART_SERIAL_BUS_TYPE)
        {
            status = STATUS_INVALID_PARAMETER;
        }
    }

    if (NT_SUCCESS(status))
    {
        uartDescriptor = (PPNP_UART_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties; 

        // Apply the configuration settings from
        // the UART descriptor.
        ...
    }

    return status;
}

이전 코드 예제의 PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER 및 PPNP_SERIAL_BUS_DESCRIPTOR 포인터 형식은 Reshub.h 헤더 파일에 정의되어 있습니다.

요구 사항

추가 정보

IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION

SerCxGetConnectionParameters

SerCxInitialize