GNE: GNE Namespace Reference


Classes
class	Address
	A wrapper class for the HawkNL NLaddress. More...
class	Buffer
	The Buffer class provides functionality to pull data types out of a raw binary data buffer. More...
class	ChannelPacket
	A ChannelPacket wraps around a normal Packet to give that Packet a channel destination and information about its source. More...
class	ChannelProvider
	The ChannelProvider provides for a set of sets of Connection objects, which are used as broadcast channels to broadcast packets to. More...
class	ClientConnection
	A class that can connect to a remote target. More...
class	ConditionVariable
	A class for a conditional variable. More...
class	Connection
	A class resembling any type of connection to a remote computer. More...
class	ConnectionEventGenerator
	A class used internally by GNE to generate the events in Connection. More...
class	ConnectionListener
	This is an abstract base class representing an interface to the Connection, ClientConnection, and ServerConnection classes. More...
class	ConnectionParams
	A class to encapsulate parameters about a connection. More...
struct	ConnectionStats
	A struct holding values returned by getStats. More...
class	ConsoleBuffer
	An abstracted Console. More...
class	Counter
	An implementation of a TimerCallback that provides a simple counter. More...
class	CustomPacket
	Many times, especially during connection, you want to send some more "free-form" data that may or may not all be related and will only be sent once. More...
class	EmptyPacket
	The EmptyPacket is a packet that has no information. More...
class	Error
	This class resembles some sort of error in GNE, with the ability to obtain a textual description of the error. More...
class	UserError
	A simple error class with a default ErrorCode of User for quick error messages. More...
class	LowLevelError
	Adds low level HawkNL and possibly system error information to any other error. More...
class	WrongGame
	An error that represents a mismatch in the games during the connection process. More...
class	UnknownPacket
	An Error when a Packet is received from the network that has an ID that is not registered with the PacketParser. More...
class	PacketTypeMismatch
	An error thrown by SyncConnection when you get a packet other than the one you are trying to receive. More...
class	UserVersionMismatch
	An error that occurs during the connecting process if the user versions are different. More...
class	ProtocolViolation
	An error that occurs during the connection process if the remote machine sends incorrect or corrupted packets to us. More...
class	BufferError
	An error that occurs during an operation on Buffer. More...
class	EventThread
	Internal class used by GNE to manage Connection events. More...
class	ExitPacket
	The ExitPacket is sent automatically by GNE when you disconnect in a proper manner. More...
struct	GNEProtocolVersionNumber
class	ListServerConnection
	A Client-side connection to a game list server for retriving a list of games. More...
class	Lock
	A small helper class that locks the object in its ctor and unlocks it in its destructor. More...
class	LockEx
	Works exactly like Lock but allows early release. More...
class	Mutex
	The mutex class models a simple mutex to provide mutual exclusion to a resource shared by threads. More...
class	NetworkObject
	Represents an object which can be replicated through the ObjectBroker. More...
class	ObjectBroker
	Serves as a base class for ObjectBrokerServer and ObjectBrokerClient and contains common functionality. More...
class	ObjectBrokerClient
	The ObjectBrokerClient takes packets generated from the ObjectBrokerServer and manages the object creations, updates, and deletes specified. More...
class	ObjectBrokerPacket
	The three ObjectBrokerPackets are all identical except for their packet IDs. More...
class	ObjectBrokerServer
	The ObjectBrokerServer assigns IDs to NetworkObject objects, and aids in the creation of ObjectBrokerPacket packets. More...
class	ObjectCreationPacket
	ObjectCreationPacket is a class used by the ObjectBroker to replicate new objects. More...
class	ObjectDeathPacket
	ObjectDeathPacket is a class used by the ObjectBroker to signify when an object is being removed from its control (usually because it is "dying"). More...
class	ObjectUpdatePacket
	ObjectCreationPacket is a class used by the ObjectBroker to update already existing objects. More...
class	Packet
	The base packet class, used for dealing with all types of packets at a fundamental level. More...
class	PacketFeeder
	The PacketFeeder class is a callback for the PacketStream thread when it is running low on packets. More...
class	PacketStream
	This class resembles a packet stream through a connection. More...
struct	PingInformation
	Information returned by GNE::PingPacket::getPingInformation. More...
class	PingPacket
	Using the PingPacket is one way to measure ping and clock offsets from a remote machine. More...
class	RateAdjustPacket
	The RateAdjustPacket is sent automatically by GNE when you change rates in the PacketStream. More...
class	ReceiveEventListener
	A class to act as an interface between ConnectionEventGenerator and its listeners. More...
class	ServerConnection
	A GNE "internal" class. More...
class	ServerConnectionListener
	A connection that listens for other connections. More...
class	SmartPtr
	The SmartPtr class is a reference-counted smart pointer implementation for general use. More...
class	NullDeleter
	Deleter that does nothing for the SmartPtr. More...
class	SocketPair
	A class used to centralize shared elements between Connection and SyncConnection. More...
class	SyncConnection
	A class for performing synchronous connections. More...
class	SynchronizedObject
	A class meant to act as a base class for objects who might want an acquire/ release pair of functions tied to a mutex for object-level synchronization. More...
class	Thread
	A class resembling a thread. More...
class	Time
	A class representing a time relative to a point in the past. More...
class	Timer
	The timer class is used to get the current time and to provide callbacks. More...
class	TimerCallback
	A pure interface class for usage in the Timer class. More...
class	WeakPtr
	The WeakPtr class is a weak pointer to an object managed by SmartPtr. More...
class	WrapperPacket
	WrapperPacket is a Packet that encapsulates another packet for the purposes of adding information to that packet. More...
Namespaces
namespace	Console
	Functions for providing very basic console support, meant for use in the example and test programs, and in console-only servers using GNE.
namespace	PacketParser
	A namespace containing functions handling the parsing of packets.
Typedefs
typedef std::list< Connection * >::iterator	ChannelIterator
typedef std::vector< ServerConnectionListener::sptr >	SCLList
typedef SCLList::iterator	SCLListIter
typedef pthread_t	ID
typedef std::map< ID, Thread::sptr >	ThreadMap
typedef ThreadMap::iterator	ThreadMapIter
typedef signed char	gint8
	Typedefs for the variable types that are common to all GNE implementations (as defined in the GNE protocol document).
typedef unsigned char	guint8
typedef guint8	gbyte
typedef guint8	gbool
	A gbool is 'false' only when its value is 0, else it is 'true'.
typedef signed short	gint16
typedef unsigned short	guint16
typedef signed int	gint32
typedef unsigned int	guint32
typedef float	gsingle
	A single precision 32-bit IEEE 754 floating point variable.
typedef double	gdouble
	A double precision 64-bit IEEE 754 floating point variable.
typedef Lock< Mutex >	LockMutex
typedef Lock< ConditionVariable >	LockCV
typedef Lock< SynchronizedObject >	LockObject
	Locks a SynchronizedObject.
typedef LockEx< Mutex >	LockMutexEx
typedef LockEx< ConditionVariable >	LockCVEx
typedef LockEx< SynchronizedObject >	LockObjectEx
typedef NetworkObject ()	ObjCreationFunc (int objectId, const Packet &)
	The function type used to create an object from a given packet.
Functions
bool	initGNE (NLenum networkType, int(atexit_ptr)(void(func)(void)), int timeToClose=10000)
	Initializes GNE and HawkNL.
void	shutdownGNE ()
	Shuts down GNE and HawkNL.
Address	getLocalAddress ()
	Use this function to get the address of the default networking device on this system, if possible.
ConnectionStats	getGlobalStats ()
	Gets the global stats.
void	enableStats ()
	Enables stats gathering, which is off by default.
void	disableStats ()
	Disables stats gathering, which is the default mode.
void	clearStats ()
	Clears all global stats.
int	getOpenConnections ()
	Returns the number of open low-level connections GNE has opened.
GNEProtocolVersionNumber	getGNEProtocolVersion ()
	Returns the GNE Protocol version number.
const char *	getGameName ()
	This function is used internally by GNE to get the name that you set in setGameInformation.
guint32	getUserVersion ()
	This function is used internally by GNE to get the version that you set in setGameInformation.
void	setGameInformation (std::string gameName, guint32 version)
	The user's game information.
void	checkVersions (const GNEProtocolVersionNumber &otherGNE, std::string otherName, guint32 otherUser)
	Compares other versions against this library.
bool	initDebug (int levelMask, const char *fileName=NULL)
	Function to initialize debugging.
void	killDebug ()
	Function to deinitialize debugging.
void	doTrace (int level, const char fn, int lineno, const char msg,...)
	A function available in a debug compile that does trace logging to a file.
template<class T>
void	swap (SmartPtr< T > &a, SmartPtr< T > &b)
template<class T, class U>
SmartPtr< T >	static_pointer_cast (SmartPtr< U > const &r)
template<class T, class U>
SmartPtr< T >	dynamic_pointer_cast (SmartPtr< U > const &r)
template<class T>
void	swap (WeakPtr< T > &a, WeakPtr< T > &b)
Variables
const int	MINLEN = 8
const int	REFLEN = 44
const int	CAPLEN = 12
const std::string	ErrorStrings []
const std::string	ViolationStrings []
char	gameNameBuf [MAX_GAME_NAME_LEN+1] = {0}
guint32	userVersion = 0
ConnectionEventGenerator::sptr	eGen
	The global event generator.
SmartPtr< ConnectionEventGenerator >	eGen
	The global event generator.
const int	CRPLEN = 48
const int	MAX_GAME_NAME_LEN = 31
	The maximum number of ASCII characters in game name that is passed into the setGameInformation function.
const double	VER = 0.74
	A numeric representation of the current version of this library.
const std::string	VER_STR = "GNE v0.71 CVS"
	A string representation of the name of the library and the current version.
const int	UDP_HEADER_SIZE = 28
	The low-level header size of a UDP header, which is used with the HawkNL internet driver that GNE uses.
const NLenum	NO_NET = 128
	Normally you would pass a network type to GNE::init, but passing this value means that no network should be initialized.
const int	DLEVEL1 = 1
	Debugging level constants for the levelMask.
const int	DLEVEL2 = 2
const int	DLEVEL3 = 4
const int	DLEVEL4 = 8
const int	DLEVEL5 = 16
const gbool	gTrue = 1
	One possible true value for a gbool.
const gbool	gFalse = 0
	The only false value for a gbool.

Detailed Description

The namespace consists of a few global functions, some constants, classes, and the GNE::Console namespace, which holds the console IO functions.

Typedef Documentation

typedef signed char GNE::gint8

Typedefs for the variable types that are common to all GNE implementations (as defined in the GNE protocol document).

"u" type variables denote unsigned versions.

typedef Lock<SynchronizedObject> GNE::LockObject

Locks a SynchronizedObject.

The Console::gout object is such an example. You can use LockObject lock(gout); as a safer alternative to the stream manipulators Console::acquire and Console::release.

Function Documentation

bool GNE::initGNE	(	NLenum	networkType,
		int()(void(func)(void))	atexit_ptr,
		int	timeToClose = `10000`
	)

Initializes GNE and HawkNL.

Call this before using any HawkNL or GNE functions. Pass it the atexit function so shutdown will be called on exit. A call to any other GNE function before this function succeeds is undefined.

Neither initGNE nor shutdownGNE calls are thread-safe, so they should only be called by the main thread.

Parameters:

	networkType	a HawkNL network driver, such as NL_IP or NL_IPX. I've only ever tested NL_IP.
	timeToClose	the amount of time in milliseconds to wait for connections to finish closing, timers to shut down, and user threads to close.

Returns:: true if GNE or HawkNL could not be initialized.

See also:: shutdownGNE

void GNE::shutdownGNE ( )

Shuts down GNE and HawkNL.

All open connections will be closed, all active timers will be shut down, and the shutDown method of all of the threads you have created will be called. The method will block for the time passed into the initGNE function. After that time has passed, the shutdown function exits. If it is being called as a result of the atexit procedure, the process will be forcefully shutdown when the atexit handlers quit, so a stalled/crashed thread won't keep the program from shutting down, but it will keep destructors from being called.

Note that if you have connections, timers, or threads running when main ends, you can be running code or be receiving events after the main function has ended. If this will be a problem you should explicitly call the shutdownGNE method.

Neither initGNE nor shutdownGNE calls are thread-safe, so they should only be called by the main thread, and most certainly not from any GNE Thread (this also means you cannot call "exit" from a GNE Thread).

You are able to re-initialize GNE. If you do this, you should act as if GNE was never initialized. A few methods claim that they can only be called once (such as setGameInformation), but ignore this claim when restarting GNE.

Address GNE::getLocalAddress ( )

Use this function to get the address of the default networking device on this system, if possible.

The port in the resulting address will be zero. The returned address is invalid if an error occurred.

ConnectionStats GNE::getGlobalStats ( )

Gets the global stats.

Very similar to Connection::getStats, but this gets cumulative stats for all sockets, user-created ones and GNE ones too you may not know about.

void GNE::enableStats ( )

Enables stats gathering, which is off by default.

When stats is not enabled, the get function's results is undefined.

GNEProtocolVersionNumber GNE::getGNEProtocolVersion ( )

Returns the GNE Protocol version number.

This is different from the library version number. This number is specified by the GNE protocol document on the GNE web site. Versions of this library obtained from CVS might have the build number non-zero. Non-beta public releases of GNE will have a build number of zero and a version and subVersion number strictly defined by the GNE protocol specification. Public alpha or beta releases might have a non-zero build number.

void GNE::setGameInformation	(	std::string	gameName,
		guint32	version
	)

The user's game information.

This information is used during the connection process to check if the versions and games match. This function should only be called once, and before making any connections.

Parameters:

	gameName	the name of your game, or any other unique string identifier in ASCII format with a length not exceeding MAX_GAME_NAME_LEN ASCII characters.
	version	a 4-byte value with the current game version in any format.

void GNE::checkVersions	(	const GNEProtocolVersionNumber &	otherGNE,
		std::string	otherName,
		guint32	otherUser
	)

Compares other versions against this library.

This is used internally by GNE to compare versions. It checks the GNE version numbers first, then the game name, then the user versions.

Exceptions:

	Error	if the GNE versions did not match.
	WrongGame	if the game is of the wrong type.
	UserVersionMismatch	if the user versions are different.

bool GNE::initDebug	(	int	levelMask,
		const char *	fileName = `NULL`
	)

Function to initialize debugging.

This is safe to call before initialization of GNE, but can be called at any time (but not multiple times). No debugging messages will be displayed until this function is called, and it is save to use the debugging macros and doTrace before calling this -- just nothing will be displayed.

Parameters:

	fileName	an optional fileName to log to. If you pass NULL for this parameter, then GNE will pick a temp file name that is safe for multiple instances. The filename will be based on time: gneHH'MM'SS.log
	levelMask	sets just how detailed the trace is, and will display all messages that match this parameter. You should bitwise OR together the levels you want to see.

Returns:: false on error

void GNE::killDebug ( )

Function to deinitialize debugging.

This will be called automatically on program exit, and the GNE user need not call it.

void GNE::doTrace	(	int	level,
		const char *	fn,
		int	lineno,
		const char *	msg,
			...
	)

A function available in a debug compile that does trace logging to a file.

This function is thread-safe.

Parameters:

	level	the "level" of detail for this trace statement, 1 being the most basic and should always be displayed. The higher you go, the more detailed the trace should get. This is so to allow debugging but not totally flood the logfile unless you need to get this detailed. These general standards are followed: 1 - startup, shutdown, and explicit error messages. 2 - connection, disconnection, and other "normal" operation. 3 - average level. packet registration, socket registration 4 - events like onReceive and such, and some reporting. 5 - very low level -- thread creation, memory allocation.
	fn	The file name this trace was called from
	lineno	The line number in the file
	msg	The message to display to the logfile, in printf style, followed by the data.

Variable Documentation

const std::string GNE::ErrorStrings[]

Initial value:

 {
  "No error.",
  "The remote end did not follow the specifications of the GNE protocol.",
  "The remote end uses an earlier version of the GNE protocol.",
  "The remote end uses a later version of the GNE protocol.",
  "The connecting game names differ.",
  "The user protocol version numbers do not match.",
  "Could not open a network socket.",
  "Could not contact the host due to connection timeout.",
  "The connection attempt was aborted.",
  "The remote end decided to refuse your connection request.",
  "Remote computer suddenly disconnected without warning, or dropped.",
  "The operation was canceled because the SyncConnection is released.",
  "The remote end sent a connection close notice.",
  "Network error when trying to read from connection.",
  "Network error when trying to write to connection.",
  "Unknown packet type encountered -- possible additional data loss.",
  "Packet type received does not match next packet type expected.",
  "An object with the given ID already exists.",
  "The given object ID does not match a known object.",
  "A packet of the wrong type was passed to the ObjectBroker.",
  "The packet ID is not registered as a valid object creation packet.",
  "Buffer underflow error (attempt to read more bytes than available).",
  "Buffer overflow error (attempt to write more bytes than the buffer can hold).",
  "An invalid value for position was given to Buffer::setPosition",
  "An invalid value for limit was given to Buffer::setLimit",
  "Other GNE (not a low-level network) error.",
  "Low-level HawkNL error:",
  "User-defined Error"
}

const std::string GNE::ViolationStrings[]

Initial value:

 {
  "",
  " Client sent an invalid request packet.",
  " Server sent an invalid connection response packet.",
  " Client sent an invalid or corrupted unreliable information packet."
}

ConnectionEventGenerator::sptr GNE::eGen

The global event generator.

The library uses this internally to register and unregister connections. The end-user will not have to use this object under any normal circumstances.

SmartPtr<ConnectionEventGenerator> GNE::eGen

The global event generator.

The library uses this internally to register and unregister connections. The end-user will not have to use this object under any normal circumstances.

const int GNE::UDP_HEADER_SIZE = 28

The low-level header size of a UDP header, which is used with the HawkNL internet driver that GNE uses.

A number that I always have trouble finding and might be useful in getting stats or calculating actual bandwidth.

const NLenum GNE::NO_NET = 128

Normally you would pass a network type to GNE::init, but passing this value means that no network should be initialized.

This is useful only in the example programs that don't use networking and do not need to initialize everything.

See also:: initGNE

GNE Namespace Reference

Classes

Namespaces

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

Function Documentation

Variable Documentation