protocol.h

支持网络和单机的麻将游戏

/* Message sent by player to claim Mah-Jong.
   Applies to both claiming a discard and mah-jong from wall. 
*/
typedef struct _PMsgMahJongMsg {
  PlayerMsgType type; /* PMsgMahJong */
  int discard; /* discard being claimed, or 0 if from wall */
} PMsgMahJongMsg;

/* Message sent by controller to announce mah-jong claim */
typedef struct _CMsgPlayerClaimsMahJongMsg {
  ControllerMsgType type; /* CMsgPlayerClaimsMahJong */
  int id; /* player claiming */
  int discard; /* discard being claimed */
} CMsgPlayerClaimsMahJongMsg;


/* Message sent by controller to announce successful mah-jong */
typedef struct _CMsgPlayerMahJongsMsg {
  ControllerMsgType type; /* CMsgPlayerMahJongs */
  int id; /* player claiming */
  Tile tile; /* If this is HiddenTile, then the mahjong is by claiming
		the discard (the tile will be named in a later claim).
		If the mahjong is from the wall, then this is the tile
		that was drawn; this allows the other players to see
		the legitimacy of scoring claims. */
} CMsgPlayerMahJongsMsg;

/* Take the mah-jonged discard for a pair. Since this can only
   happen at mah-jong, there is no need to specify a tile or
   discard number */
typedef struct _PMsgPairMsg {
  PlayerMsgType type; /* PMsgPair */
} PMsgPairMsg;

typedef struct _CMsgPlayerPairsMsg {
  ControllerMsgType type; /* CMsgPlayerPairs */
  int id;
  Tile tile; /* for convenience of other players */
} CMsgPlayerPairsMsg;

/* Form a closed pair during scoring */
typedef struct _PMsgFormClosedPairMsg {
  PlayerMsgType type; /* PMsgFormClosedPair */
  Tile tile;
} PMsgFormClosedPairMsg;

typedef struct _CMsgPlayerFormsClosedPairMsg {
  ControllerMsgType type; /* CMsgPlayerFormsClosedPair */
  int id;
  Tile tile;
} CMsgPlayerFormsClosedPairMsg;

/* These messages handle the case of special hands such as
   thirteen unique wonders */
/* Claim the discard (during scoring) to form a special hand */
typedef struct _PMsgSpecialSetMsg {
  PlayerMsgType type; /* PMsgSpecialSet */
} PMsgSpecialSetMsg;

/* Player claims the discard to form a special set with all remaining tiles;
   this is a ShowTiles as well */
typedef struct _CMsgPlayerSpecialSetMsg {
  ControllerMsgType type ; /* CMsgPlayerSpecialSet */
  int id;
  Tile tile; /* the discard tile */
  char *tiles; /* string repn of the concealed tiles */
} CMsgPlayerSpecialSetMsg;

/* Form a special set in hand */
typedef struct _PMsgFormClosedSpecialSetMsg {
  PlayerMsgType type; /* PMsgFormClosedSpecialSet */
} PMsgFormClosedSpecialSetMsg;

/* Player forms a special set in hand from the concealed tiles */
typedef struct _CMsgPlayerFormsClosedSpecialSetMsg {
  ControllerMsgType type ; /* CMsgPlayerFormsClosedSpecialSet */
  int id;
  char *tiles; /* string repn of concealed tiles */
} CMsgPlayerFormsClosedSpecialSetMsg;

/* This message is sent by a losing player after it has finished
   making scoring combinations: it reveals the concealed tiles,
   and triggers the calculation of a score. */
typedef struct _PMsgShowTilesMsg {
  PlayerMsgType type; /* PMsgShowTiles */
} PMsgShowTilesMsg;

/* This message reveals a player's concealed tiles.
   It currently just has a string repn, because I'm lazy.
   This ought to be a variable array of tiles.
*/
typedef struct _CMsgPlayerShowsTilesMsg {
  ControllerMsgType type; /* CMsgPlayerShowsTiles */
  int id;
  char *tiles; /* string repn of concealed tiles */
} CMsgPlayerShowsTilesMsg;

/* This message gives the calculated score for a hand.
*/
typedef struct _CMsgHandScoreMsg {
  ControllerMsgType type; /* CMsgHandScore */
  int id;
  int score; /* score of this hand */
  char *explanation; /* human readable calculation of the score */
} CMsgHandScoreMsg;

/* This message announces the change in cumulative score for each player.
   The explanation is text, which should be interpreted cumulatively
   with any previous settlement explanations.
*/
typedef struct _CMsgSettlementMsg {
  ControllerMsgType type; /* CMsgSettlement */
  int east;
  int south;
  int west;
  int north;
  char *explanation;
} CMsgSettlementMsg;

/* This message requests the controller to set a player option,
   or acknowledges a server set. */
typedef struct _PMsgSetPlayerOptionMsg {
  PlayerMsgType type; /* PMsgSetPlayerOption */
  PlayerOption option; /* which option is being set */
  bool ack; /* 1 if this is acknowledging a server request */
  int value; /* value of option if int or bool */
  char *text; /* value of option if string */
} PMsgSetPlayerOptionMsg;

/* This informs the player that an option has been set.
   It may be a response to a request; it may also be autonomous,
   in which case the player should send a SetPlayerOption with
   the given value to acknowledge.*/
typedef struct _CMsgPlayerOptionSetMsg {
  ControllerMsgType type; /* CMsgPlayerOptionSet */
  PlayerOption option; /* which option is being set */
  bool ack; /* 1 if acknowledging a client request */
  int value; /* value of option if int */
  char *text; /* value of option if string */
} CMsgPlayerOptionSetMsg;

/* Message to tell players game is over */
typedef struct _CMsgGameOverMsg {
  ControllerMsgType type; /* CMsgGameOver */
} CMsgGameOverMsg;

/* Message to set a game option */
typedef struct _PMsgSetGameOptionMsg {
  PlayerMsgType type; /* PMsgSetGameOption */
  word16 optname;
  char *optvalue;
} PMsgSetGameOptionMsg;

/* Message to inform players of a game option value */
typedef struct _CMsgGameOptionMsg {
  ControllerMsgType type; /* CMsgGameOption */
  int id; /* player who set it, if any */
  GameOptionEntry optentry;
} CMsgGameOptionMsg;

/* Message to query a game option. Controller will reply
 with a GameOptionMsg */
typedef struct _PMsgQueryGameOptionMsg {
  PlayerMsgType type; /* PMsgQueryGameOption */
  word16 optname; /* name of option to query */
} PMsgQueryGameOptionMsg;

/* Message to query all game options. Controller will reply
   with a sequence of GameOptionMsgs, finishing with the End pseudo-option */
typedef struct _PMsgListGameOptionsMsg {
  PlayerMsgType type; /* PMsgListGameOptions */
  bool include_disabled; /* send even disabled options */
} PMsgListGameOptionsMsg;

/* Request new manager for the game. */
typedef struct _PMsgChangeManagerMsg {
  PlayerMsgType type; /* PMsgChangeManager */
  int manager; /* new manager, or 0 if none */
} PMsgChangeManagerMsg;

/* Give new manager for the game. */
typedef struct _CMsgChangeManagerMsg {
  ControllerMsgType type; /* CMsgChangeManager */
  int id; /* player requesting change */
  int manager; /* new manager, or 0 if none */
} CMsgChangeManagerMsg;

/* Send a message to other player(s). */
typedef struct _PMsgSendMessageMsg {
  PlayerMsgType type; /* PMsgSendMessage */
  int addressee; /* id of addressee, or 0 for broadcast */
  char *text;
} PMsgSendMessageMsg;

/* Message from controller or other player. */
typedef struct _CMsgMessageMsg {
  ControllerMsgType type; /* CMsgMessage */
  int sender; /* id of sender, or 0 for message from controller */
  int addressee; /* 0 for broadcast, id of recipient otherwise */
  char *text;
} CMsgMessageMsg;

/* This message is primarily used by the controller internally.
   It sets up the wall with the given tiles */
typedef struct _CMsgWallMsg {
  ControllerMsgType type; /* CMsgWall */
  char *wall; /* wall as space separated tile codes */
} CMsgWallMsg;

/* This message serves no purpose in the protocol; it allows comments
   to be included in files of protocol commands. It is specially 
   hacked in the proto-encode scripts so that the message name
   is a hash sign # rather than the word Comment; for the decode
   script, we use the undocumented alias capability.
   Introduced at protocol 1030.
*/
typedef struct _CMsgCommentMsg { /* alias # */
  ControllerMsgType type; /* CMsgComment */
  char *comment;
} CMsgCommentMsg;

/* This message is for debugging and testing. It asks the controller
   to swap the old tile for the new tile. This is implemented by
   finding the new tile in the wall and swapping it with the old tile.
*/
typedef struct _PMsgSwapTileMsg { /* alias st */
  PlayerMsgType type; /* PMsgSwapTile */
  int id; /* player to be changed */
  Tile oldtile; 
  Tile newtile;
} PMsgSwapTileMsg;

typedef struct _CMsgSwapTileMsg {
  ControllerMsgType type; /* CMsgSwapTile */
  int id; /* player to be changed */
  Tile oldtile; 
  Tile newtile;
} CMsgSwapTileMsg;

/* dummy just to get the type field. This MUST come after all
 the real types (for auto-generation of printing and parsing) */
typedef struct _CMsgMsg {
  ControllerMsgType type;
} CMsgMsg;

typedef struct _PMsgMsg {
  PlayerMsgType type;
} PMsgMsg;

/* Two humungous unions for when they're wanted. Auto generated. */
#include "cmsg_union.h"

#include "pmsg_union.h"

/* after all that, some functions to handle conversion from/to
   the wire protocol */

/* The application programmer need only view the protocol as a sequence
   of lines. Lines may be terminated by CRLF, or LF.
   If the last character before the terminator is \ (backslash), then
   a newline is to be included in the "line", and the following
   wire line appended.
   The protocol is in fact human readable; it is described in protocol.c
*/

/* This function takes a pointer to a controller message,
   and returns a string (including terminating CRLF) encoding it.
   The returned string is in static storage, and will be overwritten
   the next time this function is called.
*/

char *encode_cmsg(CMsgMsg *msg);

/* This function takes a string, which is expected to be a complete
   line (including terminators, although their absence is ignored).
   It returns a pointer to a message structure.
   Both the message structure and any strings it contains are malloc'd.
   The argument string will be mutilated by this function.
*/
    
CMsgMsg *decode_cmsg(char *arg);


/* Text (that is, char *) elements of the protocol may contain
   special sequences of the form
   {CODE#TYPE...#TYPE:TEXT}{ARG}...{ARG}
   These are macros, which can be used to provide marked-up, rather than
   formatted messages.
   The CODE identifies the function the text serves (e.g. Pung claim,
   line of scoring details, etc.); each #TYPE notes an argument, with
   its type; and then the arguments follow. The TEXT provides a default
   text which can be used by a client that does not recognize the CODE;
   any occurrences of #n, for n = 1..9, in the TEXT should be replaced
   by the corresponding ARG, formatted according to its type; if the
   client does not recognize the type, arguments should be substituted
   as is.
   Each CODE or TYPE should be alphanumeric; they need not start
   with a letter. They may have a maximum length of 15 characters.
   Code definitions and type definitions are not strictly
   part of the protocol, and do not *require* protocol version changes.
   However, as a convenience, this file includes a function to do
   expansion with the currently defined codes and types, and the
   protocol minor version will be incremented when new codes and
   types are defined.
   All participants are required always to provide suitable default
   texts.  However, the following function is provided to do basic
   expansion of macros, recognizing no codes or types.
   NOTE: currently, no types or codes are defined.
   As a consequence of the above, any occurrence of {, }, # or \
   in text must be escaped with \.
   Note that substition is NOT recursive, nor are braces balanced:
   "{CODE: one { two } three }" will expand to
   " one { two  three }", possibly with a warning about an unescaped }.
*/

/* basic_expand_protocol_text:
   Perform text expansion as above, recognizing no codes or types.
   dest is the destination string, n its length (including terminating
   null).
   Returns 1 on success, 0 on internal errors (e.g. missing arguments),
   and -1 if dest is not long enough. dest will always be null-terminated.
   If src is null, expands to the empty string.
*/

int basic_expand_protocol_text(char *dest,const char *src,int n);

/* expand_protocol_text:
   Ditto, recognizing all currently defined codes and types.
*/
int expand_protocol_text(char *dest,const char *src,int n);

/* Similar functions for player messages */

char *encode_pmsg(PMsgMsg *msg);
PMsgMsg *decode_pmsg(char *arg);

/* functions given the size of a message type.
   If the size is negative, the last field is a char*
*/
int cmsg_size_of(ControllerMsgType t);
int pmsg_size_of(PlayerMsgType t);

/* functions to copy messages, mallocing space and 
   also mallocing any internal char stars, and to free
*/
CMsgMsg *cmsg_deepcopy(CMsgMsg *m);
PMsgMsg *pmsg_deepcopy(PMsgMsg *m);
void cmsg_deepfree(CMsgMsg *m);
void pmsg_deepfree(PMsgMsg *m);

/* enum parsing and printing functions (mainly for game options) */
#include "protocol-enums.h"

#endif /* PROTOCOL_H_INCLUDED */