Serialisation: documentation fixes, clarifying renames and whitespace fixes

est31 · est31 · commit 283bf97a1cc5 · 2015-09-14T07:02:15.000+02:00
1. Do two renames:
	* SER_FMT_CLIENT_VER_LOWEST -&gt; SER_FMT_VER_LOWEST_WRITE
	* SER_FMT_VER_LOWEST -&gt; SER_FMT_VER_LOWEST_READ
Now the two define values are consistently named with the _WRITE defines
SER_FMT_VER_{HIGHEST,LOWEST}_WRITE, and to better point out what the two
serialisation versions actually are for.

2. wrap some lines in doc/worldformat.txt, and point out that the node
timers are serialized at a later point, as this can cause confusion about
what now happens (if one doesn't strictly read the if block's conditions).

3. some whitespace fixes in NodeTimerList::serialize, and one new comment.
diff --git a/doc/worldformat.txt b/doc/worldformat.txt
@@ -45,7 +45,8 @@ Contains authentication data, player per line.
 Legacy format (until 0.4.12) of password hash is <name><password> SHA1'd,
 in the base64 encoding.
 
-Format (since 0.4.13) of password hash is #1#<salt>#<verifier>, with the parts inside <> encoded in the base64 encoding.
+Format (since 0.4.13) of password hash is #1#<salt>#<verifier>, with the
+parts inside <> encoded in the base64 encoding.
 <verifier> is an RFC 5054 compatible SRP-2048-SHA1 verifier
 of the given salt, password, and the player's name lowercased.
 
@@ -54,7 +55,7 @@ Example lines:
     celeron55::interact,shout
 - Player "Foo", password "bar", privilege "shout", with a legacy password hash:
     foo:iEPX+SQWIR3p67lj/0zigSWTKHg:shout
-- Player "Foo", password "bar", privilege "shout", with an up to date pw hash (yes it is THAT long):
+- Player "Foo", password "bar", privilege "shout", with a 0.4.13 pw hash:
     foo:#1#hPpy4O3IAn1hsNK00A6wNw#Kpu6rj7McsrPCt4euTb5RA5ltF7wdcWGoYMcRngwDi11cZhPuuR9i5Bo7o6A877TgcEwoc//HNrj9EjR/CGjdyTFmNhiermZOADvd8eu32FYK1kf7RMC0rXWxCenYuOQCG4WF9mMGiyTPxC63VAjAMuc1nCZzmy6D9zt0SIKxOmteI75pAEAIee2hx4OkSXRIiU4Zrxo1Xf7QFxkMY4x77vgaPcvfmuzom0y/fU1EdSnZeopGPvzMpFx80ODFx1P34R52nmVl0W8h4GNo0k8ZiWtRCdrJxs8xIg7z5P1h3Th/BJ0lwexpdK8sQZWng8xaO5ElthNuhO8UQx1l6FgEA:shout
 - Player "bar", no password, no privileges:
     bar::
@@ -316,6 +317,8 @@ if map format version == 24: (NOTE: Not released as stable)
       u16 timer position (z*16*16 + y*16 + x)
       s32 timeout*1000
       s32 elapsed*1000
+if map format version >= 25:
+  -- Nothing right here, node timers are serialized later
 
 u8 static object version:
 - Always 0
diff --git a/src/mapblock.cpp b/src/mapblock.cpp
@@ -564,7 +564,7 @@ void MapBlock::serialize(std::ostream &os, u8 version, bool disk)
 		throw SerializationError("ERROR: Not writing dummy block.");
 	}
 
-	FATAL_ERROR_IF(version < SER_FMT_CLIENT_VER_LOWEST, "Serialize version error");
+	FATAL_ERROR_IF(version < SER_FMT_VER_LOWEST_WRITE, "Serialisation version error");
 
 	// First byte
 	u8 flags = 0;
diff --git a/src/mapblock.h b/src/mapblock.h
@@ -504,7 +504,7 @@ class MapBlock /*: public NodeContainer*/
 
 	// These don't write or read version by itself
 	// Set disk to true for on-disk format, false for over-the-network format
-	// Precondition: version >= SER_FMT_CLIENT_VER_LOWEST
+	// Precondition: version >= SER_FMT_VER_LOWEST_WRITE
 	void serialize(std::ostream &os, u8 version, bool disk);
 	// If disk == true: In addition to doing other things, will add
 	// unknown blocks from id-name mapping to wndef
diff --git a/src/network/serverpackethandler.cpp b/src/network/serverpackethandler.cpp
@@ -103,7 +103,7 @@ void Server::handleCommand_Init(NetworkPacket* pkt)
 	// Use the highest version supported by both
 	u8 depl_serial_v = std::min(client_max, our_max);
 	// If it's lower than the lowest supported, give up.
-	if (depl_serial_v < SER_FMT_VER_LOWEST)
+	if (depl_serial_v < SER_FMT_VER_LOWEST_READ)
 		depl_serial_v = SER_FMT_VER_INVALID;
 
 	if (depl_serial_v == SER_FMT_VER_INVALID) {
@@ -347,7 +347,7 @@ void Server::handleCommand_Init_Legacy(NetworkPacket* pkt)
 	// Use the highest version supported by both
 	int deployed = std::min(client_max, our_max);
 	// If it's lower than the lowest supported, give up.
-	if (deployed < SER_FMT_VER_LOWEST)
+	if (deployed < SER_FMT_VER_LOWEST_READ)
 		deployed = SER_FMT_VER_INVALID;
 
 	if (deployed == SER_FMT_VER_INVALID) {
diff --git a/src/nodetimer.cpp b/src/nodetimer.cpp
@@ -45,28 +45,28 @@ void NodeTimer::deSerialize(std::istream &is)
 
 void NodeTimerList::serialize(std::ostream &os, u8 map_format_version) const
 {
-	if(map_format_version == 24){
+	if (map_format_version == 24) {
 		// Version 0 is a placeholder for "nothing to see here; go away."
-		if(m_data.empty()){
+		if (m_data.empty()) {
 			writeU8(os, 0); // version
 			return;
 		}
 		writeU8(os, 1); // version
 		writeU16(os, m_data.size());
 	}
 
-	if(map_format_version >= 25){
-		writeU8(os, 2+4+4);
+	if (map_format_version >= 25) {
+		writeU8(os, 2 + 4 + 4); // length of the data for a single timer
 		writeU16(os, m_data.size());
 	}
 
-	for(std::map<v3s16, NodeTimer>::const_iterator
+	for (std::map<v3s16, NodeTimer>::const_iterator
 			i = m_data.begin();
-			i != m_data.end(); ++i){
+			i != m_data.end(); ++i) {
 		v3s16 p = i->first;
 		NodeTimer t = i->second;
 
-		u16 p16 = p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X;
+		u16 p16 = p.Z * MAP_BLOCKSIZE * MAP_BLOCKSIZE + p.Y * MAP_BLOCKSIZE + p.X;
 		writeU16(os, p16);
 		t.serialize(os);
 	}
@@ -75,7 +75,7 @@ void NodeTimerList::serialize(std::ostream &os, u8 map_format_version) const
 void NodeTimerList::deSerialize(std::istream &is, u8 map_format_version)
 {
 	m_data.clear();
-	
+
 	if(map_format_version == 24){
 		u8 timer_version = readU8(is);
 		if(timer_version == 0)
diff --git a/src/serialization.h b/src/serialization.h
@@ -30,11 +30,11 @@ with this program; if not, write to the Free Software Foundation, Inc.,
 	--------------------------------
 
 	For map data (blocks, nodes, sectors).
-	
+
 	NOTE: The goal is to increment this so that saved maps will be
 	      loadable by any version. Other compatibility is not
 		  maintained.
-		  
+
 	0: original networked test with 1-byte nodes
 	1: update with 2-byte nodes
 	2: lighting is transmitted in param
@@ -70,14 +70,14 @@ with this program; if not, write to the Free Software Foundation, Inc.,
 // Saved on disk version
 #define SER_FMT_VER_HIGHEST_WRITE 25
 // Lowest supported serialization version
-#define SER_FMT_VER_LOWEST 0
-// Lowest client supported serialization version
+#define SER_FMT_VER_LOWEST_READ 0
+// Lowest serialization version for writing
 // Can't do < 24 anymore; we have 16-bit dynamically allocated node IDs
 // in memory; conversion just won't work in this direction.
-#define SER_FMT_CLIENT_VER_LOWEST 24
+#define SER_FMT_VER_LOWEST_WRITE 24
 
 inline bool ser_ver_supported(s32 v) {
-	return v >= SER_FMT_VER_LOWEST && v <= SER_FMT_VER_HIGHEST_READ;
+	return v >= SER_FMT_VER_LOWEST_READ && v <= SER_FMT_VER_HIGHEST_READ;
 }
 
 /*

Original file line number	Diff line number	Diff line change
`@@ -564,7 +564,7 @@ void MapBlock::serialize(std::ostream &os, u8 version, bool disk)`
`564`	`564`	`throw SerializationError("ERROR: Not writing dummy block.");`
`565`	`565`	`}`
`566`	`566`
`567`		`- FATAL_ERROR_IF(version < SER_FMT_CLIENT_VER_LOWEST, "Serialize version error");`
	`567`	`+ FATAL_ERROR_IF(version < SER_FMT_VER_LOWEST_WRITE, "Serialisation version error");`
`568`	`568`
`569`	`569`	`// First byte`
`570`	`570`	`u8 flags = 0;`