Inside Macintosh: Apple Game Sprockets Guide /

Chapter 4 - NetSprocket

Summary of NetSprocket

Constants

#define  kNSpMaxPlayerNameLen          31
#define  kNSpMaxGroupNameLen           31
#define  kNSpMaxPasswordLen            31
#define  kNSpMaxGameNameLen            31
#define  kNSpMaxDefinitionStringLen    255

Network Message Priority Flags

enum {
   kNSpJunk                            = 0x10000000,
   kNSpNormal                          = 0x20000000,
   kNSpRegistered                      = 0x30000000
};

Network Message Delivery Flags

enum {
   kNSpFailIfPipeFull                  = 0x00000001,
   kNSpSelfSend                        = 0x00000002,
   kNSpBlocking                        = 0x00000004
};

Options for Hosting, Joining, and Ending Games

enum {
   kNSpGameFlag_DontAdvertise          = 0x00000001,
   kNSpGameFlag_ForceTerminateGame     = 0x00000002
};

Network Message Types

enum {
   kNSpSystemMessagePrefix       = 0x80000000,
   kNSpError                     = kNSpSystemMessagePrefix | 0x7FFFFFFF,
   kNSpJoinRequest               = kNSpSystemMessagePrefix | 0x00000001,
   kNSpJoinApproved              = kNSpSystemMessagePrefix | 0x00000002,
   kNSpJoinDenied                = kNSpSystemMessagePrefix | 0x00000003,
   kNSpPlayerJoined              = kNSpSystemMessagePrefix | 0x00000004,
   kNSpPlayerLeft                = kNSpSystemMessagePrefix | 0x00000005,
   kNSpHostChanged               = kNSpSystemMessagePrefix | 0x00000006,
   kNSpGameTerminated            = kNSpSystemMessagePrefix | 0x00000007
};

Reserved Player IDs for Network Messages

enum {
   kNSpAllPlayers                      = 0x00000000,
   kNSpServerOnly                      = 0xFFFFFFFF
};

Topology Types

typedef enum {
   kNSpClientServer                    = 0x00000001
} NSpTopology;

Data Types

typedef     SInt32      NSpEventCode;
typedef     SInt32      NSpGameID;
typedef     SInt32      NSpPlayerID;
typedef     NSpPlayerID NSpGroupID;
typedef     UInt32      NSpPlayerType;
typedef     SInt32      NSpFlags;

Opaque Game Reference Structures

typedef     struct      NSpGamePrivate    *NSpGameReference;
typedef     struct      NSpProtocolPrivate*NSpProtocolReference;
typedef     struct      NSpListPrivate    *NSpProtocolListReference;
typedef     struct      NSPAddressPrivate *NSpAddressReference;

Player Information Structure

typedef struct NSpPlayerInfo {
   NSpPlayerID                id;
   NSpPlayerType              type;
   Str31                      name;
   UInt32                     groupCount;
   NSpGroupID                 groups[kVariableLengthArray];
} NSpPlayerInfo, *NSpPlayerInfoPtr;

Player List Structure

typedef struct NSpPlayerEnumeration {
   UInt32                     count;
   NSpPlayerInfoPtr           playerInfo[kVariableLengthArray];
} NSpPlayerEnumeration, *NSpPlayerEnumerationPtr;

Group Information Structure

typedef struct NSpGroupInfo {
   NSpGroupID                 id;
   UInt32                     playerCount;
   NSpPlayerID                players[kVariableLengthArray];
} NSpGroupInfo, *NSpGroupInfoPtr;

Group Enumeration Structure

typedef struct NSpGroupEnumeration {
   UInt32                     count;
   NSpGroupInfoPtr            groups[kVariableLengthArray];
} NSpGroupEnumeration, *NSpGroupEnumerationPtr;

Game Information Structure

typedef struct NSpGameInfo {
   UInt32                     maxPlayers;
   UInt32                     currentPlayers;
   UInt32                     currentGroups;
   NSpTopology                topology;
   UInt32                     reserved;
   Str31                      name;
   Str31                      password;
} NSpGameInfo;

Message Header Structure

typedef struct NSpMessageHeader {
   UInt32                     version;
   SInt32                     what;
   NSpPlayerID                from;
   NSpPlayerID                to;
   UInt32                     id;
   UInt32                     when;
   UInt32                     messageLen;
} NSpMessageHeader;

Error Message Structure

typedef struct NSpErrorMessage {
   NSpMessageHeader           header;
   OSStatus                   error;
} NSpErrorMessage;

Join Request Message Structure

typedef struct NSpJoinRequestMessage {
   NSpMessageHeader           header;
   Str31                      name;
   Str31                      password;
   UInt32                     type;
   UInt32                     customDataLen;
   UInt8                      customData[kVariableLengthArray];
} NSpJoinRequestMessage;

Join Approved Message Structure

typedef struct NSpJoinApprovedMessage {
   NSpMessageHeader           header;
} NSpJoinApprovedMessage;

Join Denied Message Structure

typedef struct NSpJoinDeniedMessage {
   NSpMessageHeader           header;
   Str255    reason;
} NSpJoinDeniedMessage;

Player Joined Message Structure

typedef struct NSpPlayerJoinedMessage {
   NSpMessageHeader           header;
   UInt32                     playerCount;
   NSpPlayerInfo              playerInfo;
} NSpPlayerJoinedMessage;

Player Left Message Structure

typedef struct NSpPlayerLeftMessage {
   NSpMessageHeader           header;
   UInt32                     playerCount;
   NSpPlayerID                playerID;
} NSpPlayerLeftMessage;

Host Changed Message Structure

typedef struct NSpHostChangedMessage {
   NSpMessageHeader           header;
   NSpPlayerID                newHost;
} NSpHostChangedMessage;

Game Terminated Message Structure

typedef struct NSpGameTerminatedMessage {
   NSpMessageHeader           header;
} NSpGameTerminatedMessage;

NetSprocket Functions

Initializing NetSprocket

OSStatus NSpInitialize		(UInt32 inStandardMessageSize,
				UInt32 inBufferSize,
				UInt32 inQElements,
				NSpGameID inGameID,
				UInt32 inTimeout);

typedef pascal void (*NSpCallbackProcPtr)
				(NSpGameReference inGame,
				void *inContext,
				NSpEventCode inCode,
				OSStatus inStatus,
				void* inCookie);

OSStatus NSpInstallCallbackHandler (NSpCallbackProcPtr inHandler,
				void *inContext);

Human Interface Functions

NSpAddressReference NSpDoModalJoinDialog
				(ConstStr31Param inGameType,
				ConstStr31Param inEntityListLabel,
				Str31 ioName,
				Str31 ioPassword);

Boolean NSpDoModalHostDialog	(NSpProtocolListReference ioProtocolList,
				Str31 ioGameName,
				Str31 ioPlayerName,
				Str31 ioPassword);

Hosting and Joining a Game

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

OSStatus NSpGame_Join 	(NSpGameReference *outGame,
				NSpAddressReference inAddress,
				ConstStr31Param inName,
				ConstStr31Param inPassword,
				NSpPlayerType inType,
				Uint32 inUserDataLen,
				void *inUserData,
				NSpFlags inFlags);

OSStatus NSpGame_EnableAdvertising
				(NSpGameReference inGame,
				NSpProtocolReference inProtocol,
				Boolean inEnable);
				
OSStatus NSpGame_Delete		(NSpGameReference inGame,
				NSpFlags inFlags);

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

OSStatus NSpInstallJoinRequestHandler
				(NSpJoinRequestHandlerProcPtr inHandler,
				void *inContext);

Sending and Receiving Messages

OSStatus NSpMessage_Send	(NSpGameReference inGame,
				NSpMessageHeader *inMessage,
				NSpFlags inFlags);

NSpMessageHeader *NSpMessage_Get(NSpGameReference inGame);
				void NSpMessage_Release(NSpGameReference inGame,
				NSpMessageHeader *inMessage);

typedef pascal Boolean 	(*NSpMessageHandlerProcPtr)
				(NSpGameReference inGame,
				NSpMessageHeader *inMessage,
				void *inContext);

OSStatus NSpInstallAsyncMessageHandler (NSpMessageHandlerProcPtr inHandler,
					void *inContext);

Managing Network Protocols

OSStatus NSpProtocol_Create	(const char* inDefinitionString,
				NSpProtocolReference *outReference);
				void NSpProtocol_Delete(NSpProtocolReference inProtocolRef);

OSStatus NSpProtocol_ExtractDefinitionString
				(NSpProtocolReference inProtocolRef,
				char *outDefinitionString);

OSStatus NSpProtocolList_Create	(NSpProtocolReference inProtocolRef,
				NSpProtocolListReference *outList);

void NSpProtocolList_Delete	(NSpProtocolListReference inProtocolList);

OSStatus NSpProtocolList_Append	(NSpProtocolListReference inProtocolList,
				NSpProtocolReference inProtocolRef);

OSStatus NSpProtocolList_Remove	(NSpProtocolListReference inProtocolList,
				NSpProtocolReference inProtocolRef);

OSStatus NSpProtocolList_RemoveIndexed
				(NSpProtocolListReference inProtocolList,
				UInt32 inIndex);

UInt32 NSpProtocolList_GetCount	(NSpProtocolListReference inProtocolList);

NSpProtocolReference NSpProtocolList_GetIndexedRef
				(NSpProtocolListReference inProtocolList,
				UInt32 inIndex);

NSpProtocolReference NSpProtocol_CreateAppleTalk (ConstStr31Param inNBPName,
				ConstStr31Param inNBPType,
				UInt32 inMaxRTT,
				UInt32 inMinThruput);

NSpProtocolReference NSpProtocol_CreateIP 	(InetPort inPort,
				UInt32 inMaxRTT,
				UInt32 inMinThruput);

Managing Player Information

NSpPlayerID NSpPlayer_GetMyID	(NSpGameReference inGame);

OSStatus NSpPlayer_GetInfo	(NSpGameReference inGame,
				NSpPlayerID inPlayerID,
				NSpPlayerInfoPtr *outInfo);

void NSpPlayer_ReleaseInfo	(NSpGameReference inGame,
				NSpPlayerInfoPtr inInfo);

OSStatus NSpPlayer_GetEnumeration	(NSpGameReference inGame,
					NSpPlayerEnumerationPtr *outPlayers);

void NSpPlayer_ReleaseEnumeration	(NSpGameReference inGame,
					NSpPlayerEnumerationPtr inPlayers);

UInt32 NSpPlayer_GetRoundTripTime	(NSpGameReference inGame,
					NSpPlayerID inPlayer,
					UInt32 inTimeout);

UInt32 NSpPlayer_GetThruput	(NSpGameReference inGame,
				NSpPlayerID inPlayer,
				UInt32 inTimeout);

Managing Groups of Players

OSStatus NSpGroup_Create	(NSpGameReference inGame,
				NSpGroupID *outGroupID);

OSStatus NSpGroup_Delete	(NSpGameReference inGame,
				NSpGroupID inGroupID);

OSStatus NSpGroup_AddPlayer	(NSpGameReference inGame,
				NSpGroupID inGroupID,
				NSpPlayerID inPlayerID);

OSStatus NSpGroup_RemovePlayer	(NSpGameReference inGame,
				NSpGroupID inGroupID,
				NSpPlayerID inPlayerID);

OSStatus NSpGroup_GetInfo	(NSpGameReference inGame,
				NSpGroupID inGroupID,
				NSpGroupInfoPtr *outInfo);

void NSpGroup_ReleaseInfo	(NSpGameReference inGame,
				NSpGroupInfoPtr inInfo);

OSStatus NSpGroup_GetEnumeration	(NSpGameReference inGame,
					NSpGroupEnumerationPtr *outGroups);

void NSpGroup_ReleaseEnumeration	(NSpGameReference inGame,
					NSpGroupEnumerationPtr inGroups);

Utility Functions

void NSpClearMessageHeader	(NSpGameReference inGame,
				NSpMessageHeader *ioMessage);

UInt32 NSpGetCurrentTimeStamp	(NSpGameReference inGame);
			
NSpAddressReference NSpConvertOTAddrToAddressReference
				(OTAddress *inAddress);

OTAddress *NSpConvertAddressReferenceToOTAddr
				(NSpAddressReference inAddress);

void NSpReleaseAddressReference	(NSpAddressReference inAddress);

Result Codes

noErr	0	No error
kNSpInitializationFailedErr	-30360	NetSprocket could not be initialized
kNSpAlreadyInitializedErr	-30361	NetSprocket has already been initialized
kNSpTopologyNotSupportedErr	-30362	The requested topology is unimplemented, or invalid value
kNSpMessageSizeTooBigErr	-30363	Current memory conditions prevent message from being sent
kNSpBufferTooSmallErr	-30364	The buffer allocated is too small to handle the data
kNSpReceiveDataErr	-30365	A problem occurred when attempting to receive data
kNSpProtocolNotAvailableErr	-30366	A protocol reference indicated a protocol that is unavailable
kNSpInvalidGameRefErr	-30367	An invalid game reference was passed
kNSpInvalidNetMessageErr	-30368	An invalid message was passed
kNSpInvalidParameterErr	-30369	A generic parameter error occurred
kNSpOTNotPresentErr	-30370	Open Transport is not installed or not installed correctly
kNSpHostFailedErr	-30371	An attemp to host a game failed
kNSpNotHostAddressErr	-30372	The address specified does not identify a NetSprocket host
kNSpMemAllocationErr	-30373	NetSprocket has run out of memory
kNSpAlreadyAdvertisingErr	-30374	The game is already being advertised on the specified protocol
kNSpNoTypeSpecifiedErr	-30375	An AppleTalk protocol reference that does not specify an NBP type was passed to the host
kNSpNotAdvertisingErr	-30376	The game is not being advertised at this time
kNSpInvalidAddressErr	-30377	An invalid address was passed
kNSpFreeQExhaustedErr	-30378	NetSprocket has exhausted its allocated queue elements and new messages will be dropped
kNSpRemovePlayerFailedErr	-30379	Your attempt to remove a player failed
kNSpAddressInUseErr	-30380	You are attempting to use an address that is already in use
NSpFeatureNotImplementedErr	-30381	You called a NetSprocket function that is not implemented
NSpNameRequiredErr	-30382	You atemped to join a game without specifying a player name
NSpInvalidPlayerIDErr	-30383	You tried to send a message to or get information about a player that is not currently in the game
NSpInvalidGroupIDErr	-30384	You tried to send a message to, or get information about a group that is not currently in the game
NSpNoPlayersErr	-30385	Returned by NSpPlayer_Enumerate when there are no players
NSpNoGroupsErr	-30386	Returned by NSpGroup_Enumerate when there are no groups
NSpNoHostVolunteersErr	-30387	Returned by NSpGame_Delete when called by a host and there are no other players capable of taking over the game
kNSpCreateGroupFailedErr	-30388	The attempt to creat a group failed
NSpAddPlayerFailedErr	-30389	An attempt to add a player to a group failed
NSpInvalidDefinitionErr	-30390	A invalid protocol definition string was passed to NSpProtocol_Create
NSpInvalidProtocolRefErr	-30391	An invalid protocol reference was passed
NSpInvalidProtocolListErr	-30392	An invalid protocol list was passed
kNSpTimeoutErr	-30393	A time out error has occurred
kNSpGameTerminatedErr	-30394	An attempt to terminate the game has failed
kNSpConnectFailedErr	-30395	A connection attempt has failed
kNSpSendFailedErr	-30396	An attempt to send a message has failed
kNSpPortTakenErr	-30397	The port you attempted to use is already in use
kNSpNotPlayingErr	-30398	The player you sent a message to is not playing the game