NS/releases/3.01/source/upp/UPPClientInterface.h
Karl 04c334c94b Tagging 3.01 release (again)
git-svn-id: https://unknownworlds.svn.cloudforge.com/ns1@15 67975925-1194-0748-b3d5-c16f83f1a3a1
2005-03-12 22:19:53 +00:00

170 lines
No EOL
6.7 KiB
C++

#ifndef UPPCLIENTINTERFACE_H
#define UPPCLIENTINTERFACE_H
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//UPP Client Interface
//
//Hides implementation of communication layer between game server
//(a.k.a. "the client") and UPP server (a.k.a. "the server")
//
//Several details that were previously tracked explicitly by the
//client (server identity, client timestamps, heartbeat management)
//are now handled behind the scenes. The client is still responsible
//for collecting player and game data for requests, and still needs
//to register itself with a call to UPP::connect. If UPP::connect fails,
//no client identity has been established with the UPP server, and any
//subsequent requests will automatically fail until a successful call
//to UPP::connect has been made.
//
//The client should call interface functions immediately when the
//corresponding state change takes place; any batching of calls will
//be the responsibility of the communication layer. Any server that
//has mp_uplink set to 0 should be considered offline, and changing
//that cvar should trigger the online/offline reporting functions.
//
//If UPP::connect fails, the client can call the function again to
//retry or notify the user that the link wasn't established.
//
//Ideally, the client should have a centralized player index ->
//UPP::PlayerInfo object function so that all of the logic for
//generating UPP::PlayerInfo snapshots can be contained in a single
//location. The ability to build a UPP::TeamInfo object should also
//be encapsulated since that information is required for both
//UPP::GameInfo and UPP::GameResultInfo objects. A clean,
//centralized implementation is less of an issue for the other UPP
//data objects, each of which is only used from a single location.
//
//Author: Karl Patrick
//Last Modified: 04/09/04
//
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#include "UPPCommonInterface.h"
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Forward declaration of UPP Client objects
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
namespace UPP
{
//Profiling objects
class PerformanceData;
class PerformanceSummary; //not implemented
//Optional callback functions - can also query for result structures
typedef void (*ProfileInfoCallback)(auto_ptr<ProfileInfo> info);
typedef void (*AuthGroupCallback)(auto_ptr<const StringSet>);
typedef void (*VariablesCallback)(auto_ptr<const StringSet>, bool startVars);
typedef void (*ProfilerCallback)(auto_ptr<PerformanceData> profile);
}
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Interface function declarations
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
namespace UPP
{
//version information
int getUPPClientLibBuildNumber(void);
//configuration
int getMaxSimultaneousRequests(void);
bool setServerConnection(const string& connection_string, const string& protocol);
bool setGeneratePerformanceData(const bool generate_profiler_info = false); //not implemented
bool setRunAsynchronously(const bool async = true);
bool setMaxSimultaneousRequests(const int max_size = 5);
auto_ptr<string> getConnectionString(void);
auto_ptr<string> getProtocol(void);
bool getGeneratePerformanceData(void); //not implemented
bool getRunAsynchronously(void);
//state information
bool isConnected(void);
bool isRecordingGame(void);
//outgoing signal functions (asynchronous, return false if signal definitely won't be sent)
bool connect(const ClientInfo& info);
bool disconnect(void);
bool requestConnectionSpeedTest(void); //always generates profiler info
bool reportPlayerEntered(const PlayerInfo& player, const bool resolvedID);
bool reportPlayerChangingIDs(const PlayerInfo& player, const string& newNetworkID, const bool resolvedID);
bool reportPlayerChangingTeams(const PlayerInfo& player, const int newTeamIndex);
bool reportPlayerExited(const PlayerInfo& player);
bool reportGameStarted(const GameInfo& game);
bool reportGameFinished(const GameResultInfo& game);
bool reportGameCancelled(void);
bool requestAuthGroups(void);
bool requestVariables(void);
//incoming signal functions (asynchronous, items are sent to callback functions
//immediately if they are defined, otherwise they are stored until retrieval
//only the most recently registered callback function is used. Register NULL to
//return to using library-side storage until retrieval
void registerProfileInfoCallback(ProfileInfoCallback callback);
void registerAuthGroupCallback(AuthGroupCallback callback);
void registerVariablesCallback(VariablesCallback callback);
void registerProfilerCallback(ProfilerCallback callback);
bool hasProfileInfo(void);
auto_ptr<ProfileInfo> getProfileInfo(void); //returns auto_ptr<NULL> if no profiles are available
bool hasPerformanceData(void);
auto_ptr<PerformanceData> getPerformanceData(void);
auto_ptr<PerformanceSummary> getPerformanceSummary(void);
auto_ptr<StringSet> listAuthGroups(void);
auto_ptr<StringSet> listGameStartVariables(void);
auto_ptr<StringSet> listGameEndVariables(void);
}
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
class UPP::PerformanceData
{
public:
virtual ~PerformanceData(void) {}
virtual const string getSignalType(void) const = 0;
virtual long getSignalTimestamp(void) const = 0;
virtual long getProcessingThreadNumber(void) const = 0;
virtual const string getConnectionString(void) const = 0;
virtual const string getConnectionProtocol(void) const = 0;
virtual int getErrorCode(void) const = 0;
virtual const string getErrorDescription(void) const = 0;
virtual long getTimeInQueue(void) const = 0;
virtual long getTimeInProcessing(void) const = 0;
virtual long getTimeInProcessingOnServer(void) const = 0;
virtual long getRequestSize(void) const = 0;
virtual long getResponseSize(void) const = 0;
};
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
class UPP::PerformanceSummary
{
public:
virtual ~PerformanceSummary(void) {}
virtual int getNumRequestsCreated(void) const = 0;
virtual int getNumRequestsSent(void) const = 0;
virtual int getNumResponsesRecieved(void) const = 0;
virtual int getNumResponsesSuccessful(void) const = 0;
//note - timers only account for signals that have recieved
//responses
virtual long getTotalTimeInQueue(void) const = 0;
virtual long getTotalTimeInProcessing(void) const = 0;
virtual long getTotalTimeInProcessingServer(void) const = 0;
virtual long getTotalRequestSize(void) const = 0;
virtual long getTotalResponseSize(void) const = 0;
};
#endif