Inside Macintosh: Apple Game Sprockets Guide /

Chapter 4 - NetSprocket / NetSprocket Reference

NetSprocket Functions / Initializing NetSprocket

NSpInitialize

You can use the NSpInitialize function to initialize the NetSprocket library.

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

inStandardMessageSize

This value is the maximum size (in bytes) of each message you expect to send regularly. For example, if your game is sending keyboard state most of the time and the keyboard state message is 40 bytes long (including the NSpMessageHeader) then you should set this value to 40. NetSprocket uses this value to optimize the message receipt buffers. Typically, games send messages that are either relatively constant in size, or the size of the message is proportional to the number of players. If your game doesn't have a typical message size, or if you want NetSprocket to choose a size for you, set this parameter to 0. Setting this value greater than 586 bytes while using AppleTalk may force NetSprocket to use multiple packets for sending the message and potentially decrease game performance.

inBufferSize

The number of bytes that NetSprocket will allocate in its interrupt-safe memory pool for networking during initialization. Usually, 200 KB or more is recommended for most games. You can approximate the networking pool with this formula: ((size of standard message * (send frequency or get frequency)) * max players) + fudge factor of 50 KB). NetSprocket cannot allocate memory at interrupt time. If you do not plan to call NetSprocket functions at interrupt time or use the asynchronous functions, or if you want NetSprocket to allocate the default amount (currently 400 KB), set this value to 0. Because NetSprocket is unable to grow its buffer after initialization, it is important to allocate enough memory in NetSprocket to send, receive, and queue the messages your game will be using.

inQElements

The maximum number of queue elements that NetSprocket will allocate. The queue elements are used to store messages until you receive them from NetSprocket. If you get messages frequently from NetSprocket, you can allocate fewer queue elements than if you do not get them frequently. NetSprocket can automatically expand its message queue, if necessary, but this will degrade performance. Specifying a small number (< 10) will use less memory, but may cause messages to be discarded due to lack of buffer space. Specifying a larger number (> 20) will allow you to call NSpMessage_Get less often and more efficiently. If you do not specify the size of a standard message, you should use the equation described for the inBufferSize parameter.

inGameID

A unique identifier for your game. For instance, if you choose not to specify an NBP type to NetSprocket when registering a game on an AppleTalk network, it will use this ID. You should use your application's creator ID.

inTimeout

The default time-out value you want NetSprocket to use when sending guaranteed messages and performing other network tasks that may require a time-out. Some NetSprocket functions require NetSprocket to keep attempting some action until a response is received. In order to prevent NetSprocket from waiting forever, it uses this value to determine when it should stop trying. If you pass 0 here, NetSprocket will use default timeouts, which vary depending on the operation.

function result

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

DESCRIPTION

NetSprocket must be initialized once in your application before making function calls from the NetSprocket library.

This function may fail under a variety of circumstances, including the failure to allocate enough application memory, insufficient system memory, or failure to initialize networking in the Mac OS.