Inside Macintosh: Apple Game Sprockets Guide /

Chapter 4 - NetSprocket / NetSprocket Reference

Data Structures

Message Header Structure

The most important structure in NetSprocket is the abstract message type. It is comprised of the NSpMessageHeader itself and is followed by custom data. The message header structure contains information about the nature of the message being delivered. The message header structure is defined by the NSpMessageHeader data type.

The fields of the message header are used by NetSprocket to deliver your message to the specified recipients. Before you send a network message, you should fill in the what, to, and messageLen parameters. NetSprocket will set the remaining parameters.

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

Field descriptions

version

Private version information for NetSprocket. Do not modify or rely upon any data in this field.

what

A constant describing the network message type. You should set this field with the constants defined in NetSprocket or a network message type that you have defined in your application.

from

A read-only parameter, which NetSprocket sets to the player ID of the sender.

to

The ID of the intended recipient. Set this value to the ID of the intended player, the group ID of the intended group of recipients, kNSpAllPlayers to send it to every player in the game, or kNSpServerOnly to send it to the server.

id

This is a read-only parameter. The NetSprocket library will assign a unique ID to each message emanating from a given player. Thus, the from and id parameters make up a unique message identifier. This allows you to identify duplicate messages.

when

This is a read-only parameter. NetSprocket will place a time stamp in milliseconds here when the message is sent from its originator. When you receive a message, you can compare this field against the value returned by the NSpGetCurrentTimeStamp function to find out how long ago the message was sent. This value is only a relative value and is accurate only to about 30 to 60 milliseconds.

messageLen

Set this field to the size of your entire message structure (as specified in the sizeof parameter), including the header and any data that follows the header.

Note

Apple reserves all messages that have a negative value (anything with the high bit set to 1). You can define your own custom message types (for example, keyboard state, voice transmission, or game map).