NAT P2P Interface

사용자끼리 데이터를 송수신하고 관련 네트워크 기능을 사용하기 위한 인터페이스입니다.

15 분 소요

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

P2P 인터페이스 액세스

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

P2P 연결 관리

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

파라미터설명
ApiVersion버전 항목입니다. 반드시 EOS_P2P_SOCKETID_API_LATEST 로 설정되어야 합니다.
SocketName멀티플레이어 게임에서 알 수 없는 피어로부터 유입되는 모든 연결을 설정할 때 사용하는 값입니다. SocketName은 1~32자의 null 종단 문자열인 알파벳 또는 숫자로 구성되어야 합니다.

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 연결을 요청할 때 사용할 수 있고, 로컬 사용자가 정보를 송신할 때 사용하려는 Socket Id로 요청이 이미 왔다면 EOS_P2P_SendPacket 은 원격 사용자의 P2P 연결 요청을 수락할 때 사용할 수 있습니다. 주어진 SocketId로 보낸 다음 연결 요청을 EOS_P2P_AcceptConnection 으로 우선 수락할 수 있다는 뜻입니다.

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

연결 요청 알림 수신

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

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

파라미터설명
Handle플랫폼 인터페이스로부터 받은 유효한 EOS_HP2P 핸들입니다.
OptionsEOS_P2P_AddNotifyPeerConnectionRequestOptions 구조체에 대한 포인터입니다.
ClientData (선택 사항)이벤트 송신 시 호출자에게 반환되는 데이터에 대한 포인터입니다.
ConnectionRequestHandler유입되는 연결 요청에 응답하는 피어 연결 요청 핸들러 역할을 할 함수입니다. 이 함수는 EOS_P2P_OnIncomingConnectionRequestInfo 구조체에 대한 포인터를 파라미터로 얻어야 합니다.

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

파라미터설명
ApiVersion버전 항목입니다. EOS_P2P_ADDNOTIFYPEERCONNECTIONREQUEST_API_LATEST 로 설정합니다.
LocalUserId유입되는 연결 요청을 기다리는 로컬 사용자의 ID로 설정합니다.
SocketId (선택 사항)연결 요청 필터링에 사용할 유효한 EOS_P2P_SocketId 구조체에 대한 포인터입니다.

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

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

파라미터설명
Handle플랫폼 인터페이스로부터 받은 유효한 EOS_HP2P 핸들입니다.
NotificationIdEOS_P2P_AddNotifyPeerConnectionRequest 에서 반환된 유효한 EOS_NotificationId 입니다. 이를 사용하여 제거하고자 하는 피어 연결 요청 핸들러를 식별할 수 있습니다.

연결 수락

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

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

파라미터설명
Handle플랫폼 인터페이스로부터 받은 유효한 EOS_HP2P 핸들입니다.
OptionsEOS_P2P_AcceptConnectionOptions 구조체에 대한 포인터입니다.

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

파라미터설명
ApiVersionEOS_P2P_ACCEPTCONNECTION_API_LATEST 로 설정합니다.
LocalUserId연결을 수락하는 로컬 사용자의 EOS_ProductUserId 로 설정합니다.
RemoteUserId로컬 사용자가 연결하려는 원격 사용자의 EOS_ProductUserId 로 설정합니다.
SocketId연결 수락을 위한 유효한 EOS_P2P_SocketId 구조체에 대한 포인터입니다.

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

연결 종료

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

파라미터설명
Handle플랫폼 인터페이스로부터 받은 유효한 EOS_HP2P 핸들입니다.
OptionsEOS_P2P_CloseConnectionOptions 구조체에 대한 포인터입니다.

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

파라미터설명
ApiVersionEOS_P2P_CLOSECONNECTION_API_LATEST 로 설정합니다.
LocalUserId연결을 종료 또는 거절하는 로컬 사용자의 EOS_ProductUserId 로 설정합니다.
RemoteUserId연결이 종료 또는 거절되는 원격 사용자의 EOS_ProductUserId 로 설정합니다.
SocketId연결 종료 또는 거절을 위한 유효한 EOS_P2P_SocketId 구조체에 대한 포인터입니다.

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

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

파라미터설명
Handle플랫폼 인터페이스로부터 받은 유효한 EOS_HP2P 핸들입니다.
OptionsEOS_P2P_CloseConnectionsOptions 구조체에 대한 포인터입니다.

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

파라미터설명
ApiVersionEOS_P2P_CLOSECONNECTIONS_API_LATEST 로 설정합니다.
LocalUserId요청한 SocketId의 모든 연결을 종료하는 로컬 사용자의 EOS_ProductUserId 로 설정합니다.
SocketId연결 종료를 위한 유효한 EOS_P2P_SocketId 구조체에 대한 포인터입니다.

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

연결 종료 알림 수신

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

파라미터설명
Handle플랫폼 인터페이스로부터 받은 유효한 EOS_HP2P 핸들입니다.
OptionsEOS_P2P_AddNotifyPeerConnectionClosedOptions 구조체에 대한 포인터입니다.
ClientData (선택 사항)이벤트 송신 시 호출자에게 반환되는 데이터에 대한 포인터입니다.
ConnectionClosedHandler연결 종료 이벤트를 날리면 호출되는 함수입니다. 이 함수는 EOS_P2P_OnRemoteConnectionClosedInfo 구조체에 대한 포인터를 파라미터로 전달받아야 합니다.

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

파라미터설명
ApiVersionEOS_P2P_ADDNOTIFYPEERCONNECTIONCLOSED_API_LATEST 로 설정합니다.
LocalUserId연결 종료를 위해 대기하는 로컬 사용자의 EOS_ProductUserId 로 설정합니다.
SocketId (선택 사항)연결 종료 이벤트 필터링에 사용할 유효한 EOS_P2P_SocketId 구조체에 대한 포인터입니다.

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

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

파라미터설명
Handle플랫폼 인터페이스로부터 받은 유효한 EOS_HP2P 핸들입니다.
NotificationIdEOS_P2P_AddNotifyPeerConnectionClosed 에서 반환된 유효한 EOS_NotificationId 입니다.

P2P 연결을 통한 데이터 송수신