COMMON: Rename and tweak MD5 functions

* names now comply to our naming conventions
* the function computeStreamMD5AsString which computes the MD5
  as a hex string now returns it as a Common::String
* add doxygen comments

svn-id: r54121

4 files changed, 44 insertions, 27 deletions

diff --git a/common/macresman.cpp b/common/macresman.cpp
index 641702b5ec..d268cfbf89 100644
--- a/common/macresman.cpp
+++ b/common/macresman.cpp
@@ -88,14 +88,12 @@ uint32 MacResManager::getResForkSize() {
 	return _resForkSize;
 }
 
-bool MacResManager::getResForkMD5(char *md5str, uint32 length) {
+Common::String MacResManager::computeResForkMD5AsString(uint32 length) {
 	if (!hasResFork())
-		return false;
+		return Common::String();
 
-	ReadStream *stream = new SeekableSubReadStream(_stream, _resForkOffset, _resForkOffset + _resForkSize);
-	bool retVal = md5_file_string(*stream, md5str, MIN<uint32>(length, _resForkSize));
-	delete stream;
-	return retVal;
+	SeekableSubReadStream resForkStream(_stream, _resForkOffset, _resForkOffset + _resForkSize);
+	return computeStreamMD5AsString(resForkStream, MIN<uint32>(length, _resForkSize));
 }
 
 bool MacResManager::open(Common::String filename) {
diff --git a/common/macresman.h b/common/macresman.h
index d47b0ca329..6b67b06bfb 100644
--- a/common/macresman.h
+++ b/common/macresman.h
@@ -82,7 +82,7 @@ public:
 	Common::SeekableReadStream *getDataFork();
 	Common::String getResName(uint32 typeID, uint16 resID);
 	uint32 getResForkSize();
-	bool getResForkMD5(char *md5str, uint32 length);
+	Common::String computeResForkMD5AsString(uint32 length = 0);
 
 	Common::String getBaseFileName() { return _baseFileName; }
 
diff --git a/common/md5.cpp b/common/md5.cpp
index df544ca0f0..e4736e85ca 100644
--- a/common/md5.cpp
+++ b/common/md5.cpp
@@ -246,7 +246,7 @@ void md5_finish(md5_context *ctx, uint8 digest[16]) {
 }
 
 
-bool md5_file(ReadStream &stream, uint8 digest[16], uint32 length) {
+bool computeStreamMD5(ReadStream &stream, uint8 digest[16], uint32 length) {
 
 #ifdef DISABLE_MD5
 	memset(digest, 0, 16);
@@ -267,12 +267,14 @@ bool md5_file(ReadStream &stream, uint8 digest[16], uint32 length) {
 	while ((i = stream.read(buf, readlen)) > 0) {
 		md5_update(&ctx, buf, i);
 
-		length -= i;
-		if (restricted && length == 0)
-			break;
+		if (restricted) {
+			length -= i;
+			if (length == 0)
+				break;
 
-		if (restricted && sizeof(buf) > length)
-			readlen = length;
+			if (sizeof(buf) > length)
+				readlen = length;
+		}
 	}
 
 	md5_finish(&ctx, digest);
@@ -280,16 +282,16 @@ bool md5_file(ReadStream &stream, uint8 digest[16], uint32 length) {
 	return true;
 }
 
-bool md5_file_string(ReadStream &stream, char *md5str, uint32 length) {
+String computeStreamMD5AsString(ReadStream &stream, uint32 length) {
+	String md5;
 	uint8 digest[16];
-	if (!md5_file(stream, digest, length))
-		return false;
-
-	for (int i = 0; i < 16; i++) {
-		snprintf(md5str + i*2, 3, "%02x", (int)digest[i]);
+	if (computeStreamMD5(stream, digest, length)) {
+		for (int i = 0; i < 16; i++) {
+			md5 += String::format("%02x", (int)digest[i]);
+		}
 	}
 
-	return true;
+	return md5;
 }
 
 } // End of namespace Common
diff --git a/common/md5.h b/common/md5.h
index 1fb937ae9b..29f3aeeb4c 100644
--- a/common/md5.h
+++ b/common/md5.h
@@ -26,18 +26,35 @@
 #define COMMON_MD5_H
 
 #include "common/scummsys.h"
+#include "common/str.h"
 
 namespace Common {
 
 class ReadStream;
 
-bool md5_file(ReadStream &stream, uint8 digest[16], uint32 length = 0);
-
-// The following method work similar to the above one, but
-// instead of computing the binary MD5 digest, it produces
-// a human readable lowercase hexstring representing the digest.
-// The md5str parameter must point to a buffer of 32+1 chars.
-bool md5_file_string(ReadStream &stream, char *md5str, uint32 length = 0);
+/**
+ * Compute the MD5 checksum of the content of the given ReadStream.
+ * The 128 bit MD5 checksum is returned directly in the array digest.
+ * If length is set to a positive value, then only the first length
+ * bytes of the stream are used to compute the checksum.
+ * @param[in] stream	the stream of whose data the MD5 is computed
+ * @param[out] digest	the computed MD5 checksum
+ * @param[in] length	the number of bytes for which to compute the checksum; 0 means all
+ * @return true on success, false if an error occurred
+ */
+bool computeStreamMD5(ReadStream &stream, uint8 digest[16], uint32 length = 0);
+
+/**
+ * Compute the MD5 checksum of the content of the given ReadStream.
+ * The 128 bit MD5 checksum is converted to a human readable
+ * lowercase hex string of length 32.
+ * If length is set to a positive value, then only the first length
+ * bytes of the stream are used to compute the checksum.
+ * @param[in] stream	the stream of whose data the MD5 is computed
+ * @param[in] length	the number of bytes for which to compute the checksum; 0 means all
+ * @return the MD5 as a hex string on success, and an empty string if an error occurred
+ */
+String computeStreamMD5AsString(ReadStream &stream, uint32 length = 0);
 
 } // End of namespace Common