Inside Macintosh: Apple Game Sprockets Guide /

Chapter 4 - NetSprocket / NetSprocket Reference

NetSprocket Functions / Hosting and Joining a Game

NSpJoinRequestHandlerProcPtr

This is a function that you as the game developer must provide if you are going to provide a custom join request handler. You must write the function as defined below. Once you have installed your join request handler, it will be called whenever a new player wishes to enter the game. Your function must return true or false, telling NetSprocket whether or not to admit the prospective player.

typedef pascal Boolean (*NSpJoinRequestHandlerProcPtr) (
	NSpGameReference inGame,
	NSpJoinRequestMessage *inMessage,
	void* inContext,
	Str255 outReason);

inGame

An opaque reference to the game object that received the join request.

inMessage

A pointer to the join request message. This is data passed to your function by NetSprocket. It will contain the name, password, and any custom data that your game specifies.

inContext

The context pointer you passed to NetSprocket when you first installed the join request handler.

outReason

A pointer to a Pascal string that NetSprocket will allocate for you. You can use this string to send textual information to a player. For example, if you are going to deny a join request, you may send your reason for denial into outReason.

function result

A value of true to inform NetSprocket to allow the prospective player into the game, or false to deny entry based on the criteria you have established.

DESCRIPTION

The purpose of the custom function is to provide the game developer more flexibility in controlling access to the game, rather than having NetSprocket allow players to join the game based on the password and minimum round-trip time of the prospective player. For example, you may want to restrict play to a particular network zone. Also, you may decide that certain levels of games may be played only by players with a previous score history.

Note

Before calling your request handler, NetSprocket will always make two checks for a prospective player. First, it will make sure that the prospective player's round-trip time meets your minimum requirements, if you have specified any. Second, it will make sure that allowing this player into the game will not exceed your maximum player count.You should not release the message passed to this function.