NAT P2P Interface

Interface to send and receive data between users, and related networking functionality.

15 mins to read

The P2P Interface enables games implementing the Epic Online Systems (EOS) SDK to set up and manage Peer-to-Peer (P2P) Connections between users. This enables them to send and receive data between one another directly, typically for the purpose of a multiplayer game. Connections made with the EOS P2P Interface are only established between authenticated users, and are secure-by-default using DTLS, which provides two distinct advantages. First, the speed of handling P2P connections is significantly increased, in that EOS's authentication greatly reduces the need for connections to be re-negotiated. Second, the process of securely handling connections is itself greatly simplified for the SDK user, abstracting out the need for detailed network socket management and condensing most functions to what data needs to be sent and to whom.

Accessing the P2P Interface

In order to use the functions within the EOS P2P Interface, you must first obtain a valid EOS_HP2P handle from the Platform Interface function EOS_Platform_GetP2PInterface, as this handle is used in all P2P Interface functions. For more information about the Platform Interface and this function, you may refer to the page on the EOS Platform Interface.

Managing P2P Connections

The P2P Interface uses the struct EOS_P2P_SocketId as a title-specified identifier for a connection between peers. Most P2P functions related to connections either require an EOS_P2P_SocketId to associate with a connection request, or to return one in order to specify what connection a received connection request is associated with. EOS_P2P_SocketId is comprised of the following parameters:

ParameterDescription
ApiVersionA version field. This must be set to EOS_P2P_SOCKETID_API_LATEST.
SocketNameA value used to vet all incoming connections from unknown peers in multiplayer games. A SocketName must contain 1-32 alpha-numeric, null-terminated characters.

The SocketName field can be a single value for all connections, or it can be a secret value known only to specific players in a multiplayer session. As accepted P2P connections expose a user's IP address to the peer that they are connecting to, it is important to not blindly accept any connection request.

A valid EOS_ProductUserId is also usually required both for users to identify themselves when sending data, and to specify which user they wish to send data to.

All function parameters and their associated values in the P2P Interface are required unless explicitly marked as optional. This includes out-parameters, which the P2P Interface often uses to output data for asynchronous functions or event responses. If a function has a return type of EOS_EResult and the return value is not EOS_Success, then take note that any out-parameters that the function provides will be unset unless specified otherwise.

Requesting Connections

When a local user attempts to send information to a remote user, such as with the EOS_P2P_SendPacket function, the P2P Interface will automatically make a request to open a connection between those two users, with an EOS_P2P_SocketId acting as the identifier for that connection. The user sending the information automatically accepts their own request for that SocketId, while the user receiving the information must accept it, usually by listening for the incoming connection request and using the EOS_P2P_AcceptConnection function.

All operations requiring an open P2P connection can be used to both request and accept a P2P connection if one is not already open. For example, EOS_P2P_AcceptConnection can be used to request a P2P connection with a remote user, and EOS_P2P_SendPacket can be used to accept a remote user's P2P connection request if one has already been made for the Socket Id that the local user is trying to use to send information. This effectively means that it is possible to use EOS_P2P_AcceptConnection to pre-emptively accept the next connection request made with a given SocketId.

If multiple connections are open with a particular user, only the first connection must be negotiated. This greatly increases the speed at which data may be received with subsequent connection requests.

Receiving Connection Request Notifications

When a user receives a connection request, a notify event is fired to all bound Peer Connection Request Handlers.

To listen for connection requests with a new Peer Connection Request Handler, use EOS_P2P_AddNotifyPeerConnectionRequest to bind a function that you would like to use as a response to incoming connection requests. The EOS_P2P_AddNotifyPeerConnectionRequest function takes the following parameters:

ParameterDescription
HandleA valid EOS_HP2P handle received from the Platform Interface.
OptionsA pointer to an EOS_P2P_AddNotifyPeerConnectionRequestOptions struct.
ClientData (Optional)Pointer to data that will be returned to the caller when the event fires.
ConnectionRequestHandlerA function that will act as your Peer Connection Request Handler, responding to incoming connection requests. This function must take a pointer to an EOS_P2P_OnIncomingConnectionRequestInfo struct as a parameter.

The EOS_P2P_AddNotifyPeerConnectionRequestOptions struct is comprised of the following parameters:

ParameterDescription
ApiVersionA version field. Set to EOS_P2P_ADDNOTIFYPEERCONNECTIONREQUEST_API_LATEST
LocalUserIdSet to the ID of the local user that is listening for incoming connection request.
SocketId (Optional)Pointer to a valid EOS_P2P_SocketId struct that you would like to use to filter connection requests.

The EOS_P2P_AddNotifyPeerConnectionRequest function will return either a valid EOS_NotificationId on success, or the value EOS_INVALID_NOTIFICATIONID on failure.

You can remove a Peer Connection Request Handler with the EOS_P2P_RemoveNotifyPeerConnectionRequest function, which requires the following parameters:

ParameterDescription
HandleA valid EOS_HP2P handle received from the Platform Interface.
NotificationIdA valid EOS_NotificationId returned from EOS_P2P_AddNotifyPeerConnectionRequest, used to identify the peer connection request handler you wish to remove.

Accepting Connections

The EOS_P2P_AcceptConnection function can be used to accept a connection that has been requested, or to start a new connection request. Both users must accept a connection for a given SocketId before the connection can be established and used to send data. The user attempting to open a connection has to call EOS_P2P_AcceptConnection, if bDisableAutoAcceptConnection is set to EOS_TRUE.

To call the EOS_P2P_AcceptConnection function, you must provide the following parameters:

ParameterDescription
HandleA valid EOS_HP2P handle received from the Platform Interface.
OptionsA pointer to an EOS_P2P_AcceptConnectionOptions struct.

The EOS_P2P_AcceptConnectionOptions struct contains the following parameters:

ParameterDescription
ApiVersionSet to EOS_P2P_ACCEPTCONNECTION_API_LATEST
LocalUserIdSet to the EOS_ProductUserId of the local user that is accepting the connection.
RemoteUserIdSet to the EOS_ProductUserId of the remote user that the local user wants to connect to.
SocketIdPointer to a valid EOS_P2P_SocketId struct that you would like to accept a connection for.

The EOS_P2P_AcceptConnection function will return a value of EOS_InvalidParameters if any of the supplied input was invalid. It will return EOS_Success if the supplied information was valid, signifying that the connection was locally accepted and will be able to send data when the remote user accepts the connection as well. Calling EOS_P2P_AcceptConnection multiple times before a Connection Closed event fires will have no effect.

Closing Connections

The EOS_P2P_CloseConnection function can be used to reject a connection that has been requested, or to close a connection that was previously accepted with a specific user. If all connections with a specific user are closed, the backing socket connection will also be destroyed soon after. The EOS_P2P_CloseConnection function requires the following parameters:

ParameterDescription
HandleA valid EOS_HP2P handle received from the Platform Interface.
OptionsA pointer to an EOS_P2P_CloseConnectionOptions struct.

The EOS_P2P_CloseConnectionOptions struct contains the following parameters:

ParameterDescription
ApiVersionSet to EOS_P2P_CLOSECONNECTION_API_LATEST.
LocalUserIdSet to the EOS_ProductUserId of the local user that is closing or rejecting the connection.
RemoteUserIdSet to the EOS_ProductUserId of the remote user whose connection is being closed or rejected.
SocketIdPointer to a valid EOS_P2P_SocketId struct you would like to close or reject a connection on.

The EOS_P2P_CloseConnection function will return either a value of EOS_InvalidParameters, signifying that the supplied input for the function was invalid, or it will return a value of EOS_Success, in which case the supplied input was valid and the connection will be closed or the connection request will be silently rejected.

The EOS_P2P_CloseConnections function can be used to close or reject all connections on a specific SocketId, rather than a connection from a specific user. This could be used at the end of a session to drop all related connections for that session. The EOS_P2P_CloseConnections function requires the following parameters:

ParameterDescription
HandleA valid EOS_HP2P handle received from the Platform Interface.
OptionsPointer to an EOS_P2P_CloseConnectionsOptions struct.

The EOS_P2P_CloseConnectionsOptions struct contains the following parameters:

ParameterDescription
ApiVersionSet to EOS_P2P_CLOSECONNECTIONS_API_LATEST
LocalUserIdSet to the EOS_ProductUserId of the local user that is closing all connections with the requested SocketId.
SocketIdPointer to a valid EOS_P2P_SocketId struct that you would like to close all connections on.

The function will return a result of EOS_InvalidParameters if any of the supplied input was invalid, or it will return EOS_Success if the supplied information was valid and all the connections with the specified SocketId were successfully closed.

Receiving Connection Closed Notifications

When an open or pending connection closes, a Connection Closed Event will fire, notifying the application and permitting it to respond. To create a handler for Connection Closed Events, use the EOS_P2P_AddNotifyPeerConnectionClosed function, which requires the following parameters:

ParameterDescription
HandleA valid EOS_HP2P handle received from the Platform Interface.
OptionsPointer to a EOS_P2P_AddNotifyPeerConnectionClosedOptions struct.
ClientData (Optional)Pointer to data that will be returned to the caller when the event fires.
ConnectionClosedHandlerA function that will be called when the Connection Closed Event fires. This function must take a pointer to an EOS_P2P_OnRemoteConnectionClosedInfo struct passed as a parameter.

The EOS_P2P_AddNotifyPeerConnectionClosedOptions struct contains the following parameters:

ParameterDescription
ApiVersionSet to EOS_P2P_ADDNOTIFYPEERCONNECTIONCLOSED_API_LATEST.
LocalUserIdSet to the EOS_ProductUserId of the local user that is listening for connections to close.
SocketId (Optional)Pointer to a valid EOS_P2P_SocketId struct that you would like to filter connection closed events on.

The EOS_P2P_AddNotifyPeerConnectionClosed function returns an EOS_NotificationId that can be used to identify the Connection Closed Event Handler.

You can remove a Connection Closed Event Handler by calling the function EOS_P2P_RemoveNotifyPeerConnectionClosed, which takes the following parameters:

ParameterDescription
HandleA valid EOS_HP2P handle received from the Platform Interface.
NotificationIdA valid EOS_NotificationId returned from EOS_P2P_AddNotifyPeerConnectionClosed.

Sending and Receiving Data Through P2P Connections