CSNetwork

Description: Client/Server network code

Source file: ...\genesis3d\OpenSource\Source\CSNetMgr.h

Contents:

Functions: Create, Destroy , GetServerID, GetOurID, GetAllPlayerID, ReceiveFromServer, ReceiveFromClient, ReceiveSystemMessage, ReceiveAllMessages, WeAreTheServer, StartSession, StopSession, SendToServer, SendToClient, FindSession, JoinSession

Types: geCSNetMgr, geCSNetMgr_NetID, geCSNetMgr_NetMsgType, geCSNetMgr_NetClient, geCSNetMgr_NetSession

Constants: view

Changes for Genesis v1.6: None

Notes: view

Constants: 

#define MAX_CLIENT_NAME 256

Return to Contents

Types:

typedef struct geCSNetMgr geCSNetMgr;

NOTE: The contents of this structure have been intentionally left out of the interface, by the designers of this module. Think of this as a handle only.
Return to Contents

 typedef uint32 geCSNetMgr_NetID;

A 32-bit number gets assigned to each client (Not an IP?)
Return to Contents

geCSNetMgr_NetMsgType

      // Types for messages received from GE_ReceiveSystemMessage

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 enum {
     NET_MSG_NONE,                           // No msg
     NET_MSG_USER,                             // User message
     NET_MSG_CREATE_CLIENT,        // A new client has joined in
     NET_MSG_DESTROY_CLIENT,     // An existing client has left
     NET_MSG_HOST,                            // We are the server now
     NET_MSG_SESSIONLOST,            // Connection was lost
     NET_MSG_SERVER_ID,                  // Internal, for hand shaking process
} geCSNetMgr_NetMsgType;
Return to Contents

geCSNetMgr_NetClient

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

geCSNetMgr_NetSession

// Windows.h must be included previously for this api to be exposed.
typedef struct geCSNetMgr_NetSession {
     char        SessionName[200]; // Description of Service provider
     GUID     Guid;                       // Service Provider GUID
     #pragma message("define a geGUID?.. wouldn't need a windows dependency here...")
} geCSNetMgr_NetSession;

Servers can have only one session. The act of starting a session is the act of starting a server

  Return to Contents

 

Functions:

GENESISAPI geCSNetMgr* GENESISCC 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.
Return to Contents

GENESISAPI void GENESISCC geCSNetMgr_Destroy(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. 
Return to Contents

GENESISAPI geCSNetMgr_NetID GENESISCC geCSNetMgr_GetServerID(geCSNetMgr* M);

M

Should point to your NetManager object;

Returns    

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.
Return to Contents

GENESISAPI geCSNetMgr_NetID GENESISCC geCSNetMgr_GetOurID(geCSNetMgr* M);

M

Should point to your NetManager object;

Returns    

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

GENESISAPI geCSNetMgr_NetID GENESISCC 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>

Return to Contents

GENESISAPI geBoolean GENESISCC geCSNetMgr_ReceiveFromServer(geCSNetMgr* M, geCSNetMgr_NetMsgType* Type, int32* Size, uint8** Data);

M

Should point to your NetManager object;

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.

Size

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

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.

Returns    

Returns false if there is no message waiting in the receive buffers
Return to Contents

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

 

M

Should point to your NetManager object; 

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. 

IdClient

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

Size

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

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.

Returns    

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.
 

Return to Contents

GENESISAPI geBoolean GENESISCC 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.

Return to Contents

GENESISAPI geBoolean GENESISCC geCSNetMgr_ReceiveAllMessages(geCSNetMgr* M, geCSNetMgr_NetID* IdFrom, geCSNetMgr_NetID* IdTo, geCSNetMgr_NetMsgType* Type, int32* Size, uint8** Data);

Not called in GTest. Not too sure what this guy is for.

Return to Contents

GENESISAPI geBoolean GENESISCC 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?

Return to Contents

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

M

Should point to your NetManager object;

SessionName    

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

PlayerName

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

Returns

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.

Return to Contents

GENESISAPI geBoolean GENESISCC geCSNetMgr_StopSession(geCSNetMgr* M);

M

Should point to your NetManager object;

Returns    

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

Comments: This shuts down the server.

Return to Contents

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

M

Should point to your NetManager object; 

Guaranteed  

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

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.

DataSize

The length of the above data.

Returns    

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.
Return to Contents

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

M

Should point to your NetManager object; 

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. 

Guaranteed    

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

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.

DataSize

The length of the above data.

Returns    

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.

 Return to Contents

GENESISAPI geBoolean GENESISCC geCSNetMgr_FindSession(geCSNetMgr* M, const char * IPAdress, geCSNetMgr_NetSession** SessionList, int32* SessionNum );

// Windows.h must be included previously for this api to be exposed.

M

Should point to your NetManager object;

IPAddress

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

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.

SessionNum

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

Returns

Returns GE_FALSE if the server didn't have a session or there was no server at that IPAddress.
Return to Contents

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

// Windows.h must be included previously for this api to be exposed.

M

Should point to your NetManager object; 

Name

Your in-game name. 

Session

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

Returns     

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.

Return to Contents

Notes: 

KDTOP Note: I have taken this excellent documentation by Royce Pipkins from the World of Genesis web page. Below are his original notes...

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.

In 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.

Return to Contents