Steamworks ドキュメンテーション
ISteamNetworkingUtils Interface
Misc networking utilities for checking the local networking environment and estimating pings.

関連するドキュメント:

ISteamNetworkingUtilsのメンバー関数は、グローバルアクセサー関数SteamNetworkingUtils()を介して呼び出されます。

初期化とステータスチェック

InitRelayNetworkAccess

void InitRelayNetworkAccess();
If you know that you are going to be using the relay network (for example, because you anticipate making P2P connections), call this to initialize the relay network. If you do not call this, the initialization will be delayed until the first time you use a feature that requires access to the relay network, which will delay that first access.

You can also call this to force a retry if the previous attempt has failed. Performing any action that requires access to the relay network will also trigger a retry, and so calling this function is never strictly necessary, but it can be useful to call it a program launch time, if access to the relay network is anticipated. Use GetRelayNetworkStatus or listen for SteamRelayNetworkStatus_t callbacks to know when initialization has completed. Typically initialization completes in a few seconds.

Note: dedicated servers hosted in known data centers do *not* need to call this, since they do not make routing decisions. However, if the dedicated server will be using P2P functionality, it will act as a "client" and this should be called.

GetRelayNetworkStatus

ESteamNetworkingAvailability GetRelayNetworkStatus( SteamRelayNetworkStatus_t *pDetails );
リレーネットワークの現在のステータスを取得。

SteamRelayNetworkStatus_tもまたコールバックです。 ステータスが変更されるか、Ping測定が開始または終了する度に、ユーザーとゲームサーバーインターフェイスの両方でトリガーされます。

SteamRelayNetworkStatus_t::m_eAvailが戻されます。 更なる詳細が欲しい場合にはnon-NULL値を渡します。

Pingロケーション関数


世界中に配置されたValveリレーへのPing時間を使用して、インターネットホストの位置を表す「marker」を作成します。 そのような2つのマーカーがあれば、パケットを送信せずに、2つのホスト間のネットワーク遅延の見積もりができます。 見積もりは、Valveネットワークを介して検出された最適なルートに基いています。 Valveネットワークを使用してトラフィックを伝送するのであれば、これはまさに必要なpingです。 それ以外の場合、ping時間はおそらく妥当な見積もりです。

マッチメイキングのためにオプションでピアーを選択する場合に非常に便利です。

マーカーは文字列に変換できるので、送信可能です。 これらのオブジェクトを操作するためにバックエンドで使用できる個別のライブラリがあります。 (参照: steamdatagramrelay)

GetLocalPingLocation

float GetLocalPingLocation( SteamNetworkPingLocation_t &result );

現在のホストに位置情報を戻します。 おおよそのデータの経過時間を秒単位で返します。データがない場合-1を返します。

リレーネットワークへのアクセスの初期化には数秒かかります。 InitializeRelayNetworkAccessを呼び出してからすぐにこれを呼び出すと、まだデータが利用可能ではない場合があります。

これにより、ping時間の再計算の途中であっても、入手可能な最も最新の情報が返されます。

EstimatePingTimeBetweenTwoLocations

int EstimatePingTimeBetweenTwoLocations( const SteamNetworkPingLocation_t &location1, const SteamNetworkPingLocation_t &location2 );

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 relayed connections, 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.

Do you need to be able to do this from a backend/matchmaking server? You are looking for the "game coordinator" library. See steamdatagramrelay for more info on how to obtain the game coordinator SDK.

EstimatePingTimeFromLocalHost

int EstimatePingTimeFromLocalHost( const SteamNetworkPingLocation_t &remoteLocation );
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 set of information about what route would be taken.

ConvertPingLocationToString

void ConvertPingLocationToString( const SteamNetworkPingLocation_t &location, char *pszBuf, int cchBufSize );
Convert a ping location into a text format suitable for sending over the wire. The format is a compact and human readable. However, it is subject to change so please do not parse it yourself. Your buffer must be at least k_cchMaxSteamNetworkingPingLocationString bytes.

ParsePingLocationString

bool ParsePingLocationString( const char *pszString, SteamNetworkPingLocation_t &result );
Parse back SteamNetworkPingLocation_t string. Returns false if we couldn't understand the string.

Ping計測ステータス関数


Using the relay network requires latency measurements be taken. Aside from calling InitializeRelayNetworkAccess when your application boots (if you know you will need access to the relay network to send traffic or just estimate pings), the latency gathering process will happen automatically. These functions allow a bit more control over the process.

CheckPingDataUpToDate

bool CheckPingDataUpToDate( float flMaxAgeSeconds );
Check if the ping data of sufficient recency is available, and if it's too old, start refreshing it.

Please only call this function when you really do need to force an immediate refresh of the data. (For example, in response to a specific user input to refresh this information.) Don't call it "just in case", before every connection, etc. That will cause extra traffic to be sent for no benefit. The library will automatically refresh the information as needed.

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.)

IsPingMeasurementInProgress

bool IsPingMeasurementInProgress();
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.

Valveネットワークトポロジー関数


List of Valve points of presence ("POP"), and ping times to them. This might be useful to you if you are use our hosting, or just need to measure latency to a cloud data center where we are running relays.

GetPingToDataCenter

int GetPingToDataCenter( SteamNetworkingPOPID popID, SteamNetworkingPOPID *pViaRelayPoP );
Fetch ping time of best available relayed route from this host to the specified data center.

GetDirectPingToPOP

int GetDirectPingToPOP( SteamNetworkingPOPID popID );
Get *direct* ping time to the relays at the point of presence.

GetPOPCount

int GetPOPCount();
Get number of network points of presence in the config

GetPOPList

int GetPOPList( SteamNetworkingPOPID *list, int nListSz );
すべてのPOP IDのリストを取得します。 Returns the number of entries that were filled into your list.

関数の設定


ネットワーキングオプションの制御。 個別の説明はESteamNetworkingConfigValueを参照してください。

SetConfigValue

bool SetConfigValue( ESteamNetworkingConfigValue eValue, ESteamNetworkingConfigScope eScopeType, intptr_t scopeObj, ESteamNetworkingConfigDataType eDataType, const void *pArg );


構成値を設定します。
  • eValue: どの値を設定するか
  • eScope: どのタイプのオブジェクト上に設定を適用するのか。
  • scopeArg: 変更したいオブジェクト (グローバルスコープでは無視されます。) 例:接続ハンドル、リッスンソケットハンドル、インターフェイスポインターなど。
  • eDataType: pValueのバッファーにあるデータのタイプ これは変数のタイプと正確に一致する必要があります。
  • pArg: 設定する値。

    NULLを渡してこのスコープの非グローバル設定を削除し、そのオブジェクトの値がグローバルのデフォルトを使用するようにできます。 Or at global scope, passing NULL will reset any custom value and restore it to the system default.

    NOTE: When setting pointers (e.g. callback functions), do not pass the function pointer directly. 引数は関数ポインターへのポインターである必要があります。

char

const char *GetConfigValueInfo( ESteamNetworkingConfigValue eValue, ESteamNetworkingConfigDataType *pOutDataType, ESteamNetworkingConfigScope *pOutScope );

Get info about a configuration value. Returns the name of the value, or NULL if the value doesn't exist. Other output parameters can be NULL if you do not need them.

IterateGenericEditableConfigValues

ESteamNetworkingConfigValue IterateGenericEditableConfigValues( ESteamNetworkingConfigValue eCurrent, bool bEnumerateDevVars );

Iterate the list of all configuration values in the current environment that it might be possible to display or edit using a generic UI. To get the first iterable value, pass k_ESteamNetworkingConfig_Invalid. Returns k_ESteamNetworkingConfig_Invalid to signal end of list.

The bEnumerateDevVars argument can be used to include "dev" vars. These are vars that are recommended to only be editable in "debug" or "dev" mode and typically should not be shown in a retail environment where a malicious local user might use this to cheat.

Shortcuts for common cases

The following functions are handy shortcuts for common use cases.
bool SetGlobalConfigValueInt32( ESteamNetworkingConfigValue eValue, int32 val ); bool SetGlobalConfigValueFloat( ESteamNetworkingConfigValue eValue, float val ); bool SetGlobalConfigValueString( ESteamNetworkingConfigValue eValue, const char *val ); bool SetConnectionConfigValueInt32( HSteamNetConnection hConn, ESteamNetworkingConfigValue eValue, int32 val ); bool SetConnectionConfigValueFloat( HSteamNetConnection hConn, ESteamNetworkingConfigValue eValue, float val ); bool SetConnectionConfigValueString( HSteamNetConnection hConn, ESteamNetworkingConfigValue eValue, const char *val );

その他の関数

AllocateMessage

SteamNetworkingMessage_t *AllocateMessage( int cbAllocateBuffer )
Allocate and initialize a message object. Usually the reason you call this is to pass it to ISteamNetworkingSockets::SendMessages. The returned object will have all of the relevant fields cleared to zero.

Optionally you can also request that this system allocate space to hold the payload itself. If cbAllocateBuffer is nonzero, the system will allocate memory to hold a payload of at least cbAllocateBuffer bytes. m_pData will point to the allocated buffer, m_cbSize will be set to the size, and m_pfnFreeData will be set to the proper function to free up the buffer.

If cbAllocateBuffer=0, then no buffer is allocated. m_pData will be NULL, m_cbSize will be zero, and m_pfnFreeData will be NULL. You will need to set each of these.

GetLocalTimestamp

SteamNetworkingMicroseconds GetLocalTimestamp();

A general purpose high resolution local timer with the following properties:
  • Monotonicity is guaranteed.
  • The initial value will be at least 24*3600*30*1e6, i.e. about 30 days worth of microseconds. In this way, the timestamp value of 0 will always be at least "30 days ago". Also, negative numbers will never be returned.
  • Wraparound / overflow is not a practical concern.

SteamNetworkingMessage_t::m_usecTimeReceived contains a timestamp that is from the same timer.

If you are running under the debugger and stop the process, the clock might not advance the full wall clock time that has elapsed between calls. If the process is not blocked from normal operation, the timestamp values will track wall clock time, even if you don't call the function frequently.

The value is only meaningful for this run of the process. Don't compare it to values obtained on another computer, or other runs of the same process.

SetDebugOutputFunction

void SetDebugOutputFunction( ESteamNetworkingSocketsDebugOutputType eDetailLevel, FSteamNetworkingSocketsDebugOutput pfnFunc );

Set a function to receive network-related information that is useful for debugging.

This can be extremely useful during development, but it can also be useful for troubleshooting problems with tech savvy end users. If you have a console or other log that customers can examine, these log messages can often be helpful to troubleshoot network issues.(Especially any warning/error messages.)

The detail level indicates what message to invoke your callback on. Lower numeric value means more important, and the value you pass is the lowest priority (highest numeric value) you wish to receive callbacks for. Except when debugging, you should only use k_ESteamNetworkingSocketsDebugOutputType_Msg or k_ESteamNetworkingSocketsDebugOutputType_Warning. For best performance, do NOT request a high detail level and then filter out messages in your callback. Instead, call this function to adjust the desired level of detail.

The value here controls the detail level for most messages. You can control the detail level for various subsystems (perhaps only for certain connections) by adjusting the configuration values k_ESteamNetworkingConfig_LogLevel_Xxxxx.

IMPORTANT: This may be called from a service thread, while we own a mutex, etc. Your callback function must be threadsafe and fast! Do not make any other Steamworks calls from within the handler.

Fake IP


The "FakeIP" system is useful for interfacing with code that assumes peers are identified using an IPv4 address. See ISteamNetworkingSockets for more information.

IsFakeIPv4

bool IsFakeIPv4( uint32 nIPv4 );

Return true if an IPv4 address is one that might be used as a "fake" one. This function is fast; it just does some logical tests on the IP and does not need to do any lookup operations.

GetRealIdentityForFakeIP

EResult GetRealIdentityForFakeIP( const SteamNetworkingIPAddr &fakeIP, SteamNetworkingIdentity *pOutRealIdentity );

Get the real identity associated with a given FakeIP.

On failure, returns:
  • k_EResultInvalidParam: the IP is not a FakeIP.
  • k_EResultNoMatch: we don't recognize that FakeIP and don't know the corresponding identity.

FakeIP's used by active connections, or the FakeIPs assigned to local identities, will always work. FakeIPs for recently destroyed connections will continue to return results for a little while, but not forever. At some point, we will forget FakeIPs to save space. It's reasonably safe to assume that you can read back the real identity of a connection very soon after it is destroyed. But do not wait indefinitely.