[Pkg-owncloud-commits] [owncloud-client] 09/171: Doc: Add checksum overview

[Sandro Knauß]

This is an automated email from the git hooks/post-receive script.

hefee-guest pushed a commit to annotated tag upstream/2.1.1+dfsg
in repository owncloud-client.

commit eb28d171f3da509d6e0794cb541320e2eb6dbffd
Author: Christian Kamm <mail at ckamm.de>
Date:   Tue Dec 8 10:59:42 2015 +0100

    Doc: Add checksum overview
---
 src/libsync/checksums.cpp | 54 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/src/libsync/checksums.cpp b/src/libsync/checksums.cpp
index 80fffaf..1e4e295 100644
--- a/src/libsync/checksums.cpp
+++ b/src/libsync/checksums.cpp
@@ -20,6 +20,60 @@
 
 #include <qtconcurrentrun.h>
 
+/** \file checksums.cpp
+ *
+ * \brief Computing and validating file checksums
+ *
+ * Overview
+ * --------
+ *
+ * Checksums are used in two distinct ways during synchronization:
+ *
+ * - to guard uploads and downloads against data corruption
+ *   (transmission checksum)
+ * - to quickly check whether the content of a file has changed
+ *   to avoid redundant uploads (content checksum)
+ *
+ * In principle both are independent and different checksumming
+ * algorithms can be used. To avoid redundant computations, it can
+ * make sense to use the same checksum algorithm though.
+ *
+ * Transmission Checksums
+ * ----------------------
+ *
+ * The usage of transmission checksums is currently optional and needs
+ * to be explicitly enabled by adding 'transmissionChecksum=TYPE' to
+ * the '[General]' section of the config file.
+ *
+ * When enabled, the checksum will be calculated on upload and sent to
+ * the server in the OC-Checksum header with the format 'TYPE:CHECKSUM'.
+ *
+ * On download, the header with the same name is read and if the
+ * received data does not have the expected checksum, the download is
+ * rejected.
+ *
+ * Transmission checksums guard a specific sync action and are not stored
+ * in the database.
+ *
+ * Content Checksums
+ * -----------------
+ *
+ * Sometimes the metadata of a local file changes while the content stays
+ * unchanged. Content checksums allow the sync client to avoid uploading
+ * the same data again by comparing the file's actual checksum to the
+ * checksum stored in the database.
+ *
+ * Content checksums are not sent to the server.
+ *
+ * Checksum Algorithms
+ * -------------------
+ *
+ * - Adler32 (requires zlib)
+ * - MD5
+ * - SHA1
+ *
+ */
+
 namespace OCC {
 
 QByteArray makeChecksumHeader(const QByteArray& checksumType, const QByteArray& checksum)

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-owncloud/owncloud-client.git