Inside Macintosh: Apple Game Sprockets Guide /

Chapter 4 - NetSprocket / NetSprocket Reference

NetSprocket Functions / Hosting and Joining a Game

NSpGame_Host

You can use the NSpGame_Host function to create a new game object. You use this function when you are preparing to host a game.

OSStatus NSpGame_Host (
		NSpGameReference *outGame,
		NSpProtocolListReference inProtocolList,
		UInt32 inMaxPlayers,
		ConstStr31Param inGameName,
		ConstStr31Param inPassword,
		ConstStr31Param inPlayerName,
		NSpPlayerType inPlayerType,
		NSpTopology inTopology,
		NSpFlags inFlags);

outGame

The address of a game reference which will be filled in by this function. Upon successful return, it will contain a pointer to the newly created game object. This field is invalid if the function returns anything other than noErr.

inProtocolList

An opaque reference to a list of protocols that has been returned from DoModalHostDialog, or created by you in your own application for advertising your game on the network.

inMaxPlayers

The maximum number of players permitted to join the game. If you want to allow unlimited players, set this value to 0. NetSprocket is more efficient when the maximum number of players is set in the inMaxPlayers field. The number of allowed groups does not affect the maximum number of players.

inGameName

A Pascal string containing the name of the game that will appear in game browsers. You must pass a valid Pascal string in this field.

inPassword

The value that prospective players must match to join the game. Players who do not enter a correct password will not be allowed to join. Use NULL if you do require a password for players joining your game.

inPlayerName

The name of the player using the application hosting the game. If there is no player using the application hosting the game, this value should be set to NULL. If the value is set to NULL, then no player will be created on the application hosting the game.

inPlayerType

The player type, which is used only if there is a player using the application hosting the game. This parameter is stored in NetSprocket's player information table and may be used by the game application. It is not used by NetSprocket.

inTopology

A constant indicating the topology to use in the game. The only topology implemented in version 1.0 is client/server, indicated by the constant kNSpClientServer.

inFlags

Options for creating the new game object. The only permissible value of inFlags in NetSprocket version 1.0 is kNSpGameFlag_DontAdvertise, which causes the NSpGame_Host function to create a game object, but not actually advertise the game on the network.

function result

A result code of noErr, or a NetSprocket or Open Transport result code.

DESCRIPTION

Once the game is created, the game will automatically be advertised on the protocols in the list.

When you have created a game object by calling NSpGame_Host, you will pass the game object to other host functions you call. Do not use this function when you plan to join a game. If you are joining a game, use the NSpGame_Join function.

NSpGame_Host will return noErr upon successful completion, placing the new game object in the outGame parameter. If the game could not be created for some reason, the NSpGameReference will be invalid (NULL). You should check the result code and determine the appropriate course of action.