WSAJoinLeaf 함수(winsock2.h)
WSAJoinLeaf 함수는 리프 노드를 다중 포인트 세션에 조인하고, 연결 데이터를 교환하고, 지정된 FLOWSPEC 구조에 따라 필요한 서비스 품질을 지정합니다.
구문
SOCKET WSAAPI WSAJoinLeaf(
[in] SOCKET s,
[in] const sockaddr *name,
[in] int namelen,
[in] LPWSABUF lpCallerData,
[out] LPWSABUF lpCalleeData,
[in] LPQOS lpSQOS,
[in] LPQOS lpGQOS,
[in] DWORD dwFlags
);
매개 변수
[in] s
멀티포인트 소켓을 식별하는 설명자입니다.
[in] name
소켓을 조인할 피어의 이름입니다.
[in] namelen
이름 길이(바이트)입니다.
[in] lpCallerData
다중 포인트 세션 설정 중에 피어로 전송할 사용자 데이터에 대한 포인터입니다.
[out] lpCalleeData
다중 포인트 세션 설정 중에 피어에서 다시 전송할 사용자 데이터에 대한 포인터입니다.
[in] lpSQOS
각 방향에 대해 하나씩 소켓의FLOWSPEC 구조체에 대한 포인터입니다.
[in] lpGQOS
나중에 소켓 그룹에 사용할 수 있습니다. 소켓 그룹에 대한 FLOWSPEC 구조체에 대한 포인터입니다(해당하는 경우).
[in] dwFlags
소켓이 보낸 사람(JL_SENDER_ONLY), 수신자(JL_RECEIVER_ONLY) 또는 둘 다(JL_BOTH)로 작동함을 나타내는 플래그입니다.
반환 값
오류가 발생하지 않으면 WSAJoinLeaf 는 새로 만든 멀티포인트 소켓에 대한 설명자인 SOCKET 형식의 값을 반환합니다. 그렇지 않으면 INVALID_SOCKET 값이 반환되고 WSAGetLastError를 호출하여 특정 오류 코드를 검색할 수 있습니다.
차단 소켓에서 반환 값은 조인 작업의 성공 또는 실패를 나타냅니다.
차단되지 않는 소켓의 경우 조인 작업의 성공적인 시작은 유효한 소켓 설명자의 반환으로 표시됩니다. 그 후 조인 작업이 완료되면 원래 소켓 에 FD_CONNECT 표시가 제공됩니다( 성공적으로 또는 그렇지 않은 경우). 애플리케이션은 조인 작업이 완료된 시기를 확인하고 연결된 오류 코드를 확인하여 작업의 성공 또는 실패를 확인하기 위해 WSAAsyncSelect 또는 WSAEventSelect 를 FD_CONNECT 이벤트에 등록된 관심과 함께 사용해야 합니다. select 함수를 사용하여 조인 작업이 완료되는 시기를 확인할 수 없습니다.
또한 다중 포인트 세션 조인 시도가 동일한 소켓의 WSAJoinLeaf 에 대한 모든 후속 호출을 완료할 때까지 오류 코드 WSAEALREADY와 함께 실패합니다. WSAJoinLeaf 작업이 성공적으로 완료되면 일반적으로 오류 코드 WSAEISCONN으로 후속 시도가 실패합니다. 루트 시작 조인을 허용하는 c_root 소켓에 대해 WSAEISCONN 규칙에 대한 예외가 발생합니다. 이러한 경우 이전 WSAJoinLeaf 작업이 완료된 후 다른 조인을 시작할 수 있습니다.
반환 오류 코드가 다중 포인트 세션 조인 시도가 실패했음을 나타내는 경우(즉, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) 애플리케이션은 동일한 소켓에 대해 WSAJoinLeaf 를 다시 호출할 수 있습니다.
| 오류 코드 | 의미 |
|---|---|
| 이 함수를 사용하기 전에 성공적인 WSAStartup 호출이 발생해야 합니다. | |
| 소켓의 로컬 주소가 이미 사용 중이며 SO_REUSEADDR 주소를 다시 사용할 수 있도록 소켓이 표시되지 않았습니다. 이 오류는 일반적으로 바인딩 시 발생하지만 바인딩이 부분적으로 와일드카드 주소(ADDR_ANY 포함)에 있고 이 함수 당시 특정 주소를 커밋해야 하는 경우 이 함수까지 지연될 수 있습니다. | |
| 원격 주소가 유효한 주소(예: ADDR_ANY)가 아닙니다. | |
| 지정된 패밀리의 주소는 이 소켓에서 사용할 수 없습니다. | |
| 비 차단 WSAJoinLeaf 호출이 지정된 소켓에서 진행 중입니다. | |
| 가입 시도는 강제로 거부되었습니다. | |
| 이름 또는 namelen 매개 변수가 사용자 주소 공간의 유효한 부분이 아니거나, namelen 매개 변수가 너무 작거나, lpCalleeData, lpSQOS 및 lpGQOS의 버퍼 길이가 너무 작거나, lpCallerData의 버퍼 길이가 너무 큽니다. | |
| WSAJoinLeaf 함수 호출은 WSA_FLAG_MULTIPOINT_C_LEAF 설정하거나 멀티포인트 플래그를 WSA_FLAG_MULTIPOINT_D_LEAF 않고 열린 UDP 소켓에서 수행되었습니다. | |
| 소켓은 이미 멀티포인트 세션의 멤버입니다. | |
| WSACancelBlockingCall을 통해 차단 Windows 소켓 1.1 호출이 취소되었습니다. | |
| 차단 Windows 소켓 1.1 호출이 진행 중이거나 서비스 공급자가 여전히 콜백 함수를 처리하고 있습니다. | |
| 네트워크 하위 시스템이 실패했습니다. | |
| 현재 이 호스트에서 네트워크에 연결할 수 없습니다. | |
| 사용할 수 있는 버퍼 공간이 없습니다. 소켓을 조인할 수 없습니다. | |
| 설명자가 소켓이 아닙니다. | |
| lpSQOS 및 lpGQOS에 지정된 FLOWSPEC 구조를 충족할 수 없습니다. | |
| lpCallerData 보강은 서비스 공급자에서 지원되지 않습니다. | |
| 멀티포인트 세션을 설정하지 않고 참가 시도가 시간 초과되었습니다. |
설명
WSAJoinLeaf 함수는 리프 노드를 멀티포인트 세션에 조인하고 세션 조인 시간에 발생하는 여러 다른 보조 작업을 수행하는 데 사용됩니다. 소켓 이 언바운드인 경우 고유 값이 시스템에 의해 로컬 연결에 할당되고 소켓이 바인딩된 것으로 표시됩니다.
WSAJoinLeaf 함수는 WSAAccept에서와 같이 소켓 설명자를 반환하고 추가 dwFlags 매개 변수가 있다는 점을 제외하고 WSAConnect와 동일한 매개 변수 및 의미 체계를 가짐 적절한 멀티포인트 플래그가 설정된 WSASocket 을 사용하여 만든 멀티포인트 소켓만 이 함수의 입력 매개 변수 에 사용할 수 있습니다. 반환된 소켓 설명자는 조인 작업이 완료될 때까지 사용할 수 없습니다. 예를 들어 원래 소켓의 WSAAsyncSelect 또는 WSAEventSelect에서 해당 FD_CONNECT 표시가 수신된 후 소켓이 차단 되지 않는 모드인 경우 이 새 소켓 설명자에서 closesocket을 호출하여 보류 중인 조인 작업을 취소할 수 있다는 점을 제외합니다. 다중 포인트 세션의 루트 애플리케이션은 여러 리프 노드를 추가하기 위해 WSAJoinLeaf 를 한 번 이상 호출할 수 있지만 한 번에 하나의 멀티포인트 연결 요청이 미해결될 수 있습니다. 추가 정보는 멀티포인트 및 멀티캐스트 의미 체계를 참조하세요 .
차단이 없는 소켓의 경우 연결을 즉시 완료할 수 없는 경우가 많습니다. 이 경우 이 함수는 아직 사용할 수 없는 소켓 설명자를 반환하고 작업이 진행됩니다. 이 경우 함수가 성공적인 시작 표시를 효과적으로 반환했기 때문에 WSAEWOULDBLOCK 과 같은 오류 코드는 없습니다. 최종 결과 성공 또는 실패가 알려지면 클라이언트가 원래 소켓의 알림을 등록하는 방법에 따라 WSAAsyncSelect 또는 WSAEventSelect를 통해 보고될 수 있습니다. 두 경우 모두 FD_CONNECT 알림이 발표되고 FD_CONNECT 연결된 오류 코드는 성공 또는 특정 실패 이유를 나타냅니다. select 함수는 WSAJoinLeaf에 대한 완료 알림을 검색하는 데 사용할 수 없습니다.
WSAJoinLeaf에서 반환하는 소켓 설명자는 입력 소켓 설명자(s)가 c_root 또는 c_leaf 여부에 따라 다릅니다. c_root 소켓과 함께 사용할 경우 name 매개 변수는 추가할 특정 리프 노드를 지정하고 반환된 소켓 설명자는 새로 추가된 리프 노드에 해당하는 c_leaf 소켓입니다. 새로 만든 소켓에는 WSAAsyncSelect 또는 WSAEventSelect에 등록된 비동기 이벤트를 포함하여 s와 동일한 속성이 있습니다. 멀티포인트 데이터 교환에 사용되는 것이 아니라 특정 c_leaf 존재하는 연결에 대한 네트워크 이벤트 표시(예: FD_CLOSE)를 수신하는 데 사용됩니다. 일부 멀티포인트 구현에서는 루트와 개별 리프 노드 간의 사이드 채팅에 이 소켓을 사용할 수도 있습니다. 해당 리프 노드가 closesocket 을 호출하여 멀티포인트 세션에서 중퇴하면 이 소켓에 대한 FD_CLOSE 표시가 수신됩니다. 대칭적으로 WSAJoinLeaf에서 반환된 c_leaf 소켓에서 closesocket을 호출하면 해당 리프 노드의 소켓이 FD_CLOSE 알림을 받습니다.
WSAJoinLeaf가 c_leaf 소켓을 사용하여 호출되는 경우 이름 매개 변수에는 루트 애플리케이션의 주소(루팅된 제어 체계의 경우) 또는 기존 다중 포인트 세션(루트되지 않은 제어 체계)이 포함되며 반환된 소켓 설명자는 입력 소켓 설명자와 동일합니다. 즉, 새 소켓 설명자가 할당되지 않습니다. 루트 제어 체계에서 루트 애플리케이션은 listen을 호출하여 c_root 소켓을 수신 대기 모드로 전환합니다. 표준 FD_ACCEPT 알림은 리프 노드가 멀티포인트 세션에 참가하도록 요청할 때 전달됩니다. 루트 애플리케이션은 일반적인 accept 또는 WSAAccept 함수를 사용하여 새 리프 노드를 허용합니다. accept 또는 WSAAccept에서 반환된 값은 WSAJoinLeaf에서 반환된 것과 마찬가지로 c_leaf 소켓 설명자이기도 합니다. 루트 시작 조인과 리프 시작 조인을 모두 허용하는 멀티포인트 구성표를 수용하려면 이미 수신 모드에 있는 c_root 소켓을 WSAJoinLeaf에 대한 입력으로 사용할 수 있습니다.
애플리케이션은 지정한 매개 변수에 의해 직접 또는 간접적으로 가리키는 메모리 공간을 할당해야 합니다.
lpCallerData는 다중 포인트 세션 조인 요청과 함께 전송할 사용자 데이터를 포함하는 값 매개 변수입니다. lpCallerData가 NULL이면 피어에 사용자 데이터가 전달되지 않습니다. lpCalleeData는 다중 포인트 세션 설정의 일부로 피어에서 다시 전달된 모든 사용자 데이터를 포함하는 결과 매개 변수입니다. lpCalleeData 매개 변수가 가리키는 WSABUF 구조체의 len 멤버는 처음에 애플리케이션에서 할당하고 WSABUF 구조체의 buf 멤버가 가리키는 버퍼의 길이를 포함합니다. 사용자 데이터가 다시 전달되지 않은 경우 lpCalleeData 매개 변수가 가리키는 WSABUF 구조체의 len 멤버가 0으로 설정됩니다. lpCalleeData 정보는 다중 포인트 조인 작업이 완료되면 유효합니다.
차단 소켓의 경우 WSAJoinLeaf 함수가 반환되는 경우입니다. 차단되지 않는 소켓의 경우 조인 작업이 완료된 후입니다. 예를 들어 원래 소켓 에 대한 알림이 FD_CONNECT 후에 발생할 수 있습니다. lpCalleeData가 NULL이면 사용자 데이터가 다시 전달되지 않습니다. 사용자 데이터의 정확한 형식은 소켓이 속한 주소 패밀리에 따라 다릅니다.
다중 포인트 세션 설정 시 애플리케이션은 lpSQOS 및/또는 lpGQOS 매개 변수를 사용하여 WSAIoctl 을 통해 소켓에 대해 만들어진 이전 서비스 사양의 품질을 SIO_SET_QOS 또는 SIO_SET_GROUP_QOS opcodes로 재정의할 수 있습니다.
lpSQOS 매개 변수는 소켓의FLOWSPEC 구조체를 각 방향에 대해 하나씩 지정한 다음 추가 공급자별 매개 변수를 지정합니다. 일반적으로 연결된 전송 공급자 또는 특정 유형의 소켓이 서비스 품질 요청을 적용할 수 없는 경우 다음과 같이 오류가 반환됩니다. 단방향 소켓에 대해 각각의 송신 또는 수신 흐름 사양 값이 무시됩니다. 공급자별 매개 변수를 지정하지 않으면 lpCalleeData 매개 변수가 가리키는 WSABUF 구조체의 buf 및 len 멤버를 각각 NULL 및 0으로 설정해야 합니다. lpSQOS에 대한 NULL 값은 애플리케이션에서 제공하는 서비스 품질을 나타내지 않습니다.
향후 소켓 그룹을 위해 예약됩니다. lpGQOS 매개 변수는 소켓 그룹에 대한 FLOWSPEC 구조를 지정합니다(해당하는 경우). 각 방향에 대해 하나씩, 추가 공급자별 매개 변수가 뒤따릅니다. 공급자별 매개 변수를 지정하지 않으면 lpCalleeData 매개 변수가 가리키는 WSABUF 구조체의 buf 및 len 멤버를 각각 NULL 및 0으로 설정해야 합니다. lpGQOS에 대한 NULL 값은 애플리케이션에서 제공하는 서비스 그룹 품질을 나타내지 않습니다. 이 매개 변수는 s 가 소켓 그룹의 작성자가 아닌 경우 무시됩니다.
연결된 소켓이 중단되면(즉, 어떤 이유로든 닫히게 됨) 삭제하고 다시 만들어야 합니다. 연결된 소켓에서 어떤 이유로든 상황이 어지러울 때 애플리케이션은 안정적인 지점으로 돌아가기 위해 필요한 소켓을 삭제하고 다시 만들어야 한다고 가정하는 것이 가장 안전합니다.
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 |