WSPStartup 함수(ws2spi.h)

  • 아티클

WSPStartup 함수는 클라이언트에서 WINDOWS 소켓 SPI(서비스 공급자 인터페이스)의 사용을 시작합니다.

구문

int WSPStartup(
  [in]  WORD                wVersionRequested,
  [out] LPWSPDATA           lpWSPData,
  [in]  LPWSAPROTOCOL_INFOW lpProtocolInfo,
  [in]  WSPUPCALLTABLE      UpcallTable,
  [out] LPWSPPROC_TABLE     lpProcTable
);

매개 변수

[in] wVersionRequested

가장 높은 버전의 Windows 소켓 SPI는 호출자가 사용할 수 있는 지원입니다. 상위 바이트는 부 버전(수정 버전) 번호를 지정합니다. 하위 바이트는 주 버전 번호를 지정합니다.

[out] lpWSPData

Windows 소켓 서비스 공급자에 대한 정보를 수신하는 WSPDATA 데이터 구조에 대한 포인터입니다.

[in] lpProtocolInfo

원하는 프로토콜의 특성을 정의하는 WSAProtocol_Info 구조체에 대한 포인터입니다. 이는 단일 공급자 DLL이 여러 다른 서비스 공급자를 인스턴스화할 수 있는 경우에 특히 유용합니다.

[in] UpcallTable

WSPUpCallTable 구조에 전달된 Winsock 2 DLL(Ws2_32.dll) 업콜 디스패치 테이블입니다.

[out] lpProcTable

SPI 함수 포인터 테이블에 대한 포인터입니다. 이 테이블은 WSPProc_Table 구조체로 반환됩니다.

반환 값

성공하면 WSPStartup 함수는 0을 반환합니다. 그렇지 않으면 아래에 나열된 오류 코드 중 하나를 반환합니다.

오류 코드 의미
WSASYSNOTREADY
 네트워크 하위 시스템을 사용할 수 없습니다. 이 오류는 네트워크 서비스를 제공하는 데 사용하는 기본 시스템을 현재 사용할 수 없으므로 현재 Windows 소켓 구현이 작동하지 않는 경우 반환됩니다.
WSAVERNOTSUPPORTED
 Winsock.dll 버전이 범위를 벗어났습니다. 요청된 Windows 소켓 SPI 지원 버전이 이 특정 Windows 소켓 서비스 공급자가 제공하지 않으면 이 오류가 반환됩니다.
WSAEINPROGRESS
 차단 Windows 소켓 1.1 작업이 진행 중입니다.
WSAEPROCLIM
 Windows 소켓 구현에서 지원하는 작업 수에 대한 제한에 도달했습니다.
WSAEFAULT
 lpWSPData 또는 lpProcTable 매개 변수가 잘못되었습니다.

설명

Windows Sockets 2 전송 서비스 공급자는 서비스 공급자 초기화 함수에 사용되는 단일 내보낸 프로시저 진입점 인 WSPStartup이 있는 DLL입니다. 다른 모든 서비스 공급자 함수는 lpProcTable 매개 변수에서 WSPStartup 함수에 전달된 서비스 공급자의 디스패치 테이블을 통해 Winsock 2 DLL에 액세스할 수 있습니다. 서비스 공급자 DLL은 필요한 경우에만 WinSock 2 DLL에 의해 메모리에 로드되고 서비스가 더 이상 필요하지 않을 때 언로드됩니다.

또한 서비스 공급자 인터페이스는 전송 서비스 공급자가 Winsock 2 DLL(업콜)을 호출하여 DLL 지원 서비스를 가져오는 몇 가지 상황을 정의합니다. 전송 서비스 공급자는 WSPStartup 함수에 전달된 UpcallTable 매개 변수에서 Winsock 2 DLL에 대한 업콜 디스패치 테이블을 반환합니다.

WSPStartup 함수는 프로세스별로 Windows Sockets SPI 클라이언트에서 호출하는 첫 번째 Windows Sockets SPI 함수여야 합니다. 클라이언트가 필요한 Windows 소켓 SPI 버전을 지정하고 업콜 디스패치 테이블을 제공할 수 있습니다. Windows Sockets 서비스 공급자가 만든 모든 업콜(즉, WPU 접두사 함수)은 클라이언트의 업콜 디스패치 테이블을 통해 호출됩니다. 또한 이 함수를 사용하면 클라이언트가 특정 Windows 소켓 서비스 공급자 구현에 대한 세부 정보를 검색할 수 있습니다. Windows 소켓 SPI 클라이언트는 WSPStartup 호출이 성공한 후에만 추가 Windows 소켓 SPI 함수를 실행할 수 있습니다. 나머지 SPI 함수에 대한 포인터 테이블은 WSPProc_Table 구조를 반환하는 lpProcTable 매개 변수를 통해 검색됩니다.

Winsock 2 DLL은 표준 Windows 동적 라이브러리 로드 메커니즘을 사용하여 서비스 공급자의 인터페이스 DLL을 시스템에 로드하고 WSPStartup 함수를 호출하여 초기화합니다. 이는 일반적으로 인터페이스 DLL이 현재 메모리에 로드되지 않은 서비스 공급자와 연결될 새 소켓을 만들기 위해 소켓 또는 WSASocket 함수를 호출하는 애플리케이션에 의해 트리거됩니다.

현재 Windows 소켓 SPI와 기능상 차이가 있을 수 있는 Windows 소켓 SPI 및 Ws2_32.dll 향후 버전을 지원하기 위해 WSPStartup에서 협상이 진행됩니다. WSPStartup(Ws2_32.dll 또는 계층화된 프로토콜) 및 Windows Sockets 서비스 공급자의 호출자는 서로 지원할 수 있는 가장 높은 버전의 Windows 소켓을 서로 나타내며, 각 호출자는 서로의 최고 버전이 허용되는지 확인합니다. WSPStartup에 진입하면 Windows 소켓 서비스 공급자가 클라이언트에서 요청한 버전을 검사합니다. 이 버전이 서비스 공급자가 지원하는 가장 낮은 버전보다 크거나 같은 경우 호출이 성공하고 서비스 공급자는 WSPDATA 구조의 wHighVersion 멤버에서 지원하는 가장 높은 버전을 반환하고 wVersion 멤버에서 wVersionRequested 매개 변수에 지정된 상위 버전 및 버전의 최소값을 반환합니다. 그런 다음 Windows 소켓 서비스 공급자는 Windows 소켓 SPI 클라이언트가 wVersion 멤버에 지정된 Windows 소켓 버전을 사용한다고 가정합니다. WSPDATA 구조의 wVersion 멤버가 호출자에게 허용되지 않는 경우 LPWSPCleanup을 호출하고 다른 Windows 소켓 서비스 공급자를 검색하거나 초기화에 실패해야 합니다.

이 협상을 통해 Windows 소켓 서비스 공급자와 Windows 소켓 SPI 클라이언트가 모두 다양한 Windows 소켓 버전을 지원할 수 있습니다. 버전 범위가 겹치는 경우 클라이언트는 Windows 소켓 서비스 공급자를 성공적으로 활용할 수 있습니다.

Windows 소켓 사양의 현재 버전은 버전 2.2입니다. 현재 Winsock DLL (Ws2_32.dll)은 다음 버전의 Windows 소켓 사양을 요청하는 애플리케이션을 지원합니다.

  • 1.0
  • 1.1
  • 2.0
  • 2.1
  • 2.2

더 높은 버전의 Windows 소켓 사양의 새 구문에 대한 모든 권한을 얻으려면 애플리케이션이 이 상위 버전에 대해 협상해야 합니다. 이 경우 wVersionRequested 매개 변수를 요청 버전 2.2로 설정해야 합니다. 또한 애플리케이션은 적절한 헤더 파일에 대한 컴파일, 새 라이브러리와의 연결 또는 기타 특수한 경우와 같이 더 높은 버전의 Windows 소켓 사양을 완전히 준수해야 합니다. Winsock 2 지원에 대한 Winsock2.h 헤더 파일은 Microsoft SDK(Windows SDK(소프트웨어 개발 키트))에 포함되어 있습니다.

Windows 소켓 버전 2.2는 Windows Server 2008, Windows Vista, Windows Server 2003, Windows XP, Windows 2000, Windows NT 4.0 SP4(서비스 팩 4) 이상, Windows Me, Windows 98 및 Windows 95 OSR2에서 지원됩니다. Windows 소켓 버전 2.2도 에서 지원됩니다.
Windows 소켓 2 업데이트가 포함된 Windows 95. 이러한 플랫폼의 애플리케이션은 일반적으로 wVersionRequested 매개 변수를 적절하게 설정하여 Winsock 2.2를 요청해야 합니다.

Windows 95 및 Windows NT 3.51 이하 버전에서 Windows 소켓 버전 1.1은 지원되는 Windows 소켓 사양의 가장 높은 버전입니다.

Winsock DLL에서 지원하는 더 낮은 버전의 Windows 소켓 사양을 사용하여 작성된 애플리케이션 또는 DLL이 WSPStartup 함수를 사용하여 이 하위 버전을 성공적으로 협상할 수 있습니다. 예를 들어 애플리케이션은 Winsock 2.2 DLL을 사용하여 플랫폼의 WSPStartup 함수에 전달된 wVersionRequested 매개 변수에서 버전 1.1을 요청할 수 있습니다. 이 경우 애플리케이션은 요청된 버전에 맞는 기능만 사용해야 합니다. 새 Ioctl 코드, 기존 함수의 새로운 동작 및 새 함수를 사용하면 안 됩니다. WSPStartup에서 제공하는 버전 협상은 주로 Windows 95 및 Windows NT 3.51 이하용으로 개발된 이전 Winsock 1.1 애플리케이션이 이후 버전의 Windows에서 동일한 동작으로 실행되도록 허용하는 데 사용되었습니다. Winsock 1.1 지원에 대한 Winsock.h 헤더 파일은 Windows SDK 포함되어 있습니다.

다음 차트에서는 WSPStartup 이 다양한 WS2_32.DLL 및 Windows Sockets SP(서비스 공급자) 버전과 함께 작동하는 방식의 예를 보여 줍니다.

DLL
 
versions		 SP
 
versions		 wVersionRequested wVersion wHighVersion 최종 결과
1.1 1.1 1.1 1.1 1.1 1.1 사용
1.0 1.1 1.0 1.1 1.0 1.0 1.0 사용
1.0 1.0 1.1 1.0 1.0 1.1 1.0 사용
1.1 1.0 1.1 1.1 1.1 1.1 1.1 사용
1.1 1.0 1.1 1.0 1.0 DLL 실패
1.0 1.1 1.0 --- --- WSAVERNOTSUPPORTED
1.0 1.1 1.0 1.1 1.1 1.1 1.1 1.1 사용
1.0 1.1 2.0 1.1 2.0 1.1 1.1 1.1 사용
1.0 1.1 2.0 2.0 2.0 2.0 2.0 2.0 사용
1.0 1.1 2.0 2.1 2.2 2.2 2.2 2.2 2.2 use 2.2
 

다음 코드 조각에서는 Windows Sockets SPI 버전 2만 지원하는 Windows Sockets SPI 클라이언트가 WSPStartup 호출을 만드는 방법을 보여 줍니다.

WORD wVersionRequested;
WSPDATA WSPData;
 
int err;
 
WSPUPCALLTABLE upcallTable =
{ 
    /* initialize upcallTable with function pointers */
};
 
LPWSPPROC_TABLE lpProcTable =
{ 
    /* allocate memory for the ProcTable */
};
 
wVersionRequested = MAKEWORD( 2, 2 );
 
err = WSPStartup( wVersionRequested, &WSPData, lpProtocolBuffer, upcallTable, lpProcTable );
if ( err != 0 ) {
    /* Tell the user that we could not find a usable */
    /* Windows Sockets service provider.                     */
    return;
}
 
/* Confirm that the Windows Sockets service provider supports 2.2.*/
/* Note that if the service provider supports versions */
/* greater than 2.2 in addition to 2.2, it will still */
/* return 2.2 in wVersion since that is the version we  */
/* requested.                                           */
 
if ( LOBYTE( WSPData.wVersion ) != 2 ||
         HIBYTE( WSPData.wVersion ) != 2 ) {
    /* Tell the user that we could not find a usable */
    /* Windows Sockets service provider.                     */
    LPWSPCleanup( );
    return;   
}
 
/* The Windows Sockets service provider is acceptable. Proceed. */

그리고 이 코드 조각은 버전 2.2만 지원하는 Windows Sockets 서비스 공급자가 WSPStartup 협상을 수행하는 방법을 보여 줍니다.

/* Make sure that the version requested is >= 2.2.  */
/* The low byte is the major version and the high   */
/* byte is the minor version.                       */
 
if ( (LOBYTE( wVersionRequested ) < 2) ||
     ((LOBYTE( wVersionRequested ) == 2) &&
     (HIBYTE( wVersionRequested ) < 2))) {
    return WSAVERNOTSUPPORTED;
}
 
/* Since we only support 2.2, set both wVersion and  */
/* wHighVersion to 2.2.                              */
 
lpWSPData->wVersion = MAKEWORD( 2, 2 );
lpWSPData->wHighVersion = MAKEWORD( 2, 2 );

Windows 소켓 SPI 클라이언트가 WSPStartup 호출에 성공하면 필요에 따라 다른 Windows 소켓 SPI 호출을 진행할 수 있습니다. Windows Sockets 서비스 공급자의 서비스 사용이 완료되면 클라이언트는 Windows 소켓 서비스 공급자가 클라이언트에 할당된 리소스를 해제할 수 있도록 LPWSPCleanup 을 호출해야 합니다.

WSPStartup 함수는 각 클라이언트 프로세스에서 한 번 이상 호출해야 하며 Winsock 2 DLL 또는 다른 엔터티에서 여러 번 호출할 수 있습니다. 성공한 각 WSPStartup 호출에 대해 일치하는 LPWSPCleanup 함수를 호출해야 합니다. 서비스 공급자는 프로세스별로 참조 횟수를 유지해야 합니다. 각 WSPStartup 호출에서 호출자는 서비스 공급자 DLL에서 지원하는 버전 번호를 지정할 수 있습니다.

서비스 공급자는 WSPStartup 함수에 의해 UpcallTable 매개 변수로 수신된 클라이언트의 업콜 디스패치 테이블에 대한 포인터를 프로세스별로 저장해야 합니다. 지정된 프로세스가 WSPStartup을 여러 번 호출하는 경우 서비스 공급자는 가장 최근에 제공된 업콜 디스패치 테이블 포인터만 사용해야 합니다.

WSPDATA 구조 정보를 두 번 이상 가져와야 하는 경우 Windows 소켓 SPI 클라이언트는 WSPStartup을 두 번 이상 호출할 수 있습니다. 이러한 각 호출에서 클라이언트는 공급자가 지원하는 버전 번호를 지정할 수 있습니다.

타사 DLL이 Windows 소켓 공급자를 사용할 수 있도록 허용하려면 성공한 모든 WSPStartup 호출에 해당하는 하나의 LPWSPCleanup 호출이 있어야 합니다. 예를 들어 WSPStartup 을 세 번 호출하는 경우 LPWSPCleanup 에 대한 해당 호출은 세 번 발생해야 합니다. LPWSPCleanup에 대한 처음 두 호출은 내부 카운터를 감소하는 것 외에는 아무 것도 수행하지 않습니다. 최종 LPWSPCleanup 호출은 필요한 모든 리소스 할당 취소를 수행합니다.

이 함수(및 대부분의 다른 서비스 공급자 함수)는 클라이언트가 16비트 Windows 소켓 1.1 클라이언트인 경우 16비트 프로세스로 시작된 스레드에서 호출할 수 있습니다. 16비트 프로세스의 한 가지 중요한 제한 사항은 16비트 프로세스가 스레드를 만들 수 없다는 것입니다. 이는 구현의 일부로 내부 서비스 스레드를 사용하려는 서비스 공급자 구현자에게 중요합니다.

다행히 일반적으로 서비스 스레드에 대한 조건이 강한 영역은 두 가지뿐입니다.

이러한 두 영역은 모두 32비트 프로세스에서만 호출할 수 있는 새로운 Windows 소켓 2 함수를 통해서만 액세스할 수 있습니다.

다음 두 가지 디자인 규칙을 신중하게 따르는 경우 서비스 스레드를 안전하게 사용할 수 있습니다.

  • 16비트 Windows 소켓 1.1 클라이언트에서 사용할 수 없는 기능에 대해서만 서비스 스레드를 사용합니다.
  • 요청 시 서비스 스레드만 만듭니다.

내부 서비스 스레드 사용에는 몇 가지 다른 주의 사항이 적용됩니다. 첫째, 스레드는 일반적으로 성능 저하를 수행합니다. 가능한 한 적게 사용하고 가능한 한 스레드 전환을 방지합니다. 둘째, 일부 실행 이벤트에서 스레드가 필요한 코드 경로를 실행하는 16비트 프로세스에서 결과를 기대하지 않는 경우 코드는 항상 스레드를 만드는 동안 발생하는 오류에 대해 검사 정상적으로 그리고 유익하게 실패해야 합니다(예: WSAEOPNOTSUPP 사용).

계층화된 서비스 공급자는 이 함수의 구현을 제공하지만 WSPStartup 을 호출하여 프로토콜 체인의 다음 계층을 초기화할 때 이 함수의 클라이언트이기도 합니다. 다음 계층의 WSPStartup에 대한 호출은 이 계층의 WSPStartup 을 실행하는 동안 발생하거나 LPWSPSocket 이 호출될 때와 같이 요청 시 지연 및 호출될 수 있습니다. 어떤 경우든 프로토콜 체인의 계층을 통해 전파되므로 이 함수의 lpProtocolInfo 매개 변수에 몇 가지 특별한 고려 사항이 적용됩니다.

계층화된 공급자는 lpProtocolInfo에서 참조하는 구조체의 ProtocolChain을 검색하여 체인에서 고유한 위치(레이어의 카탈로그 항목 ID를 검색)와 체인의 다음 요소 ID를 확인합니다. 다음 요소가 다른 계층인 경우 다음 계층의 WSPStartup이 호출될 때 이 계층은 수정되지 않은 동일한 체인 정보를 사용하여 수정되지 않은 동일한 WSAProtocol_Info 구조를 참조하는 lpProtocolInfo를 다음 계층에 전달해야 합니다. 그러나 다음 계층이 기본 프로토콜(즉, 체인의 마지막 요소)인 경우 이 계층은 기본 공급자의 WSPStartup을 호출할 때 대체를 수행합니다. 이 경우 lpProtocolInfo 매개 변수에서 기본 공급자의 WSAPROTOCOL_INFO 구조를 참조해야 합니다.

이 정책의 한 가지 중요한 이점은 기본 서비스 공급자가 프로토콜 체인을 인식할 필요가 없다는 것입니다.

이 동일한 전파 정책은 LPWSPAddressToString, LPWSPDuplicateSocket, LPWSPSocket 또는 LPWSPStringToAddress와 같은 다른 함수의 계층화된 시퀀스를 통해 WSAPROTOCOL_INFO구조를 전파할 때 적용됩니다.

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버 Windows 2000 Server[데스크톱 앱만]
대상 플랫폼 Windows
헤더 ws2spi.h

추가 정보

WSAProtocol_Info

LPWSPAddressToString

LPWSPStringToAddress

LPWSPCleanup

LPWSPDuplicateSocket

LPWSPEventSelect

WSPProc_Table

LPWSPSend

LPWSPSendTo

LPWSPSocket

WSPUpCallTable