PFN_WSK_SOCKET_CONNECT 콜백 함수(wsk.h)

아티클
08/08/2023

WskSocketConnect 함수는 새 연결 지향 소켓을 만들고, 로컬 전송 주소에 바인딩하고, 지정된 원격 전송 주소에 연결하고, 연결된 소켓 개체에 대한 포인터를 반환합니다.

구문

PFN_WSK_SOCKET_CONNECT PfnWskSocketConnect;

NTSTATUS PfnWskSocketConnect(
  [in]           PWSK_CLIENT Client,
  [in]           USHORT SocketType,
  [in]           ULONG Protocol,
  [in]           PSOCKADDR LocalAddress,
  [in]           PSOCKADDR RemoteAddress,
                 ULONG Flags,
  [in, optional] PVOID SocketContext,
  [in, optional] const WSK_CLIENT_CONNECTION_DISPATCH *Dispatch,
  [in, optional] PEPROCESS OwningProcess,
  [in, optional] PETHREAD OwningThread,
  [in, optional] PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in, out]      PIRP Irp
)
{...}

매개 변수

[in] Client

의 WskProviderNpi 매개 변수를 통해 반환된 WSK_CLIENT 구조체에 대한 포인터입니다. WskCaptureProviderNPI 함수입니다.

[in] SocketType

생성되는 소켓의 형식입니다. 지원되는 소켓 유형은 다음과 같습니다.

SOCK_STREAM

신뢰할 수 있는 연결 지향 바이트 스트림 통신을 지원합니다.

SOCK_DGRAM

신뢰할 수 없는 연결 없는 데이터그램 통신을 지원합니다.

SOCK_RAW

전송 프로토콜에 대한 원시 액세스를 지원합니다.

지원되는 각 주소 패밀리에 대해 지원되는 소켓 유형에 대한 자세한 내용은
WSK 주소 패밀리.

[in] Protocol

생성되는 소켓에 대한 전송 프로토콜입니다. 지원되는 각 주소 패밀리에 대해 지원되는 프로토콜에 대한 자세한 내용은 WSK 주소 패밀리를 참조하세요.

[in] LocalAddress

소켓을 바인딩할 로컬 전송 주소를 지정하는 구조체에 대한 포인터입니다. WSK 애플리케이션은 생성되는 소켓의 주소 패밀리에 해당하는 특정 SOCKADDR 구조체 형식에 대한 포인터를 지정해야 합니다.

[in] RemoteAddress

소켓을 연결할 원격 전송 주소를 지정하는 구조체에 대한 포인터입니다. WSK 애플리케이션은 생성되는 소켓의 주소 패밀리에 해당하는 특정 SOCKADDR 구조체 형식에 대한 포인터를 지정해야 합니다.

Flags

이 매개 변수는 시스템 사용을 위해 예약되어 있습니다. WSK 애플리케이션은 이 매개 변수를 0으로 설정해야 합니다.

[in, optional] SocketContext

생성되는 소켓에 대해 호출자가 제공한 컨텍스트에 대한 포인터입니다. WSK 하위 시스템은 이 포인터를 소켓의 이벤트 콜백 함수에 전달합니다. 컨텍스트 정보는 WSK 하위 시스템에 불투명하며 페이징되지 않은 메모리에 저장되어야 합니다. WSK 애플리케이션이 새 소켓에서 이벤트 콜백 함수를 사용하도록 설정하지 않는 경우 이 포인터를 NULL로 설정해야 합니다.

[in, optional] Dispatch

상수에 대한 포인터 WSK_CLIENT_CONNECTION_DISPATCH 구조체입니다. 이 구조체는 새 소켓에 대한 이벤트 콜백 함수에 대한 포인터를 포함하는 디스패치 테이블입니다. WSK 애플리케이션이 새 소켓에 대해 모든 이벤트 콜백 함수를 사용하도록 설정하지 않는 경우 디스패치 테이블의 포인터를 사용하지 않는 이벤트 콜백 함수에 대해 NULL 로 설정해야 합니다. WSK 애플리케이션이 새 소켓에서 이벤트 콜백 함수를 사용하도록 설정하지 않는 경우 이 포인터를 NULL로 설정해야 합니다.

[in, optional] OwningProcess

WSK 하위 시스템이 소켓을 바인딩할 때 사용할 보안 컨텍스트를 검색하는 프로세스에 대한 포인터입니다. WSK 하위 시스템은 보안 컨텍스트를 사용하여 해당 주소가 이미 사용 중인 경우 로컬 전송 주소를 공유할 수 있는지 여부를 확인합니다. 현재 프로세스를 지정하기 위해 WSK 애플리케이션은 이 포인터를 NULL로 설정합니다.

[in, optional] OwningThread

WSK 하위 시스템이 소켓을 바인딩할 때 사용할 보안 컨텍스트를 검색하는 특정 스레드에 대한 포인터입니다. WSK 하위 시스템은 보안 컨텍스트를 사용하여 해당 주소가 이미 사용 중인 경우 로컬 전송 주소를 공유할 수 있는지 여부를 확인합니다. WSK 애플리케이션이 특정 스레드를 지정할 필요가 없는 경우 이 포인터를 NULL로 설정합니다.

[in, optional] SecurityDescriptor

생성되는 소켓에 적용할 보안 설명자를 지정하는 SECURITY_DESCRIPTOR 구조체에 대한 포인터입니다. 보안 설명자는 소켓이 바인딩된 로컬 전송 주소의 공유를 제어합니다. WSK 애플리케이션이 NULL이 아닌 포인터를 지정하는 경우 WSK_CACHE_SD 제어 코드로 WskControlClient 함수를 호출하여 가져온 보안 설명자의 캐시된 복사본에 대한 포인터를 지정해야 합니다. 로컬 전송 주소의 공유를 허용하지 않는 기본 보안 설명자를 지정하기 위해 WSK 애플리케이션은 SecurityDescriptor 를 NULL로 설정합니다.

SECURITY_DESCRIPTOR 구조에 대한 자세한 내용은 Microsoft Windows SDK 설명서의 SECURITY_DESCRIPTOR 참조 페이지를 참조하세요.

[in, out] Irp

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

반환 값

WskSocketConnect 는 다음 NTSTATUS 코드 중 하나를 반환합니다.

반환 코드	설명
STATUS_SUCCESS	새 소켓이 성공적으로 만들어졌습니다. IRP는 성공 상태 완료됩니다.
STATUS_PENDING	WSK 하위 시스템이 소켓을 즉시 만들 수 없습니다. WSK 하위 시스템은 새 소켓을 만든 후 IRP를 완료합니다. 소켓 만들기의 상태 IRP의 IoStatus.Status 필드에 반환됩니다.
기타 상태 코드	오류가 발생했습니다. IRP는 실패 상태 완료됩니다.

설명

IRP가 성공 상태 완료된 경우 IRP의 IoStatus.Information 필드에는 새 소켓에 대한 소켓 개체 구조(WSK_SOCKET)에 대한 포인터가 포함됩니다.

WSK 애플리케이션은 WSK_TRANSPORT_LIST_QUERY 제어 코드로 WskControlClient 함수를 호출하여 사용 가능한 전송 프로토콜 목록을 가져올 수 있습니다. WskControlClient는 SocketType 및 프로토콜 매개 변수의 유효한 조합이 모두 포함된 WSK_TRANSPORT 구조의 목록을 반환합니다.

WSK 하위 시스템은 LocalAddress 매개 변수가 가리키는 SOCKADDR 구조체에 지정된 주소 패밀리에서 새 소켓의 주소 패밀리를 결정합니다.

WSK 애플리케이션이 소켓을 바인딩하거나 연결하기 전에 소켓 옵션을 설정하거나 소켓에서 I/O 제어 작업을 실행해야 하는 경우 WSK 애플리케이션은 WskSocketConnect 함수를 호출하는 대신 WskSocket, WskBind 및 WskConnect 함수를 호출해야 합니다.

WSK 애플리케이션이 새 소켓을 성공적으로 만들면 새 소켓의 모든 이벤트 콜백 함수가 기본적으로 사용하지 않도록 설정됩니다. 새 소켓의 이벤트 콜백 함수를 사용하도록 설정하는 방법에 대한 자세한 내용은 이벤트 콜백 함수 사용 및 비활성화를 참조하세요.

WSK 애플리케이션이 SecurityDescriptor 매개 변수에 대해 NULL이 아닌 포인터를 지정하는 경우 IRP가 완료될 때까지 캐시된 보안 설명자를 해제해서는 안 됩니다.

WSK 하위 시스템은 WSK 애플리케이션을 대신하여 새 소켓의 소켓 개체 구조(WSK_SOCKET)에 대한 메모리를 할당합니다. WSK 하위 시스템은 소켓이 닫혀 있을 때 이 메모리의 할당을 취소합니다.

요구 사항

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