P2P

Epic Online Services Interface: P2P Interface

This module contains functionality to interact with the NAT P2P Interface, which has functionality to send and receive data between users, and related networking functionality.

P2P connections enable game clients 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 Datagram Transport Layer (DTLS). DTLS provides two distinct advantages over other communications protocols: *The speed of handling P2P connections is significantly increased, resulting in EOS's authentication having a greatly reduced need for connections to be re-negotiated.

Functions

The following are the functions of the P2P module:

Structs

The following are the structs of the P2P module:

PacketQueueInfo

Constants

The following are the constants and enums of the P2P module:

eos_p2p_accept_connection

Epic Online Services Function: EOS_P2P_AcceptConnection

This function accepts or requests a connection with a specific peer on a specific Socket ID. If this connection was not already locally accepted, EOS will securely message the peer, and trigger a PeerConnectionRequest notification notifying them of the connection request. If the PeerConnectionRequest notification is not bound for all socket IDs or for the requested socket ID in particular, the request will be silently ignored. If the remote peer accepts the connection, a notification will be broadcast to the EOS_P2P_AddNotifyPeerConnectionEstablished when the connection is ready to send packets. If multiple Socket IDs are accepted with one peer, they will share one physical socket. Even if a connection is already locally accepted, EOS_RESULT.SUCCESS will still be returned if the input was valid. EOS_RESULT.INVALID_PARAMETERS will be returned if the input is invalid.

Syntax:

eos_p2p_accept_connection(local_user_id, remote_user_id, socket_name)

Argument	Type	Description
local_user_id	String	The Product User ID of the local user who is accepting any pending or future connections with `remote_user_id`
remote_user_id	String	The Product User ID of the remote user who has either sent a connection request or is expected to in the future
socket_name	String	The socket ID of the connection to accept on

Returns:

EOS_RESULT

eos_p2p_add_notify_incoming_packet_queue_full

Epic Online Services Function: EOS_P2P_AddNotifyIncomingPacketQueueFull

This function listens for when the packet queue has become full. This event gives an opportunity to read packets to make room for new incoming packets. If this event fires and no packets are read by calling eos_p2p_receive_packet or the packet queue size is not increased by eos_p2p_set_packet_queue_size, any packets that are received after this event are discarded until there is room again in the queue.

The function returns a valid notification ID if successfully bound, or EOS_INVALID_NOTIFICATIONID otherwise.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

eos_p2p_add_notify_incoming_packet_queue_full()

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	the string `"eos_p2p_add_notify_incoming_packet_queue_full"`
overflow_packet_channel	Real	The channel the incoming packet is for
overflow_packet_local_user_id	String	The Product User ID of the local user who is receiving the packet that would overflow the queue
overflow_packet_size_bytes	Real	The size in bytes of the incoming packet (and related metadata) that would overflow the queue
packet_queue_current_size_bytes	Real	The current size in bytes the incoming packet queue is currently using
packet_queue_max_size_bytes	Real	The maximum size in bytes the incoming packet queue is allowed to use

eos_p2p_add_notify_peer_connection_closed

Epic Online Services Function: EOS_P2P_AddNotifyPeerConnectionClosed

This function listens for when a previously accepted connection that was either open or pending is closed. When a connection closes, packets are flushed. This includes reliable packets.

The function returns a valid notification ID if successfully bound, or EOS_INVALID_NOTIFICATIONID otherwise.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

eos_p2p_add_notify_peer_connection_closed(local_user_id, socket_name)

Argument	Type	Description
local_user_id	String	The Product User ID of the local user who would like notifications
socket_name	String	The optional socket ID to listen for to be closed. If an empty string `""` is passed, this function handler will be called for all closed connections.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	the string `"eos_p2p_add_notify_peer_connection_closed"`
local_user_id	String	The local user who is being notified of a connection being closed
reason	EOS_CONNECTION_CLOSED_REASON	The reason the connection was closed (if known)
remote_user_id	String	The Product User ID of the remote user who this connection was with
socket_name	String	The socket ID of the connection being closed

eos_p2p_add_notify_peer_connection_established

Epic Online Services Function: EOS_P2P_AddNotifyPeerConnectionEstablished

This function listens for when a connection is established. This is fired when we first connect to a peer, when we reconnect to a peer after a connection interruption, and when our underlying network connection type changes (for example, from a direct connection to relay, or vice versa). Network Connection Type changes will always be broadcast with a EOS_CONNECTION_ESTABLISHED_TYPE.RECONNECTION connection type, even if the connection was not interrupted. If the network status changes from offline to online, you must call this function again.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

eos_p2p_add_notify_peer_connection_established(local_user_id, socket_name)

Argument	Type	Description
local_user_id	String	The Product User ID of the local user who would like to receive notifications
socket_name	String	The optional socket ID, used as a filter for established connections. If an empty string `""` is passed, this function handler will be called for all sockets.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	the string `"eos_p2p_add_notify_peer_connection_established"`
local_user_id	String	The Product User ID of the local user who is being notified of a connection being established
connection_type	EOS_CONNECTION_ESTABLISHED_TYPE	Whether this is a new connection or reconnection
network_type	EOS_NETWORK_CONNECTION_TYPE	What type of network connection is being used for this connection
socket_id	String	The socket ID of the connection being established
remote_user_id	String	The Product User ID of the remote user who this connection was with

eos_p2p_add_notify_peer_connection_interrupted

Epic Online Services Function: EOS_P2P_AddNotifyPeerConnectionInterrupted

This function listens for when a previously opened connection is interrupted. The connection will automatically attempt to reestablish, but it may not be successful. If a connection reconnects, it will trigger the P2P PeerConnectionEstablished notification with the EOS_CONNECTION_ESTABLISHED_TYPE.RECONNECTION connection type. If a connection fails to reconnect, it will trigger the P2P PeerConnectionClosed notification. Packets remain queued during connection interruptions. When a connection closes, packets are flushed. This includes reliable packets.

The function returns the notification ID.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

eos_p2p_add_notify_peer_connection_interrupted(local_user_id, socket_name)

Argument	Type	Description
local_user_id	String	The Product User ID of the local user who would like notifications
socket_name	String	An optional socket ID to filter interrupted connections on. If an empty string, this function handler will be called for all interrupted connections.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	the string `"eos_p2p_add_notify_peer_connection_interrupted"`
local_user_id	String	The local user who is being notified of a connection that was interrupted
remote_user_id	String	The Product User ID of the remote user who this connection was with
socket_name	String	The socket ID of the connection that was interrupted

eos_p2p_add_notify_peer_connection_request

Epic Online Services Function: EOS_P2P_AddNotifyPeerConnectionRequest

This function listens for incoming connection requests on a particular Socket ID, or optionally all Socket IDs. The Social Async Event will only be called if the connection has not already been accepted. If the network status changes from offline to online, you must call this function again.

The function returns the notification ID.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

eos_p2p_add_notify_peer_connection_request(local_user_id, socket_name)

Argument	Type	Description
local_user_id	String	The Product User ID of the user who is listening for incoming connection requests
socket_name	String	The optional socket ID to listen for, used as a filter for incoming connection requests; If an empty string, incoming connection requests will not be filtered

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The string `"eos_p2p_add_notify_peer_connection_request"`
local_user_id	String	The Product User ID of the local user who is being requested to open a P2P session with `remote_user_id`
remote_user_id	String	The Product User ID of the remote user who requested a peer connection with the local user
socket_name	String	The ID of the socket the Remote User wishes to communicate on

eos_p2p_clear_packet_queue

Epic Online Services Function: EOS_P2P_ClearPacketQueue

This function clears queued incoming and outgoing packets.

Syntax:

eos_p2p_clear_packet_queue(local_user_id, remote_user_id, socket_name)

Argument	Type	Description
local_user_id	String	The Product User ID of the local user for whom we want to clear the queued packets
remote_user_id	String	The Product User ID to who (outgoing) or from who (incoming) packets are queued
socket_name	String	The socket used for packets to be cleared

Returns:

EOS_RESULT

eos_p2p_close_connection

Epic Online Services Function: EOS_P2P_CloseConnection

For all (or optionally one specific) Socket ID(s) with a specific peer: stop receiving packets, drop any locally queued packets, and if no other Socket ID is using the connection with the peer, close the underlying connection. If your application wants to migrate an existing connection with a peer it already connected to, it is recommended to call eos_p2p_accept_connection with the new Socket ID first before calling eos_p2p_close_connection, to prevent the shared physical socket from being torn down prematurely.

The function returns EOS_RESULT.SUCCESS if the provided data is valid, EOS_RESULT.INVALID_PARAMETERS otherwise.

Syntax:

eos_p2p_close_connection(local_user_id, remote_user_id, socket_name)

Argument	Type	Description
local_user_id	String	The Product User ID of the local user who would like to close a previously accepted connection (or decline a pending invite)
remote_user_id	String	The Product User ID of the remote user to disconnect from (or to reject a pending invite from)
socket_name	String	The socket ID of the connection to close (or optionally an empty string to not accept any connection requests from the Remote User)

Returns:

EOS_RESULT

eos_p2p_close_connections

Epic Online Services Function: EOS_P2P_CloseConnections

This function closes any open Connections for a specific Peer Connection ID.

The function returns EOS_RESULT.SUCCESS if the provided data is valid, EOS_RESULT.INVALID_PARAMETERS otherwise.

Syntax:

eos_p2p_close_connections(local_user_id, socket_name)

Argument	Type	Description
local_user_id	String	The Product User ID of the local user who would like to close all connections that use a particular socket ID
socket_name	String	The socket ID of the connections to close

Returns:

EOS_RESULT

eos_p2p_get_nat_type

Epic Online Services Function: EOS_P2P_GetNATType

This function gets the last queried NAT type, if it has been successfully queried with eos_p2p_query_nat_type before.

The function returns the previously queried NAT type if cached data is available, or EOS_NAT_TYPE.UNKNOWN otherwise.

Syntax:

eos_p2p_get_nat_type()

Returns:

EOS_NAT_TYPE

eos_p2p_get_next_received_packet_size

Epic Online Services Function: EOS_P2P_GetNextReceivedPacketSize

This function gets the size of the packet that will be returned by eos_p2p_receive_packet for a particular user, if there are any available packets to be retrieved.

Syntax:

eos_p2p_get_next_received_packet_size(local_user_id, requested_channel)

Argument	Type	Description
local_user_id	String	The Product User ID of the local user who is receiving the packet
requested_channel	Real	The channel to request the data for, a value from 0 to 255 (inclusive). If a negative value is passed, we're retrieving the size of the next packet on any channel.

Returns:

Real

eos_p2p_get_packet_queue_info

Epic Online Services Function: EOS_P2P_GetPacketQueueInfo

This function gets the current cached information related to the incoming and outgoing packet queues. An empty struct is returned if the input was invalid in some way.

Syntax:

eos_p2p_get_packet_queue_info()

Returns:

PacketQueueInfo

eos_p2p_get_port_range

Epic Online Services Function: EOS_P2P_GetPortRange

This function gets the current chosen port and the number of other ports to try above the chosen port if the chosen port is unavailable.

The function returns a struct with two variables: out_port and out_num_additional_ports_to_try. An empty struct is returned if the input was invalid in some way.

Syntax:

eos_p2p_get_port_range()

Returns:

Struct

eos_p2p_get_relay_control

Epic Online Services Function: EOS_P2P_GetRelayControl

This function gets the current relay control setting, or a negative value if the operation failed.

Syntax:

eos_p2p_get_relay_control()

Returns:

EOS_RELAY_CONTROL

eos_p2p_query_nat_type

Epic Online Services Function: EOS_P2P_QueryNATType

This function queries the current NAT-type of the connection. It returns an async ID.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

eos_p2p_query_nat_type()

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	the string `"eos_p2p_query_nat_type"`
status	EOS_RESULT	The result code for the query
status_message	String	Text representation of the status code
identifier	Real	The identifier returned by the call to the function
nat_type	EOS_NAT_TYPE	The queried NAT type

eos_p2p_receive_packet

Epic Online Services Function: EOS_P2P_ReceivePacket

This function receives the next packet for the local user, and information associated with this packet, if it exists.

The function returns the number of bytes written to the buffer if successful.

Syntax:

eos_p2p_receive_packet(buff, local_user_id, max_data_size_bytes, requested_channel)

Argument	Type	Description
buff	Real	The buffer to write the data to
local_user_id	String	The Product User ID of the user who is receiving the packet
max_data_size_bytes	Real	The maximum amount of data in bytes that can be safely copied to the buffer in the function call
requested_channel	Real	An optional channel to request the data for. If a value < 0 is passed, the next packet is retrieved on any channel

Returns:

Real

eos_p2p_remove_notify_incoming_packet_queue_full

Epic Online Services Function: EOS_P2P_RemoveNotifyIncomingPacketQueueFull

This function stops listening for full incoming packet queue events on a previously bound handler.

Syntax:

eos_p2p_remove_notify_incoming_packet_queue_full(notification_id)

Argument	Type	Description
notification_id	Real	The previously bound notification ID

Returns:

N/A

eos_p2p_remove_notify_peer_connection_closed

Epic Online Services Function: EOS_P2P_RemoveNotifyPeerConnectionClosed

This function stops notifications for connections being closed on a previously bound handler.

Syntax:

eos_p2p_remove_notify_peer_connection_closed(notification_id)

Argument	Type	Description
notification_id	Real	The previously bound notification ID

Returns:

N/A

eos_p2p_remove_notify_peer_connection_established

Epic Online Services Function: EOS_P2P_RemoveNotifyPeerConnectionEstablished

This function stops notifications for connections being established on a previously bound handler.

Syntax:

eos_p2p_remove_notify_peer_connection_established(notification_id)

Argument	Type	Description
notification_id	Real	The previously bound notification ID

Returns:

N/A

eos_p2p_remove_notify_peer_connection_interrupted

Epic Online Services Function: EOS_P2P_RemoveNotifyPeerConnectionInterrupted

This function stops notifications for connections being interrupted on a previously bound handler.

Syntax:

eos_p2p_remove_notify_peer_connection_interrupted(notification_id)

Argument	Type	Description
notification_id	Real	The previously bound notification ID

Returns:

N/A

eos_p2p_remove_notify_peer_connection_request

Epic Online Services Function: EOS_P2P_RemoveNotifyPeerConnectionRequest

This function stops listening for connection requests on a previously bound handler.

Syntax:

eos_p2p_remove_notify_peer_connection_request(notification_id)

Argument	Type	Description
notification_id	Real	The previously bound notification ID

Returns:

N/A

eos_p2p_send_packet

Epic Online Services Function: EOS_P2P_SendPacket

This function sends a packet to a peer at the specified address. If there is already an open connection to this peer, it will be sent immediately. If there is no open connection, an attempt to connect to the peer will be made. An EOS_RESULT.SUCCESS result only means the data was accepted to be sent, not that it has been successfully delivered to the peer.

The function returns one of the following:

EOS_RESULT.SUCCESS - If the packet was queued to be sent successfully
EOS_RESULT.INVALID_PARAMETERS - If the input was invalid
EOS_RESULT.LIMIT_EXCEEDED - If the amount of data being sent is too large, or the outgoing packet queue was full
EOS_RESULT.NO_CONNECTION - If disable_auto_accept_connection was set to true and the connection was not currently accepted (call eos_p2p_accept_connection first, or set disable_auto_accept_connection to false)

Syntax:

eos_p2p_send_packet(allow_delayed_delivery, disable_auto_accept_connection, channel, local_user_id, reliability, remote_user_id, socket_name)

Argument	Type	Description
allow_delayed_delivery	Boolean	If `false` and we do not already have an established connection to the peer, this data will be dropped
disable_auto_accept_connection	Boolean	If set to `true`, eos_p2p_send_packet will not automatically establish a connection with the `remote_user_id` and will require explicit calls to eos_p2p_accept_connection first whenever the connection is closed. If set to `false`, eos_p2p_send_packet will automatically accept and start the connection any time it is called and the connection is not already open.
channel	Real	The channel associated with this data
local_user_id	String	The Product User ID of the local user who is sending this packet
reliability	EOS_PACKET_RELIABILITY	Sets the reliability of the delivery of this packet.
remote_user_id	String	The Product User ID of the Peer you would like to send a packet to
socket_name	String	The socket ID for data you are sending in this packet

Returns:

EOS_RESULT

eos_p2p_set_packet_queue_size

Epic Online Services Function: EOS_P2P_SetPacketQueueSize

This function sets the maximum packet queue sizes that packets waiting to be sent or received can use. If the packet queue size is made smaller than the current queue size while there are packets in the queue that would push this packet size over, existing packets are kept but new packets may not be added to the full queue until enough packets are sent or received.

The function returns EOS_RESULT.SUCCESS if the input options were valid, or EOS_RESULT.INVALID_PARAMETERS if the input was invalid in some way.

Syntax:

eos_p2p_set_packet_queue_size(incoming_packet_queue_max_size_bytes, outgoing_packet_queue_max_size_bytes)

Argument	Type	Description
incoming_packet_queue_max_size_bytes	Real	The ideal maximum amount of bytes the incoming packet queue can consume
outgoing_packet_queue_max_size_bytes	Real	The ideal maximum amount of bytes the outgoing packet queue can consume

Returns:

EOS_RESULT

eos_p2p_set_port_range

Epic Online Services Function: EOS_P2P_SetPortRange

This function sets configuration options related to network ports.

It returns one of the following:

EOS_RESULT.SUCCESS - if the options were set successfully
EOS_RESULT.INVALID_PARAMETERS - if the options are invalid in some way

Syntax:

eos_p2p_set_port_range(port, max_additional_ports_to_try)

Argument	Type	Description
port	Real	The ideal port to use for P2P traffic. The default value is 7777. If set to 0, the OS will choose a port. If set to 0, `max_additional_ports_to_try` must be set to 0.
max_additional_ports_to_try	Real	The maximum amount of additional ports to try if `port` is unavailable. Ports will be tried from `port` to `port + max_additional_ports_to_try` inclusive, until one is available or we run out of ports. If no ports are available, P2P connections will fail. The default value is 99.

Returns:

EOS_RESULT

eos_p2p_set_relay_control

Epic Online Services Function: EOS_P2P_SetRelayControl

This function sets how relay servers are to be used. This setting does not immediately apply to existing connections, but may apply to existing connections if the connection requires renegotiation.

The function returns one of the following:

EOS_RESULT.SUCCESS - if the options were set successfully
EOS_RESULT.INVALID_PARAMETERS - if the options are invalid in some way

Syntax:

eos_p2p_set_relay_control(relay_control)

Argument	Type	Description
relay_control	EOS_RELAY_CONTROL	The requested level of relay servers for P2P connections. This setting is only applied to new P2P connections, or when existing P2P connections reconnect during a temporary connectivity outage. Peers with an incompatible setting to the local setting will not be able to connect.

Returns:

EOS_RESULT

EOS_NAT_TYPE

Epic Online Services Enum: EOS_ENATType

This enum holds the possible categories of NAT strictness.