Communication/DGetMessage
Communication/DPutMessage
Communication/KCheckMessage
Communication/KCreateGame
Communication/KGetMessage
Communication/KGetMessageDirect
Communication/KInitConnection
Communication/KPutMessage
Communication/KPutMessageDirect
Communication/KWaitForUser
Communication/Message_Organization
Communication/PCheckMessage
Communication/PCloseConn
Communication/PCreateGame
Communication/PDestroyGame
Communication/PGetMessage
Communication/PInitConnection
Communication/PPutMessage
Communication/Pause
Communication/Resume
Strategia/Communication

     DGetMessage -- Get message by debugger from Communication.

     This function is for debugger use only. It will get any message send by
     kernel or player programs.

     Message structure, message type.

     Message type or MSG_ERR if something went wrong. Global variable will hold
     extra explanation.

     DPutMessage -- Put message from debugger

     Send message to kernel program. PutKMessage will automatically fill in
     Msg field of structure.

     Message structure, message type.

     Message type or MSG_ERR if something went wrong. Global variable will hold
     extra explanation.

     PCheckMessage -- Check if MsgType is correct for kernel

     Size  PCheckMessage( MsgType )
     ULONG PCheckMessage( ULONG )

     This function will return the size of message of type MsgType. It will
     check if MsgType is allowed for kernel. If not, this function returns 0.

     MsgType -- ID of message.

     Size -- full size of message in bytes or 0 if not Player message.

     Used internally by KPutMessage .

     None known yet.

     KPutMessage .

     KCreateGame -- Create and startup the game.

     Result KCreateGame( KC, Players)
     BOOL   KCreateGame( struct KConn *, ULONG *)

     Create the game, and wait for other players.

     KC          - PConn structure, obtained using KInitConnection
     Players     - Pointer to ULONG, that will hold number of connected players

     TRUE  - if game was created.
     FALSE - cannot create the game.

      Player: MSG_P_OPEN   - I want to play with this kernel
   
   Kenrel: (Communication):
   
     - Check if game in progress
        then: MSG_K_NOOPENACK        
        else:        

     - Check if other user waiting on game without this user
        then: MSG_K_NOOPENACK
        else:        
             
     - If other user waiting on this user
        then: add the user to list and check if all waited users are on the list
        else:
        
     - This user is the first, so create its list and wait on other users. 
       After las user is on the list:
         send to this user:   MSG_K_OPENACK
         send to other users: MSG_K_OPENACK    

     Connection must have been estabilished before calling this function. 
     This function is used internally by KInitConnection.

     None known yet.

     PInitConnection .

     KGetMessage -- Get message from Player or Debugger.

     Message KGetMessage(Message, KC, Player)
     ULONG   KGetMessage(struct GameMessage *, struct KConn *, ULONG )

     This function is for Kernel use only. It will wait for any message send by
     player program. It will try to read one or return MSG_EMPTY
     if there is no one.

     Message - pointer to buffer that will hold the result.
     KC      - KConn structure obtained by KInitConnection
     Player  - The player this function is waiting for.

     Message type or MSG_ERR if something went wrong. Global variable will hold
     extra explanation.

     None known yet.

     KInitConnection, KPutMessage. 

     KGetMessageDirect -- Get message using socket directly.

     Message KGetMessageDirect(Message, KC, Socket)
     ULONG   KGetMessageDirect(struct GameMessage *, struct KConn *, SOCKET_TYPE )

     This function is for Kernel use only. It will wait for any message send by
     program with provided socket. It will try to read one or return MSG_EMPTY
     if there is no one. This function is for internal Communication usage.

     Message - pointer to buffer that will hold the result.
     KC      - KConn structure obtained by KInitConnection
     Socket  - Communication socket.

     Message type or MSG_ERR if something went wrong. Global variable will hold
     extra explanation.

     Kernel should use higher level KGetMessage function.

     None known yet.

     KInitConnection, KGetMessage. 

     KInitConnection -- Startup kernel comm port.

     KConn KInitConnection(Players)
     struct KConnect KInitConnection(ULONG *)

     This function will perform all what is needed to startup a game over
     network. It will estabilish connection, setup players sockets and finally
     begin the game.
     

     Players -- Pointer to ULONG that will hold nr of net initialized players

     Pointer to KConn structure, that will be needed in all network calls
     If pointer is NULL, something went wrong.

     None known yet.

     KGetMessage, KPutMessage .

     KPutMessage -- Put message from kernel.

     Message KPutMessage(MessageType, Message, Player, KC)
     ULONG   KPutMessage(ULONG, struct GameMessage *, ULONG, struct KConn *)

     Send message structure from kernel to klient program. 

     MessageType -- Type of the game message, *MUST* be MSG_K_xxx
     Message     -- Pointer to the message structure.
     Player      -- Player that should get the message.

     Message type (the same as MessageType) or MSG_ERROR if something went 
     wrong. Global variable will hold extra explanation.

     KPutMessage will automatically fill in Msg field of structure.

     None known yet.

     KGetMessage.

     KPutMessageDirect -- Put message from kernel directly to socket.

     Message KPutMessageDirect(MessageType, Message, Player)
     ULONG   KPutMessageDirect(ULONG, struct GameMessage *, ULONG)

     Send message structure from kernel to klient program using provided socket. 
     This function is for internal communication usage - mainly game startup. 

     MessageType -- Type of the game message, *MUST* be MSG_K_xxx
     Message     -- Pointer to the message structure.
     Player      -- Player that should get the message.

     Message type (the same as MessageType) or MSG_ERROR if something went 
     wrong. Global variable will hold extra explanation.

     KPutMessageDirect will automatically fill in Msg field of structure.
     KPutMessage is provided for kernel usage.

     None known yet.

     KPutMessage.

     KWaitForUser -- Wait for connection to socket and MSG_P_OPEN.

     Players KWaitForUser( KC, Socket, PlayerNames, PlayerName )
     ULONG   KWaitForUser( struct KConn *, SOCKET_TYPE *, char ***, char ** )

     Wait for any player to connect to the socket, then wait for startup message
     MSG_P_OPEN. It set pointers to some fields of this message's structure.

     KC          - PConn structure, obtained using KInitConnection
     Socket      - Pointer to SOCKET_TYPE, that will be set to hold socket of connected
                   player.
     PlayerNames - Pointer to pointer, that will be set to point to the table of
                   player names (pointers to NULL terminated strings).
     PlayerName  - Pointer to pointer, that will be set to point to the name of
                   player that is trying to connect.

     Players - Number of players this player wan't to play with. If this is 0,
               then some error was encountered. In this case user was not connected.
    

      Kernel: Listen()
      Player: Create socket, Connect
      Kernel: Accept()
      Kernel: KGetMsg()
      Player: MSG_P_OPEN   - I want to play with this kernel
   
   Kenrel: (Communication):
   
     - Check if there are users this user want to play
        then: Setup pointers
        else: send MSG_K_NOOPENACK
              set pointers to NULL
              return 0

     If this function fails, all pointers are set to NULL.

     None known yet.

     PInitConnection .

    - Message MUST be of certain type. It will be ignored otherwise
    - Message is ignored if it's number is lower than the last received
    - Message is ignored if it's type is the same as the last received

  Starting the game:

    * - means dialog messages


   Player: MSG_P_OPEN   - I want to play with this kernel
   
   Kenrel: (Communication):
   
     - Check if game in progress
        then: MSG_K_NOOPENACK        
        else:        

     - Check if other user waiting on game without this user
        then: MSG_K_NOOPENACK
        else:        
             
     - If other user waiting on this user
        then: add the user to list and check if all waited users are on the list
        else:
        
     - This user is the first, so create its list and wait on other users. 
       After las user is on the list:
         send to this user:   MSG_K_OPENACK
         send to other users: MSG_K_OPENACK    
     
   Ending the game:
   
   Wariant 1:
   
   Player: MSG_P_END
   Kernel: MSG_K_ENDASK do wszystkich z listy
   
      - Czekam na odpowiedzi od wszystkich.
      
      - Gdy wszystkie MSG_P_ENDACK
         then: 
            1 wysyîamy do wszystkich MSG_K_QUITNOW
            2 odsyîamy do playera MSG_K_ENDACK
            3 niszczymy grë i poîâczenia
            
         else: wysyîamy do Playera MSG_K_NOENDACK
   

    Wariant 2:
    
    Kernel: MSG_K_QUITNOW
    Player: koniec gry
    
    Wariant 3:
    
    Player: MSG_P_QUIT    want to quit immediately
    Kernel: MSG_K_QUITTED do wszystkich oprócz Player, informacja o poraűce
     - gdy lista graczy pusta           
        then: MSG_P_QUIT
        else: dalej gra        
  
  Common actions:

  PAUSE THE GAME

  Player is initiator:
  
  *Player: MSG_P_PAUSE       ask for pause
   Kernel: MSG_K_PAUSE       command all players to pause
  *        MSG_K_PAUSE       acknowlegde player with pause
          
  *Player: MSG_P_RESUME      continue the game
  
   Kernel: MSG_K_RESUME      command all player to resume
  *        MSG_K_RESUME      acknowledge with resume 
  
  
  Kernel is initiator:
  
  Kernel: MSG_K_PAUSE 
  Player: wait for message
  Kernel: MSG_K_RESUME
  Player: continue the game      
  
  
  ASKING FOR STATUS:
  
  Player: MSG_P_STATUS    want to get it's status
  Kernel: MSG_K_STATUSACK status information
  
  
  ASKING FOR FIELD CONTENTS:
  
  Player: MSG_P_FIELD    want to get field information
  Kernel: MSG_K_FIELDACK field information

  
  ASKING FOR MOVE:
  
  Player: MSG_P_MOVE    want to get move army
  Kernel: if move is possible
          then: MSG_K_MOVEACK move acknowledge
          else: MSG_K_NOMOVEACK  move may not be performed

  
  ASKING FOR WORK:
  
  Player: MSG_P_WORK    want to change working status of people
  Kernel: if change is possible
          then: MSG_K_WORKACK   change acknowledge
          else: MSG_K_NOWORKACK changes may not be performed


  ASKING FOR BUILD:
  
  Player: MSG_P_BUILD    want to build something
  Kernel: if build is possible
          then: MSG_K_BUILDACK   build acknowledge
          else: MSG_K_NOBUILDACK build may not be performed
    

     PCheckMessage -- Check if MsgType is correct for Player module

     Size  PCheckMessage( MsgType )
     ULONG PCheckMessage( ULONG )

     This function will return the size of message of type MsgType. It will
     check if MsgType is allowed for Player. If not, this function returns 0.

     MsgType -- ID of message.

     Size -- full size of message in bytes or 0 if not Player message.

     Used internally by PPutMessage .

     None known yet.

     PPutMessage .

     PCloseConn -- Close game and player connection port.

          PCloseConn( PC )
     void PCloseConn( struct PConn * )

     This function will perform all what is needed to stop a game over
     network and deallocate resources needed for network transfers. 
     Passing NULL pointer is OK, but won't do anything useful.
     

     PC - pointer to previously allocated PConn structure.

     Pointer to PConn structure, that will be needed in all network calls.
     If pointer is NULL, something went wrong.

     Player: MSG_P_END
     Kernel: MSG_K_ENDASK do wszystkich z listy
   
      - Czekam na odpowiedzi od wszystkich.
      
      - Gdy wszystkie MSG_P_ENDACK
         then: 
            1 wysyîamy do wszystkich MSG_K_QUITNOW
            2 odsyîamy do playera MSG_K_ENDACK
            3 niszczymy grë i poîâczenia
            
         else: wysyîamy do Playera MSG_K_NOENDACK

     None known yet.

     PInitConn

     PCreateGame -- Create and startup the game.

     Result PCreateGame( PC, PlayerNames )
     BOOL   PCreateGame( struct PConn * , char **)

     Ask kernel for creating the game, and wait for other players.

     PC          - PConn structure, obtained using PInitConnection
     PlayerNames - Table of null terminated Player names pointers. After the last
                   player there must be NULL pointer.

     TRUE  - if game was created
     FALSE - cannot create the game

      Player: MSG_P_OPEN   - I want to play with this kernel
   
   Kenrel: (Communication):
   
     - Check if game in progress
        then: MSG_K_NOOPENACK        
        else:        

     - Check if other user waiting on game without this user
        then: MSG_K_NOOPENACK
        else:        
             
     - If other user waiting on this user
        then: add the user to list and check if all waited users are on the list
        else:
        
     - This user is the first, so create its list and wait on other users. 
       After las user is on the list:
         send to this user:   MSG_K_OPENACK
         send to other users: MSG_K_OPENACK    

     Connection must have been estabilished before calling this function. 
     PlayerNames table MUST be present to the end of game.
     This function is used internally by PInitConnection.

     PInitConnection .

      PDestroyGame -- Relase the connection with Kernel

           PDestroyGame( PC )
      void PDestroyGame( struct PConn * )

      Inform the kernel, that this user won't play any longer.

      PC - PConn structure obtained from PInitConnection .

    Player: MSG_P_QUIT    want to quit immediately
    Kernel: MSG_K_QUITTED do wszystkich oprócz Player, informacja o poraűce
     - gdy lista graczy pusta           
        then: MSG_P_QUIT
        else: dalej gra        

    User has surrendered - other players will get this message.

    None known yet.

     PGetMessage -- Get message from Kernel.

     Message PGetMessage(Message, PC)
     ULONG   PGetMessage(struct GameMessage *, struct PConn *)

     This function is for Player use only. It will get any message send by
     debugger or kernel programs. It will try to read one or return MSG_EMPTY
     if there is no one.

     Message - pointer to buffer, that will hold resulting message.
     PC      - pointer to PConn structure obtained by PInitConnection.

     Message type or MSG_ERR if something went wrong. Global variable will hold
     extra explanation.

     None known yet.

     PPutMessage. 

     PInitConnection -- Startup player connection port.

     PConn PInitConnection( char **PlayerTable )
     struct PConnect InitConnection(  char **PlayerTable )

     This function will perform all what is needed to startup a game over
     network. It will estabilish connection, setup player socket and finally
     begin the game.
     

     PlayerTable - table of pointers to null terminated user names. After last 
                   player name there should be NULL in the table.

     Pointer to PConn structure, that will be needed in all network calls.
     If pointer is NULL, something went wrong.

     None known yet.

     PGetMessage, PPutMessage

     PPutMessage -- Put message from Player

     Message PPutMessage(MsgType, Message, PC)
     ULONG   PPutMessage(ULONG, struct Message *, struct PConn *PC)

     Send message to kernel program. PPutMessage will automatically fill in
     Msg field of structure.

     MsgType -- Type of the message, must be MSG_P_xxx.
     Message -- Pointer to message that will be send.
     PC      -- Pointer to structure created by PInitComm.

     Message type or MSG_ERR if something went wrong. Global variable will hold
     extra explanation.

     None known yet.

      PInitComm, PGetMessage

     Pause -- Pause the Game.

     Result Pause(PC)
     ULONG  Pause(struct PConn *)

     Function issued by Player, should pause the game. 

     PC - Pointer to PConn structure obtained with PInitConnection.

     FALSE - error pausing the game.
     TRUE  - game pausing succeded.

     Player is initiator:
  
  *Player: MSG_P_PAUSE       ask for pause
   Kernel: MSG_K_PAUSE       command all players to pause
           if all will accept the question    
  *        then: MSG_K_PAUSE       acknowlegde player with pause
  *        else: MSG_K_RESUME      no chance for the pause
           
          
    The above is in Resume function.

  *Player: MSG_P_RESUME      continue the game
  
   Kernel: MSG_K_RESUME      command all player to resume
  *        MSG_K_RESUME      acknowledge with resume 
  

     Game MUST be paused only once.  Otherwise function will abort and return 
     FALSE. Paused games must be resumed with Resume.

     None known yet.

     Resume .

     Resume -- Resume the Game

     Result Resume(PC)
     ULONG Resume(struct PConn *)

     Function issued by Player, should resume the paused game.

     PC - Pointer to PConn structure obtained with PInitConnection.

         FALSE - error resuming the game
         TRUE  - resuming the game succeded

   Player is initiator:
           
          
  *Player: MSG_P_RESUME      continue the game
  
   Kernel: MSG_K_RESUME      command all players to resume
  *        MSG_K_RESUME      acknowledge with resume 
  

     Never resume the game that was not paused or have been resumed. 
     In this case function will abort and return FALSE.

     None known yet.

     Pause.

     Communication -- Network Communication program.

     (c) Copyright 1997 by Wojciech Czyű.

     Communication module for UNIX strategy game.

     Wojciech Czyz.

     Saturday 01-Nov-97 21:09:35.

  INTERNALS:
      Communication  uses  Berkley  UNIX  socket's  as  the lowest level of data
      movement. It will automagically hide internal mechanisms into easy to use
      functions. The global data route used in strategy game:

    Level   Logical                         Data passing
            Units                           Unit connection


      e     Player (Human or programmed)
                |
                |                           Decisions
                |
      d     (Graphical) User Interface 
                |
                |                           Events
                |
      c      Player program
                |
                |                           Communication's function calls
                |
      b      Communication (Player side)  
                |
                |                           Socket based data passing
                |
      a      Berkley sockets
                |
                |                           File or TCP IP data connection
                |
      0      Network or local connection
                |
                |                           File or TCP IP data connection
                |
      A      Berkley sockets
                |
                |                           Socket based data passing
                |
      B      Communication (Kernel side)   
                |
                |                           Communication's function calls
                |
      C      Kernel   
             
    Function of this unit is to emulate direct connection beetween Kernel (Level
    C) and player program (Level c). Connection beetwen C and c levels may be
    replaced by one logical unit - Communication module. New data flow chart:
             
    Level   Logical                         Data passing
            Units                           Unit connection


      e     Player (Human or programmed)
                |
                |                           Decisions
                |
      d     (Graphical) User Interface 
                |
                |                           Events
                |
      c      Player program
                |
                |                           Communication's function calls
                |
      C      Kernel   
             

    Communication module encapsulates following sections:
    
     - Socket programming and configuration
     - Automatic detection of sockets
     - Game startup
     - Debugger handling
                 
             

     Saturday 01-Nov-97 22:13:55 - Defines, structure and main function
                                   definitions, standard function headers.
     Sunday 02-Nov-97 17:39:55   - Rough body of functions, synchro for now.
     Sunday 02-Nov-97 17:40:26   - Includes defined.
     Sunday 02-Nov-97 18:17:43   - KConnection structure defined.
     Sunday 02-Nov-97 20:26:55   - PConn structure defined. KConnection renamed
                                   KConn. 
     Sunday 02-Nov-97 20:27:24   - KInitConn and PInitConn implemented.
     Sunday 02-Nov-97 20:42:40   - PPutMessage recoded to use PConn structure.
     Sunday 02-Nov-97 22:07:39   - Some errors removed, KInitConn, KGetMsg,
                                   PInitConn, PPutMsg ready for test.
     Saturday 03-Jan-98 14:59:04 - Starting cleanup and testing.
     Saturday 03-Jan-98 15:40:42 - Added TEST_VERBOSE define, all printf's enclosed
     Saturday 03-Jan-98 16:32:56 - START I KONIEC gry, PCheckMessage
     Sunday 04-Jan-98 16:36:09   - Message counter and reset added to message structure
     Sunday 04-Jan-98 19:04:44   - Pause and Resume functions "body".
     Sunday 04-Jan-98 19:11:11   - PInitConn changed to allocate GeneralBuffer
     Sunday 04-Jan-98 19:20:47   - PCloseConn added.
     Sunday 04-Jan-98 20:55:17   - "Started" added to PConn structure
     Sunday 04-Jan-98 20:55:33   - Started and Paused FALSEd at PInitConnection .
     Sunday 04-Jan-98 21:20:59   - CreateGame created.
     Sunday 04-Jan-98 21:26:25   - CreateGame used in PInitConnection.
     Sunday 04-Jan-98 21:31:56   - CreateGame renamed as PCreateGame .
     Sunday 04-Jan-98 21:40:23   - PDestroyGame created.
     Sunday 04-Jan-98 21:40:41   - PDestroyGame used in PCloseConnection.
     Sunday 04-Jan-98 21:44:23   - Time to cleanup autodocs.
     Sunday 04-Jan-98 21:49:38   - PCheckMessage autodoc cleaned.
     Sunday 04-Jan-98 22:00:08   - PCreateGame autodoc cleaned.
     Sunday 04-Jan-98 22:05:38   - PDestroyGame autodoc cleaned.
     Sunday 04-Jan-98 22:08:40   - KInitConnection autodoc cleaned.
     Sunday 04-Jan-98 22:15:54   - PInitConnection autodoc cleaned.
     Sunday 04-Jan-98 22:18:50   - PCloseConn autodoc cleaned.
     Sunday 04-Jan-98 22:23:36   - KGetMessage autodoc cleaned.
     Sunday 04-Jan-98 22:27:26   - PPutMessage autodoc cleaned.
     Sunday 04-Jan-98 22:31:05   - PGetMessage autodoc cleaned.
     Sunday 04-Jan-98 22:40:37   - Pause autodoc cleaned.
     Sunday 04-Jan-98 22:40:59   - Resume autodoc cleaned.
     Wednesday 07-Jan-98 22:53:41 - Time to implement rest of Game start
     Wednesday 07-Jan-98 23:13:10 - KGetMessage autodoc completed - inputs
     Thursday 08-Jan-98 00:21:39  - KCreateGame in progress
     Thursday 08-Jan-98 12:14:21  - KWaitForUser implemented (not fully).
     Thursday 08-Jan-98 13:16:37  - KCreateGame nearly completed.
     Saturday 10-Jan-98 23:40:24  - KCheckMessage implemented.
     Saturday 10-Jan-98 23:49:55  - KPutMessageDirect implemented. KPutMessage will use
                                    KPutMessageDirect.
     Sunday 11-Jan-98 00:05:32    - KGetMessageDirect implemented. KGetMessage will use
                                    KGetMessageDirect.
     Sunday 11-Jan-98 00:06:22    - KCreateGame finished.
     Sunday 11-Jan-98 00:11:53    - PInitConnecttion: close(Socket) added in several places
     Sunday 11-Jan-98 00:12:37    - Time for compilation
     Sunday 11-Jan-98 00:25:48    - KWaitForUser - Socket now will be set to PlaySock.
     Sunday 11-Jan-98 10:29:27    - KInitConnection - error handling now include cleanup
     Sunday 11-Jan-98 10:54:46    - KInitConnection - GeneralBuffer added.
     Sunday 11-Jan-98 12:26:42    - PDestroyGame no longer marked as internal.
     Sunday 11-Jan-98 14:43:55    - PGetMessage implemented, autodoc cleaned.
     Sunday 11-Jan-98 15:48:02    - Error messages cleanup.
     Sunday 11-Jan-98 16:14:38    - KCreateGame error conditions cleaned up.

     MAX_PLAYERS const must be moved to kernel module.

  HARDWARE              
     Any UNIX platform