PFN_WSK_CONTROL_SOCKET 콜백 함수(wsk.h)

아티클
08/08/2023

WskControlSocket 함수는 소켓에서 제어 작업을 수행합니다.

구문

PFN_WSK_CONTROL_SOCKET PfnWskControlSocket;

NTSTATUS PfnWskControlSocket(
  [in]            PWSK_SOCKET Socket,
  [in]            WSK_CONTROL_SOCKET_TYPE RequestType,
  [in]            ULONG ControlCode,
  [in]            ULONG Level,
  [in]            SIZE_T InputSize,
  [in, optional]  PVOID InputBuffer,
  [in]            SIZE_T OutputSize,
  [out, optional] PVOID OutputBuffer,
  [out, optional] SIZE_T *OutputSizeReturned,
  [in, out]       PIRP Irp
)
{...}

매개 변수

[in] Socket

컨트롤 작업이 수행되는 소켓의 소켓 개체를 지정하는 WSK_SOCKET 구조체에 대한 포인터입니다.

[in] RequestType

수행 중인 컨트롤 작업의 형식을 지정하는 값입니다. WSK 애플리케이션은 이 매개 변수를 다음 값 중 하나로 설정합니다.

WskSetOption

소켓 옵션의 상태 또는 값을 설정합니다.

WskGetOption

소켓 옵션의 상태 또는 값을 가져옵니다.

WskIoctl

I/O 컨트롤 작업을 수행합니다.

[in] ControlCode

RequestType 매개 변수가 WskSetOption 또는 WskGetOption으로 설정된 경우 ControlCode 매개 변수는 값이 설정되거나 검색되는 특정 소켓 옵션을 지정합니다. WSK 하위 시스템이 지원하는 소켓 옵션에 대한 자세한 내용은 WSK 소켓 옵션을 참조하세요. 기본 네트워크 프로토콜은 추가 소켓 옵션을 지원할 수 있습니다.

RequestType 매개 변수가 WskIoctl로 설정된 경우 ControlCode 매개 변수는 수행 중인 특정 I/O 컨트롤 작업을 지정합니다. WSK 하위 시스템이 지원하는 I/O 제어 작업에 대한 자세한 내용은 WSK 소켓 IOCTL 작업을 참조하세요. 기본 네트워크 프로토콜은 추가 소켓 I/O 제어 작업을 지원할 수 있습니다.

[in] Level

소켓 옵션 값이 설정되거나 검색되는 네트워크 스택의 수준입니다. WSK 하위 시스템 수준 소켓 옵션의 경우 WSK 애플리케이션은 이 매개 변수를 SOL_SOCKET 설정해야 합니다. 전송 프로토콜 또는 네트워크 프로토콜 수준 소켓 옵션의 경우 WSK 애플리케이션은 이 매개 변수를 기본 전송에 적합한 수준으로 설정해야 합니다.

RequestType 매개 변수가 WskIoctl로 설정된 경우 Level 매개 변수는 무시됩니다.

[in] InputSize

InputBuffer 매개 변수가 가리키는 버퍼의 데이터 바이트 수입니다.

[in, optional] InputBuffer

지정된 컨트롤 작업을 수행하는 데 필요한 입력 데이터를 제공하는 호출자가 할당한 버퍼입니다. 지정된 컨트롤 작업에 입력 데이터가 필요하지 않은 경우 WSK 애플리케이션은 이 매개 변수를 NULL 로 설정하고 InputSize 매개 변수를 0으로 설정해야 합니다.

[in] OutputSize

OutputBuffer 매개 변수가 가리키는 버퍼의 크기입니다.

[out, optional] OutputBuffer

지정된 컨트롤 작업에서 반환되는 출력 데이터를 수신하는 호출자가 할당한 버퍼입니다. 지정된 컨트롤 작업에서 출력 데이터가 반환되지 않으면 WSK 애플리케이션은 이 매개 변수를 NULL 로 설정하고 OutputSize 매개 변수를 0으로 설정해야 합니다.

[out, optional] OutputSizeReturned

OutputBuffer 매개 변수가 가리키는 버퍼에 반환되는 데이터 바이트 수를 수신하는 ULONG 형식 변수에 대한 포인터입니다. WSK 애플리케이션은 다음이 모두 true인 경우를 제외하고 OutputSizeReturned 매개 변수를 NULL 로 설정해야 합니다.

Irp 매개 변수가 NULL로 설정됩니다.
수행 중인 작업은 OutputBuffer 매개 변수가 가리키는 버퍼의 출력 데이터를 반환합니다.
수행 중인 작업에서 반환되는 출력 데이터의 바이트 수는 알 수 없습니다.

[in, out] Irp

WSK 하위 시스템이 제어 작업을 비동기적으로 완료하는 데 사용하는 호출자 할당 IRP에 대한 포인터입니다. WSK 함수와 함께 IRP를 사용하는 방법에 대한 자세한 내용은 Winsock 커널 함수에서 IRP 사용을 참조하세요.

RequestType 매개 변수가 WskSetOption 또는 WskGetOption으로 설정된 경우 Irp 매개 변수는 필수이거나 선택 사항이거나 설정되거나 검색되는 특정 소켓 옵션에 따라 NULL이어야 합니다. 지원되는 각 소켓 옵션의 Irp 매개 변수 요구 사항에 대한 자세한 내용은 WSK 소켓 옵션을 참조하세요.

RequestType 매개 변수가 WskIoctl로 설정된 경우 Irp 매개 변수가 필요하거나, 선택 사항이거나, 수행 중인 특정 I/O 컨트롤 작업에 따라 NULL이어야 합니다. 지원되는 각 I/O 컨트롤 작업에 대한 Irp 매개 변수의 요구 사항에 대한 자세한 내용은 WSK 소켓 IOCTL 작업을 참조하세요.

반환 값

WskControlSocket 은 다음 NTSTATUS 코드 중 하나를 반환합니다.

반환 코드	설명
STATUS_SUCCESS	컨트롤 작업이 성공적으로 완료되었습니다. WSK 애플리케이션이 Irp 매개 변수에서 IRP에 대한 포인터를 지정하면 성공 상태 IRP가 완료되고 OutputBuffer 매개 변수가 가리키는 버퍼에 반환되는 바이트 수가 IRP의 IoStatus.Information 필드에 반환됩니다.
STATUS_PENDING	WSK 하위 시스템이 제어 작업을 즉시 완료할 수 없습니다. WSK 하위 시스템은 컨트롤 작업을 완료한 후 IRP를 완료합니다. 컨트롤 작업의 상태 IRP의 IoStatus.Status 필드에 반환됩니다. 작업이 성공하면 OutputBuffer 매개 변수가 가리키는 버퍼에 반환되는 바이트 수가 IRP의 IoStatus.Information 필드에 반환됩니다.
STATUS_EVENT_PENDING	WSK 하위 시스템이 제어 작업을 즉시 완료할 수 없습니다. 이 값은 WSK 애플리케이션이 해당 이벤트 콜백 함수에 대한 현재 진행 중인 호출이 있고 Irp 매개 변수가 NULL인 경우에만 소켓에서 이벤트 콜백 함수를 사용하지 않도록 설정하는 경우에만 반환됩니다. 이벤트 콜백 함수를 사용하지 않도록 설정하는 방법에 대한 자세한 내용은 SO_WSK_EVENT_CALLBACK 참조하세요.
STATUS_FILE_FORCED_CLOSED	소켓이 더 이상 작동하지 않습니다. IRP는 실패 상태 완료됩니다. WSK 애플리케이션은 WskCloseSocket 함수를 호출하여 가능한 한 빨리 소켓을 닫아야 합니다.
기타 상태 코드	오류가 발생했습니다. IRP는 실패 상태 완료됩니다.

설명

WSK 애플리케이션이 RequestType 매개 변수에서 WskSetOption 또는 WskGetOption을 지정하는 경우 각 소켓 옵션에 입력 및 출력 버퍼를 사용하는 방법에 대한 자세한 내용은 WSK 소켓 옵션을 참조하세요.

WSK 애플리케이션이 RequestType 매개 변수에서 WskIoctl을 지정하는 경우 입력 및 출력 버퍼가 각 I/O 컨트롤 작업에 사용되는 방법에 대한 자세한 내용은 WSK 소켓 IOCTL 작업을 참조하세요.

WskControlSocket 함수가 STATUS_PENDING 반환하는 경우 InputBuffer 매개 변수 또는 OutputBuffer 매개 변수가 가리키는 버퍼는 IRP가 완료될 때까지 유효한 상태를 유지해야 합니다. WSK 애플리케이션이 ExAllocateXxx 함수 중 하나를 사용하여 버퍼를 할당한 경우 IRP가 완료될 때까지 해당 ExFreeXxx 함수로 메모리를 해제할 수 없습니다. WSK 애플리케이션이 스택에 버퍼를 할당한 경우 IRP가 완료될 때까지 WskControlSocket 함수를 호출하는 함수에서 반환할 수 없습니다.

RequestType 매개 변수가 WskIoctl로 설정되고 ControlCode 매개 변수가 SIO_ADDRESS_LIST_QUERY, SIO_ADDRESS_LIST_CHANGE 또는 SIO_ADDRESS_LIST_SORT 설정된 경우를 제외하고 WskControlSocket 함수의 호출자는 IRQL< = DISPATCH_LEVEL 실행되어야 합니다. 이 경우 호출자는 IRQL = PASSIVE_LEVEL 실행되어야 합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista 이상 버전의 Windows 운영 체제에서 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	wsk.h(Wsk.h 포함)
IRQL	<= DISPATCH_LEVEL(설명 섹션 참조)