WSAConnect 함수(winsock2.h)

아티클
08/27/2023

WSAConnect 함수는 다른 소켓 애플리케이션에 대한 연결을 설정하고, 연결 데이터를 교환하고, 지정된 FLOWSPEC 구조에 따라 필요한 서비스 품질을 지정합니다.

구문

int WSAAPI WSAConnect(
  [in]  SOCKET         s,
  [in]  const sockaddr *name,
  [in]  int            namelen,
  [in]  LPWSABUF       lpCallerData,
  [out] LPWSABUF       lpCalleeData,
  [in]  LPQOS          lpSQOS,
  [in]  LPQOS          lpGQOS
);

매개 변수

[in] s

연결되지 않은 소켓을 식별하는 설명자입니다.

[in] name

연결할 주소를 지정하는 sockaddr 구조체에 대한 포인터입니다. IPv4의 경우 sockaddr 에는 주소 패밀리, 대상 IPv4 주소 및 대상 포트에 대한 AF_INET 포함됩니다. IPv6의 경우 sockaddr 구조에는 주소 패밀리, 대상 IPv6 주소, 대상 포트에 대한 AF_INET6 포함되며 추가 흐름 및 scope ID 정보가 포함될 수 있습니다.

[in] namelen

name 매개 변수가 가리키는 sockaddr 구조체의 길이(바이트)입니다.

[in] lpCallerData

연결 설정 중에 다른 소켓으로 전송할 사용자 데이터에 대한 포인터입니다. 설명 부분을 참조하세요.

[out] lpCalleeData

연결 설정 중에 다른 소켓에서 다시 전송할 사용자 데이터에 대한 포인터입니다. 설명 부분을 참조하세요.

[in] lpSQOS

소켓의FLOWSPEC 구조체에 대한 포인터로, 각 방향에 대해 하나씩 지정합니다.

[in] lpGQOS

나중에 소켓 그룹에 사용할 수 있습니다. 소켓 그룹에 대한 FLOWSPEC 구조체에 대한 포인터입니다(해당하는 경우). 이 매개 변수는 NULL이어야 합니다.

반환 값

오류가 발생하지 않으면 WSAConnect 는 0을 반환합니다. 그렇지 않으면 SOCKET_ERROR 반환하고 WSAGetLastError를 호출하여 특정 오류 코드를 검색할 수 있습니다. 차단 소켓에서 반환 값은 연결 시도의 성공 또는 실패를 나타냅니다.

차단되지 않는 소켓을 사용하면 연결 시도를 즉시 완료할 수 없습니다. 이 경우 WSAConnect 는 SOCKET_ERROR 반환하고 WSAGetLastError 는 WSAEWOULDBLOCK을 반환합니다. 따라서 애플리케이션은 다음을 수행할 수 있습니다.

select를 사용하여 소켓이 쓰기 가능한지 확인하여 연결 요청의 완료를 확인합니다.
애플리케이션이 WSAAsyncSelect 를 사용하여 연결 이벤트에 대한 관심을 나타내는 경우 연결 작업이 완료되면 애플리케이션이 FD_CONNECT 알림을 받게 됩니다(성공 여부).
애플리케이션이 WSAEventSelect 를 사용하여 연결 이벤트에 대한 관심을 나타내는 경우 연결 작업이 완료되면 연결된 이벤트 개체에 신호가 전송됩니다(성공 여부).

차단되지 않는 소켓의 경우 연결 시도가 동일한 소켓에서 WSAConnect 에 대한 모든 후속 호출을 완료할 때까지 오류 코드 WSAEALREADY와 함께 실패합니다.

반환 오류 코드가 연결 시도가 실패했음을 나타내는 경우(즉, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) 애플리케이션은 동일한 소켓에 대해 WSAConnect 를 다시 호출할 수 있습니다.

오류 코드	의미
WSANOTINITIALISED	이 함수를 사용하기 전에 성공적인 WSAStartup 호출이 발생해야 합니다.
WSAENETDOWN	네트워크 하위 시스템이 실패했습니다.
WSAEADDRINUSE	소켓의 로컬 주소가 이미 사용 중이며 SO_REUSEADDR 주소를 다시 사용할 수 있도록 소켓이 표시되지 않았습니다. 이 오류는 일반적으로 바인딩 실행 중에 발생하지만 bind 함수가 부분적으로 와일드카드 주소(ADDR_ANY 포함)에서 작동하고 이 함수 당시 특정 주소를 "커밋"해야 하는 경우 이 함수까지 지연될 수 있습니다.
WSAEINTR	(차단) Windows 소켓 1.1 호출이 WSACancelBlockingCall을 통해 취소되었습니다.
WSAEINPROGRESS	차단 Windows 소켓 1.1 호출이 진행 중이거나 서비스 공급자가 여전히 콜백 함수를 처리하고 있습니다.
WSAEALREADY	비 차단 연결 또는 WSAConnect 호출이 지정된 소켓에서 진행 중입니다.
WSAEADDRNOTAVAIL	원격 주소가 유효한 주소(예: ADDR_ANY)가 아닙니다.
WSAEAFNOSUPPORT	지정된 패밀리의 주소는 이 소켓에서 사용할 수 없습니다.
WSAECONNREFUSED	연결 시도가 거부되었습니다.
WSAEFAULT	이름 또는 namelen 매개 변수가 사용자 주소 공간의 유효한 부분이 아니거나, namelen 매개 변수가 너무 작거나, lpCalleeData, lpSQOS 및 lpGQOS의 버퍼 길이가 너무 작거나, lpCallerData의 버퍼 길이가 너무 큽니다.
WSAEINVAL	매개 변수 가 수신 대기 소켓이거나 지정된 대상 주소가 소켓이 속한 제한된 그룹의 주소와 일치하지 않거나 lpGQOS 매개 변수가 NULL이 아닙니다.
WSAEISCONN	소켓이 이미 연결되어 있습니다(연결 지향 소켓만 해당).
WSAENETUNREACH	현재 이 호스트에서 네트워크에 연결할 수 없습니다.
WSAEHOSTUNREACH	연결할 수 없는 호스트로 소켓 작업을 시도했습니다.
WSAENOBUFS	사용할 수 있는 버퍼 공간이 없습니다. 소켓을 연결할 수 없습니다.
WSAENOTSOCK	설명자가 소켓이 아닙니다.
WSAEOPNOTSUPP	lpSQOS 및 lpGQOS에 지정된 FLOWSPEC 구조를 충족할 수 없습니다.
WSAEPROTONOSUPPORT	lpCallerData 매개 변수는 서비스 공급자에서 지원되지 않습니다.
WSAETIMEDOUT	연결을 설정하지 않고 연결 시간이 초과되었습니다.
WSAEWOULDBLOCK	소켓은 차단 해제로 표시되며 연결을 즉시 완료할 수 없습니다.
WSAEACCES	setsockopt SO_BROADCAST 사용하도록 설정되지 않아 데이터그램 소켓을 브로드캐스트 주소에 연결하지 못했습니다.

설명

WSAConnect 함수는 지정된 대상에 대한 연결을 만들고 연결 시 발생하는 여러 다른 보조 작업을 수행하는 데 사용됩니다. 소켓이 바인딩되지 않은 경우 고유 값이 시스템에 의해 로컬 연결에 할당되고 소켓이 바인딩된 것으로 표시됩니다.

Windows Vista 이상을 대상으로 하는 애플리케이션의 경우 클라이언트 애플리케이션 디자인을 크게 간소화하는 WSAConnectByList 또는 WSAConnectByName 함수를 사용하는 것이 좋습니다.

연결 지향 소켓(예: SOCK_STREAM 입력)의 경우 이름 (소켓의 네임스페이스에 있는 주소)을 사용하여 외부 호스트에 대한 활성 연결이 시작됩니다. 자세한 설명은 바인딩을 참조하세요. 이 호출이 성공적으로 완료되면 소켓이 데이터를 보내고 받을 준비가 됩니다. 이름 구조의 주소 매개 변수가 모두 0이면 WSAConnect는 WSAEADDRNOTAVAIL 오류를 반환합니다. 활성 연결을 다시 연결하려는 시도는 오류 코드 WSAEISCONN으로 실패합니다.

참고 소켓이 열리면 setsockopt 호출이 수행되고 sendto 호출이 수행되면 Windows Sockets는 암시적 바인딩 함수 호출을 수행합니다.

연결 지향 비블로킹 소켓의 경우 연결을 즉시 완료할 수 없는 경우가 많습니다. 이러한 경우 이 함수는 WSAEWOULDBLOCK 오류를 반환합니다. 그러나 작업이 진행됩니다. 성공 또는 실패 결과가 알려지면 클라이언트가 알림을 등록하는 방법에 따라 여러 가지 방법 중 하나로 보고될 수 있습니다. 클라이언트에서 select를 사용하는 경우 writefds 집합에서 성공이 보고되고 예외 집합에 오류가 보고 됩니다 . 클라이언트가 WSAAsyncSelect 또는 WSAEventSelect를 사용하는 경우 FD_CONNECT 알림이 발표되고 FD_CONNECT 연결된 오류 코드는 성공 또는 실패의 특정 이유를 나타냅니다.

연결 없는 소켓(예: SOCK_DGRAM 입력)의 경우 WSAConnect 에서 수행하는 작업은 소켓이 후속 연결 지향 송신 및 수신 작업(send, WSASend, recv 및 WSARecv)에서 사용될 수 있도록 기본 대상 주소를 설정하는 것일 뿐입니다. 지정된 대상 주소 이외의 주소에서 받은 모든 데이터그램은 삭제됩니다. 전체 이름 구조가 모두 0이면(이름 구조의 주소 매개 변수뿐만 아니라) 소켓의 연결이 끊어집니다. 그런 다음 기본 원격 주소가 확정되지 않으므로 보내기, WSASend, recv 및 WSARecv 호출은 오류 코드 WSAENOTCONN을 반환합니다. 그러나 sendto, WSASendTo, recvfrom 및 WSARecvFrom 은 계속 사용할 수 있습니다. 소켓이 이미 연결되어 있더라도 WSAConnect 를 다시 호출하면 기본 대상을 변경할 수 있습니다. 이름이 이전 WSAConnect와 다른 경우 수신 대기 중인 모든 데이터그램은 삭제됩니다.

연결 없는 소켓의 경우 이름은 브로드캐스트 주소를 포함하여 유효한 주소를 나타낼 수 있습니다. 그러나 브로드캐스트 주소에 연결하려면 소켓에 setsockopt SO_BROADCAST 사용하도록 설정되어 있어야 합니다. 그렇지 않으면 WSACONnect 가 오류 코드 WSAEACCES와 함께 실패합니다.

연결이 없는 소켓에서는 사용자 간 데이터 교환이 불가능하며 해당 매개 변수는 자동으로 무시됩니다.

애플리케이션은 지정한 매개 변수에 의해 직접 또는 간접적으로 가리키는 메모리 공간을 할당해야 합니다.

lpCallerData 매개 변수에는 연결 요청(연결 데이터라고 함)과 함께 전송될 모든 사용자 데이터에 대한 포인터가 포함되어 있습니다. 이는 연결을 설정하기 위해 네트워크 요청과 함께 전송되는 일반 네트워크 데이터 스트림이 아닌 추가 데이터입니다. 이 옵션은 DECNet, OSI TP4 등의 레거시 프로토콜에서 사용됩니다.

참고 연결 데이터는 Windows의 TCP/IP 프로토콜에서 지원되지 않습니다. 연결 데이터는 원시 소켓을 통해 ATM(RAWWAN)에서만 지원됩니다.

lpCallerData가 NULL이면 피어에 사용자 데이터가 전달되지 않습니다. lpCalleeData는 WSABUF 구조에서 연결 설정의 일부로 다른 소켓에서 다시 전달된 사용자 데이터를 포함하는 결과 매개 변수입니다. lpCalleeData 매개 변수가 가리키는 WSABUF 구조체의 len 멤버는 처음에 WSABUF 구조체의 buf 멤버에 대해 애플리케이션에서 할당한 버퍼의 길이를 포함합니다. 사용자 데이터가 다시 전달되지 않은 경우 lpCalleeData 매개 변수가 가리키는 WSABUF 구조체의 len 멤버가 0으로 설정됩니다. lpCalleeData 정보는 연결 작업이 완료되면 유효합니다. 차단 소켓의 경우 WSAConnect 함수가 반환되면 연결 작업이 완료됩니다. 차단되지 않는 소켓의 경우 FD_CONNECT 알림이 발생한 후 완료됩니다. lpCalleeData가 NULL이면 사용자 데이터가 다시 전달되지 않습니다. 사용자 데이터의 정확한 형식은 소켓이 속한 주소 패밀리와 관련이 있습니다.

연결 시 애플리케이션은 lpSQOS 및 lpGQOS 매개 변수를 사용하여 SIO_SET_QOS 또는 SIO_SET_GROUP_QOS opcode를 사용하여 WSAIoctl 을 통해 소켓에 대해 만들어진 이전 서비스 사양의 품질을 재정의할 수 있습니다.

lpSQOS 매개 변수는 소켓의FLOWSPEC 구조를 각 방향에 하나씩 지정하고 추가 공급자별 매개 변수를 지정합니다. 일반적으로 연결된 전송 공급자 또는 특정 유형의 소켓이 서비스 품질 요청을 적용할 수 없는 경우 다음과 같이 오류가 반환됩니다. 전송 또는 수신 흐름 사양 값은 단방향 소켓에 대해 각각 무시됩니다. 공급자별 매개 변수가 지정되지 않은 경우 lpCalleeData 매개 변수가 가리키는 WSABUF 구조체의 buf 및 len 멤버를 각각 NULL 및 0으로 설정해야 합니다. lpSQOS 매개 변수에 대한 NULL 값은 애플리케이션에서 제공하는 서비스 품질을 나타내지 않습니다.

나중에 소켓 그룹 lpGQOS 에서 사용하도록 예약된 은 소켓 그룹에 대한 FLOWSPEC 구조를 지정합니다(해당하는 경우) 각 방향에 대해 하나씩, 추가 공급자별 매개 변수를 차례로 지정합니다. 공급자별 매개 변수가 지정되지 않은 경우 lpCalleeData 매개 변수가 가리키는 WSABUF 구조체의 buf 및 len 멤버를 각각 NULL 및 0으로 설정해야 합니다. lpGQOS에 대한 NULL 값은 애플리케이션에서 제공하는 서비스 그룹 품질을 나타내지 않습니다. 가 소켓 그룹의 작성자가 아닌 경우 이 매개 변수는 무시됩니다.

어떤 이유로든 연결된 소켓이 닫히면 삭제하고 다시 만들어야 합니다. 연결된 소켓에서 어떤 이유로든 상황이 어지러울 때 애플리케이션은 안정적인 지점으로 돌아가기 위해 필요한 소켓을 삭제하고 다시 만들어야 한다고 가정하는 것이 가장 안전합니다.

참고WSAConnect와 같은 차단 Winsock 호출을 실행할 때 Winsock은 호출이 완료되기 전에 네트워크 이벤트를 기다려야 할 수 있습니다. Winsock은 이 상황에서 경고 가능한 대기를 수행하며, 동일한 스레드에서 예약된 APC(비동기 프로시저 호출)에 의해 중단될 수 있습니다. 동일한 스레드에서 지속적인 차단 Winsock 호출을 중단한 APC 내에서 또 다른 차단 Winsock 호출을 실행하면 정의되지 않은 동작이 발생하며 Winsock 클라이언트에서 시도해서는 안 됩니다.

Windows Phone 8: 이 함수는 Windows Phone 8 이상에서 Windows Phone 스토어 앱에서 지원됩니다.

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