Files
UnrealEngine/Engine/Source/ThirdParty/EOSSDK/SDK/Include/eos_p2p.h
2025-05-18 13:04:45 +08:00

305 lines
18 KiB
C

// Copyright Epic Games, Inc. All Rights Reserved.
#pragma once
#include "eos_p2p_types.h"
/**
* P2P functions to help manage sending and receiving of messages to peers.
*
* These functions will attempt to punch through NATs, but will fallback to using Epic relay servers if a direct connection cannot be established.
*/
/**
* Send 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_Success
* result only means the data was accepted to be sent, not that it has been successfully delivered to the peer.
*
* @param Options Information about the data being sent, by who, to who
* @return EOS_EResult::EOS_Success - If packet was queued to be sent successfully
* EOS_EResult::EOS_InvalidParameters - If input was invalid
* EOS_EResult::EOS_LimitExceeded - If amount of data being sent is too large, or the outgoing packet queue was full
* EOS_EResult::EOS_NoConnection - If bDisableAutoAcceptConnection was set to EOS_TRUE and the connection was not currently accepted (call EOS_P2P_AcceptConnection first, or set bDisableAutoAcceptConnection to EOS_FALSE)
*/
EOS_DECLARE_FUNC(EOS_EResult) EOS_P2P_SendPacket(EOS_HP2P Handle, const EOS_P2P_SendPacketOptions* Options);
/**
* Gets the size of the packet that will be returned by ReceivePacket for a particular user, if there is any available
* packets to be retrieved.
*
* @param Options Information about who is requesting the size of their next packet
* @param OutPacketSizeBytes The amount of bytes required to store the data of the next packet for the requested user
* @return EOS_EResult::EOS_Success - If OutPacketSizeBytes was successfully set and there is data to be received
* EOS_EResult::EOS_InvalidParameters - If input was invalid
* EOS_EResult::EOS_NotFound - If there are no packets available for the requesting user
*/
EOS_DECLARE_FUNC(EOS_EResult) EOS_P2P_GetNextReceivedPacketSize(EOS_HP2P Handle, const EOS_P2P_GetNextReceivedPacketSizeOptions* Options, uint32_t* OutPacketSizeBytes);
/**
* Receive the next packet for the local user, and information associated with this packet, if it exists.
*
* @param Options Information about who is requesting the size of their next packet, and how much data can be stored safely
* @param OutPeerId The Remote User who sent data. Only set if there was a packet to receive.
* @param OutSocketId The Socket ID of the data that was sent. Only set if there was a packet to receive.
* @param OutChannel The channel the data was sent on. Only set if there was a packet to receive.
* @param OutData Buffer to store the data being received. Must be at least EOS_P2P_GetNextReceivedPacketSize in length or data will be truncated
* @param OutBytesWritten The amount of bytes written to OutData. Only set if there was a packet to receive.
* @return EOS_EResult::EOS_Success - If the packet was received successfully
* EOS_EResult::EOS_InvalidParameters - If input was invalid
* EOS_EResult::EOS_NotFound - If there are no packets available for the requesting user
*
* @see EOS_P2P_GetNextReceivedPacketSize
*/
EOS_DECLARE_FUNC(EOS_EResult) EOS_P2P_ReceivePacket(EOS_HP2P Handle, const EOS_P2P_ReceivePacketOptions* Options, EOS_ProductUserId* OutPeerId, EOS_P2P_SocketId* OutSocketId, uint8_t* OutChannel, void* OutData, uint32_t* OutBytesWritten);
/**
* Listen for incoming connection requests on a particular Socket ID, or optionally all Socket IDs. The bound function
* 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.
*
* @param Options Information about who would like notifications, and (optionally) only for a specific socket
* @param ClientData This value is returned to the caller when ConnectionRequestHandler is invoked
* @param ConnectionRequestHandler The callback to be fired when we receive a connection request
* @return A valid notification ID if successfully bound, or EOS_INVALID_NOTIFICATIONID otherwise
*
* @see EOS_P2P_RemoveNotifyPeerConnectionRequest
*/
EOS_DECLARE_FUNC(EOS_NotificationId) EOS_P2P_AddNotifyPeerConnectionRequest(EOS_HP2P Handle, const EOS_P2P_AddNotifyPeerConnectionRequestOptions* Options, void* ClientData, EOS_P2P_OnIncomingConnectionRequestCallback ConnectionRequestHandler);
/**
* Stop listening for connection requests on a previously bound handler.
*
* @param NotificationId The previously bound notification ID
*
* @see EOS_P2P_AddNotifyPeerConnectionRequest
*/
EOS_DECLARE_FUNC(void) EOS_P2P_RemoveNotifyPeerConnectionRequest(EOS_HP2P Handle, EOS_NotificationId NotificationId);
/**
* Listen 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_CET_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.
*
* @param Options Information about who would like notifications about established connections, and for which socket
* @param ClientData This value is returned to the caller when ConnectionEstablishedHandler is invoked
* @param ConnectionEstablishedHandler The callback to be fired when a connection has been established
* @return A valid notification ID if successfully bound, or EOS_INVALID_NOTIFICATIONID otherwise
*
* @see EOS_P2P_AddNotifyPeerConnectionInterrupted
* @see EOS_P2P_AddNotifyPeerConnectionClosed
* @see EOS_P2P_RemoveNotifyPeerConnectionEstablished
*/
EOS_DECLARE_FUNC(EOS_NotificationId) EOS_P2P_AddNotifyPeerConnectionEstablished(EOS_HP2P Handle, const EOS_P2P_AddNotifyPeerConnectionEstablishedOptions* Options, void* ClientData, EOS_P2P_OnPeerConnectionEstablishedCallback ConnectionEstablishedHandler);
/**
* Stop notifications for connections being established on a previously bound handler.
*
* @param NotificationId The previously bound notification ID
*
* @see EOS_P2P_AddNotifyPeerConnectionEstablished
*/
EOS_DECLARE_FUNC(void) EOS_P2P_RemoveNotifyPeerConnectionEstablished(EOS_HP2P Handle, EOS_NotificationId NotificationId);
/**
* Listen 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_CET_Reconnection connection type.
* If a connection fails to reconnect, it will trigger the P2P PeerConnectionClosed notification.
*
* @param Options Information about who would like notifications about interrupted connections, and for which socket
* @param ClientData This value is returned to the caller when ConnectionInterruptedHandler is invoked
* @param ConnectionInterruptedHandler The callback to be fired when an open connection has been interrupted
* @return A valid notification ID if successfully bound, or EOS_INVALID_NOTIFICATIONID otherwise
*
* @see EOS_P2P_AddNotifyPeerConnectionEstablished
* @see EOS_P2P_AddNotifyPeerConnectionClosed
* @see EOS_P2P_RemoveNotifyPeerConnectionInterrupted
*/
EOS_DECLARE_FUNC(EOS_NotificationId) EOS_P2P_AddNotifyPeerConnectionInterrupted(EOS_HP2P Handle, const EOS_P2P_AddNotifyPeerConnectionInterruptedOptions* Options, void* ClientData, EOS_P2P_OnPeerConnectionInterruptedCallback ConnectionInterruptedHandler);
/**
* Stop notifications for connections being interrupted on a previously bound handler.
*
* @param NotificationId The previously bound notification ID
*
* @see EOS_P2P_AddNotifyPeerConnectionInterrupted
*/
EOS_DECLARE_FUNC(void) EOS_P2P_RemoveNotifyPeerConnectionInterrupted(EOS_HP2P Handle, EOS_NotificationId NotificationId);
/**
* Listen for when a previously accepted connection that was either open or pending is closed.
*
* @param Options Information about who would like notifications about closed connections, and for which socket
* @param ClientData This value is returned to the caller when ConnectionClosedHandler is invoked
* @param ConnectionClosedHandler The callback to be fired when an open connection has been closed
* @return A valid notification ID if successfully bound, or EOS_INVALID_NOTIFICATIONID otherwise
*
* @see EOS_P2P_AddNotifyPeerConnectionEstablished
* @see EOS_P2P_AddNotifyPeerConnectionInterrupted
* @see EOS_P2P_RemoveNotifyPeerConnectionClosed
*/
EOS_DECLARE_FUNC(EOS_NotificationId) EOS_P2P_AddNotifyPeerConnectionClosed(EOS_HP2P Handle, const EOS_P2P_AddNotifyPeerConnectionClosedOptions* Options, void* ClientData, EOS_P2P_OnRemoteConnectionClosedCallback ConnectionClosedHandler);
/**
* Stop notifications for connections being closed on a previously bound handler.
*
* @param NotificationId The previously bound notification ID
*
* @see EOS_P2P_AddNotifyPeerConnectionClosed
*/
EOS_DECLARE_FUNC(void) EOS_P2P_RemoveNotifyPeerConnectionClosed(EOS_HP2P Handle, EOS_NotificationId NotificationId);
/**
* Accept or Request a connection with a specific peer on a specific Socket ID.
*
* If this connection was not already locally accepted, we 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_EResult::EOS_Success will still be returned if the input was valid.
*
* @param Options Information about who would like to accept a connection, and which connection
* @return EOS_EResult::EOS_Success - if the provided data is valid
* EOS_EResult::EOS_InvalidParameters - if the provided data is invalid
*/
EOS_DECLARE_FUNC(EOS_EResult) EOS_P2P_AcceptConnection(EOS_HP2P Handle, const EOS_P2P_AcceptConnectionOptions* Options);
/**
* 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_AcceptConnection
* with the new Socket ID first before calling EOS_P2P_CloseConnection, to prevent the shared physical socket from being torn down prematurely.
*
* @param Options Information about who would like to close a connection, and which connection.
* @return EOS_EResult::EOS_Success - if the provided data is valid
* EOS_EResult::EOS_InvalidParameters - if the provided data is invalid
*/
EOS_DECLARE_FUNC(EOS_EResult) EOS_P2P_CloseConnection(EOS_HP2P Handle, const EOS_P2P_CloseConnectionOptions* Options);
/**
* Close any open Connections for a specific Peer Connection ID.
*
* @param Options Information about who would like to close connections, and by what socket ID
* @return EOS_EResult::EOS_Success - if the provided data is valid
* EOS_EResult::EOS_InvalidParameters - if the provided data is invalid
*/
EOS_DECLARE_FUNC(EOS_EResult) EOS_P2P_CloseConnections(EOS_HP2P Handle, const EOS_P2P_CloseConnectionsOptions* Options);
/**
* Query the current NAT-type of our connection.
*
* @param Options Information about what version of the EOS_P2P_QueryNATType API is supported
* @param ClientData arbitrary data that is passed back to you in the CompletionDelegate
* @param CompletionDelegate The callback to be fired when we finish querying our NAT type
*/
EOS_DECLARE_FUNC(void) EOS_P2P_QueryNATType(EOS_HP2P Handle, const EOS_P2P_QueryNATTypeOptions* Options, void* ClientData, const EOS_P2P_OnQueryNATTypeCompleteCallback CompletionDelegate);
/**
* Get our last-queried NAT-type, if it has been successfully queried.
*
* @param Options Information about what version of the EOS_P2P_GetNATType API is supported
* @param OutNATType The queried NAT Type, or unknown if unknown
* @return EOS_EResult::EOS_Success - if we have cached data
* EOS_EResult::EOS_NotFound - If we do not have queried data cached
*/
EOS_DECLARE_FUNC(EOS_EResult) EOS_P2P_GetNATType(EOS_HP2P Handle, const EOS_P2P_GetNATTypeOptions* Options, EOS_ENATType* OutNATType);
/**
* Set 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.
*
* @param Options Information about relay server config options
* @return EOS_EResult::EOS_Success - if the options were set successfully
* EOS_EResult::EOS_InvalidParameters - if the options are invalid in some way
*
* @see EOS_ERelayControl
*/
EOS_DECLARE_FUNC(EOS_EResult) EOS_P2P_SetRelayControl(EOS_HP2P Handle, const EOS_P2P_SetRelayControlOptions* Options);
/**
* Get the current relay control setting.
*
* @param Options Information about what version of the EOS_P2P_GetRelayControl API is supported
* @param OutRelayControl The relay control setting currently configured
* @return EOS_EResult::EOS_Success - if the input was valid
* EOS_EResult::EOS_InvalidParameters - if the input was invalid in some way
*/
EOS_DECLARE_FUNC(EOS_EResult) EOS_P2P_GetRelayControl(EOS_HP2P Handle, const EOS_P2P_GetRelayControlOptions* Options, EOS_ERelayControl* OutRelayControl);
/**
* Set configuration options related to network ports.
*
* @param Options Information about network ports config options
* @return EOS_EResult::EOS_Success - if the options were set successfully
* EOS_EResult::EOS_InvalidParameters - if the options are invalid in some way
*/
EOS_DECLARE_FUNC(EOS_EResult) EOS_P2P_SetPortRange(EOS_HP2P Handle, const EOS_P2P_SetPortRangeOptions* Options);
/**
* Get the current chosen port and the amount of other ports to try above the chosen port if the chosen port is unavailable.
*
* @param Options Information about what version of the EOS_P2P_GetPortRange API is supported
* @param OutPort The port that will be tried first
* @param OutNumAdditionalPortsToTry The amount of ports to try above the value in OutPort, if OutPort is unavailable
* @return EOS_EResult::EOS_Success - if the input options were valid
* EOS_EResult::EOS_InvalidParameters - if the input was invalid in some way
*/
EOS_DECLARE_FUNC(EOS_EResult) EOS_P2P_GetPortRange(EOS_HP2P Handle, const EOS_P2P_GetPortRangeOptions* Options, uint16_t* OutPort, uint16_t* OutNumAdditionalPortsToTry);
/**
* 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.
*
* @param Options Information about packet queue size
* @return EOS_EResult::EOS_Success - if the input options were valid
* EOS_EResult::EOS_InvalidParameters - if the input was invalid in some way
*/
EOS_DECLARE_FUNC(EOS_EResult) EOS_P2P_SetPacketQueueSize(EOS_HP2P Handle, const EOS_P2P_SetPacketQueueSizeOptions* Options);
/**
* Gets the current cached information related to the incoming and outgoing packet queues.
*
* @param Options Information about what version of the EOS_P2P_GetPacketQueueInfo API is supported
* @param OutPacketQueueInfo The current information of the incoming and outgoing packet queues
* @return EOS_EResult::EOS_Success - if the input options were valid
* EOS_EResult::EOS_InvalidParameters - if the input was invalid in some way
*/
EOS_DECLARE_FUNC(EOS_EResult) EOS_P2P_GetPacketQueueInfo(EOS_HP2P Handle, const EOS_P2P_GetPacketQueueInfoOptions* Options, EOS_P2P_PacketQueueInfo* OutPacketQueueInfo);
/**
* Listen for when our 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_ReceivePacket
* or the packet queue size is not increased by EOS_P2P_SetPacketQueueSize, any packets that are received after
* this event are discarded until there is room again in the queue.
*
* @param Options Information about what version of the EOS_P2P_AddNotifyIncomingPacketQueueFull API is supported
* @param ClientData Arbitrary data that is passed back to you in the CompletionDelegate
* @param IncomingPacketQueueFullHandler The callback to be fired when the incoming packet queue is full
* @return A valid notification ID if successfully bound, or EOS_INVALID_NOTIFICATIONID otherwise
*/
EOS_DECLARE_FUNC(EOS_NotificationId) EOS_P2P_AddNotifyIncomingPacketQueueFull(EOS_HP2P Handle, const EOS_P2P_AddNotifyIncomingPacketQueueFullOptions* Options, void* ClientData, EOS_P2P_OnIncomingPacketQueueFullCallback IncomingPacketQueueFullHandler);
/**
* Stop listening for full incoming packet queue events on a previously bound handler.
*
* @param NotificationId The previously bound notification ID
*/
EOS_DECLARE_FUNC(void) EOS_P2P_RemoveNotifyIncomingPacketQueueFull(EOS_HP2P Handle, EOS_NotificationId NotificationId);
/**
* Clear queued incoming and outgoing packets.
*
* @param Options Information about which queues should be cleared
* @return EOS_EResult::EOS_Success - if the input options were valid (even if queues were empty and no packets where cleared)
* EOS_EResult::EOS_IncompatibleVersion - if wrong API version
* EOS_EResult::EOS_InvalidUser - if an invalid/remote user was used
* EOS_EResult::EOS_InvalidParameters - if input was invalid in other way
*/
EOS_DECLARE_FUNC(EOS_EResult) EOS_P2P_ClearPacketQueue(EOS_HP2P Handle, const EOS_P2P_ClearPacketQueueOptions* Options);