soc.message
Class SOCStatusMessage

java.lang.Object
  extended by soc.message.SOCMessage
      extended by soc.message.SOCStatusMessage
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable

public class SOCStatusMessage
extends SOCMessage

This is a text message that shows in a status box on the client. Used for "welcome" message at initial connect to game (follows JOINAUTH or JOINGAMEAUTH), or rejection if client can't join that game (or channel). Also used in SOCAccountClient to tell the user if their change was made successfully.

Sent in response to any message type used by clients to request authentication and create or connect to a game or channel: SOCJoinGame, SOCJoin, SOCImARobot, SOCAuthRequest, SOCNewGameWithOptionsRequest.

Status values:

The Status Value parameter (nonnegative integer) was added in version 1.1.06. For backwards compatibility, the status value (integer getStatusValue() ) is not sent as a parameter if it is 0. (In JSettlers older than 1.1.06, status value is always 0.) Earlier versions simply printed the entire message as text, without trying to parse anything.
Status value back-compatibility:
The server-called method toCmd(int, int, String) checks client version compatibility to avoid sending newly defined status codes/values to clients too old to understand them; older "fallback" status values are sent instead. See individual status values' javadocs.

"Debug Is On" notification:

In version 1.1.17 and newer, a server with debug commands enabled will send a STATUSMESSAGE right after sending its VERSION, which will include text such as "debug is on" or "debugging on". It won't send a nonzero status value, because older client versions might treat it as generic failure and disconnect.

In version 2.0.00 and newer, the server's "debug is on" status is SV_OK_DEBUG_MODE_ON. Older clients are sent SV_OK, and the status text to older clients must include the word "debug".

Author:
Robert S. Thomas
See Also:
Serialized Form

Field Summary
static java.lang.String MSG_SV_NEWCHANNEL_TOO_MANY_CREATED
          Text for SV_NEWCHANNEL_TOO_MANY_CREATED.
static java.lang.String MSG_SV_NEWGAME_ALREADY_EXISTS
          Text for server or client to present: New game requested, but this game already exists
static java.lang.String MSG_SV_NEWGAME_NAME_REJECTED
          Text for server or client to present: New game requested, but game name or player name does not meet standards
static java.lang.String MSG_SV_NEWGAME_NAME_TOO_LONG
          Text for server or client to present: New game requested, but game name or player name is too long.
static java.lang.String MSG_SV_NEWGAME_TOO_MANY_CREATED
          Text for SV_NEWGAME_TOO_MANY_CREATED.
private static long serialVersionUID
           
private  java.lang.String status
          Status message
static int SV_ACCT_CREATED_OK
          For account creation, new account was created successfully = 7
static int SV_ACCT_CREATED_OK_FIRST_ONE
          For account creation, new account was created successfully and was the first account = 18.
static int SV_ACCT_NOT_CREATED_DENIED
          For account creation, the requesting user's account is not authorized to create accounts = 17.
static int SV_ACCT_NOT_CREATED_ERR
          For account creation, an error prevented the account from being created, or server doesn't use accounts, = 8.
static int SV_CANT_JOIN_GAME_VERSION
          This game version is too new for your client's version to join = 5
static int SV_NAME_IN_USE
          This name is already logged in = 4.
static int SV_NAME_NOT_FOUND
          Name not found in server's accounts = 2.
static int SV_NEWCHANNEL_TOO_MANY_CREATED
          New chat channel requested, but client already has created too many active channels.
static int SV_NEWGAME_ALREADY_EXISTS
          New game requested with game options, but this game already exists = 11
static int SV_NEWGAME_NAME_REJECTED
          New game requested, but name of game or player does not meet standards = 12
static int SV_NEWGAME_NAME_TOO_LONG
          New game requested, but name of game or player is too long = 13.
static int SV_NEWGAME_OPTION_UNKNOWN
          New game requested with game options, but some are not recognized by the server = 9
static int SV_NEWGAME_OPTION_VALUE_TOONEW
          New game requested with game options, but this option or value is too new for the client to handle = 10
static int SV_NEWGAME_TOO_MANY_CREATED
          New game requested, but client already has created too many active games.
static int SV_NOT_OK_GENERIC
          SV_NOT_OK_GENERIC = 1 : Generic "not OK" status value.
static int SV_OK
          Status value constants.
static int SV_OK_DEBUG_MODE_ON
          Client has connected successfully (SV_OK) and the server's Debug Mode is on.
static int SV_PROBLEM_WITH_DB
          Cannot log in or create account due to a temporary database problem = 6
static int SV_PW_REQUIRED
          Password required but missing = 16.
static int SV_PW_WRONG
          Incorrect password = 3.
private  int svalue
          Optional status value; defaults to 0 (SV_OK)
 
Fields inherited from class soc.message.SOCMessage
ACCEPTOFFER, ADMINPING, ADMINRESET, AUTHREQUEST, BANKTRADE, BCASTTEXTMSG, BOARDLAYOUT, BOARDLAYOUT2, BOARDSPECIALEDGE, BUILDREQUEST, BUYCARDREQUEST, CANCELBUILDREQUEST, CHANGEFACE, CHANNELS, CHOOSEPLAYER, CHOOSEPLAYERREQUEST, CLEAROFFER, CLEARTRADEMSG, CREATEACCOUNT, DEBUGFREEPLACE, DELETECHANNEL, DELETEGAME, DEVCARDACTION, DEVCARDCOUNT, DICERESULT, DICERESULTRESOURCES, DISCARD, DISCARDREQUEST, DISCOVERYPICK, ENDTURN, FIRSTPLAYER, GAME_NONE, GAMEMEMBERS, GAMEOPTIONGETDEFAULTS, GAMEOPTIONGETINFOS, GAMEOPTIONINFO, GAMES, GAMESERVERTEXT, GAMESTATE, GAMESTATS, GAMESWITHOPTIONS, GAMETEXTMSG, IMAROBOT, INVENTORYITEMACTION, JOIN, JOINAUTH, JOINGAME, JOINGAMEAUTH, LARGESTARMY, LASTSETTLEMENT, LEAVE, LEAVEALL, LEAVEGAME, LEGALEDGES, LOCALIZEDSTRINGS, LONGESTROAD, MAKEOFFER, MEMBERS, messageType, MONOPOLYPICK, MOVEPIECE, MOVEPIECEREQUEST, MOVEROBBER, NEWCHANNEL, NEWGAME, NEWGAMEWITHOPTIONS, NEWGAMEWITHOPTIONSREQUEST, NULLMESSAGE, PICKRESOURCES, PICKRESOURCESREQUEST, PIECEVALUE, PLAYDEVCARDREQUEST, PLAYERELEMENT, PLAYERELEMENTS, PLAYERSTATS, POTENTIALSETTLEMENTS, PUTPIECE, REJECTCONNECTION, REJECTOFFER, REMOVEPIECE, RESETBOARDAUTH, RESETBOARDREJECT, RESETBOARDREQUEST, RESETBOARDVOTE, RESETBOARDVOTEREQUEST, RESOURCECOUNT, REVEALFOGHEX, ROBOTDISMISS, ROBOTJOINGAMEREQUEST, ROLLDICE, ROLLDICEPROMPT, ROLLDICEREQUEST, SCENARIOINFO, sep, sep_char, sep2, sep2_char, SERVERPING, SETPLAYEDDEVCARD, SETSEATLOCK, SETSPECIALITEM, SETTURN, SETUPDONE, SIMPLEACTION, SIMPLEREQUEST, SITDOWN, STARTGAME, STATUSMESSAGE, SVPTEXTMSG, TEXTMSG, TIMINGPING, TURN, UPDATEROBOTPARAMS, VERSION
 
Constructor Summary
SOCStatusMessage(int sv, java.lang.String st)
          Create a StatusMessage message, with a nonzero status value.
SOCStatusMessage(java.lang.String st)
          Create a StatusMessage message, with status value 0 (SV_OK).
 
Method Summary
 java.lang.String getStatus()
           
 int getStatusValue()
           
static SOCStatusMessage parseDataStr(java.lang.String s)
          Parse the command String into a StatusMessage message.
static boolean statusValidAtVersion(int statusValue, int cliVersion)
          Is this status value defined in this version? If not, SV_NOT_OK_GENERIC should be sent instead.
 java.lang.String toCmd()
          STATUSMESSAGE sep [svalue sep2] status
static java.lang.String toCmd(int sv, int cliVers, java.lang.String st)
          STATUSMESSAGE sep [svalue sep2] status -- includes backwards compatibility.
static java.lang.String toCmd(int sv, java.lang.String st)
          STATUSMESSAGE sep [svalue sep2] status -- does not include backwards compatibility.
 java.lang.String toString()
          Simple human-readable representation, used for debug purposes.
 
Methods inherited from class soc.message.SOCMessage
arrayIntoStringBuf, enumIntoStringBuf, getClassNameShort, getMaximumVersion, getMinimumVersion, getType, isSingleLineAndSafe, isSingleLineAndSafe, toMsg
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

serialVersionUID

private static final long serialVersionUID
See Also:
Constant Field Values

SV_OK

public static final int SV_OK
Status value constants. SV_OK = 0 : Welcome, OK to connect.

Since:
1.1.06
See Also:
SV_NOT_OK_GENERIC, Constant Field Values

SV_NOT_OK_GENERIC

public static final int SV_NOT_OK_GENERIC
SV_NOT_OK_GENERIC = 1 : Generic "not OK" status value. This is given to the client if a more specific value does not apply, or if the client's version is older than the version where the more specific value was introduced.

Since:
1.1.06
See Also:
SV_OK, Constant Field Values

SV_NAME_NOT_FOUND

public static final int SV_NAME_NOT_FOUND
Name not found in server's accounts = 2. In version 1.1.19 and higher, the server never replies with this to any authentication request message type; SV_PW_WRONG is sent even if the name doesn't exist.

Since:
1.1.06
See Also:
Constant Field Values

SV_PW_WRONG

public static final int SV_PW_WRONG
Incorrect password = 3. Also used in v1.1.19 and higher for authentication replies when the account name is not found, instead of SV_NAME_NOT_FOUND.

If no password was given but the server requires passwords (a config option in server v1.1.19 and higher), it will reply with SV_PW_REQUIRED if the client is v1.1.19 or higher, SV_PW_WRONG if lower.

Since:
1.1.06
See Also:
Constant Field Values

SV_NAME_IN_USE

public static final int SV_NAME_IN_USE
This name is already logged in = 4. In version 1.1.08 and higher, a "take over" option is used for reconnect when a client loses connection, and server doesn't realize it. A new connection can "take over" the name after a minute's timeout. For actual timeouts, see SOCServer.checkNickname.

Since:
1.1.06
See Also:
Constant Field Values

SV_CANT_JOIN_GAME_VERSION

public static final int SV_CANT_JOIN_GAME_VERSION
This game version is too new for your client's version to join = 5

Server v1.1.20 and newer also send this value to SOCAccountClient if client is too old to create accounts at the server's version because of a required logon auth or other message added since that client's version.

Since:
1.1.06
See Also:
Constant Field Values

SV_PROBLEM_WITH_DB

public static final int SV_PROBLEM_WITH_DB
Cannot log in or create account due to a temporary database problem = 6

Since:
1.1.06
See Also:
Constant Field Values

SV_ACCT_CREATED_OK

public static final int SV_ACCT_CREATED_OK
For account creation, new account was created successfully = 7

Since:
1.1.06
See Also:
SV_ACCT_CREATED_OK_FIRST_ONE, Constant Field Values

SV_ACCT_NOT_CREATED_ERR

public static final int SV_ACCT_NOT_CREATED_ERR
For account creation, an error prevented the account from being created, or server doesn't use accounts, = 8.

To see whether a server v1.1.19 or newer uses accounts and passwords, check whether SOCServerFeatures.FEAT_ACCTS is sent when the client connects.

Since:
1.1.06
See Also:
SV_ACCT_NOT_CREATED_DENIED, Constant Field Values

SV_NEWGAME_OPTION_UNKNOWN

public static final int SV_NEWGAME_OPTION_UNKNOWN
New game requested with game options, but some are not recognized by the server = 9

Since:
1.1.07
See Also:
SOCServer.handleNEWGAMEWITHOPTIONSREQUEST(soc.server.genericServer.StringConnection, soc.message.SOCNewGameWithOptionsRequest), Constant Field Values

SV_NEWGAME_OPTION_VALUE_TOONEW

public static final int SV_NEWGAME_OPTION_VALUE_TOONEW
New game requested with game options, but this option or value is too new for the client to handle = 10

Format of this status text is:
Status string with error message SEP2 game name SEP2 option keyname with problem SEP2 option keyname with problem (if more than one) ...

Since:
1.1.07
See Also:
SOCServer.handleNEWGAMEWITHOPTIONSREQUEST(soc.server.genericServer.StringConnection, soc.message.SOCNewGameWithOptionsRequest), Constant Field Values

SV_NEWGAME_ALREADY_EXISTS

public static final int SV_NEWGAME_ALREADY_EXISTS
New game requested with game options, but this game already exists = 11

Since:
1.1.07
See Also:
SOCServer.handleNEWGAMEWITHOPTIONSREQUEST(soc.server.genericServer.StringConnection, soc.message.SOCNewGameWithOptionsRequest), Constant Field Values

SV_NEWGAME_NAME_REJECTED

public static final int SV_NEWGAME_NAME_REJECTED
New game requested, but name of game or player does not meet standards = 12

Since:
1.1.07
See Also:
SOCServer.createOrJoinGameIfUserOK(soc.server.genericServer.StringConnection, java.lang.String, java.lang.String, java.lang.String, java.util.Map), Constant Field Values

SV_NEWGAME_NAME_TOO_LONG

public static final int SV_NEWGAME_NAME_TOO_LONG
New game requested, but name of game or player is too long = 13. The text returned with this status shall indicate the max permitted length.

Since:
1.1.07
See Also:
SOCServer.createOrJoinGameIfUserOK(soc.server.genericServer.StringConnection, java.lang.String, java.lang.String, java.lang.String, java.util.Map), Constant Field Values

SV_NEWGAME_TOO_MANY_CREATED

public static final int SV_NEWGAME_TOO_MANY_CREATED
New game requested, but client already has created too many active games. The text returned with this status shall indicate the max number.

Since:
1.1.10
See Also:
SOCServer.createOrJoinGameIfUserOK(soc.server.genericServer.StringConnection, java.lang.String, java.lang.String, java.lang.String, java.util.Map), Constant Field Values

SV_NEWCHANNEL_TOO_MANY_CREATED

public static final int SV_NEWCHANNEL_TOO_MANY_CREATED
New chat channel requested, but client already has created too many active channels. The text returned with this status shall indicate the max number.

Since:
1.1.10
See Also:
Constant Field Values

SV_PW_REQUIRED

public static final int SV_PW_REQUIRED
Password required but missing = 16. Used if server config settings require all players to have user accounts and passwords.

Clients older than v1.1.19 won't recognize this status value; if possible they should be sent SV_PW_WRONG instead.

Since:
1.1.19
See Also:
Constant Field Values

SV_ACCT_NOT_CREATED_DENIED

public static final int SV_ACCT_NOT_CREATED_DENIED
For account creation, the requesting user's account is not authorized to create accounts = 17.

Since:
1.1.19
See Also:
SV_ACCT_NOT_CREATED_ERR, Constant Field Values

SV_ACCT_CREATED_OK_FIRST_ONE

public static final int SV_ACCT_CREATED_OK_FIRST_ONE
For account creation, new account was created successfully and was the first account = 18. Normally (when not the first account) the status code returned is SV_ACCT_CREATED_OK. This separate code is provided to let the client know they must authenticate before creating any other accounts.

This status is not sent if the server is in Open Registration mode (SOCServerFeatures.FEAT_OPEN_REG), because in that mode there's nothing special about the first account and no need to authenticate before creating others.

Clients older than v1.1.20 won't recognize this status value; they should be sent SV_ACCT_CREATED_OK instead.

Since:
1.1.20
See Also:
Constant Field Values

SV_OK_DEBUG_MODE_ON

public static final int SV_OK_DEBUG_MODE_ON
Client has connected successfully (SV_OK) and the server's Debug Mode is on. Versions older than 2.0.00 get SV_OK instead; see toCmd(int, int, String).

Since:
2.0.00
See Also:
Constant Field Values

MSG_SV_NEWGAME_ALREADY_EXISTS

public static final java.lang.String MSG_SV_NEWGAME_ALREADY_EXISTS
Text for server or client to present: New game requested, but this game already exists

Since:
1.1.07
See Also:
Constant Field Values

MSG_SV_NEWGAME_NAME_REJECTED

public static final java.lang.String MSG_SV_NEWGAME_NAME_REJECTED
Text for server or client to present: New game requested, but game name or player name does not meet standards

Since:
1.1.07
See Also:
Constant Field Values

MSG_SV_NEWGAME_NAME_TOO_LONG

public static final java.lang.String MSG_SV_NEWGAME_NAME_TOO_LONG
Text for server or client to present: New game requested, but game name or player name is too long. Maximum permitted length is appended to this message after the trailing ":".

Since:
1.1.07
See Also:
Constant Field Values

MSG_SV_NEWGAME_TOO_MANY_CREATED

public static final java.lang.String MSG_SV_NEWGAME_TOO_MANY_CREATED
Text for SV_NEWGAME_TOO_MANY_CREATED. Maximum game count is appended to this after the trailing ":".

Since:
1.1.10
See Also:
Constant Field Values

MSG_SV_NEWCHANNEL_TOO_MANY_CREATED

public static final java.lang.String MSG_SV_NEWCHANNEL_TOO_MANY_CREATED
Text for SV_NEWCHANNEL_TOO_MANY_CREATED. Maximum channel count is appended to this after the trailing ":".

Since:
1.1.10
See Also:
Constant Field Values

status

private java.lang.String status
Status message


svalue

private int svalue
Optional status value; defaults to 0 (SV_OK)

Since:
1.1.06
Constructor Detail

SOCStatusMessage

public SOCStatusMessage(java.lang.String st)
Create a StatusMessage message, with status value 0 (SV_OK).

Parameters:
st - the status message text. For this constructor, since status value is 0, may not contain SOCMessage.sep2 characters. This will cause parsing to fail on the remote end.

SOCStatusMessage

public SOCStatusMessage(int sv,
                        java.lang.String st)
Create a StatusMessage message, with a nonzero status value. Does not check that sv is compatible with the client it's sent to; for that use toCmd(int, int, String) instead.

Parameters:
sv - status value (from constants defined here, such as SV_OK)
st - the status message text. If sv is nonzero, you may embed SOCMessage.sep2 characters in your string, and they will be passed on for the receiver to parse.
Since:
1.1.06
Method Detail

getStatus

public java.lang.String getStatus()
Returns:
the status message text. Is allowed to contain SOCMessage.sep2 characters.

getStatusValue

public int getStatusValue()
Returns:
the status value, as in SV_OK

toCmd

public java.lang.String toCmd()
STATUSMESSAGE sep [svalue sep2] status

Specified by:
toCmd in class SOCMessage
Returns:
the command string

toCmd

public static java.lang.String toCmd(int sv,
                                     java.lang.String st)
STATUSMESSAGE sep [svalue sep2] status -- does not include backwards compatibility. This method is best for sending status values SV_OK or SV_NOT_OK_GENERIC. for other newer status values, call toCmd(int, int, String) instead.

Parameters:
sv - the status value; if 0 or less, is not output. Should be a constant such as SV_OK. Remember that not all client versions recognize every status; see toCmd(int, int, String).
st - the status message text. If sv is nonzero, you may embed SOCMessage.sep2 characters in your string, and they will be passed on for the receiver to parse.
Returns:
the command string

toCmd

public static java.lang.String toCmd(int sv,
                                     int cliVers,
                                     java.lang.String st)
STATUSMESSAGE sep [svalue sep2] status -- includes backwards compatibility. Calls statusValidAtVersion(int, int). if sv isn't recognized in that client version, will send SV_NOT_OK_GENERIC or another "fallback" value defined in the client. See individual status values' javadocs for details.

Parameters:
sv - the status value; if 0 or less, is not output. Should be a constant such as SV_OK.
cliVers - Client's version, same format as Version.versionNumber()
st - the status message text. If sv is nonzero, you may embed SOCMessage.sep2 characters in your string, and they will be passed on for the receiver to parse.
Returns:
the command string
Since:
1.1.07

statusValidAtVersion

public static boolean statusValidAtVersion(int statusValue,
                                           int cliVersion)
Is this status value defined in this version? If not, SV_NOT_OK_GENERIC should be sent instead. A different fallback value can be sent instead if the client is new enough to understand it; for example instead of SV_ACCT_CREATED_OK_FIRST_ONE, send SV_ACCT_CREATED_OK.

Server calls toCmd(int, int, String) to check client version and send a compatible status value.

Parameters:
statusValue - status value (from constants defined here, such as SV_OK)
cliVersion - Client's version, same format as Version.versionNumber(); below 1.1.06, only 0 (SV_OK) is allowed. If cliVersion > ourVersion, will act as if cliVersion == ourVersion.
Since:
1.1.07

parseDataStr

public static SOCStatusMessage parseDataStr(java.lang.String s)
Parse the command String into a StatusMessage message. If status is nonzero, you may embed SOCMessage.sep2 characters in your string, and they will be passed on to the receiver.

Parameters:
s - the String to parse
Returns:
a StatusMessage message, or null of the data is garbled

toString

public java.lang.String toString()
Description copied from class: SOCMessage
Simple human-readable representation, used for debug purposes.

Specified by:
toString in class SOCMessage
Returns:
a human readable form of the message