NAT P2P Interface

P2P 인터페이스를 사용하면 게임에서 에픽 온라인 서비스(Epic Online Services, EOS) SDK를 구현하여 사용자 간의 P2P(Peer-to-Peer) 연결을 구성하고 관리할 수 있습니다. P2P는 보통 멀티플레이어 게임에서 상호 간에 데이터를 직접 송수신하는 데 사용됩니다. EOS P2P 인터페이스에 의한 연결은 인증된 사용자 사이에서만 이루어질 수 있으며, 기본적으로 DTLS로 보안을 확보합니다. 이 인터페이스의 강점은 두 가지입니다. 첫 번째는 EOS의 인증이 연결 재조정 필요성을 현저히 감소시켜 P2P 연결 제어 속도가 눈에 띄게 증가한다는 점입니다. 두 번째는 SDK 사용자를 위해 연결 제어 시 보안 과정이 매우 간소화되어 세부 네트워크 소켓을 관리할 필요가 없고, 데이터 송신 대상 및 송신 데이터 관련 대부분의 함수가 압축된다는 점입니다.

EOS P2P 인터페이스에서 함수를 사용하려면 우선 플랫폼 인터페이스(Platform Interface) 함수 EOS_Platform_GetP2PInterface 로부터 유효한 EOS_HP2P 핸들을 얻어야 합니다. 이 핸들은 모든 P2P 인터페이스 함수에 사용됩니다. 플랫폼 인터페이스 및 이 함수에 대한 자세한 내용은 EOS 플랫폼 인터페이스 페이지를 참고하세요.

P2P 인터페이스는 피어 간 연결용 특정 타이틀 식별자로 EOS_P2P_SocketId 구조체를 사용합니다. 연결 관련 P2P 함수 대부분은 수신 연결 요청 시 EOS_P2P_SocketId 가 필요하거나, 수신 연결 요청과 관련된 연결을 특정하기 위해 이를 반환할 필요가 있습니다. EOS_P2P_SocketId 는 다음과 같은 파라미터로 구성됩니다.

SocketName 항목은 모든 연결을 대상으로 하나의 값이거나, 멀티플레이어 세션의 특정 플레이어만 아는 비밀 값일 수 있습니다. P2P 연결을 수락하면 연결된 피어에 사용자의 IP 주소를 노출하므로 연결 요청을 무작정 수락하면 안 됩니다.

사용자가 데이터 송신 시 자신을 식별하고, 송신 대상인 사용자를 특정하기 위해 유효한 EOS_ProductUserId 도 필요한 편입니다.

P2P 인터페이스의 모든 함수 파라미터와 관련 값은 선택 사항이라고 따로 표시되지 않았다면 필요합니다. 여기에는 P2P 인터페이스가 때때로 비동기 함수 또는 이벤트 응답용으로 데이터를 출력할 때 사용하는 아웃 파라미터도 포함됩니다. 어떤 함수의 반환 유형이 EOS_EResult 고 반환 값이 EOS_Success 가 아니면 해당 함수가 제공하는 모든 아웃 파라미터는 달리 특정되지 않는 한 설정되지 않습니다.

로컬 사용자가 EOS_P2P_SendPacket 함수 등으로 원격 사용자에게 정보를 보내려고 시도하면 P2P 인터페이스가 자동으로 두 사용자 간 연결 개방 요청을 합니다. 이때 EOS_P2P_SocketId 는 이 연결의 식별자 역할을 합니다. 정보를 보내는 사용자는 자동으로 해당 SocketId의 자체 요청을 수락하고, 정보를 수신하는 사용자는 수락해야 합니다. 정보 수신자는 일반적으로 유입되는 연결 요청을 대기하고 EOS_P2P_AcceptConnection 함수를 사용하는 방식을 사용합니다.

연결이 이미 개방되지 않은 경우, 개방형 P2P 연결이 필요한 모든 연산은 P2P 연결 요청과 수락 모두에 사용할 수 있습니다. 예를 들어 EOS_P2P_AcceptConnection 은 원격 사용자와의 P2P 연결을 요청할 때 사용할 수 있고, 로컬 사용자가 정보를 송신할 때 사용하려는 소켓 ID로 요청이 이미 왔다면 EOS_P2P_SendPacket 은 원격 사용자의 P2P 연결 요청을 수락할 때 사용할 수 있습니다. 주어진 SocketId로 보낸 다음 연결 요청을 EOS_P2P_AcceptConnection 으로 우선 수락할 수 있다는 뜻입니다.

특정 사용자가 여러 연결을 개방했다면 첫 번째 연결만 성사되어야 합니다. 이는 차후 연결 요청에 의한 데이터 수신 속도를 크게 향상합니다.

사용자가 연결 요청을 받으면 모든 바운드 피어 연결 요청 핸들러(Peer Connection Request Handler) 에 알림 이벤트가 갑니다.

새로운 피어 연결 요청 핸들러로 연결 요청을 수신하려면 유입되는 연결 요청에 대한 응답으로 사용하고자 하는 함수를 EOS_P2P_AddNotifyPeerConnectionRequest 로 바인딩합니다. EOS_P2P_AddNotifyPeerConnectionRequest 함수는 다음과 같은 파라미터를 수용합니다.

EOS_P2P_AddNotifyPeerConnectionRequestOptions 구조체는 다음과 같은 파라미터로 구성됩니다.

EOS_P2P_AddNotifyPeerConnectionRequest 함수는 성공 시 유효한 EOS_NotificationId 를, 실패 시 EOS_INVALID_NOTIFICATIONID` 값을 반환합니다.

EOS_P2P_RemoveNotifyPeerConnectionRequest 함수를 사용해 피어 연결 요청 핸들러를 제거할 수 있습니다. 해당 함수는 다음과 같은 파라미터가 필요합니다.

EOS_P2P_AcceptConnection 함수는 요청한 연결을 수락하거나 새로운 연결 요청을 시작할 때 사용할 수 있습니다. 두 사용자 모두 주어진 SocketId를 통한 연결을 수락해야 연결 후 데이터를 송신할 수 있습니다. 연결 개방을 시도하는 사용자는 bDisableAutoAcceptConnection 이 EOS_TRUE 로 설정된 경우 EOS_P2P_AcceptConnection 을 호출해야 합니다.

EOS_P2P_AcceptConnection 함수를 호출하려면 다음과 같은 파라미터를 제공해야 합니다.

EOS_P2P_AcceptConnectionOptions 구조체는 다음과 같은 파라미터를 가지고 있습니다.

제공된 입력 중 하나라도 유효하지 않으면 EOS_P2P_AcceptConnection 함수는 EOS_InvalidParameters 값을 반환합니다. 제공된 정보가 유효하면 EOS_Success 를 반환하며, 해당 연결이 로컬과 원격 사용자에 의해 수락되면 데이터를 송신할 수 있다는 것을 뜻합니다. 연결 종료 이벤트가 보내지기 전에는 EOS_P2P_AcceptConnection 을 여러 번 호출해도 아무런 효과도 없습니다.

###연결 종료 EOS_P2P_CloseConnection 함수는 요청한 연결을 거절하거나 기존에 수락된 특정 사용자와의 연결을 종료할 때 사용할 수 있습니다. 특정 사용자와의 모든 연결이 종료되면 지원 소켓 연결도 곧 소멸합니다. EOS_P2P_CloseConnection 함수는 다음과 같은 파라미터가 필요합니다.

EOS_P2P_CloseConnectionOptions 구조체는 다음과 같은 파라미터를 가지고 있습니다.

EOS_P2P_CloseConnection 함수는 EOS_InvalidParameters 값을 반환하거나 EOS_Success 값을 반환합니다. 전자는 함수에 제공된 입력이 유효하지 않다는 것을 의미하고, 후자의 경우 제공된 입력이 유효하여 연결이 종료되거나 연결 요청이 조용히 거절됩니다.

EOS_P2P_CloseConnections 함수를 사용하면 특정 사용자와의 연결이 아니라 특정 SocketId의 모든 연결을 종료 또는 거절할 수 있습니다. 세션 종료 시 이를 이용해 해당 세션과 관련된 모든 연결을 끊을 수 있습니다. EOS_P2P_CloseConnections 함수에는 다음과 같은 파라미터가 필요합니다.

EOS_P2P_CloseConnectionsOptions 구조체는 다음과 같은 파라미터를 가지고 있습니다.

제공된 입력 중 하나라도 유효하지 않으면 해당 함수는 EOS_InvalidParameters 값을 반환하고, 제공된 정보가 유효하며 특정된 SocketId 의 모든 연결이 성공적으로 종료되면 EOS_Success 를 반환합니다.

개방 또는 보류된 연결이 종료되면 연결 종료 이벤트(Connection Closed Event) 를 전달하여 애플리케이션에 알리고 응답을 허용합니다. 연결 종료 이벤트의 핸들러를 생성하기 위해서는 EOS_P2P_AddNotifyPeerConnectionClosed 함수를 사용하는데, 이 함수는 다음과 같은 파라미터가 필요합니다.

EOS_P2P_AddNotifyPeerConnectionClosedOptions 구조체는 다음과 같은 파라미터를 가지고 있습니다.

EOS_P2P_AddNotifyPeerConnectionClosed 함수는 연결 종료 이벤트 핸들러 식별에 사용할 수 있는 EOS_NotificationId 를 반환합니다.

EOS_P2P_RemoveNotifyPeerConnectionClosed 함수를 호출하여 연결 종료 이벤트 핸들러를 제거할 수 있는데, 이 함수는 다음과 같은 파라미터를 수용합니다.

P2P 연결에 성공하면 사용자는 P2P 연결을 통해 데이터를 송수신할 수 있습니다.

EOS_P2P_SendPacket 함수는 다른 사용자에게 패킷을 안전하게 보냅니다. 해당 피어에 대해서 이미 개방된 연결이 있으면 즉시 송신합니다. 개방된 연결이 없으면 새로운 연결을 위한 요청이 이루어집니다. EOS_P2P_SendPacket 함수는 다음과 같은 파라미터를 수용합니다.

EOS_P2P_SendPacketOptions 구조체는 다음과 같은 파라미터를 포함합니다.

제공된 입력 중 하나라도 유효하지 않으면 이 함수는 EOS_InvalidParameters 를 반환하고, 제공된 정보가 유효하며 송신이 가능하면 EOS_Success 를 반환합니다. Success가 반환됐다는 건 패킷이 성공적으로 전달됐다는 게 아니라 성공적으로 보냈다는 뜻입니다. 신뢰할 수 없는 데이터 송신이 이루어졌으므로 성공적으로 전달되었는지는 보증할 수 없습니다.

P2P 인터페이스는 사용자가 받은 패킷을 내부적으로 큐에 등록하며, EOS_P2P_ReceivePacket 함수 호출을 기다렸다가 호출이 되면 큐에서 해당 패킷을 제거하고 데이터를 버퍼에 저장합니다. 이 함수는 다음과 같은 파라미터를 받습니다.

EOS_P2P_ReceivePacketOptions 구조체는 다음과 같은 파라미터를 가지고 있습니다.

입력 파라미터 중 하나라도 유효하지 않으면 이 함수는 EOS_InvalidParameters 를 반환합니다. 패킷 및 관련 데이터가 모든 아웃 파라미터에 성공적으로 복사되면 EOS_Success 를 반환하고, 요청을 완료할 패킷이 없으면 EOS_NotFound 를 반환합니다. 해당 함수가 EOS_Success 값을 반환할 때만 아웃 파라미터에 작성할 수 있다는 사실에 주목할 필요가 있습니다.

EOS_P2P_ReceivePacketOptions 는 OutData 로 버퍼 자체를 특정하고, MaxDataSizeBytes 로 안전하게 버퍼에 작성할 수 있는 데이터 양도 지정해야 합니다. 제공된 버퍼가 다음 패킷을 넣기에 너무 작으면 해당 데이터는 제공된 버퍼 길이에 맞게 조용히 길이가 줄어듭니다. OutData 에 NULL 버퍼를 설정하고 MaxDataSizeBytes 크기를 0으로 하여 패킷 데이터를 폐기하는 것도 가능합니다. EOS_P2P_MAX_PACKET_SIZE 버퍼를 안전하게 사용하여 패킷 데이터를 저장하는 것도 가능하지만, EOS_P2P_ReceivePacket 을 호출하기 전에 EOS_P2P_GetNextReceivedPacketSize 를 호출하여 패킷 데이터의 정확한 크기를 얻는 것이 좋습니다. DTLS/SCTP/UDP 패킷 오버헤드로 인해 EOS_P2P_MAX_PACKET_SIZE 는 1170입니다.

EOS_P2P_GetNextReceivedPacketSize 는 내부 큐에서 다음 패킷을 제거하지 않고도 패킷의 크기를 바이트로 얻으며, 다음과 같은 파라미터를 수용합니다.

EOS_P2P_GetNextReceivedPacketSizeOptions 구조체는 다음과 같은 파라미터를 가지고 있습니다.

입력 파라미터 중 하나라도 유효하지 않으면 이 함수는 EOS_InvalidParameters 값을 반환하고, 패킷 데이터 크기가 OutPacketSizeBytes 에 성공적으로 복사되면 EOS_Success 값을 반환합니다. 이용할 수 있는 데이터가 없으면 해당 함수는 EOS_NotFound 값을 대신 반환합니다.

P2P 인터페이스가 NAT-Traversal 시도 시, 하나 이상의 피어가 제한된 NAT를 보유했을 때는 항상 유입되는 연결을 수신할 수 있는 건 아닙니다. 이런 경우에는 NAT-Traversal이 실패했을 때 자동으로 사용되는 중계 과정이 필요합니다. P2P 인터페이스는 사용자가 쉽게 피어와 연결을 할 수 있는지를 판별하기 위해 로컬 사용자의 인터넷 관련 NAT 유형 을 쿼리할 수 있습니다. 이는 EOS_ENATType 으로 나타내며, 다음과 같은 값을 수용합니다.

EOS_P2P_QueryNATType 함수는 현재 연결의 NAT 유형을 비동기적으로 판별할 수 있습니다. 이를 위해 이 함수는 원격 서버에 여러 데이터 패킷을 보내며, 해당 서버는 이에 응답하여 로컬 애플리케이션이 사용한 IP와 포트가 무엇인지 알려줍니다. 요청이 이미 처리 중일 때 추가 EOS_P2P_QueryNATType 호출이 이루어지면 첫 요청으로 그룹화하여 새 요청을 시작하지 않습니다. EOS_P2P_QueryNATType 은 다음과 같은 파라미터를 수용합니다.

EOS_P2P_QueryNATTypeOptions 구조체는 다음과 같은 파라미터를 가지고 있습니다.

NAT 유형 쿼리가 비동기이므로 이 함수는 값을 직접 반환하지 않습니다. 대신 쿼리 종료 시 발동하도록 등록된 함수인 NAT 유형 쿼리드 핸들러(Queried Handler) 를 통해 사용자의 NAT 유형을 출력합니다. 이 쿼리가 사용자의 NAT 유형을 판별하지 못하고 EOS_NAT_Unknown 값을 대신 반환하는 경우도 있습니다.

EOS_P2P_QueryNATType 이 완료되면 사용자의 NAT 유형값이 캐싱되는데, 대신 EOS_P2P_GetNATType 함수를 호출하여 해당 값을 즉시 반환하게 할 수 있습니다. 이때 EOS_P2P_QueryNATType 이 최소 한 번은 성공적으로 완료되어야만 반환이 이루어집니다. EOS_P2P_GetNATType 함수를 호출하려면 다음과 같은 파라미터를 제공해야 합니다.

EOS_P2P_GetNATTypeOptions 구조체는 다음과 같은 파라미터를 가지고 있습니다.

이전에 EOS_P2P_QueryNATType 이 성공적으로 호출되었다면 EOS_P2P_GetNATType 함수는 EOS_Success 를 반환합니다. 이전에 EOS_P2P_QueryNATType 이 호출되지 않았거나 완료되지 않은 경우, EOS_NotFound 를 반환합니다.