Utilitaires de réseau divers pour la vérification de l'environnement de réseau local et l'estimation des pings.
Pour plus d'informations, veuillez vous référer aux documents suivants.
Les fonctions membres pour ISteamNetworkingUtils sont appelées via la fonction d'accesseur global SteamNetworkingUtils().
Initialisation et vérification d'état
InitRelayNetworkAccess
void InitRelayNetworkAccess();
Appelez ceci pour initialiser le réseau relais si vous savez à l'avance que vous allez l'utiliser (par exemple, parce que vous anticipez de réaliser des connexions P2P). Si vous ne l'appelez pas, l'initialisation sera retardée jusqu'à la première instance de la fonctionnalité qui aura besoin d'un accès au réseau relais, ce qui retardera cet accès initial.
Vous pouvez aussi appeler cette fonction pour forcer une nouvelle tentative si la première a échoué. Toute action qui requiert un accès au réseau relais provoquera également une nouvelle tentative, c'est pourquoi il n'est jamais strictement nécessaire d'appeler cette fonction, mais cela peut être utile de l'appeler au lancement du programme, s'il est prévu qu'un accès au réseau relais sera utilisé. Utilisez
GetRelayNetworkStatus ou attendez les rappels de
SteamRelayNetworkStatus_t pour savoir si l'initialisation est achevée. L'initialisation prend généralement quelques secondes.
Remarque : les serveurs dédiés hébergés dans des centres de données connus *n'ont pas* besoin de l'appeler, puisqu'ils ne prennent aucune décision de routage. Cependant, si le serveur dédié utilise la fonctionnalité P2P, il endosse alors le rôle de « client » et la fonction doit être appelée.
GetRelayNetworkStatus
ESteamNetworkingAvailability GetRelayNetworkStatus( SteamRelayNetworkStatus_t *pDetails );
Rapporte l'état actuel du réseau relais.
SteamRelayNetworkStatus_t est aussi un rappel. Il est déclenché sur les interfaces du client et du serveur de jeu chaque fois qu'il y a un changement d'état, ou que la mesure du ping commence ou s'arrête.
SteamRelayNetworkStatus_t::m_eAvail est retourné. Si vous voulez en savoir plus, vous pouvez transmettre une valeur qui n'est pas NULL.
Fonctions de localisation du ping
Nous utilisons les temps de pings vers les relais de Valve à travers le monde pour générer un « marqueur » qui décrit où se trouve un hôte Internet. Avec deux marqueurs de ce type, nous sommes en mesure d'estimer la latence du réseau entre deux hôtes sans envoyer de paquets. L'estimation est fondée sur la route optimale trouvée dans le réseau de Valve. Si c'est sur le réseau de Valve que passe votre trafic, alors ce ping est exactement celui qui vous intéresse. Sinon, le temps de ping constitue probablement une estimation raisonnable.
Cette fonction est très utile pour sélectionner des pairs optionnels pour le matchmaking.
Les marqueurs peuvent aussi être convertis en chaines de caractères, ce qui permet de les transmettre. Nous avons une bibliothèque séparée que vous pouvez utiliser de votre côté pour manipuler ces objets. (Consultez
steamdatagramrelay pour en savoir plus.)
GetLocalPingLocation
float GetLocalPingLocation( SteamNetworkPingLocation_t &result );
Renvoie les coordonnées de localisation pour l'hôte en cours. Renvoie l'âge approximatif des données en secondes, ou −1 si aucune donnée n'est disponible.
L'initialisation de l'accès au réseau relais prend quelques secondes. Si vous l'appelez trop rapidement après l'appel de
InitializeRelayNetworkAccess, les données risquent de ne pas encore être disponibles.
Cette action renvoie toujours les informations les plus récentes en notre possession, même si nous sommes en train de recalculer les temps de ping.
EstimatePingTimeBetweenTwoLocations
int EstimatePingTimeBetweenTwoLocations( const SteamNetworkPingLocation_t &location1, const SteamNetworkPingLocation_t &location2 );
Estime la latence d'une boucle entre deux emplacements au hasard en millisecondes. C'est une estimation prudente basée sur le routage via le réseau relais. Pour les connexions relayées les plus basiques, le temps de ping sera précis, puisqu'il sera basé sur le chemin qui s'avèrera probablement être celui utilisé.
Si un chemin IP direct est utilisé (peut-être via le passage NAT), alors le chemin sera différent et il est possible que le temps de ping en soit amélioré, ou bien qu'il empire ! Le routage IP standard est fréquemment insatisfaisant !
Mais même dans ce cas, l'estimation obtenue avec cette méthode représente une approximation raisonnable de la latence maximale (elle présente aussi l'avantage d'un retour immédiat sans l'envoi de paquets).
Il peut arriver que nous ne puissions pas faire d'estimation sur le chemin. Dans ce cas, une valeur négative est retournée. k_nSteamNetworkingPing_Failed indique qu'une difficulté sur le réseau est à la source de l'échec (le ping a échoué, etc.). k_nSteamNetworkingPing_Unknown est renvoyé si nous ne sommes pas en mesure de répondre à la question pour quelqu'autre raison.
Doit-on pouvoir faire cela depuis un serveur principal ou de matchmaking ? La bibliothèque « coordinateur de jeu » est ce qu'il vous faut. Consultez l'article
steamdatagramrelay pour savoir comment obtenir le SDK du coordinateur de jeu.
EstimatePingTimeFromLocalHost
int EstimatePingTimeFromLocalHost( const SteamNetworkPingLocation_t &remoteLocation );
Identique à EstimatePingTime, mais présuppose qu'un emplacement soit l'hôte local. Cette méthode est un peu plus rapide, spécialement si vous avez besoin de calculer plusieurs de ces temps de ping en boucle pour trouver le plus court.
Dans quelques cas rares, cela peut renvoyer une estimation légèrement différente à celle qui combine GetLocalPingLocation à EstimatePingTimeBetweenTwoLocations. La raison en est que cette fonction utilise un ensemble d'informations un peu plus complet sur le chemin qui doit être emprunté.
ConvertPingLocationToString
void ConvertPingLocationToString( const SteamNetworkPingLocation_t &location, char *pszBuf, int cchBufSize );
Convertit la localisation d'un ping au format texte, ce qui permet de l'envoyer par le réseau. Le format est compact et contrôlable de visu. Il peut toutefois changer, c'est pourquoi nous vous déconseillons de l'analyser vous-même. Votre tampon doit faire au moins k_cchMaxSteamNetworkingPingLocationString octets.
ParsePingLocationString
bool ParsePingLocationString( const char *pszString, SteamNetworkPingLocation_t &result );
Analyse la chaine de caractères SteamNetworkPingLocation_t renvoyée. Elle retourne false si nous n'avons pas réussi à la comprendre.
Fonctions d'état des mesures de ping
L'utilisation du réseau relais demande de prendre des mesures de la latence. À l'exception de l'appel
InitializeRelayNetworkAccess au démarrage de l'application (si vous savez déjà que vous aurez besoin de l'accès au réseau relais pour envoyer du trafic ou que vous voulez seulement une estimation des temps de ping), le processus de mesure de la latence s'effectue automatiquement. Ces fonctions vous confèrent un peu plus de contrôle sur ce processus.
CheckPingDataUpToDate
bool CheckPingDataUpToDate( float flMaxAgeSeconds );
Vérifiez si les données de ping dont la date est suffisamment récente sont disponibles. Si elles sont trop anciennes, commencez à les réactualiser.
Veuillez n'appeler cette fonction que si vous avez
vraiment besoin de forcer une actualisation immédiate des données (par exemple, en réponse à l'entrée d'un utilisateur ou d'une utilisatrice pour actualiser cette information). Ne l'appelez pas « au cas où » avant chaque connexion, etc. Cela provoquerait l'envoi de trafic supplémentaire pour rien. La bibliothèque actualisera les informations automatiquement quand cela sera nécessaire.
Renvoie true si des données suffisamment récentes sont déjà disponibles.
Renvoie false si des données suffisamment récentes ne sont pas disponibles. Dans ce cas, si la mesure du ping n'est pas déjà en cours, elle a tout de même été initiée (vous ne pouvez pas recommencer une mesure déjà en cours).
IsPingMeasurementInProgress
bool IsPingMeasurementInProgress();
Renvoie true si nous prenons des mesures de ping pour mettre à jour la localisation de notre ping ou sélectionner un routage optimal. Les mesures de ping prennent en général quelques secondes, 10 au maximum.
Fonctions topologiques du réseau de Valve
Liste des points de présence de Valve (« POP ») et des temps de ping qui leur sont associés. Ceci peut vous être utile si vous utilisez notre hébergement ou si vous avez besoin de mesurer la latence vers un centre de données du cloud où nous exécutons des relais.
GetPingToDataCenter
int GetPingToDataCenter( SteamNetworkingPOPID popID, SteamNetworkingPOPID *pViaRelayPoP );
Rapporte le temps de ping sur le meilleur chemin disponible via relais depuis cet hôte jusqu'au centre de données indiqué.
GetDirectPingToPOP
int GetDirectPingToPOP( SteamNetworkingPOPID popID );
Obtient le temps de ping *direct* jusqu'aux relais au point de présence.
GetPOPCount
int GetPOPCount();
Obtient le nombre de points de présence du réseau dans la configuration.
GetPOPList
int GetPOPList( SteamNetworkingPOPID *list, int nListSz );
Obtient la liste de tous les identifiants POP. Elle renvoie le nombre d'entrées qui ont été remplies dans votre liste.
Fonctions de configuration
Elles commandent les options du réseau. Vous trouverez les descriptions individuelles avec ESteamNetworkingConfigValue.
SetConfigValue
bool SetConfigValue( ESteamNetworkingConfigValue eValue, ESteamNetworkingConfigScope eScopeType, intptr_t scopeObj,
ESteamNetworkingConfigDataType eDataType, const void *pArg );
Définit une valeur de configuration.
- eValue : la valeur définie.
- eScope : le type d'objet sur lequel vous allez appliquer le paramètre.
- scopeArg : l'objet que vous voulez changer (à ignorer si le champ d'application est global). Par exemple, un handle de connexion, un handle de socket d'écoute, un pointeur d'interface, etc.
- eDataType : le type de données qui se trouve dans le tampon à pValue. Il doit correspondre exactement au type de la variable !
- pArg : valeur à laquelle la définir.
Vous pouvez passer NULL pour supprimer un paramètre non global à ce champ d'application, ce qui entrainera l'utilisation par la valeur attachée à cet objet des paramètres globaux par défaut. Ou quand le champ d'application est global, passer NULL réinitialisera toute valeur personnalisée et rétablira la valeur par défaut du système.
REMARQUE : quand vous définissez les pointeurs (comme les fonctions de rappel), ne transmettez pas directement le pointeur de fonction. Votre argument devrait être un pointeur vers un pointeur de fonction.
char
const char *GetConfigValueInfo( ESteamNetworkingConfigValue eValue, ESteamNetworkingConfigDataType *pOutDataType, ESteamNetworkingConfigScope *pOutScope );
Obtient les informations sur une valeur de configuration. Renvoie le nom de la valeur, ou NULL si elle n'existe pas. D'autres paramètres de sortie peuvent être NULL si vous n'en avez pas besoin.
IterateGenericEditableConfigValues
ESteamNetworkingConfigValue IterateGenericEditableConfigValues( ESteamNetworkingConfigValue eCurrent, bool bEnumerateDevVars );
Itère la liste de toutes les valeurs de configuration de l'environnement actuel qu'il est possible d'afficher ou de modifier à l'aide d'une interface utilisateur générique. Pour obtenir la première valeur itérable, passez K_ESteamNetworkingConfig_invalid. Renvoie k_ESteamNetworkingConfig_Invalid pour indiquer la fin de la liste.
L'argument bEnumerateDevVars peut être utilisé pour inclure les variables « dev ». Il est recommandé de ne modifier ces variables qu'en mode « debug » ou « dev ». Elles ne doivent généralement pas être affichées dans un environnement de vente au détail, où une personne malveillante pourrait les utiliser pour tricher.
Raccourcis pour les situations courantes
Les fonctions suivantes sont des raccourcis pratiques pour ces situations courantes.
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 );
Fonctions diverses
AllocateMessage
SteamNetworkingMessage_t *AllocateMessage( int cbAllocateBuffer )
Assigne et initialise un objet de message. Vous aurez en général besoin d'appeler cette fonction pour la transmettre à
ISteamNetworkingSockets::SendMessages. L'objet renvoyé aura tous les champs pertinents remis à zéro.
Vous avez aussi l'option de demander que ce système alloue de l'espace pour contenir la charge utile en elle-même. Si cbAllocateBuffer n'est pas à zéro, le système va alors allouer de la mémoire pour qu'elle contienne au minimum une charge utile du montant de cbAllocateBuffer en octets. m_pData va pointer vers le tampon assigné, m_cbSize sera défini sur sa taille et m_pfnFreeData sera défini sur la fonction correcte pour libérer le tampon.
Si cbAllocateBuffer=0, alors aucun espace du tampon n'est alloué. m_pData sera NULL, m_cbSize sera à zéro et m_pfnFreeData sera NULL. Vous devrez déterminer chacune de ces valeurs.
GetLocalTimestamp
SteamNetworkingMicroseconds GetLocalTimestamp();
Horloge locale à haute précision à usage général qui possède les propriétés suivantes.
- Monotonie garantie.
- La valeur de départ est au moins 24 x 3600 x 1e6, soit à peu près l'équivalent de 30 jours en microsecondes. Ainsi, la valeur d'horodatage « 0 » datera toujours d'il y a au moins « 30 jours ». En outre, les nombres négatifs ne seront jamais renvoyés.
- Il n'y a pas lieu de s'inquiéter du risque de boucle ou de débordement.
SteamNetworkingMessage_t::m_usecTimeReceived contient un horodatage qui provient de la même horloge.
Si vous êtes dans un débogueur et que vous arrêtez le processus, l'horloge risque de ne pas avancer d'autant de temps que la durée réelle entre les deux appels. Si rien n'empêche le processus de s'effectuer normalement, les valeurs de l'horodatage suivront le temps réel, même si vous n'appelez pas la fonction régulièrement.
La valeur est pertinente pour cette exécution du processus uniquement. Ne comparez pas les valeurs obtenues depuis un autre ordinateur ou d'autres exécutions du même processus.
SetDebugOutputFunction
void SetDebugOutputFunction( ESteamNetworkingSocketsDebugOutputType eDetailLevel, FSteamNetworkingSocketsDebugOutput pfnFunc );
Définit une fonction pour qu'elle reçoive des informations relatives au réseau utiles au débogage.
Elle peut être extrêmement utile non seulement pendant la phase de développement, mais aussi pour la résolution de problèmes avec une partie de la clientèle qui maitrise la technologie. Si vous avez une console ou un journal que la clientèle peut examiner, ces messages de journal peuvent souvent contribuer à résoudre les problèmes de réseau (en particulier tous les messages d'avertissement ou d'erreur).
Le niveau de détails indique à partir de quel message vous devrez faire votre rappel. Plus un message est important, plus sa valeur numérique est basse. La valeur à transmettre est donc le niveau de priorité le plus bas (autrement dit la valeur numérique la plus haute) pour lequel vous souhaitez recevoir des rappels. Débogage excepté, vous devez seulement utiliser k_ESteamNetworkingSocketsDebugOutputType_Msg ou k_ESteamNetworkingSocketsDebugOutputType_Warning. Pour des performances optimales, NE DEMANDEZ PAS un niveau de détails élevé pour ensuite filtrer les messages dans votre rappel. Appeler plutôt cette fonction pour ajuster le niveau de détail désiré.
La valeur indiquée ici gère le niveau de détails de la plupart des messages. Vous pouvez contrôler le niveau de détails de différents sous-systèmes (peut-être uniquement pour certaines connexions) en ajustant les valeurs de configuration de type K_ESteamNetworkingConfig_LogLevel_xxxxx.
IMPORTANT : cette fonction peut être appelée depuis un thread de service, pendant que nous sommes en possession d'un mutex, etc.
Votre fonction de rappel doit être thread-safe et rapide ! N'effectuez aucun autre appel Steamworks depuis l'intérieur du gestionnaire.
Fausse adresse IP
Le système « FakeIP » est utile pour connecter deux appareils avec un code qui suppose que ces appareils sont identifiés à l'aide d'une adresse IPv4. Voir
ISteamNetworkingSockets pour plus d'informations.
IsFakeIPv4
bool IsFakeIPv4( uint32 nIPv4 );
Renvoie true si une adresse IPv4 est susceptible d'être utilisée comme une « fausse » adresse. Cette fonction est rapide. Elle effectue juste quelques tests logiques sur l'adresse IP et ne nécessite aucune opération de recherche.
GetRealIdentityForFakeIP
EResult GetRealIdentityForFakeIP( const SteamNetworkingIPAddr &fakeIP, SteamNetworkingIdentity *pOutRealIdentity );
Obtient la véritable identité associée à une fausse adresse IP donnée.
En cas d'échec, renvoie :
- k_EResultInvalidParam si l'IP n'est pas fausse ;
- k_EResultNoMatch si l'IP n'est pas reconnue et qu'elle ne peut être identifiée.
Les fausses adresses IP utilisées pour des connexions actives, ou attribuées à des identités locales, fonctionneront toujours. Les fausses adresses IP de connexions récemment supprimées continueront à renvoyer des résultats pendant un certain temps, mais pas indéfiniment. À un moment donné, les fausses adresses IP seront oubliées pour gagner de la place. On peut raisonnablement supposer que l'identité réelle d'une connexion peut être découverte très rapidement après sa destruction. Cependant, n'attendez pas indéfiniment.
