|
|
//====== Copyright Valve Corporation, All rights reserved. ====================
//
// Purpose: misc networking utilities
//
//=============================================================================
#ifndef ISTEAMNETWORKINGUTILS
#define ISTEAMNETWORKINGUTILS
#ifdef _WIN32
#pragma once
#endif
#include "steamnetworkingtypes.h"
struct SteamDatagramRelayAuthTicket;
//-----------------------------------------------------------------------------
/// Misc networking utilities for checking the local networking environment
/// and estimating pings.
class ISteamNetworkingUtils{public:
/// Fetch current timestamp. These values never go backwards, and
/// the initial value is low enough that practically speaking it's
/// not necessary to worry about the value wrapping around.
virtual SteamNetworkingMicroseconds GetLocalTimestamp() = 0;
/// Check if the ping data of sufficient recency is available, and if
/// it's too old, start refreshing it.
///
/// Games that use the ping location information will typically
/// want to call this at boot time, to make sure all prerequisites
/// are ready. Especially since the first measurement might take
/// slightly longer than subsequent measurements.
///
/// Returns true if sufficiently recent data is already available.
///
/// Returns false if sufficiently recent data is not available. In this
/// case, ping measurement is initiated, if it is not already active.
/// (You cannot restart a measurement already in progress.)
///
/// A FIXME event will be posted when measurement is completed.
virtual bool CheckPingDataUpToDate( float flMaxAgeSeconds ) = 0;
/// Return location info for the current host. Returns the approximate
/// age of the data, in seconds, or -1 if no data is available.
/// Note that this might return an age older than the age of your game's
/// process, if the data was obtained before you game started.
///
/// This always return the most up-to-date information we have available
/// right now, even if we are in the middle of re-calculating ping times.
virtual float GetLocalPingLocation( SteamNetworkPingLocation_t &result ) = 0;
/// Return true if we are taking ping measurements to update our ping
/// location or select optimal routing. Ping measurement typically takes
/// a few seconds, perhaps up to 10 seconds.
virtual bool IsPingMeasurementInProgress() = 0;
/// Estimate the round-trip latency between two arbitrary locations, in
/// milliseconds. This is a conservative estimate, based on routing through
/// the relay network. For most basic connections based on SteamID,
/// this ping time will be pretty accurate, since it will be based on the
/// route likely to be actually used.
///
/// If a direct IP route is used (perhaps via NAT traversal), then the route
/// will be different, and the ping time might be better. Or it might actually
/// be a bit worse! Standard IP routing is frequently suboptimal!
///
/// but even in this case, the estimate obtained using this method is a
/// reasonable upper bound on the ping time. (Also it has the advantage
/// of returning immediately and not sending any packets.)
///
/// In a few cases we might not able to estimate the route. In this case
/// a negative value is returned. k_nSteamNetworkingPing_Failed means
/// the reason was because of some networking difficulty. (Failure to
/// ping, etc) k_nSteamNetworkingPing_Unknown is returned if we cannot
/// currently answer the question for some other reason.
virtual int EstimatePingTimeBetweenTwoLocations( const SteamNetworkPingLocation_t &location1, const SteamNetworkPingLocation_t &location2 ) = 0;
/// Same as EstimatePingTime, but assumes that one location is the local host.
/// This is a bit faster, especially if you need to calculate a bunch of
/// these in a loop to find the fastest one.
///
/// In rare cases this might return a slightly different estimate than combining
/// GetLocalPingLocation with EstimatePingTimeBetweenTwoLocations. That's because
/// this function uses a slightly more complete description
virtual int EstimatePingTimeFromLocalHost( const SteamNetworkPingLocation_t &remoteLocation ) = 0;
// FIXME:
//
// Check current internet connection status
//
// Low level ticket stuff. I need to get some advice and talk through how this should work
// or how best to tuck it away and make it transparent.
//
virtual bool ReceivedTicket( const void *pvTicket, int cbTicket, SteamDatagramRelayAuthTicket *pOutParsedTicket ) = 0; virtual bool HasTicketForServer( CSteamID steamID ) = 0; virtual uint32 GetIPForServerSteamIDFromTicket( CSteamID steamID ) = 0;
//
// Low level network config stuff I haven't figure out how best to tuck away.
// Dota and CSGO use it because we have gameservers in the datacenter, and
// we need this information to do region selection. But most games won't
// need it.
//
/// Fetch directly measured ping time from local host to a particular network PoP.
/// Most games will not need to call this.
virtual int GetPingToDataCenter( SteamNetworkingPOPID popID, SteamNetworkingPOPID *pViaRelayPoP ) = 0; virtual int GetDirectPingToPOP( SteamNetworkingPOPID popID ) = 0;
/// Get number of network PoPs in the config
virtual int GetPOPCount() = 0;
/// Get list of all POP IDs
virtual int GetPOPList( SteamNetworkingPOPID *list, int nListSz ) = 0;};#define STEAMNETWORKINGUTILS_VERSION "SteamNetworkingUtils001"
/// Get ISteamNetworkingUtils object. This will eventually go in Steam_api.h with all the rest of its kin
STEAMDATAGRAMLIB_INTERFACE ISteamNetworkingUtils *SteamNetworkingUtils();
#endif // ISTEAMNETWORKINGUTILS
|
