[Freeciv-Dev] [SNAPSHOT] Notes and serial numbers

[Raimar Falke <hawk@xxxxxxxxxxxxxxxxxxxxxxx>]

Hi,

attached is a snapshot of new event/message system. Since "event" and
"message" was already in use the system is based on a "note". It is
not complete. I need some input from you about certain decisions.

The following things are done (affected files in ()):
 - added note packet (common/packets and common/note)
 - added send_note_* (server/plrhand)
 - added some example note messages (server/cityhand,
   server/stdinhand, server/unithand)
 - added incomplete client note handling (client/packhand)
 - added serial number for each packet (common/packets,
   common/connection, common/capstr, client/clinet, server/sernet)
 - changed return value of send_packet_* from unused hardcoded value
   to serial number (common/packets)
 - added callbacks to the client (client/civclient)
 - added example callbacks (client/civclient)
 - added final notes (see common/note.h for docu) (common/note,
   server/srv_main)

Each packet has two new fields: its serial number (sno for short) and
the initiator serial number. The fields are used in the following way:
 - client: connection contains next_sno=45, initiator_sno=0
 - client: send_packet_* is called
 - client: send_packet_data is called
   * connection.next_sno=46
   * packet gets an extra sno=45, intiator_sno=0
 - server: player connection before packet got received: next_sno=78, 
initiator_sno=0
 - server: get_packet_from_connection()
   * player_connection.initiator_sno=45
 - server: some handle_* method
 - server: send_packet_* is called
 - server: send_packet_data is called
   * player_connection.next_sno=79
   * packet gets an extra sno=79, intiator_sno=45
 - server: if the packet got processed: player_connection.initiator_sno=0
 - client: will receive a packet with sno=79, intiator_sno=45

Final notes are a way to ensure that the client will get at least one
packet from the server. This final note is also the last packet for a
given command. If the server hasn't sent a final note (CBT_FAILURE,
CBT_SUCCESS) and the processing of the command is about to finish an
extra note will be sent which uses CBT_FINAL.

TODO:
 - decide how to handle display options for client:
     Currently there are checkboxes for every event type.
     Should the user select the display type by category or by
     individual message? The client doesn't have a list of all possible
     messages. Maybe selectiing categories in a tree view?
 - complete client handling of a note (format_note):
     Dirk has agreed to implement the va_* magic in
     format_note(). However he is busy.
 - review cagtegories:
     For all current events can I assign a cagtegory. However this part
     needs some review.
 - decide if {SEND,RECEIVE}_{VARS,START,END} macros will be used:
     A lot of code is shared between all send_packet_* and
     receive_packet_* methods. This shouldn't be.
 - decide whether the serial numbers will be prefixed or appended
   (common/packets:APPEND_SNO):
     The current format of a packet is:
        u16 size; 
        u8 type; 
        u8 data[size];
     The serial fields could be added after the type field. So that
     size, type and the serial number fields form a header. It is also
     possible that the serial fields get appended after the data. This
     is needed to cooperate with versions without serial fields.
 - decide the size of the serial number (u16 or u32)
     How many packets are sent in a long game?
 - decide if the client encodes in the initiator_sno of its packet the
   desire to get a final note:
     Since not all clients may require a final note the initiator_sno
     field can be used to let the server know this. The fields is
     unused for client->server packets.

        Raimar

-- 
 email: rf13@xxxxxxxxxxxxxxxxx
  A supercomputer is a computer running an endless loop in just a second

note-5.diff.gz
Description: GNU Zip compressed data