host.anzo.eossdk.eos.sdk

Class EOS_P2P_Interface

java.lang.Object

com.sun.jna.PointerType

host.anzo.eossdk.eos.sdk.EOS_P2P_Interface

All Implemented Interfaces:

com.sun.jna.NativeMapped

public class EOS_P2P_Interface
extends com.sun.jna.PointerType

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.

Since:

8/21/2023

Constructor Summary

Constructors

Constructor and Description
EOS_P2P_Interface()
EOS_P2P_Interface(com.sun.jna.Pointer address)

Method Summary

Modifier and Type	Method and Description
EOS_EResult	acceptConnection(EOS_P2P_AcceptConnectionOptions options) Accept or Request a connection with a specific peer on a specific Socket ID.
EOS_NotificationId	addNotifyIncomingPacketQueueFull(EOS_P2P_AddNotifyIncomingPacketQueueFullOptions options, com.sun.jna.Pointer clientData, EOS_P2P_OnIncomingPacketQueueFullCallback incomingPacketQueueFullHandler) Listen for when our packet queue has become full.
EOS_NotificationId	addNotifyPeerConnectionClosed(EOS_P2P_AddNotifyPeerConnectionClosedOptions options, com.sun.jna.Pointer clientData, EOS_P2P_OnRemoteConnectionClosedCallback connectionClosedHandler) Listen for when a previously accepted connection that was either open or pending is closed.
EOS_NotificationId	addNotifyPeerConnectionEstablished(EOS_P2P_AddNotifyPeerConnectionEstablishedOptions options, com.sun.jna.Pointer clientData, EOS_P2P_OnPeerConnectionEstablishedCallback connectionEstablishedHandler) Listen for when a connection is established.
EOS_NotificationId	addNotifyPeerConnectionInterrupted(EOS_P2P_AddNotifyPeerConnectionInterruptedOptions options, com.sun.jna.Pointer clientData, EOS_P2P_OnPeerConnectionInterruptedCallback connectionInterruptedHandler) Listen for when a previously opened connection is interrupted.
EOS_NotificationId	addNotifyPeerConnectionRequest(EOS_P2P_AddNotifyPeerConnectionRequestOptions options, com.sun.jna.Pointer clientData, EOS_P2P_OnIncomingConnectionRequestCallback connectionRequestHandler) Listen for incoming connection requests on a particular Socket ID, or optionally all Socket IDs.
EOS_EResult	clearPacketQueue(EOS_P2P_ClearPacketQueueOptions options) Clear queued incoming and outgoing packets.
EOS_EResult	closeConnection(EOS_P2P_CloseConnectionOptions 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.
EOS_EResult	closeConnections(EOS_P2P_CloseConnectionsOptions options) Close any open Connections for a specific Peer Connection ID.
EOS_ENATType	getNATType(EOS_P2P_GetNATTypeOptions options) Get our last-queried NAT-type, if it has been successfully queried.
EOS_EResult	getNextReceivedPacketSize(EOS_P2P_GetNextReceivedPacketSizeOptions options, java.nio.IntBuffer outPacketSizeBytes) 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.
EOS_P2P_PacketQueueInfo	getPacketQueueInfo(EOS_P2P_GetPacketQueueInfoOptions options) Gets the current cached information related to the incoming and outgoing packet queues.
EOS_EResult	getPortRange(EOS_P2P_GetPortRangeOptions options, com.sun.jna.ptr.ShortByReference outPort, com.sun.jna.ptr.ShortByReference outNumAdditionalPortsToTry) Get the current chosen port and the amount of other ports to try above the chosen port if the chosen port is unavailable.
EOS_EResult	getRelayControl(EOS_P2P_GetRelayControlOptions options, java.nio.IntBuffer outRelayControl) Get the current relay control setting.
void	queryNATType(EOS_P2P_QueryNATTypeOptions options, com.sun.jna.Pointer clientData, EOS_P2P_OnQueryNATTypeCompleteCallback completionDelegate) Query the current NAT-type of our connection.
EOS_EResult	receivePacket(EOS_P2P_ReceivePacketOptions options, EOS_ProductUserId outPeerId, EOS_P2P_SocketId outSocketId, java.nio.ByteBuffer outChannel, com.sun.jna.Pointer outData, java.nio.IntBuffer outBytesWritten) Receive the next packet for the local user, and information associated with this packet, if it exists.
void	removeNotifyIncomingPacketQueueFull(EOS_NotificationId notificationId) Stop listening for full incoming packet queue events on a previously bound handler.
void	removeNotifyPeerConnectionClosed(EOS_NotificationId notificationId) Stop notifications for connections being closed on a previously bound handler.
void	removeNotifyPeerConnectionEstablished(EOS_NotificationId notificationId) Stop notifications for connections being established on a previously bound handler.
void	removeNotifyPeerConnectionInterrupted(EOS_NotificationId notificationId) Stop notifications for connections being interrupted on a previously bound handler.
void	removeNotifyPeerConnectionRequest(EOS_NotificationId notificationId) Stop listening for connection requests on a previously bound handler.
EOS_EResult	sendPacket(EOS_P2P_SendPacketOptions options) Send a packet to a peer at the specified address.
EOS_EResult	setPacketQueueSize(EOS_P2P_SetPacketQueueSizeOptions options) Sets the maximum packet queue sizes that packets waiting to be sent or received can use.
EOS_EResult	setPortRange(EOS_P2P_SetPortRangeOptions options) Set configuration options related to network ports.
EOS_EResult	setRelayControl(EOS_P2P_SetRelayControlOptions options) Set how relay servers are to be used.

Methods inherited from class com.sun.jna.PointerType

equals, fromNative, getPointer, hashCode, nativeType, setPointer, toNative, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

EOS_P2P_Interface

public EOS_P2P_Interface(com.sun.jna.Pointer address)

EOS_P2P_Interface

public EOS_P2P_Interface()

Method Detail

sendPacket

public EOS_EResult sendPacket(EOS_P2P_SendPacketOptions options)

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.

Parameters:

options - Information about the data being sent, by who, to who

Returns:

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)

getNextReceivedPacketSize

public EOS_EResult getNextReceivedPacketSize(EOS_P2P_GetNextReceivedPacketSizeOptions options,
                                             java.nio.IntBuffer outPacketSizeBytes)

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.

Parameters:

options - Information about who is requesting the size of their next packet

outPacketSizeBytes - The amount of bytes required to store the data of the next packet for the requested user

Returns:

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

receivePacket

public EOS_EResult receivePacket(EOS_P2P_ReceivePacketOptions options,
                                 EOS_ProductUserId outPeerId,
                                 EOS_P2P_SocketId outSocketId,
                                 java.nio.ByteBuffer outChannel,
                                 com.sun.jna.Pointer outData,
                                 java.nio.IntBuffer outBytesWritten)

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

Parameters:

options - Information about who is requesting the size of their next packet, and how much data can be stored safely

outPeerId - The Remote User who sent data. Only set if there was a packet to receive.

outSocketId - The Socket ID of the data that was sent. Only set if there was a packet to receive.

outChannel - The channel the data was sent on. Only set if there was a packet to receive.

outData - Buffer to store the data being received. Must be at least EOS_P2P_GetNextReceivedPacketSize in length or data will be truncated

outBytesWritten - The amount of bytes written to OutData. Only set if there was a packet to receive.

Returns:

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 Also:

getNextReceivedPacketSize(EOS_P2P_GetNextReceivedPacketSizeOptions, IntBuffer)

addNotifyPeerConnectionRequest

public EOS_NotificationId addNotifyPeerConnectionRequest(EOS_P2P_AddNotifyPeerConnectionRequestOptions options,
                                                         com.sun.jna.Pointer clientData,
                                                         EOS_P2P_OnIncomingConnectionRequestCallback connectionRequestHandler)

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.

Parameters:

options - Information about who would like notifications, and (optionally) only for a specific socket

clientData - This value is returned to the caller when ConnectionRequestHandler is invoked

connectionRequestHandler - The callback to be fired when we receive a connection request

Returns:

A valid notification ID if successfully bound, or EOS_NotificationId.EOS_INVALID_NOTIFICATIONID otherwise

See Also:

removeNotifyPeerConnectionRequest(EOS_NotificationId)

removeNotifyPeerConnectionRequest

public void removeNotifyPeerConnectionRequest(EOS_NotificationId notificationId)

Stop listening for connection requests on a previously bound handler.

Parameters:

notificationId - The previously bound notification ID

See Also:

addNotifyPeerConnectionRequest(EOS_P2P_AddNotifyPeerConnectionRequestOptions, Pointer, EOS_P2P_OnIncomingConnectionRequestCallback)

addNotifyPeerConnectionEstablished

public EOS_NotificationId addNotifyPeerConnectionEstablished(EOS_P2P_AddNotifyPeerConnectionEstablishedOptions options,
                                                             com.sun.jna.Pointer clientData,
                                                             EOS_P2P_OnPeerConnectionEstablishedCallback connectionEstablishedHandler)

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.

Parameters:

options - Information about who would like notifications about established connections, and for which socket

clientData - This value is returned to the caller when ConnectionEstablishedHandler is invoked

connectionEstablishedHandler - The callback to be fired when a connection has been established

Returns:

A valid notification ID if successfully bound, or EOS_NotificationId.EOS_INVALID_NOTIFICATIONID otherwise

See Also:

addNotifyPeerConnectionInterrupted(EOS_P2P_AddNotifyPeerConnectionInterruptedOptions, Pointer, EOS_P2P_OnPeerConnectionInterruptedCallback), addNotifyPeerConnectionClosed(EOS_P2P_AddNotifyPeerConnectionClosedOptions, Pointer, EOS_P2P_OnRemoteConnectionClosedCallback), removeNotifyPeerConnectionEstablished(EOS_NotificationId)

removeNotifyPeerConnectionEstablished

public void removeNotifyPeerConnectionEstablished(EOS_NotificationId notificationId)

Stop notifications for connections being established on a previously bound handler.

Parameters:

notificationId - The previously bound notification ID

See Also:

addNotifyPeerConnectionEstablished(EOS_P2P_AddNotifyPeerConnectionEstablishedOptions, Pointer, EOS_P2P_OnPeerConnectionEstablishedCallback)

addNotifyPeerConnectionInterrupted

public EOS_NotificationId addNotifyPeerConnectionInterrupted(EOS_P2P_AddNotifyPeerConnectionInterruptedOptions options,
                                                             com.sun.jna.Pointer clientData,
                                                             EOS_P2P_OnPeerConnectionInterruptedCallback connectionInterruptedHandler)

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.

Parameters:

options - Information about who would like notifications about interrupted connections, and for which socket

clientData - This value is returned to the caller when ConnectionInterruptedHandler is invoked

connectionInterruptedHandler - The callback to be fired when an open connection has been interrupted

Returns:

A valid notification ID if successfully bound, or EOS_NotificationId.EOS_INVALID_NOTIFICATIONID otherwise

See Also:

addNotifyPeerConnectionEstablished(EOS_P2P_AddNotifyPeerConnectionEstablishedOptions, Pointer, EOS_P2P_OnPeerConnectionEstablishedCallback), addNotifyPeerConnectionClosed(EOS_P2P_AddNotifyPeerConnectionClosedOptions, Pointer, EOS_P2P_OnRemoteConnectionClosedCallback), removeNotifyPeerConnectionInterrupted(EOS_NotificationId)

removeNotifyPeerConnectionInterrupted

public void removeNotifyPeerConnectionInterrupted(EOS_NotificationId notificationId)

Stop notifications for connections being interrupted on a previously bound handler.

Parameters:

notificationId - The previously bound notification ID

See Also:

addNotifyPeerConnectionInterrupted(EOS_P2P_AddNotifyPeerConnectionInterruptedOptions, Pointer, EOS_P2P_OnPeerConnectionInterruptedCallback)

addNotifyPeerConnectionClosed

public EOS_NotificationId addNotifyPeerConnectionClosed(EOS_P2P_AddNotifyPeerConnectionClosedOptions options,
                                                        com.sun.jna.Pointer clientData,
                                                        EOS_P2P_OnRemoteConnectionClosedCallback connectionClosedHandler)

Listen for when a previously accepted connection that was either open or pending is closed.

Parameters:

options - Information about who would like notifications about closed connections, and for which socket

clientData - This value is returned to the caller when ConnectionClosedHandler is invoked

connectionClosedHandler - The callback to be fired when an open connection has been closed

Returns:

A valid notification ID if successfully bound, or EOS_NotificationId.EOS_INVALID_NOTIFICATIONID otherwise

See Also:

addNotifyPeerConnectionEstablished(EOS_P2P_AddNotifyPeerConnectionEstablishedOptions, Pointer, EOS_P2P_OnPeerConnectionEstablishedCallback), addNotifyPeerConnectionInterrupted(EOS_P2P_AddNotifyPeerConnectionInterruptedOptions, Pointer, EOS_P2P_OnPeerConnectionInterruptedCallback), removeNotifyPeerConnectionClosed(EOS_NotificationId)

removeNotifyPeerConnectionClosed

public void removeNotifyPeerConnectionClosed(EOS_NotificationId notificationId)

Stop notifications for connections being closed on a previously bound handler.

Parameters:

notificationId - The previously bound notification ID

See Also:

addNotifyPeerConnectionClosed(EOS_P2P_AddNotifyPeerConnectionClosedOptions, Pointer, EOS_P2P_OnRemoteConnectionClosedCallback)

acceptConnection

public EOS_EResult acceptConnection(EOS_P2P_AcceptConnectionOptions options)

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.

Parameters:

options - Information about who would like to accept a connection, and which connection

Returns:

EOS_EResult.EOS_Success - if the provided data is valid
EOS_EResult.EOS_InvalidParameters - if the provided data is invalid

closeConnection

public EOS_EResult closeConnection(EOS_P2P_CloseConnectionOptions 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.

Parameters:

options - Information about who would like to close a connection, and which connection.

Returns:

EOS_EResult.EOS_Success - if the provided data is valid
EOS_EResult.EOS_InvalidParameters - if the provided data is invalid

closeConnections

public EOS_EResult closeConnections(EOS_P2P_CloseConnectionsOptions options)

Close any open Connections for a specific Peer Connection ID.

Parameters:

options - Information about who would like to close connections, and by what socket ID

Returns:

EOS_EResult.EOS_Success - if the provided data is valid
EOS_EResult.EOS_InvalidParameters - if the provided data is invalid

queryNATType

public void queryNATType(EOS_P2P_QueryNATTypeOptions options,
                         com.sun.jna.Pointer clientData,
                         EOS_P2P_OnQueryNATTypeCompleteCallback completionDelegate)

Query the current NAT-type of our connection.

Parameters:

options - Information about what version of the EOS_P2P_QueryNATType API is supported

clientData - arbitrary data that is passed back to you in the CompletionDelegate

completionDelegate - The callback to be fired when we finish querying our NAT type

getNATType

public EOS_ENATType getNATType(EOS_P2P_GetNATTypeOptions options)
                        throws EOSException

Get our last-queried NAT-type, if it has been successfully queried.

Parameters:

options - Information about what version of the EOS_P2P_GetNATType API is supported

Returns:

The queried NAT Type, or unknown if unknown

Throws:

EOSNotFoundException - If we do not have queried data cached

EOSException

setRelayControl

public EOS_EResult setRelayControl(EOS_P2P_SetRelayControlOptions options)

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.

Parameters:

options - Information about relay server config options

Returns:

EOS_EResult.EOS_Success - if the options were set successfully
EOS_EResult.EOS_InvalidParameters - if the options are invalid in some way

See Also:

EOS_ERelayControl

getRelayControl

public EOS_EResult getRelayControl(EOS_P2P_GetRelayControlOptions options,
                                   java.nio.IntBuffer outRelayControl)

Get the current relay control setting.

Parameters:

options - Information about what version of the EOS_P2P_GetRelayControl API is supported

outRelayControl - The relay control setting currently configured

Returns:

EOS_EResult.EOS_Success - if the input was valid
EOS_EResult.EOS_InvalidParameters - if the input was invalid in some way

setPortRange

public EOS_EResult setPortRange(EOS_P2P_SetPortRangeOptions options)

Set configuration options related to network ports.

Parameters:

options - Information about network ports config options

Returns:

EOS_EResult.EOS_Success - if the options were set successfully EOS_EResult.EOS_InvalidParameters - if the options are invalid in some way

getPortRange

public EOS_EResult getPortRange(EOS_P2P_GetPortRangeOptions options,
                                com.sun.jna.ptr.ShortByReference outPort,
                                com.sun.jna.ptr.ShortByReference outNumAdditionalPortsToTry)

Get the current chosen port and the amount of other ports to try above the chosen port if the chosen port is unavailable.

Parameters:

options - Information about what version of the EOS_P2P_GetPortRange API is supported

outPort - The port that will be tried first

outNumAdditionalPortsToTry - The amount of ports to try above the value in OutPort, if OutPort is unavailable

Returns:

EOS_EResult.EOS_Success - if the input options were valid EOS_EResult.EOS_InvalidParameters - if the input was invalid in some way

setPacketQueueSize

public EOS_EResult setPacketQueueSize(EOS_P2P_SetPacketQueueSizeOptions options)

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.

Parameters:

options - Information about packet queue size

Returns:

EOS_EResult.EOS_Success - if the input options were valid EOS_EResult.EOS_InvalidParameters - if the input was invalid in some way

getPacketQueueInfo

public EOS_P2P_PacketQueueInfo getPacketQueueInfo(EOS_P2P_GetPacketQueueInfoOptions options)
                                           throws EOSException

Gets the current cached information related to the incoming and outgoing packet queues.

Parameters:

options - Information about what version of the EOS_P2P_GetPacketQueueInfo API is supported

Returns:

The current information of the incoming and outgoing packet queues

Throws:

EOSInvalidParametersException - if the input was invalid in some way

EOSException

addNotifyIncomingPacketQueueFull

public EOS_NotificationId addNotifyIncomingPacketQueueFull(EOS_P2P_AddNotifyIncomingPacketQueueFullOptions options,
                                                           com.sun.jna.Pointer clientData,
                                                           EOS_P2P_OnIncomingPacketQueueFullCallback incomingPacketQueueFullHandler)

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.

Parameters:

options - Information about what version of the EOS_P2P_AddNotifyIncomingPacketQueueFull API is supported

clientData - Arbitrary data that is passed back to you in the CompletionDelegate

incomingPacketQueueFullHandler - The callback to be fired when the incoming packet queue is full

Returns:

A valid notification ID if successfully bound, or EOS_NotificationId.EOS_INVALID_NOTIFICATIONID otherwise

removeNotifyIncomingPacketQueueFull

public void removeNotifyIncomingPacketQueueFull(EOS_NotificationId notificationId)

Stop listening for full incoming packet queue events on a previously bound handler.

Parameters:

notificationId - The previously bound notification ID

clearPacketQueue

public EOS_EResult clearPacketQueue(EOS_P2P_ClearPacketQueueOptions options)

Clear queued incoming and outgoing packets.

Parameters:

options - Information about which queues should be cleared

Returns:

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