protocol.h

一个网络和单机的麻将游戏源码

/* $Header: /home/jcb/newmj/RCS/protocol.h,v 11.15 2003/10/06 19:58:19 jcb Rel $
 * protocol.h
 * defines the messages passed between players and controller
 */
/****************** COPYRIGHT STATEMENT **********************
 * This file is Copyright (c) 2000 by J. C. Bradfield.       *
 * Distribution and use is governed by the LICENCE file that *
 * accompanies this file.                                    *
 * The moral rights of the author are asserted.              *
 *                                                           *
 ***************** DISCLAIMER OF WARRANTY ********************
 * This code is not warranted fit for any purpose. See the   *
 * LICENCE file for further information.                     *
 *                                                           *
 *************************************************************/

#ifndef PROTOCOL_H_INCLUDED
#define PROTOCOL_H_INCLUDED

#include "tiles.h"
#include "player.h" /* required for ChowPosition */

/* some constants */

/* This is the largest wall that this level of the protocol supports */
#define MAX_WALL_SIZE 144

/* a bool is an integer constrained to be 0 or 1 */
typedef int bool;

/* a word16 is a word of at most 15 (to allow for final null) characters,
   without white space */
typedef char word16[16];

/* First we have the definitions for options. These are logically
   part of the game module, but they are also needed by the this
   module. Unfortunately, protocol.h can't just include game.h,
   since game.h depends on this, and I can't see how to remove
   the circularity.
*/

/* here are the names of the options. Option 0 for unknown.
   The End option also has special reserved meaning.
   Names (omitting GO) shd be 15 chars or less */
typedef enum {
  /* make-enums sub { $_[0] =~ s/^GO//; } */
  GOUnknown=0,
  GOTimeout, /* the timeout in seconds for claims. Default: 15 */
  GOTimeoutGrace, /* grace period when clients handle timeouts locally */
  GOScoreLimit, /* limit for score. Default 1000 */
  GONoLimit, /* true if no limit on scores. Then ScoreLimit is
	       notional value of limit hand */
  GOMahJongScore, /* base points for going out */
  GOSevenPairs, /* seven pairs hand allowed? */
  GOSevenPairsVal, /* value of a seven pair hand */
    /* the following group of options concerns flowers, by
       which is meant flowers and seasons as in the classical
       rules */
  GOFlowers, /* are flowers to be dealt? */
  GOFlowersLoose, /* flowers replaced from dead wall? */
  GOFlowersOwnEach, /* score for each own flower or season */
  GOFlowersOwnBoth, /* score for own flower and season. N.B.
		       In this case there will also be two 
		       scores of FlowersOwnEach */
  GOFlowersBouquet, /* all four flowers or all four seasons */
  GODeadWall, /* is there a dead wall, or do we play to the end? */
  GODeadWall16, /* is the dead wall 16 tiles unreplenished (per Millington)
		   or the normal 14 replenished. */
  GOConcealedFully, /* score for a fully concealed hand */
  GOConcealedAlmost, /* score for hand concealed up to mah jong,
			or to end of game (if next option applies) */
  GOLosersPurity, /* do losers score the doubles for pure and almost 
		       concealed hand? */
  GOKongHas3Types, /* do we use Millington's 3-way kong distinction? */
  GOEastDoubles, /* does East pay and receive double (as in Chinese Classical)? */
  GOLosersSettle, /* do losers pay among themselves? */
  GODiscDoubles, /* does the discarder pay a double score? */
  GOEnd } GameOption;
#define GONumOptions (GOEnd+1)

/* and the types of options: printed as bool, int, string etc.
   The string option is limited to 127 characters, and may
   not contain white space. (I can't
   remember why I thought it might be wanted.) */
typedef enum {
  /* make-enums sub { $_[0] =~ s/^GOT// ; $_[0] =~ y/A-Z/a-z/; } */
  GOTBool, 
  GOTInt, 
  GOTNat, /* non-negative integer -- introduced at proto 1020 */
  GOTScore, /* a score is an int, but with a special interpretation:
	       if < 10000, it's a number of points; if a multiple of
	       10000, it's that number of doubles (up to 100); and 
	       a fractional (/100) multiple of 100000000 indicates so
	       many limits. It may combine a limit with a number
	       of doubles, in which case the number of doubles is
	       used only in a no limit game. */
  GOTString } GameOptionType;

typedef struct _GameOptionEntry {
  GameOption option; /* integer option number */
  char name[16]; /* short name: shd be same as name of option number */
  GameOptionType type; /* type of option value */
  int protversion; /* least protocol version required to use this
		      option. N.B. This may well be before the introduction
		      of the option, as with many options clients do not
		      have to know about them, and can use the server provided
		      text to allow the user to set them. */
  bool enabled; /* is this option understood in this game? */
  union { bool optbool; int optint; unsigned int optnat; int optscore; char optstring[128]; } value;
  char desc[128]; /* short description */
  void *userdata; /* field for client use */
} GameOptionEntry;


/* The fundamental principle is that players cannot change the state
   of the game---including their own hand. They send a message to
   the controller declaring what they want to do; the controller then
   issues the message implementing it. 
   These messages should NOT be seen as request and reply, but simply
   as event deliveries.
*/

/* Protocol version is an integer of the form 1000*major+minor.
   The protocol major version should be incremented only when
   it is impossible for an earlier client to play with the new
   protocol. Normally, servers and players should be able to 
   downgrade to the lowest common minor version.
   Note: in the earlier versions, including the alpha binary release,
   the version was just 1,2,3, corresponding to our current major.
   However, we will view all those as major 0, and start again at 1000.
   Note that this is not really just the protocol version; it's more
   a version of the protocol plus options etc.
*/

/* This define gives the protocol version implemented in this file */
#define PROTOCOL_VERSION 1060

/* This global variable, found in protocol.c, is used by many functions
   to determine the protocol version currently being used.
   It would be better if this were an argument to every function that
   used it, or if every function were passed a Game structure, but this
   would be too inconvenient. So this global variable is used instead.
   If we ever program with different games in the same process, care will
   have to be taken to manage this.
*/
extern int protocol_version;

/* These structures are the programmer's view of the messages.
   The protocol is actually defined by the wire protocol, not by
   these structs.
*/

/* NOTE: for bad reasons, these enums should always be less
   than 1000000 (to allow space for flag bits) */

/* types of message from controller to player.
   For convenience in debugging, the actual values are widely spaced.
*/
typedef enum {
  CMsgError = 0,
  CMsgInfoTiles = 1,
  CMsgStateSaved = 2,
  CMsgConnectReply = 10,
  CMsgPlayer = 20,
  CMsgNewRound = 29,
  CMsgGame = 30,
  CMsgNewHand = 31,
  CMsgPlayerDeclaresSpecial = 34,
  CMsgStartPlay = 35,
  CMsgStopPlay = 36,
  CMsgPause = 37,
  CMsgPlayerReady = 38,
  CMsgPlayerDraws = 40,
  CMsgPlayerDrawsLoose = 41,
  CMsgPlayerDiscards = 50,
  CMsgClaimDenied = 51,
  CMsgPlayerDoesntClaim = 52,
  CMsgDangerousDiscard = 55,
  CMsgPlayerClaimsPung = 60,
  CMsgPlayerPungs = 61,
  CMsgPlayerFormsClosedPung = 62,
  CMsgPlayerClaimsKong = 70,
  CMsgPlayerKongs = 71,
  CMsgPlayerDeclaresClosedKong = 80,
  CMsgPlayerAddsToPung = 81,
  CMsgPlayerRobsKong = 85,
  CMsgCanMahJong = 87,
  CMsgPlayerClaimsChow = 90,
  CMsgPlayerChows = 91,
  CMsgPlayerFormsClosedChow = 92,
  CMsgWashOut = 99,
  CMsgPlayerClaimsMahJong = 100,
  CMsgPlayerMahJongs = 101,
  CMsgPlayerPairs = 102,
  CMsgPlayerFormsClosedPair = 103,
  CMsgPlayerShowsTiles = 105,
  CMsgPlayerSpecialSet = 106,
  CMsgPlayerFormsClosedSpecialSet = 107,
  CMsgPlayerOptionSet = 110,
  CMsgHandScore = 115,
  CMsgSettlement = 120,
  CMsgGameOver = 200,
  CMsgGameOption = 300,
  CMsgChangeManager = 310,
  CMsgMessage = 400,
  CMsgWall = 900,
  CMsgComment = 999,
  CMsgSwapTile = 1000,
} ControllerMsgType;

/* Types of message sent by player. The numbers more or less
   match the corresponding controller messages.
*/
typedef enum {
  PMsgSaveState = 1,
  PMsgLoadState = 2,
  PMsgConnect = 10,
  PMsgDeclareSpecial = 33,
  PMsgRequestPause = 36,
  PMsgReady = 37,
  PMsgDiscard = 50,
  PMsgNoClaim = 51,
  PMsgPung = 60,
  PMsgFormClosedPung = 62,
  PMsgKong = 70,
  PMsgDeclareClosedKong = 80,
  PMsgAddToPung = 81,
  PMsgQueryMahJong = 87,
  PMsgChow = 90,
  PMsgFormClosedChow = 92,
  PMsgDeclareWashOut = 99,
  PMsgMahJong = 100,
  PMsgPair = 102,
  PMsgFormClosedPair = 103,
  PMsgShowTiles = 105,
  PMsgSpecialSet = 106,
  PMsgFormClosedSpecialSet = 107,
  PMsgSetPlayerOption = 110,
  PMsgSetGameOption = 300,
  PMsgQueryGameOption = 301,
  PMsgListGameOptions = 302,
  PMsgChangeManager = 310,
  PMsgSendMessage = 400,
  PMsgSwapTile = 1000,
} PlayerMsgType;
#define DebugMsgsStart 1000

/* NOTE: it is currently assumed (by the wire protocol) that these
   structures have at most one (char *) component, and if they do,
   it's the final element in the structure.
   If this assumption becomes invalid, work will have to be done on
   the wire protocol code; especially since much of the conversion
   routines is automatically generated from this file.
   For the same reason, when adding new structures, the layout
   and naming convention should be the same as the existing ones.
*/

/* message sent by controller to player to signal an error.
   The string is a human readable description.
*/

typedef struct _CMsgErrorMsg {
  ControllerMsgType type; /* CMsgError */
  int seqno; /* sequence number of player message provoking error, or 0 */
  char *error; /* human readable explanation */
} CMsgErrorMsg;


/* This message requests the controller to save the state
   of the current game. */
/* Note: in protocol versions before 1025, the filename field
   did not exist. This should require no special handling. */
typedef struct _PMsgSaveStateMsg {
  PlayerMsgType type; /* PMsgSaveState */
  char *filename; /* name of file to save in; subject to interpretation
		     and overriding by server. May be null. */
} PMsgSaveStateMsg;

/* This message informs players that the state of the game
   has been saved. */
/* This message was introduced at pversion 1025. */
typedef struct _CMsgStateSavedMsg {
  ControllerMsgType type; /* CMsgStateSaved */
  int id; /* player who requested save */
  char *filename; /* file in which saved. Server dependent.
		     May include full path information in 
		     system dependent form */
} CMsgStateSavedMsg;

/* This message requests the server to load the game state
   from a saved file. There is no reply on success; an error
   is returned on failure. */
/* This message was introduced at pversion 1038. */
typedef struct _PMsgLoadStateMsg {
  PlayerMsgType type; /* PMsgSaveState */
  char *filename; /* name of file to load; subject to interpretation
		     and overriding by server. */
} PMsgLoadStateMsg;

/* This message is purely informational, and is mainly useful
   for debugging or for very dumb clients. It may be sent to
   a player whenever its hand changes, and contains a human
   readable presentation of the player's tiles.
*/
typedef struct _CMsgInfoTilesMsg {
  ControllerMsgType type; /* CMsgInfoTiles */
  int id; /* id of player---in teaching situation might send
	     info on other players too */
  char *tileinfo;
} CMsgInfoTilesMsg;

/* Message sent by player after connecting to controller. */

typedef struct _PMsgConnectMsg {
  PlayerMsgType type; /* PMsgConnect */
  int pvers;  /* protocol version used by player */
  int last_id;  /* (if non-zero) identifier from last session;
		   controller is not bound to keep this, but will try */
  char *name;  /* player's name */
} PMsgConnectMsg;

/* Message sent by controller to player on receipt of ConnectMsg */
typedef struct _CMsgConnectReplyMsg {
  ControllerMsgType type; /* CMsgConnectReply */
  int pvers;  /* protocol version of server */
  int id; /* id assigned by controller, or zero if connection refused */
  char *reason; /* human readable reason for refusal (if refused) */
} CMsgConnectReplyMsg;

/* Message sent by controller to inform players of each other's existence.
   When a player connects, it receives one such message for every already
   existing player; and each existing player receives a message for the
   new player.
   This message is also sent if a player changes its name.
   After protocol version 1034, if the name is empty, this means
   "delete the player". (Empty names were previously permitted,
   but this was always a mistake.)
*/
typedef struct _CMsgPlayerMsg {
  ControllerMsgType type; /* CMsgPlayer */
  int id; /* id of player */
  char *name; /* name of player */
} CMsgPlayerMsg;

/* Message sent by controller to initiate a game (possibly continued
   from a previous session). Contains the initial wind assignment.
*/

typedef struct _CMsgGameMsg {
  ControllerMsgType type; /* CMsgGame */
  int east; /* id of player in east */
  int south; /* id of south */
  int west; /* id of west */
  int north; /* id of north */
  TileWind round; /* wind of the current round */