Tutorial - Genesis API Netplay Function Reference

Warning: This documentation was not written by Eclipse.

It was written by Royce Pipkins . That means that it may very well contain serious errors. Please don't flood Eclipse with questions about this stuff (chances are they haven't even seen this), wait for them to come out with official documentation. Thanks.

I the mean-time please feel welcome to try out the limited documemtation I assembled while trying to make a Minimum NetPlay Application. (Source to be put-up soon.) Feedback is welcome.

typedef uint32 geCSNetMgr_NetID;
A 32-bit number gets assigned to each client (Not an IP?)

typedef enum
{
NET_MSG_USER,
NET_MSG_CREATE_CLIENT,
NET_MSG_DESTROY_CLIENT,
NET_MSG_HOST
} geCSNetMgr_NetMsgType;
Types of messages that can be received.

Comment : Anything you send directly is a NET_MSG_USER packet. The send functions will ask you only for a destination, data size and a pointer to the data you want to xmit. A client who makes a successful call to geCSNetMgr_JoinSession will apparently generate a NET_MSG_CREATE_CLIENT. The data of a NET_MSG_CREATE_CLIENT will contain only the geCSNetMgr_NetClient struct for the client who just joined the session. A NET_MSG_DESTROY_CLIENT may come from the act of a client destroying its NetManager object.

typedef struct
{
char Name[32];
geCSNetMgr_NetID Id;
} geCSNetMgr_NetClient;
This object is used to identify clients in various function calls.

typedef struct geCSNetMgr_NetSession
{
char SessionName[200]; // Description of Service provider
GUID Guid; // Service Provider GUID
} geCSNetMgr_NetSession;
Servers can have only one session. The act of starting a session is the act of starting a server.

geCSNetMgr *geCSNetMgr_Create(void);
Returns a Net Manager object. You have to have one (and only one) before you do anything with the Net API. Most of the other functions take the NetManager object as a parameter.

void geCSNetMgr_Destroy(geCSNetMgr **ppM);

geCSNetMgr **ppM Pass in the address of a pointer that points to a Net Manager. I guess it's ** because it assumes that the Net Manager pointer is the only copy you have. NULL or not, after this call, dereferenceing this pointer would be a bad idea.

geBoolean geCSNetMgr_FindSession(geCSNetMgr *M, const char *IPAddress, geCSNetMgr_NetSession **SessionList, int32 *SessionNum );

geCSNetMgr *M Should point to your NetManager object;

const char *IPAddress The address of the server you are querying about a session. Pass a NULL to get a special SessionList value.

geCSNetMgr_NetSession **SessionList Pass the address of an unintialized _NetSession pointer. The pointer will come back pointing to the start of an array of _NetSession structs. If you specified an IPAddress the array will contain only the one element for that server. (Assuming it is a running server) If you passed a NULL you will get an array of sessions; one for each running server on your LAN. If your not on a LAN you will likely get no elements at all.

int32 *SessionNum Pass the address of an unintialized int. It will come back containing the number of sessions in the above array.

geBoolean geCSNetMgr_FindSession Returns GE_FALSE if the server didn't have a session or there was no server at that IPAddress.

geBoolean geCSNetMgr_JoinSession(geCSNetMgr *M, const char *Name, const geCSNetMgr_NetSession* Session);

geCSNetMgr *M Should point to your NetManager object;

const char *Name Your in-game name.

const geCSNetMgr_NetSession* Session Pass the address of any one of the geCSNetMgr_NetSession structs you got from geCSNetMgr_FindSession

geBoolean geCSNetMgr_JoinSession Returns GE_FALSE if you are unable to join the session for some reason.

Comments: This call in essence opens a communications path between the server that has the specified session, and the calling client. After this call, this client and the server will be able to use the various types of Send and Receive functions (see below) to talk to one another.

geCSNetMgr_NetID geCSNetMgr_GetServerID(geCSNetMgr *M);

geCSNetMgr *M Should point to your NetManager object;

geCSNetMgr_NetID geCSNetMgr_GetServerID Returns the NetManager assigned ID of the server. I'm not too sure what good it will do you however. Clients don't need it to transmit to the server.

geCSNetMgr_NetID geCSNetMgr_GetOurID(geCSNetMgr *M);

geCSNetMgr *M Should point to your NetManager object;

geCSNetMgr_NetID geCSNetMgr_GetOurID Returns the NetManager assigned ID for the caller. I'm also not too sure what good this will do you.

geCSNetMgr_NetID geCSNetMgr_GetAllPlayerID(geCSNetMgr *M);
Not called by GTest. It is not clear who the return NetID will represent. If the intent is the cycle thru ID's by calling
iteratively how do you tell it to start from the start of the list instead of from the last call. Maybe you just save the
first return value and wait for a subsequent return to match it? <shrug>

geBoolean geCSNetMgr_WeAreTheServer(geCSNetMgr *M);
Not called by GTest. It might send out a NET_MSG_HOST msg to everybody it knows about. Lots of questions here: Does each
client know about all the other clients? Does it work if the old server still has a valid session going? (i.e. rogue call). Does
it work if the old server has already gone down in flames?

geBoolean geCSNetMgr_StartSession(geCSNetMgr *M, const char *SessionName, const char *PlayerName );

geCSNetMgr *M Should point to your NetManager object;

const char *SessionName This string will be made available to clients who find the session on this server.

const char *PlayerName All servers have a local client. This is the name to be associated with that client.

geBoolean geCSNetMgr_StartSession Returns false if there is some kind of problem.

Comments: Calling this function is the act of starting a server. It is important to realize that one client will also be created for the server and will automatically join the newly created session. This client will work exactly like a normal one.

geBoolean geCSNetMgr_StopSession(geCSNetMgr *M);

geCSNetMgr *M Should point to your NetManager object;

geBoolean geCSNetMgr_StopSession Return false on a problem. (No active session?)

Comments: This shuts down the server.

Send Functions

geBoolean geCSNetMgr_SendToServer(geCSNetMgr *M, geBoolean Guaranteed, uint8 *Data, int32 DataSize);

geCSNetMgr *M Should point to your NetManager object;

geBoolean Guaranteed I guess the client will demand somekind of ACK from the server. Haven't tried it.

uint8 *Data A pointer to a blob of data you wish to pass along to the server. A struct perhaps, or maybe some data you concatenated together with memcpy. However you put it together, you will be responsible taking the data back apart when you write the receiving server code.

int32 DataSize The length of the above data.

geBoolean geCSNetMgr_SendToServer Returns false if it can't send it. Also, perhaps, if it was sent guaranteed but not ACK'ed by server, but again I have not tried it.

geBoolean geCSNetMgr_SendToClient(geCSNetMgr *M, geCSNetMgr_NetID To, geBoolean Guaranteed, uint8 *Data, int32 DataSize);

geCSNetMgr *M Should point to your NetManager object;

geCSNetMgr_NetID To The geCSNetMgr_NetID number that was assigned to the client you want to transmit to. For now at least, this parameter seems to be ignored. All connected clients will receive any message sent with this function.

geBoolean Guaranteed I guess the server will demand somekind of ACK from the client

uint8 *Data A pointer to a blob of data you wish to pass along to a client. A struct perhaps, or maybe some data you concatenated together with memcpy. However you put it together, you will be responsible taking the data back apart when you write the receiving client code.

int32 DataSize The length of the above data.

geBoolean geCSNetMgr_SendToClient Returns false if it can't send it. Also, perhaps, if it was sent guaranteed but not ACK'ed by client, but I have not tried it.

Questions: can a client send to another client with this? Can a client get another clients ..._NetID?

Comments: For the server, the "To" parameter is ignored right now. *All* connected clients will receive any data transmitted
via this function. This may well change next beta.

Receive Functions

General Note: the buffer pointed to by the "Data" parameter, in the below receive functions, is not valid long. Make a copy.

(I think it is valid until the next NetPlay call, but ....)

geBoolean geCSNetMgr_ReceiveFromServer(geCSNetMgr *M, uint32 *Type, int32 *Size, uint8 **Data);

geCSNetMgr *M Should point to your NetManager object;

uint32 *Type Pass the address to an uninitalized geCSNetMgr_NetMsgType. Anything that was sent by one of the two SEND functions above will result in Type being filled with the value NET_MSG_USER when it is received with this function.

int32 *Size Pass the address to an uninitalized int. It will be filled with the size of received data.

uint8 **Data Pass the address of an uninitialized uint8 pointer. The pointer will come back pointing to the received data. Make a copy or process the data in short order.

geBoolean geCSNetMgr_ReceiveFromServer Returns false if there is no message waiting in the receive buffers.

geBoolean geCSNetMgr_ReceiveFromClient(geCSNetMgr *M, geCSNetMgr_NetMsgType *Type, geCSNetMgr_NetID *IdClient, int32 *Size, uint8 **Data);

geCSNetMgr *M Should point to your NetManager object;

geCSNetMgr_NetMsgType *Type Pass the address to an uninitalized geCSNetMgr_NetMsgType. Anything that was sent by one of the two SEND functions above will result in Type being filled with the value NET_MSG_USER when it is received by the server.

geCSNetMgr_NetID *IdClient Pass the address of an uninitialized geCSNetMgr_NetID. It will be filled with the NetID representing the client who sent the message.

int32 *Size Pass the address to an uninitalized int. It will be filled with the size of received data .

uint8 **Data Pass the address of an uninitialized uint8 pointer. The pointer will come back pointing to the received data. Make a copy or process the data in short order.

geBoolean geCSNetMgr_ReceiveFromClient Returns false if there is no message waiting in the receive buffers,

Comments: I have not attempted to have a client try to use this to get data that another client sent directly to it using SendToClient. It might be considered too far off the client server paradigm, and not supported.

geBoolean geCSNetMgr_ReceiveSystemMessage(geCSNetMgr *M, geCSNetMgr_NetID IdFor, geCSNetMgr_NetMsgType *Type, geCSNetMgr_NetClient *Client);
Not called in GTest. Not too sure what this guy is for.

geBoolean geCSNetMgr_ReceiveAllMessages(geCSNetMgr *M, geCSNetMgr_NetID *IdFrom, geCSNetMgr_NetID *IdTo, geCSNetMgr_NetMsgType *Type, int32 *Size, uint8 **Data);
Not called in GTest. Not sure what it is for.

geCSNetMgr *M	Should point to your NetManager object;
const char *IPAddress	The address of the server you are querying about a session. Pass a NULL to get a special SessionList value.
geCSNetMgr_NetSession **SessionList	Pass the address of an unintialized _NetSession pointer. The pointer will come back pointing to the start of an array of _NetSession structs. If you specified an IPAddress the array will contain only the one element for that server. (Assuming it is a running server) If you passed a NULL you will get an array of sessions; one for each running server on your LAN. If your not on a LAN you will likely get no elements at all.
int32 *SessionNum	Pass the address of an unintialized int. It will come back containing the number of sessions in the above array.
geBoolean geCSNetMgr_FindSession	Returns GE_FALSE if the server didn't have a session or there was no server at that IPAddress.

geCSNetMgr *M	Should point to your NetManager object;
const char *Name	Your in-game name.
const geCSNetMgr_NetSession* Session	Pass the address of any one of the geCSNetMgr_NetSession structs you got from geCSNetMgr_FindSession
geBoolean geCSNetMgr_JoinSession	Returns GE_FALSE if you are unable to join the session for some reason.

geCSNetMgr *M	Should point to your NetManager object;
geCSNetMgr_NetID geCSNetMgr_GetServerID	Returns the NetManager assigned ID of the server. I'm not too sure what good it will do you however. Clients don't need it to transmit to the server.

geCSNetMgr *M	Should point to your NetManager object;
geCSNetMgr_NetID geCSNetMgr_GetOurID	Returns the NetManager assigned ID for the caller. I'm also not too sure what good this will do you.

geCSNetMgr *M	Should point to your NetManager object;
const char *SessionName	This string will be made available to clients who find the session on this server.
const char *PlayerName	All servers have a local client. This is the name to be associated with that client.
geBoolean geCSNetMgr_StartSession	Returns false if there is some kind of problem.

geCSNetMgr *M	Should point to your NetManager object;
geBoolean geCSNetMgr_StopSession	Return false on a problem. (No active session?)

geCSNetMgr *M	Should point to your NetManager object;
geBoolean Guaranteed	I guess the client will demand somekind of ACK from the server. Haven't tried it.
uint8 *Data	A pointer to a blob of data you wish to pass along to the server. A struct perhaps, or maybe some data you concatenated together with memcpy. However you put it together, you will be responsible taking the data back apart when you write the receiving server code.
int32 DataSize	The length of the above data.
geBoolean geCSNetMgr_SendToServer	Returns false if it can't send it. Also, perhaps, if it was sent guaranteed but not ACK'ed by server, but again I have not tried it.

geCSNetMgr *M	Should point to your NetManager object;
geCSNetMgr_NetID To	The geCSNetMgr_NetID number that was assigned to the client you want to transmit to. For now at least, this parameter seems to be ignored. All connected clients will receive any message sent with this function.
geBoolean Guaranteed	I guess the server will demand somekind of ACK from the client
uint8 *Data	A pointer to a blob of data you wish to pass along to a client. A struct perhaps, or maybe some data you concatenated together with memcpy. However you put it together, you will be responsible taking the data back apart when you write the receiving client code.
int32 DataSize	The length of the above data.
geBoolean geCSNetMgr_SendToClient	Returns false if it can't send it. Also, perhaps, if it was sent guaranteed but not ACK'ed by client, but I have not tried it.

geCSNetMgr *M	Should point to your NetManager object;
uint32 *Type	Pass the address to an uninitalized geCSNetMgr_NetMsgType. Anything that was sent by one of the two SEND functions above will result in Type being filled with the value NET_MSG_USER when it is received with this function.
int32 *Size	Pass the address to an uninitalized int. It will be filled with the size of received data.
uint8 **Data	Pass the address of an uninitialized uint8 pointer. The pointer will come back pointing to the received data. Make a copy or process the data in short order.
geBoolean geCSNetMgr_ReceiveFromServer	Returns false if there is no message waiting in the receive buffers.

geCSNetMgr *M	Should point to your NetManager object;
geCSNetMgr_NetMsgType *Type	Pass the address to an uninitalized geCSNetMgr_NetMsgType. Anything that was sent by one of the two SEND functions above will result in Type being filled with the value NET_MSG_USER when it is received by the server.
geCSNetMgr_NetID *IdClient	Pass the address of an uninitialized geCSNetMgr_NetID. It will be filled with the NetID representing the client who sent the message.
int32 *Size	Pass the address to an uninitalized int. It will be filled with the size of received data .
uint8 **Data	Pass the address of an uninitialized uint8 pointer. The pointer will come back pointing to the received data. Make a copy or process the data in short order.
geBoolean geCSNetMgr_ReceiveFromClient	Returns false if there is no message waiting in the receive buffers,