WSAIoctl 함수(winsock2.h)
WSAIoctl 함수는 소켓의 모드를 제어합니다.
구문
int WSAAPI WSAIoctl(
[in] SOCKET s,
[in] DWORD dwIoControlCode,
[in] LPVOID lpvInBuffer,
[in] DWORD cbInBuffer,
[out] LPVOID lpvOutBuffer,
[in] DWORD cbOutBuffer,
[out] LPDWORD lpcbBytesReturned,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);
매개 변수
[in] s
소켓을 식별하는 설명자입니다.
[in] dwIoControlCode
수행할 작업의 제어 코드입니다. Winsock IOCTL을 참조하세요.
[in] lpvInBuffer
입력 버퍼에 대한 포인터입니다.
[in] cbInBuffer
입력 버퍼의 크기(바이트)입니다.
[out] lpvOutBuffer
출력 버퍼에 대한 포인터입니다.
[in] cbOutBuffer
출력 버퍼의 크기(바이트)입니다.
[out] lpcbBytesReturned
실제 출력 바이트 수에 대한 포인터입니다.
[in] lpOverlapped
WSAOVERLAPPED 구조체에 대한 포인터입니다(겹치지 않는 소켓의 경우 무시됨).
[in] lpCompletionRoutine
형식: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
반환 값
성공적으로 완료되면 WSAIoctl 은 0을 반환합니다. 그렇지 않으면 SOCKET_ERROR 값이 반환되고 WSAGetLastError를 호출하여 특정 오류 코드를 검색할 수 있습니다.
| 오류 코드 | 의미 |
|---|---|
| 겹치는 작업이 성공적으로 시작되었으며 나중에 완료가 표시됩니다. | |
| 네트워크 하위 시스템이 실패했습니다. | |
| lpvInBuffer, lpvOutBuffer, lpcbBytesReturned, lpOverlapped 또는 lpCompletionRoutine 매개 변수가 사용자 주소 공간의 유효한 부분에 완전히 포함되지 않았거나 cbInBuffer 또는 cbOutBuffer 매개 변수가 너무 작습니다. | |
| dwIoControlCode 매개 변수가 유효한 명령이 아니거나 지정된 입력 매개 변수가 허용되지 않거나 지정된 소켓 형식에 명령을 적용할 수 없습니다. | |
| 콜백이 진행 중일 때 함수가 호출됩니다. | |
| 설명자 가 소켓이 아닙니다. | |
| 지정된 IOCTL 명령을 실현할 수 없습니다. 예를 들어 SIO_SET_QOS 또는 SIO_SET_GROUP_QOS 지정된 FLOWSPEC 구조체를 충족할 수 없습니다. | |
| 소켓이 비차단으로 표시되고 요청된 작업이 차단됩니다. | |
| 소켓 옵션은 지정된 프로토콜에서 지원되지 않습니다. 예를 들어 IPv6 소켓에서 SIO_GET_BROADCAST_ADDRESS IOCTL을 사용하려고 시도했거나 데이터그램 소켓에서 TCP SIO_KEEPALIVE_VALS IOCTL을 사용하려고 했습니다. |
설명
WSAIoctl 함수는 소켓, 전송 프로토콜 또는 통신 하위 시스템에 연결된 운영 매개 변수를 설정하거나 검색하는 데 사용됩니다.
lpOverlapped 및 lpCompletionRoutine이 모두 NULL인 경우 이 함수의 소켓은 겹치지 않는 소켓으로 처리됩니다. 겹치지 않는 소켓의 경우 lpOverlapped 및 lpCompletionRoutine 매개 변수가 무시되므로 소켓이 차단 모드인 경우 함수가 차단할 수 있다는 점을 제외하고 함수가 표준 ioctlsocket 함수처럼 동작합니다. 소켓 이 비차단 모드인 경우 지정된 작업을 즉시 완료할 수 없는 경우 이 함수는 WSAEWOULDBLOCK을 반환할 수 있습니다. 이 경우 애플리케이션은 Windows 메시지(WSAAsyncSelect 사용) 기반 또는 이벤트(WSAEventSelect 사용) 기반 알림 메커니즘을 사용하여 소켓을 차단 모드로 변경하고 요청을 다시 발생하거나 해당 네트워크 이벤트(예 FD_ROUTING_INTERFACE_CHANGE: SIO_ROUTING_INTERFACE_CHANGE 또는 SIO_ADDRESS_LIST_CHANGE 경우 FD_ADDRESS_LIST_CHANGE)를 기다릴 수 있습니다.
겹치는 소켓의 경우 즉시 완료할 수 없는 작업이 시작되고 나중에 완료가 표시됩니다. 반환되는 lpcbBytesReturned 매개 변수가 가리키는 DWORD 값은 무시될 수 있습니다. 작업이 완료되었을 때 적절한 완료 메서드가 신호를 받으면 반환되는 최종 완료 상태 및 바이트를 검색할 수 있습니다.
모든 IOCTL은 서비스 공급자의 구현에 따라 무기한 차단할 수 있습니다. 애플리케이션이 WSAIoctl 호출에서 차단을 허용할 수 없는 경우 겹치는 I/O는 다음을 포함하여 차단할 가능성이 높은 IOCTL에 대해 권장됩니다.
SIO_ADDRESS_LIST_CHANGE
SIO_FINDROUTE
SIO_FLUSH
SIO_GET_QOS
SIO_GET_GROUP_QOS
SIO_ROUTING_INTERFACE_CHANGE
SIO_SET_QOS
SIO_SET_GROUP_QOS
일부 프로토콜별 IOCTL은 특히 차단될 수 있습니다. 사용 가능한 정보는 관련 프로토콜별 부속서를 확인합니다.
lpCompletionRoutine 매개 변수가 가리키는 완료 루틴의 프로토타입은 다음과 같습니다.
#ifndef UNICODE
#define UNICODE
#endif
#define WIN32_LEAN_AND_MEAN
#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>
// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")
void CALLBACK CompletionRoutine (
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
CompletionRoutine은 애플리케이션에서 제공하는 함수 이름의 자리 표시자입니다. dwError 매개 변수는 lpOverlapped 매개 변수로 표시된 대로 겹치는 작업에 대한 완료 상태 지정합니다. cbTransferred 매개 변수는 수신된 바이트 수를 지정합니다. dwFlags 매개 변수는 이 IOCTL에 사용되지 않습니다. 완료 루틴은 값을 반환하지 않습니다.
dwIoControlCode 매개 변수가 이제 32비트 엔터티인 만큼 opcode 식별자 공간을 분할하는 편리한 방법을 제공하면서 현재 정의된 ioctlsocket opcode를 유지하는 인코딩 체계를 채택할 수 있습니다. dwIoControlCode 매개 변수는 Windows Sockets 1.1 및 Unix 제어 코드와의 이전 버전과의 호환성을 유지하면서 새 제어 코드를 추가할 때 프로토콜 및 공급업체의 독립성을 허용하도록 빌드되었습니다. dwIoControlCode 매개 변수에는 다음과 같은 형식이 있습니다.
| I | O | V | T | 공급업체/주소 패밀리 | 코드 |
|---|---|---|---|---|---|
| 3 | 3 | 2 | 2 2 | 2 2 2 2 2 2 2 1 1 1 1 | 1 1 1 1 1 1 |
| 1 | 0 | 9 | 8 7 | 6 5 4 3 2 1 0 9 8 7 6 | 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 |
출력 버퍼가 IOC_OUT 코드에 유효한 경우 O가 설정됩니다. 입력 버퍼와 출력 버퍼를 모두 사용하여 코드를 제어하여 I와 O를 모두 설정합니다.
IOC_VOID 코드에 대한 매개 변수가 없는 경우 V가 설정됩니다.
T는 IOCTL의 형식을 정의하는 2비트 수량입니다. 다음 값이 정의됩니다.
0 IOCTL은 FIONREAD 및 FIONBIO와 마찬가지로 표준 Unix IOCTL 코드입니다.
1 IOCTL은 일반 Windows 소켓 2 IOCTL 코드입니다. Windows 소켓 2에 대해 정의된 새 IOCTL 코드에는 T == 1이 있습니다.
2 IOCTL은 특정 주소 패밀리에만 적용됩니다.
3 IOCTL은 IOC_VENDOR 마찬가지로 특정 공급업체의 공급자에만 적용됩니다. 이 유형을 사용하면 공급업체 /주소 패밀리 매개 변수에 표시되는 공급업체 번호를 회사에 할당할 수 있습니다. 그런 다음 공급업체는 IOCTL을 클리어링하우스에 등록하지 않고도 해당 공급업체에 한정된 새 IOCTL을 정의하여 공급업체의 유연성과 프라이버시를 제공할 수 있습니다.
공급업체/주소 패밀리 코드를 소유하거나(T == 3인 경우) 코드가 적용되는 주소 패밀리를 포함하는 공급업체를 정의하는 11비트 수량입니다(T == 2인 경우). Unix IOCTL 코드(T == 0)인 경우 이 매개 변수의 값은 Unix의 코드와 같습니다. 일반 Windows 소켓 2 IOCTL(T == 1)인 경우 이 매개 변수를 코드 매개 변수의 확장으로 사용하여 추가 코드 값을 제공할 수 있습니다.
코드 작업에 대한 특정 IOCTL 코드를 포함하는 16비트 수량입니다.
다음 Unix IOCTL 코드(명령)가 지원됩니다.
다음 Windows 소켓 2 명령이 지원됩니다.
겹치는 작업이 즉시 완료되면 WSAIoctl 은 값 0을 반환하고 lpcbBytesReturned 매개 변수는 출력 버퍼의 바이트 수로 업데이트됩니다. 겹치는 작업이 성공적으로 시작되고 나중에 완료될 경우 이 함수는 SOCKET_ERROR 반환하고 오류 코드 WSA_IO_PENDING 나타냅니다. 이 경우 lpcbBytesReturned 은 업데이트되지 않습니다. 겹치는 작업이 완료되면 출력 버퍼의 데이터 양은 완료 루틴(지정된 경우)의 cbTransferred 매개 변수를 통해 또는 WSAGetOverlappedResult의 lpcbTransfer 매개 변수를 통해 표시됩니다.
겹치는 소켓을 사용하여 호출되는 경우 lpOverlapped 매개 변수는 겹치는 작업 기간 동안 유효해야 합니다. lpOverlapped 매개 변수는 WSAOVERLAPPED 구조체의 주소를 포함합니다.
lpCompletionRoutine 매개 변수가 NULL이면 유효한 이벤트 개체 핸들이 포함된 경우 겹치는 작업이 완료될 때 lpOverlapped의 hEvent 매개 변수가 신호를 보냅니다. 애플리케이션은 WSAWaitForMultipleEvents 또는 WSAGetOverlappedResult 를 사용하여 이벤트 개체를 기다리거나 폴링할 수 있습니다.
완료 루틴의 프로토타입은 다음과 같습니다.
void CALLBACK CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
이 CompletionRoutine 은 애플리케이션 정의 또는 라이브러리 정의 함수의 자리 표시자입니다. 완료 루틴은 스레드가 경고 가능한 상태인 경우에만 호출됩니다. 스레드를 경고 가능한 상태로 전환하려면 fAlertable 또는 bAlertable 매개 변수가 TRUE로 설정된 WSAWaitForMultipleEvents, WaitForSingleObjectEx 또는 WaitForMultipleObjectsEx 함수를 사용합니다.
CompletionRoutine의 dwError 매개 변수는 lpOverlapped로 표시된 대로 겹치는 작업에 대한 완료 상태 지정합니다. cbTransferred 매개 변수는 반환된 바이트 수를 지정합니다. 현재 플래그 값은 정의되지 않으며 dwFlags는 0이 됩니다. CompletionRoutine 함수는 값을 반환하지 않습니다.
이 함수에서 반환하면 이 소켓에 대해 보류 중인 다른 완료 루틴을 호출할 수 있습니다. 완료 루틴은 겹치는 작업이 완료되는 순서와 같은 순서로 호출할 수 있는 것은 아닙니다.
호환성
T == 0이 있는 IOCTL 코드는 버클리 소켓에서 사용되는 IOCTL 코드의 하위 집합입니다. 특히 FIOASYNC와 동일한 명령은 없습니다.Windows 8.1 및 Windows Server 2012 R2: 이 함수는 Windows 8.1, Windows Server 2012 R2 이상에서 Windows 스토어 앱에서 지원됩니다.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 8.1, Windows Vista [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | winsock2.h |
| 라이브러리 | Ws2_32.lib |
| DLL | Ws2_32.dll |
추가 정보
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기