Storm Reference

SNet API Functions

SNetCreateGame()

SNetDestroy()

SNetEnumGames()

SNetEnumProviders()

SNetGetNetworkLatency()

SNetGetNumPlayers()

SNetGetPlayerCaps()

SNetGetPlayerName()

SNetGetProviderCaps()

SNetGetTurnsInTransit()

SNetInitializeProvider()

SNetJoinGame()

SNetLeaveGame()

SNetPerformUpgrade()

SNetReceiveMessage()

SNetReceiveTurns()

SNetRegisterEventHandler()

SNetResetLatencyMeasurements()

SNetSelectGame()

SNetSelectProvider()

SNetSendMessage()

SNetSendTurn()

SNetStartGame()

SNetUnregisterEventHandler()

Callback Functions

CheckAuthProc()

CreateProc()

DrawDescProc()

EnumGamesProc()

EnumProvidersProc()

EventProc()

GetArtProc()

GetDataProc()

MessageBoxProc()

PlaySoundProc()

StatusProc()

Data Structures

SNETCAPS

SNETCREATEDATA

SNETPLAYERDATA

SNETPROGRAMDATA

SNETUIDATA

SNETVERSIONDATA


SNetCreateGame

Creates a new network game using the currently selected network provider, and adds the local player as the game master.  The game master is always player number one.

Rather than calling this function manually, an application will generally call SNetSelectGame() to present the user with a list of games and allow him to join a game or create a new one.

BOOL SNetCreateGame (

LPCSTR	gamename,

LPCSTR	gamepassword,

LPCSTR	gamedescription,

LPVOID	initdata,

DWORD	initdatabytes,

DWORD	maxplayers,

LPCSTR	playername,

LPCSTR	playerdescription,

DWORD	*playerid

);

Parameters

gamename

The name of the game being created, as specified by the player.  For example, Bobs Game.

gamepassword

A password for the game.  If the password is not blank, then the game is considered private.  It does not show up on lists of games, and players cannot join the game without knowing the password.  Passwords are not case sensitive.

gamedescription

A description of the game.  This can be generated by the program, and contain information about the game options.  On joining systems, the options strings may be simply displayed as text, or may be decoded by the game into a graphical or iconic representation of game options, such as whether fog of war is in effect.

initdata

A pointer to application-specific initialization data.  This data is sent to all joining players.  The application receives it on the joining side through the SNET_EVENT_INITDATA callback, which it is guaranteed to get on its first call to SNetReceiveMessage() or SNetReceiveTurns() after joining.  The maximum size of the initialization data is equal to the maximum message size for the current network provider.

initdatabytes

The number of bytes in the application-specific initialization data.

maxplayers

The maximum number of players which will be allowed to join this game.  This number must be less than or equal to the maximum number of players that was set during the call to SNetInitializeProvider().

playername

The name of the local player.

playerdescription

A description of the local player.  This can be generated by the program, and contain information such as the players character class or level.  On joining systems, it may be decoded into a graphical or iconic representation of the player.

playerid

The ID that is assigned to the player, if creating the game is successful.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No network provider has been initialized

•	No game name or description is specified

•	The maximum number of players is out of range

•	No player name or description is specified

•	No variable is given to receive the player ID

•	The system is out of memory

•	The network provider uses a server, and the server is unable to process the request


SNetDestroy

Closes all active games, uninitializes the network provider, and frees all memory used by this module.

Normally, a program should call StormDestroy() once at the end of the program, rather than calling the individual destroy functions.

BOOL SNetDestroy ();

Parameters

None.

Return Value

•	This function returns TRUE for success or FALSE for failure.


SNetEnumGames

Enumerates all games available on the current network provider which match the program and version IDs.  The callback function you provide is called once for each matching game.

Some network providers can take a significant amount of time to find all active games (for example, one second).  Instead of blocking for this duration, the function returns only the games it currently knows about, and then gives you a hint about when you should call it back to receive a more complete list.

Rather than calling this function manually, an application will generally call SNetSelectGame() to present the user with a list of games and allow him to join a game or create a new one.

BOOL SNetEnumGames (

SNETENUMGAMESPROC	callback,

DWORD	*hintnextcall

);

Parameters

callback

The applications callback function.  See EnumGamesProc() for a description.

hintnextcall

The time that the application should wait before calling this function again, in milliseconds.  If this number is zero, there is no need to call the function again.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No network provider has been initialized

•	No callback function is provided

•	The system is out of memory

•	The network provider is unable to retrieve a list of games


SNetEnumProviders

Enumerates all network providers installed on the system.  The callback function you provide is called once for each provider.  If desired, you can specify a minimum set of capabilities, and only providers which meet or exceed those capabilities will be returned.

Rather than calling this function manually, an application will generally call SNetSelectProvider() to present the user with a list of network providers and allow him to select and initialize one.

BOOL SNetEnumProviders (

SNETCAPSPTR	mincaps,

SNETENUMPROVIDERSPROC	callback

);

Parameters

mincaps

A pointer to an SNETCAPS structure specifying the minimum capabilities required of network providers.  The size field must be filled in which the size of the structure.  Any other field can contain a number to specify a minimum capability, or zero to specify that the field should be ignored.

If the mincaps parameter is NULL, all network providers are enumerated.

callback

The applications callback function.  See EnumProvidersProc() for a description.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No callback function is provided

•	The size field of the SNETCAPS structure is invalid


SNetGetNetworkLatency

Returns the expected or measured round-trip latency.  This is twice the approximate time, in milliseconds, that a message sent from one computer will take to reach another computer.

BOOL SNetGetNetworkLatency (

DWORD	measurementtype,

DWORD	*result

);

Parameters

measurementtype

An identifier specifying the way in which the latency should be measured.

Value	Meaning
SNET_LMT_EXPECTED	The expected latency for this network provider.  This value is always the same for any given network provider.
SNET_LMT_CURRENT	The current latency of the game.  This computer must currently be joined in a game.  The latency returned is the highest latency between this computer and any of the other players.
SNET_LMT_PEAK	The peak latency of the game.  This computer must currently be joined in a game.  The latency returned is the highest measured latency between this computer and any of the other players since the beginning of the game, or since the last call to SNetResetLatencyMeasurements().
result

The returned latency.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No network provider has been initialized

•	The measurement type identifier is invalid

•	The measurement type calls for a measured rather than expected latency, and no game has been created or joined

•	No variable is provided to receive the result


SNetGetNumPlayers

Returns the number of active players in the game, and the range of active player IDs.  The range of IDs may be larger than the number of active players if players have dropped out of the game.

BOOL SNetGetNumPlayers (

DWORD	*firstplayerid,

DWORD	*lastplayerid,

DWORD	*activeplayers

};

Parameters

firstplayerid

The lowest numbered ID of any active player.

lastplayerid

The highest numbered ID of any active player.

activeplayers

The total number of active players.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No network provider has been initialized

•	No game has been created or joined


SNetGetPlayerCaps

Returns the capabilities of an individual player.  You can use this function to get the latency between this machine and any other player in the game.

BOOL SNetGetPlayerCaps (

DWORD	playerid,

SNETCAPSPTR	caps

);

Parameters

playerid

The ID of the player for which capabilities will be returned.

caps

An SNETCAPS structure.  You must fill in the size field before passing this structure to SNetGetPlayerCaps().

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No network provider has been initialized

•	No game has been created or joined

•	No active player exists with the given ID

•	The size field of the SNETCAPS structure is invalid


SNetGetPlayerName

Returns the name of any player in the game.

BOOL SNetGetPlayerName (

DWORD	playerid,

LPSTR	buffer,

DWORD	buffersize

);

Parameters

playerid

The ID of the player whose name is being requested.

buffer

A string buffer into which the name will be copied.

buffersize

The size, in characters, of the buffer.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No network provider has been initialized

•	No game has been created or joined

•	No active player exists with the given ID

•	No buffer is given

•	The size of the buffer is zero


SNetGetProviderCaps

Returns the capabilities of the currently selected network provider.

BOOL SNetGetProviderCaps (

SNETCAPSPTR	caps

);

Parameters

caps

An SNETCAPS structure.  You must fill in the size field before passing this structure to SNetGetProviderCaps().

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No network provider has been initialized

•	The size field of the SNETCAPS structure is invalid


SNetGetTurnsInTransit

Returns the number of turns which have been from this machine with SNetSendTurn() but not yet received with SNetReceiveTurns().  It is generally a good idea to keep two or more turns in transit (on the wire) so that other machines can process turns without having to wait for them to be transmitted.

For example, if a game runs at the rate of two turns per second, and for each turn it simply sends its turn and then waits for turns from all other players to arrive, then the game speed may be cut in half when running on a high-latency network such as the Internet.  This is because at least a quarter of a second will be wasted for every turn waiting for turns to arrive from other players.

However, if the game is modified so that it always sends out turns two in advance of what it is processing (sending turn 3 and then processing all turns for turn 1, sending turn 4 and then processing all turns for turn 2, etc.) then the turns will have plenty of time for transmission, so no game delay will be required.

The two primary ways to compensate for latency in a turn-based game are:

1. 	Decrease the number of turns processed per second, or

2. 	Increase the number of turns in transit.

Since decreasing the number of turns processed per second compensates not only for latency problems but also bandwidth problems, it is probably best to fix the number of turns in transit at two and then adjust the number of turns per second.  You can get a recommendation for the number of turns per second from the network providers capabilities, returned during SNetEnumerateProviders().

BOOL SNetGetTurnsInTransit (

DWORD	*turns

);

Parameters

turns

The number of turns that have been sent from this computer with SNetSendTurn() but not yet received with SNetReceiveTurns().

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No network provider has been initialized

•	No game has been created or joined

•	No variable is provided to receive the result


SNetInitializeProvider

Initializes the given network provider, which will provide support for all further SNet calls.

Some providers can take a second or more to initialize, especially if initialization involves connecting to a server.

Rather than calling this function manually, an application will generally call SNetSelectProvider() to present the user with a list of network providers and allow him to select and initialize one.

BOOL SNetInitializeProvider (

DWORD	providerid,

SNETPROGRAMDATAPTR	programdata,

SNETPLAYERDATAPTR	playerdata,

SNETUIDATAPTR	interfacedata,

SNETVERSIONDATAPTR	versiondata

);

Parameters

providerid

The ID of the provider to be initialized.  This is obtained from a call to SNetEnumerateProviders().

You can also specify zero to use the null provider.  The null provider is used just like any other provider, but it does not make use of any communications medium.  It is provided so that single player games can use the same code as multi-player games.  To create a single player game using the null provider, first initialize the provider, then create a game using SNetCreateGame(), then send messages and turns using the SNet functions as normal.  At the end of the game, call SNetLeaveGame().

programdata

A pointer to a structure containing information about the program, such as the program name, version, and number of players supported.  This is a mandatory parameter.

playerdata

A pointer to a structure containing the name and description of the current player.  The provider may use this information if it performs a matchmaking process.  This is a mandatory parameter.

interfacedata

A pointer to a structure containing information about how the network provider should display user interface screens if necessary.  Most network providers will fail if this information is not given.  For example, the modem provider cannot query the user for a phone number to dial without the ability to display user interface screens.

versiondata

A pointer to a structure containing information about the application which is necessary for automatic version control.  Some network providers are capable of performing over-the-wire version updates.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	The program data is missing or invalid.

•	The player data is missing or invalid.

•	The interface data is missing or invalid, and the provider needs to display user interface in order to initialize itself.

•	The system is out of memory or resources

•	The network provider was unable to initialize itself.  For example, the IPX provider may fail if IPX support is not available, and the Battle.net provider may fail if it cannot contact any Battle.net servers.

•	The application needs to be upgraded before it can connect to the server.

If this function fails, the application should call GetLastError() to determine the reason for failure.  If GetLastError() returns SNET_ERROR_REQUIRES_UPGRADE, the application should call SNetPerformUpgrade().


SNetJoinGame

Joins an existing game.  Rather than calling this function manually, an application will generally call SNetSelectGame() to present the user with a list of games and allow him to join a game or create a new one.

To leave a game after joining, call SNetLeaveGame().

BOOL SNetJoinGame (

DWORD	gameid,

LPCSTR	gamename,

LPCSTR	gamepassword,

LPCSTR	playername,

LPCSTR	playerdescription,

DWORD	*playerid

);

Parameters

gameid

The ID of the game to be joined.  You can discover IDs of active games using SNetEnumGames().

gamename

The name of the game to be joined.  By passing a name, you can join a game which was not enumerated, such as a private game.  If gameid is not zero, this parameter is ignored.

gamepassword

The password of the game to be joined.  The function will fail if the password is incorrect.  If the game to be joined is not password protected, simply pass a blank password.

playername

The name of the local player.

playerdescription

A description of the local player.  This can be generated by the program, and contain information such as the players character class or level.

playerid

The ID that is assigned to the player, if joining is successful.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No network provider has been initialized

•	No player name or description is specified

•	No variable is provided to receive the player ID

•	The game owner cannot be contacted (possibly due to a firewall)

•	The game password is incorrect

•	The game is full or is closed to new players

•	The system is out of memory


SNetLeaveGame

Leaves the current game.  If the local player created the game using SNetCreateGame(), and hasnt yet started the game, then leaving will destroy the game.  Otherwise, the game will continue without the local player.

BOOL SNetLeaveGame();

Parameters

None.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No network provider has been initialized


SNetPerformUpgrade

Performs an automatic version update of the application.  You should call this function is SNetSelectProvider() or SNetInitializeProvider() fails and GetLastError() returns SNET_ERROR_REQUIRES_UPGRADE.

BOOL SNetPerformUpgrade (

DWORD	*upgradestatus

);

Parameters

upgradestatus

Returns one of the following values, specifying whether the upgrade was successful:

Value	Meaning
SNET_UPGRADE_FAILED	The upgrade failed or was canceled by the user.
SNET_UPGRADE_NOT_NEEDED	No upgrade is needed.
SNET_UPGRADE_SUCCEEDED	The upgrade succeeded.
SNET_UPGRADING_TERMINATE	The upgrade is currently in progress.  The patch program needs the application to terminate so that it can modify the applications EXE or DLL files.  The patch program will restart the application after the upgrade is complete.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No variable was provided to receive the upgrade status

•	The upgrade failed or was canceled by the user

•	No upgrade was needed


SNetReceiveMessage

This function receives the next unread message from any player.

BOOL SNetReceiveMessage (

DWORD	*senderplayerid,

LPVOID	*data,

DWORD	*databytes

);

Parameters

senderplayerid

If a message is available, this parameter returns the ID of the player who sent the message.

data

If a message is available, this parameter returns a pointer to the message data.  The pointer remains valid until the next call to an SNet function or to StormDestroy().

databytes

If a message is available, this parameter returns the number of bytes in the message.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No network provider has been initialized

•	No game has been created or joined

•	No messages are available


SNetReceiveTurns

This function receives the next set of turns from every active player, if all turns are available.

BOOL SNetReceiveTurns (

DWORD	firstplayerid,

DWORD	arraysize,

LPVOID	*arraydata,

LPDWORD	arraydatabytes,

LPDWORD	arrayplayerstatus

);

Parameters

firstplayerid

The player ID of the first player for which a turn will be received.  For example, if this parameter is one, then slot zero in the each array corresponds to player number one.

arraysize

The number of slots in each array.  This limits the number of players for which turns can be returned.

arraydata

An array of pointers, which will be filled in with pointers to the message data for each players turn.  Each returned pointer will remain valid until the next call to an SNet function or to StormDestroy().

arraydatabytes

An array of DWORDs, which will be filled in with the size, in bytes, of the message data for each players turn.

arrayplayerstatus

An array of DWORDs, which will be filled in with the status of each player, whether or not the function successfully returns turns for each player.  The following status codes can be returned:

Value	Meaning
SNET_PS_UNUSED	There is no active player in this slot.
SNET_PS_READY	The next turn for this player has been received.
SNET_PS_WAITING	The next turn for this player has not yet been received.
SNET_PS_NOTRESPONDING	The next turn for this player has not been received, and attempts to contact the computer for a resend have been unsuccessful.  The player may have lost his network connection.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No network provider has been initialized

•	No game has been created or joined

•	An array size of zero is specified

•	An array was not provided

•	This machine has not yet received the next turn from at least one player


SNetRegisterEventHandler

Registers a callback function which will be called when the specified event occurs.  Applications can use this functionality to receive notifications of players joining and leaving a game, among other things.

Events can occur at any time, but Storm queues the events and only dispatches them to the appropriate event handler function during an application call to SNetReceiveMessage() or SNetReceiveTurns().  This protects the application from reentrancy issues.

BOOL SNetRegisterEventHandler (

DWORD	eventid,

SNETEVENTPROC	callback

);

Parameters

eventid

The ID of the event for which the callback function is being registered.  The following events are defined:

Value	Meaning
SNET_EVENT_INITDATA	Used to receive application-specific initialization data that the game creator specified in the call to SNetCreateGame().
SNET_EVENT_GAMEDESTROY	The current game has been destroyed by the owner.
SNET_EVENT_GAMESTART	The current game has been started.
SNET_EVENT_PLAYERJOIN	A player has joined the current game.
SNET_EVENT_PLAYERLEAVE	A player has left the current game.

callback

A pointer to the callback function.  See EventProc() for a description.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	An invalid event ID was specified

•	No callback function was provided


SNetResetLatencyMeasurements

This function has two effects.  First, it clears the peak latency that has been measured since the beginning of the game, as returned by SNetGetNetworkLatency() with SNET_LMT_PEAK.  Second, it causes all players in the game to be immediately polled for a new current latency, as returned by SNetGetNetworkLatency() with SNET_LMT_CURRENT.

It can be useful to call SNetResetLatencyMeasurements() after a player drops out of a game, especially if the game bases its speed or number of turns per second on the measured latency of the current players.

BOOL SNetResetLatencyMeasurements ();

Parameters

None.

Return Value

This function returns TRUE for success or FALSE for failure.


SNetSelectGame

Supplies user interface screens to allow the player to select from a list of games or create a new game, then creates or joins the game and returns the local users game player ID.

BOOL SNetSelectGame (

DWORD	flags,

SNETPROGRAMDATAPTR	programdata,

SNETPLAYERDATAPTR	playerdata,

SNETUIDATAPTR	interfacedata,

SNETVERSIONDATAPTR	versiondata,

DWORD	*playerid

);

Parameters

flags

A set of flags specifying which options should be provided to the user.  The following flags are defined:

Value	Meaning
SNET_SF_ALLOWCREATE	The user is allowed to create new games.  If this flag is not specified, the user is only allowed to join existing games.

programdata

A pointer to a structure containing information about the program, such as the program name, version, and number of players supported.  This is a mandatory parameter.

playerdata

A pointer to a structure containing the name and description of the current player.  The provider may use this information if it performs a matchmaking process.  The provider also uses this information when creating or joining a game.  This is a mandatory parameter.

interfacedata

A pointer to a structure containing information about how the network provider should display user interface screens if necessary.  Most network providers will fail if this information is not given.  For example, the modem provider cannot query the user for a phone number to dial without the ability to display user interface screens.

versiondata

A pointer to a structure containing information about the application which is necessary for automatic version control.  Some network providers are capable of performing over-the-wire version updates.

playerid

The ID that is assigned to the player, if the function successfully creates or joins a game.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No network provider has been initialized.

•	The program data is missing or invalid.

•	The player data is missing or invalid.

•	The interface data is missing or invalid

•	No variable is provided to receive the player ID.

•	The user canceled the creation or joining process.

•	The system is out of memory.


SNetSelectProvider

Supplies user interface screens to allow the user to select a network provider, then initializes that provider.

BOOL SNetSelectGame (

SNETCAPSPTR	mincaps,

SNETPROGRAMDATAPTR	programdata,

SNETPLAYERDATAPTR	playerdata,

SNETUIDATAPTR	interfacedata,

SNETVERSIONDATAPTR	versiondata,

DWORD	*providerid

);

Parameters

programdata

A pointer to a structure containing information about the program, such as the program name, version, and number of players supported.  This is a mandatory parameter.

playerdata

A pointer to a structure containing the name and description of the current player.  The provider may use this information if it performs a matchmaking process. This is a mandatory parameter.

interfacedata

A pointer to a structure containing information about how the network provider should display user interface screens if necessary.  Most network providers will fail if this information is not given.  For example, the modem provider cannot query the user for a phone number to dial without the ability to display user interface screens.

versiondata

A pointer to a structure containing information about the application which is necessary for automatic version control.  Some network providers are capable of performing over-the-wire version updates.

providerid

The ID of the provider that was selected.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	The program data is missing or invalid.

•	The player data is missing or invalid.

•	The interface data is missing or invalid, and the provider needs to display interface during the initialization process.

•	The network provider was unable to initialize itself.  For example, the IPX provider may fail if IPX support is not available, and the Battle.net provider may fail if it cannot contact any Battle.net servers.

•	The application needs to be upgraded before it can connect to the server.

If this function fails, the application should call GetLastError() to determine the reason for failure.  If GetLastError() returns SNET_ERROR_REQUIRES_UPGRADE, the application should call SNetPerformUpgrade().


SNetSendMessage

Sends a message to another player, or to all players.  It must be received on the target computer using SNetReceiveMessage().

A message is different from a turn, in that messages can be sent between two individual players, and can be sent at any time, whereas turns are sent to all players at a specific interval.  The choice of whether to use messages or turns depends on the networking model of the game.  Games can also mix and match, using messages for some purposes and turns for others.

BOOL SNetSendMessage (

DWORD	targetplayerid,

LPVOID	data,

DWORD	databytes

);

Parameters

targetplayerid

The ID of the player to whom the message will be sent.  Specify SNET_BROADCASTPLAYERID to broadcast the message to all players.

data

A pointer to the message data.

databytes

The size of the message, in bytes.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No network provider has been initialized

•	No game has been created or joined

•	A player ID was given, and no active player exists with that ID

•	No data pointer was provided

•	The size of the message is zero

•	The system is out of memory


SNetSendTurn

Sends out the next turn for this computer.  The turn must be received on the local machine and all other machines in the game using SNetReceiveTurns().

Typically, a game will send a turn as soon as it is generated (for example, as soon as the user performs an action), and then receive turns at a specific rate, such as two turns per second.  By sending turns as soon as they are generated, rather than sending only two turns per second, the game ensures that turns are given as much time as possible to travel over the wire.  However, it is also important for the game to ensure that it has always sent more turns than it has processed, to ensure that there are always turns on the wire.  The game can accomplish this by checking the number of turns in transit, using SNetGetTurnsInTransit(), before calling SNetReceiveTurns().

BOOL SNetSendTurn (

LPVOID	data,

DWORD	databytes

);

Parameters

data

A pointer to the turn data.

databytes

The size of the turn data, in bytes.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No network provider has been initialized

•	No game has been created or joined

•	No data pointer was provided

•	The size of the turn is zero

•	The system is out of memory


SNetStartGame

Starts the current game.  Only the game master can call this function.  Once the game has been started, no new players can join, and the game will continue even if the game master has left.

The SNetStartGame() function was designed around games like Warcraft, where all players sit in a chat room while waiting for the game to join, and then start playing the game at the same time.  It makes less sense in a game like Quake where players can drop in and out of the game at any time.  For this reason, it will probably be removed and replaced with a more comprehensive API that allows individual control over such game attributes as whether new players can join, whether the game shows up in lists of games, and whether the game master is necessary to maintain the game.

BOOL SNetStartGame ();

Parameters

None.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	No network provider has been initialized

•	No game has been created or joined

•	The local player is not the master player

•	The game has already been started


SNetUnregisterEventHandler

This removes a given function from the list of registered event handlers.

BOOL SNetUnregisterEventHandler (

DWORD	eventid,

SNETEVENTPROC	callback

);

Parameters

eventid

The event ID for which the handler was registered.  See SNetRegisterEventHandler() for a list of event IDs.

callback

A pointer to the event handler function.

Return Value

This function returns TRUE for success or FALSE for failure.  The function can fail if:

•	An invalid event ID was specified

•	No callback function was provided


CheckAuthProc

CheckAuthProc() is a placeholder for an application-defined function name.

This function is called by the current network provider to determine whether the active user is authorized to join a game or chat channel.

BOOL CALLBACK CheckAuthProc (

DWORD	itemtype,

LPCSTR	playername,

LPCSTR	playerdescription,

DWORD	userflags,

LPCSTR	itemdescription,

LPSTR	errorbuffer,

DWORD	errorsize

);

Parameters

itemtype

An identifier which tells whether the name and description describe a game or a player.  It can be one of the following values:

Value	Meaning
SNET_AUTHTYPE_GAME	Item is a game.
SNET_AUTHTYPE_CHANNEL	Item is a chat channel.

playername

The name of the player.

playerdescription

An application defined string containing information about the player.

userflags

A set of flags for the player.  The following flags are currently defined:

Value	Meaning
SNET_DDPF_BLIZZARD	Player is a Blizzard employee
SNET_DDPF_MODERATOR	Player is a channel moderator
SNET_DDPF_SPEAKER	Player is a speaker for a special event
SNET_DDPF_SYSOP	Player is a sysop of the selected gaming service
SNET_DDPF_SQUELCHED	Player has been squelched by the local user

itemdescription

If itemtype is SNET_AUTHTYPE_GAME, this field contains the game description.  If itemtype is SNET_AUTHTYPE_CHANNEL, this field contains the channel name.

errorbuffer

A pointer to a string buffer which the application fills in with an error message in the case that authorization is not granted.

errorsize

The size, in characters, of the string buffer.

Return Value

This function should return TRUE if the user is authorized to join the game or channel, or FALSE if the function fails or the user is not authorized.


CreateProc

CreateProc() is a placeholder for an application-defined function name.

This function is called by from SNetSelectGame() if the user has decided to create a new game.  The create callback is responsible for display a dialog to the user to request game information like the game name and difficulty, and then calling SNetCreateGame().

BOOL CALLBACK CreateProc (

SNETCREATEDATAPTR	createdata,

SNETPROGRAMDATAPTR	programdata,

SNETPLAYERDATAPTR	playerdata,

SNETUIDATAPTR	interfacedata,

SNETVERSIONDATAPTR	versiondata,

DWORD	 *	playerid

);

Parameters

createdata

A structure provided by the service provider containing data that the application will need to create the game.  When the data in this structure conflicts with the applications own data, the application should use the data in the structure.  For example, the maxplayers field may be set lower than the applications maximum number of players if the network provider does not support the applications maximum number of players.

programdata

A structure containing the program data that was passed to SNetSelectGame().

playerdata

A structure containing the player data that was passed to SNetSelectGame().

interfacedata

A structure containing the interface data that was passed to SNetSelectGame(), modified as necessary to ensure that the dialog that the create callback displays fits with the network providers interface.

versiondata

A structure containing the version data that was passed to SNetSelectGame().

playerid

A pointer to a DWORD which the function should fill in with the player ID assigned in the call to SNetCreateGame().

Return Value

The application should return TRUE if it called SNetCreateGame() and the call was successful.  It should return FALSE if the game was not created for any reason.


DrawDescProc

DrawDescProc() is a placeholder for an application-defined function name.

This function is called by Storm or the current network provider when it needs to draw a game or player description.

BOOL CALLBACK DrawDescProc (

DWORD	providerid,

DWORD	itemtype,

LPCSTR	itemname,

LPCSTR	itemdescription,

DWORD	itemflags,

DWORD	itemcreationtime,

DWORD	drawflags,

LPDRAWITEMSTRUCT	drawdata

);

Parameters

providerid

The ID of the network provider which is making the request.

itemtype

An identifier which tells whether the name and description describe a game or a player.  It can be one of the following values:

Value	Meaning
SNET_DRAWTYPE_GAME	Item is a game
SNET_DRAWTYPE_PLAYER	Item is a player

itemname

The name of the game or player.

itemdescription

The description of the game or player.

itemflags

A set of flags for the game or player.  The following flags are currently defined for players:

Value	Meaning
SNET_DDPF_BLIZZARD	Player is a Blizzard employee
SNET_DDPF_MODERATOR	Player is a channel moderator
SNET_DDPF_SPEAKER	Player is a speaker for a special event
SNET_DDPF_SYSOP	Player is a sysop of the selected gaming service
SNET_DDPF_SQUELCHED	Player has been squelched by the local user

itemcreationtime

The creation time of the game, expressed as the number of seconds since midnight, January 1, 1970 UTC.

drawflags

A set of flags defining how the item should be drawn.  The following flags are defined:

Value	Meaning
SNET_DDF_INCLUDENAME	The callback function should draw the game name as well as the description.  If this flag is not specified then the game is already visible elsewhere on the screen, and only the description needs to be drawn.
SNET_DDF_MULTILINE	The area for the description is large enough to include more than one line of text.

drawdata

A structure containing information about the output device.  This includes the device context, and the rectangle (in client coordinates) to which the application should bound its output.

Return Value

This function should return TRUE if the description was successfully drawn, or FALSE if an error occurred.


EnumGamesProc

EnumGamesProc() is a placeholder for an application-defined function name.

This function is called by SNetEnumGames() once for each active game that matches the program and version IDs of the application.

BOOL CALLBACK EnumGamesProc (

DWORD	gameid,

LPCSTR	gamename,

LPCSTR	gamedescription

);

Parameters

gameid

Unique identifier of the game.  Pass this value to SNetJoinGame().

gamename

The name of the game.

gamedescription

A description of the game.

Return Value

This function should return TRUE to continue enumeration, or FALSE to stop.


EnumProvidersProc

EnumProvidersProc() is a placeholder for an application-defined function name.

This function is called by SNetEnumProviders() once for each network provider installed on the system.

BOOL CALLBACK EnumProvidersProc (

DWORD	providerid,

LPCSTR	name,

LPCSTR	requirements,

SNETCAPSPTR	caps

);

Parameters

providerid

The unique ID of the provider.  Pass this value to SNetInitializeProvider().

name

The name of the provider.

requirements

A string describing the requirements for using this provider, such as two computers connected by a serial cable and null-modem.

caps

The capabilities of this provider.

Return Value

This function should return TRUE to continue enumeration, or FALSE to stop.


EventProc

EventProc() is a placeholder for an application-defined function name.

This function is called to notify the application of a network event.  Network events are queued up, and only delivered to the application when it calls SNetReceiveMessage() or SNetReceiveTurns().

void CALLBACK EventProc (

SNETEVENTPTR event

);

Parameters

eventdata

A pointer to a structure describing the event, and containing the ID of the player who caused the event to be generated.

Return Value

This function does not return a value.


GetArtProc

GetArtProc() is a placeholder for an application-defined function name.

This function is called by Storm or the current network provider to get artwork necessary for displaying a user interface screen.

BOOL CALLBACK GetArtProc (

DWORD	 providerid,

DWORD	 artid,

LPPALETTEENTRY	 palette,

LPBYTE	 buffer,

DWORD	 buffersize,

int	*width,

int	*height,

int	*bitdepth

);

Parameters

providerid

The ID of the network provider which is requesting the artwork, or zero if the artwork is being requested for a screen which is not provider specific.

artid

The ID of the artwork being requested.  The standard artwork IDs are shown below.  Network providers can define their own IDs, above 0x80000000, for artwork that is specific to the provider.

Value	Meaning
SNET_ART_BACKGROUND	The background bitmap for the dialog.
SNET_ART_BUTTONTEXTURE	The texture which is tiled over buttons in the dialog.

palette

A pointer to an array of palette entries, to be filled in by the function.  This parameter can be NULL if the provider doesnt need to load a palette.

buffer

A pointer to a buffer where the function should copy the bitmap data.  This parameter can be NULL if the provider doesnt need the bitmap data, or if it is only querying the bitmap dimensions.

buffersize

The size of the buffer pointed to by buffer.

width

A pointer to a variable which the function should fill in with the width of the bitmap.  This parameter can be NULL if the provider doesnt need the bitmap width.

height

A pointer to a variable which the function should fill in with the height of the bitmap.  This parameter can be NULL if the provider doesnt need the bitmap height.

bitdepth

A pointer to a variable which the function should fill in with the number of bits per pixel in the bitmap.  This parameter can be NULL if the provider doesnt need the bitmap pixel depth.

Return Value

This function should return TRUE if the picture was successfully loaded, or FALSE if an error occurred.


GetDataProc

GetDataProc() is a placeholder for an application-defined function name.

This function can be called by a network provider to get data other than artwork from the current application.  To get artwork, a network provider calls GetArtProc().

BOOL CALLBACK GetDataProc (

DWORD	providerid,

DWORD	dataid,

LPVOID	buffer,

DWORD	buffersize,

DWORD	*bytesused

);

Parameters

providerid

The ID of the network provider which is requesting the artwork.

dataid

The ID of the data item being requested.  There are no predefined IDs.  Network providers can define their own IDs, above 0x80000000, for data that is specific to the provider.

buffer

A pointer to a buffer where the function should copy the data.  This parameter can be NULL if the provider is only querying the data size.

buffersize

The size of the buffer pointed to by buffer.

bytesused

A pointer to a variable which the function should fill in with the number of bytes written to the buffer.  If the buffer is NULL, the function should fill in the total number of bytes in the data item.

Return Value

This function should return TRUE if the data ID is valid and can be provided, or FALSE otherwise.


MessageBoxProc

MessageBoxProc() is a placeholder for an application-defined function name.

This function is called by Storm or the current network provider when it needs to display a message box.

BOOL CALLBACK MessageBoxProc (

HWND	parentwindow,

LPCSTR	text,

LPCSTR	caption,

UINT	type

);

Parameters

parentwindow

A handle to the window that the message box should use as its parent.

text

The text of the message.  The procedure should dynamically scale the message box in order to fit the entire text.

caption

The caption, which should be used as the title of the message box window.

type

A set of flags which indicate the type of the message box.  The following constants are allowed:

Value	Meaning
MB_OK	The message box contains one push button: OK.  This is the default.
MB_OKCANCEL	The message box contains two push buttons: OK and Cancel.
MB_RETRYCANCEL	The message box contains two push buttons: Retry and Cancel.
MB_YESNO	The message box contains two push buttons: Yes and No.
MB_YESNOCANCEL	The message box contains three push buttons: Yes, No, and Cancel.
MB_DEFBUTTON1	The first button is the default button.  This is the default.
MB_DEFBUTTON2	The second button is the default button.
MB_DEFBUTTON3	The third button is the default button.

flags

A set of flags specifying how the sound should be played.  Use the SND_* constants defined in Windows.h.

Return Value

The return value is FALSE if the procedure is not able to display the message box.

Otherwise, the return value is one of the following item values returned by the dialog box:

IDOK	The OK button was selected.
IDCANCEL	The Cancel button was selected.
IDYES	The Yes button was selected.
IDNO	The No button was selected.
IDRETRY	The Retry button was selected.


PlaySoundProc

PlaySoundProc() is a placeholder for an application-defined function name.

This function is called by Storm or the current network provider when it needs to play a sound effect.

BOOL CALLBACK PlaySoundProc (

DWORD	providerid,

DWORD	soundid,

DWORD	flags

);

Parameters

providerid

The ID of the network provider which is making the request.

soundid

The ID of the requested sound effect.  The standard IDs are shown below.  Network providers can define their own IDs, above 0x80000000, for sound effects that are specific to the provider.

Value	Meaning
SNET_SND_CHANGEFOCUS	A sound to indicate that the user has changed to focus to a new menu or list-box item.
SNET_SND_SELECTITEM	A sound to indicate that the user has selected the current item.

flags

A set of flags specifying how the sound should be played.  Use the SND_* constants defined in Windows.h.

Return Value

This function should return TRUE if the sound was successfully played, or FALSE if an error occurred.


StatusProc

StatusProc() is a placeholder for an application-defined function name.

This function is called by the network provider during a long operation to allow the program to provide visual feedback to the user.

BOOL CALLBACK StatusProc (

LPCSTR	statustext,

DWORD	workcompleted,

DWORD	estimatedworkremaining,

DWORD	flags,

SNETABORTPROC	abortproc

);

Parameters

statustext

A human-readable description of the current status of the operation.

workcompleted

A value representing the amount of work on this operation that the network provider has already completed.

estimatedworkremaining

A value representing the network providers best estimate for the amount of work remaining.  If the application wants to display the progress as a percent, it can use the following equation:

percent = (completed*100)/(completed+remaining).

flags

A set of flags which specify the state of the service provider.  There are no flags currently defined.

abortproc

A pointer to a function that the application can call to cancel the current operation.

Return Value

If the application uses this information, it should return TRUE.  Otherwise, it should return FALSE.


SNETCAPS

The SNETCAPS structure contains capabilities for a network provider or a player.

typedef struct _SNETCAPS {

DWORD	size;

DWORD	flags;

DWORD	maxmessagesize;

DWORD	maxqueuesize;

DWORD	maxplayers;

DWORD	bytessec;

DWORD	latencyms;

DWORD	defaultturnssec;

DWORD	defaultturnsintransit;

} SNETCAPS, *SNETCAPSPTR;

Members

size

The size of the structure, in bytes.  Must be filled in by the application.

flags

Network capability flags.  No flags are currently defined.

maxmessagesize

The maximum size, in bytes, of a message or turn that can be sent using this network provider.

maxqueuesize

The maximum size of the outgoing message queue.  This field is only meaningful if the network provider makes use of Microsoft DirectPlay.

maxplayers

The maximum number of players supported by this network provider.

bytessec

The expected bandwidth of the communications medium, expressed in bytes per second.

latencyms

The expected latency of the communications medium, expressed as the number of milliseconds for a round-trip transmission.

defaultturnssec

The recommended number of turns per second for this network provider.

defaultturnsintransit

The recommended number of turns that the application should maintain in transit when using this network provider.


SNETCREATEDATA

The SNETCREATEDATA structure is used in the create game callback function to communicate information about the current providers abilities.

typedef struct _SNETCREATEDATA {

DWORD	size;

DWORD	providerid;

DWORD	maxplayers;

DWORD	createflags;

} SNETCREATEDATA, *SNETCREATEDATAPTR;

Members

size

The size of the structure, in bytes.

providerid

The ID of the currently selected provider.

maxplayers

The maximum number of players that can join the game.  This value is the minimum of the maximum number of players the application supports and the maximum number of players the provider supports.

createflags

A set of flags specifying what creation options are available.  The following flags are defined:

Value	Meaning
SNET_CF_ALLOWPRIVATEGAMES	The creation callback function should allow the user the opportunity to create a private game.


SNETPLAYERDATA

The SNETPLAYERDATA function contains information about the local player.  This information is required when initializing a provider, since the provider may provide a matchmaking service, and when creating or joining a game.

typedef struct _SNETPLAYERDATA {

DWORD	size;

DWORD	playername;

DWORD	playerdescription;

} SNETPLAYERDATA, *SNETPLAYERDATAPTR;

Members

size

The size of the structure, in bytes.

playername

The name of the local player.

playerdescription

A description of the local player.  This can be generated by the program, and contain information such as the players character class or level.


SNETPROGRAMDATA

The SNETPROGRAMDATA structure contains information about the application, such as the program name and version number.

typedef struct _SNETPROGRAMDATA {

DWORD	size;

LPCSTR	programname;

LPCSTR	programdescription;

DWORD	programid;

DWORD	versionid;

DWORD	reserved;

DWORD	maxplayers;

LPVOID	initdata;

DWORD	initdatabytes;

} SNETPROGRAMDATA, *SNETPROGRAMDATAPTR;

Members

size

The size of the structure, in bytes.

programname

The name of the program.

programdescription

The description of the program.  This usually includes a name and version number.  It is displayed at the bottom of the standard connection screens.  If this field is not provided, Storm will automatically generate it using the EXE files product version information.

programid

A unique 32-bit identifier for the application.  The use of this unique identifier allows multiple applications using Storm to create games on the same network without interfering with each other.

versionid

A unique 32-bit identifier for the network version of the application.  This number should be incremented whenever a change in the application makes it incompatible with older versions.

reserved

Reserved -- must be set to 0.

maxplayers

The maximum number of players per game supported by the application.

initdata

Application-specific initialization data.  This data is provided by the game creator, and is available to all joining computers through the SNET_EVENT_INITDATA callback.

initdatabytes

The size of the application-specific initialization data.


SNETUIDATA

The SNETUIDATA structure contains information which Storm and the network providers use to display user interface on behalf of the application program.

typedef struct _SNETUIDATA {

DWORD	size;

HWND	parentwindow;

SNETGETARTPROC	artcallback;

SNETCHECKAUTHPROC	authcallback;

SNETCREATEPROC	createcallback;

SNETDRAWDESCPROC	drawdesccallback;

SNETSELECTEDPROC	selectedcallback;

SNETMESSAGEBOXPROC	messageboxcallback;

SNETPLAYSOUNDPROC	soundcallback;

SNETSTATUSPROC	statuscallback;

SNETGETDATAPROC	getdatacallback;

} SNETUIDATA, *SNETUIDATAPTR;

Members

size

The size of the structure, in bytes.

parentwindow

The window handle of the active window.  If Storm or a network provider creates a dialog box, it will use this handle for the parent window.

artcallback

A pointer to a function which Storm or a network provider can call to obtain artwork for the dialog background or controls.

authcallback

A pointer to a function which the network provider calls to determine whether the local player has access to a chat room.  This only applies to network providers which provide chat functionality.

createcallback

A pointer to a function which the network provider calls when the user has decided to create a game.  This function is responsible for asking the user for the game name and options, and then calling SNetCreateGame().

drawdesccallback

A pointer to a function which the network provider calls if it needs to draw a game or player description.  This allows the application to perform its own drawing.  For example, it could convert a cryptic description string which only the application understands, like FOG LOW BATTLE.PUD into a group of icons which would represent the game options in a way players could easily understand.

selectedcallback

A pointer to a function which Storm calls when the user selects a network provider.  This provides the application a chance to review the network providers ID and capabilities, and either accept the selection or present the user with an error message and reject the selection.

messageboxcallback

A pointer to a function which Storm and the network provider can use to display message boxes.

soundcallback

A pointer to a function which Storm and the network provider can use to play sound effects.

statuscallback

A pointer to a function that the network provider can use to provide feedback on the status of a long operation.

getdatacallback

A pointer to a function that the network provider can use to request provider-specific data from the application.


SNETVERSIONDATA

The SNETVERSIONDATA structure contains information that is needed to perform an over-the-wire program upgrade.

typedef struct _SNETVERSIONDATA {

DWORD	size;

LPCSTR	versionstring;

LPCSTR	executablefile;

LPCSTR	originalarchivefile;

LCPSTR	patcharchivefile;

} SNETVERSIONDATA, *SNETVERSIONDATAPTR;

Members

size

The size of the structure, in bytes.

versionstring

A human-readable string representing the product version.  If this string is provided, it overrides the product version string in the executable files version information resource.

executablefile

The full path name of the programs executable file.

originalarchivename

The full path name to the archive file which contains all of the programs data.  This file will typically be located on CD.

patcharchivefile

The full path name to the archive file which contains patched program data.  This file must be located on the users hard drive.