NC-6947: Add progress callback for model IO

Includes example in SDK, UnitTest, and documentation

- Make progress more granular
- Add UnitTest_ProgressCallback
- Add intra-model updates
(their actual progress is monotonically increasing, but actually made up.)

Author: martinweismann

CMakeLists.txt

@@ -8,8 +8,8 @@ project (lib3MF)
 
 # Define Version
 set(LIB3MF_VERSION_MAJOR 1)				# increase on every backward-compatibility breaking change of the API
-set(LIB3MF_VERSION_MINOR 0)				# increase on every backward compatible change of the API
-set(LIB3MF_VERSION_MICRO 9)				# increase on on every change that does not alter the API
+set(LIB3MF_VERSION_MINOR 1)				# increase on every backward compatible change of the API
+set(LIB3MF_VERSION_MICRO 3)				# increase on on every change that does not alter the API
 
 set(CMAKE_INSTALL_BINDIR bin CACHE PATH "directory for installing binary files")
 set(CMAKE_INSTALL_LIBDIR lib CACHE PATH "directory for installing library files")
@@ -99,7 +99,7 @@ SET_TARGET_PROPERTIES(${PROJECT_NAME}_s PROPERTIES PREFIX "" IMPORT_PREFIX "")
 if (UNIX)
 	target_compile_options(${PROJECT_NAME}_s PUBLIC "-fPIC")
 	# Uncomment the following to but the version info into the .so-file.
-	SET_TARGET_PROPERTIES(${PROJECT_NAME}_s PROPERTIES VERSION "${LIB3MF_VERSION_MAJOR}.${LIB3MF_VERSION_MINOR}.${LIB3MF_VERSION_MICRO}.${BUILD_NUMBER}")
+	SET_TARGET_PROPERTIES(${PROJECT_NAME}_s PROPERTIES VERSION "${LIB3MF_VERSION_MAJOR}.${LIB3MF_VERSION_MINOR}.${LIB3MF_VERSION_MICRO}")
 	SET_TARGET_PROPERTIES(${PROJECT_NAME}_s PROPERTIES SOVERSION "${LIB3MF_VERSION_MAJOR}")
 	if (NOT APPLE)
 		SET_TARGET_PROPERTIES(${PROJECT_NAME}_s PROPERTIES LINK_FLAGS -s)

Include/Common/3MF_ProgressMonitor.h

@@ -0,0 +1,79 @@
+/*++
+
+Copyright (C) 2018 Autodesk Inc.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Abstract: Progress Monitor
+
+--*/
+
+#ifndef __NMR_PROGRESSMONITOR
+#define __NMR_PROGRESSMONITOR
+
+#include "Common/3MF_ProgressTypes.h"
+
+#include <memory>
+#include <mutex>
+#include <stack>
+
+namespace NMR
+{
+#define PROGRESS_SLICEUPDATE 1000
+#define PROGRESS_NODEUPDATE 100000
+#define PROGRESS_TRIANGLEUPDATE 100000
+#define PROGRESS_READUPDATE 20000
+#define PROGRESS_READSLICESUPDATE 100
+#define PROGRESS_READBUFFERUPDATE 100
+
+	class CProgressMonitor
+	{
+	public:
+		CProgressMonitor();
+		void SetProgressCallback(Lib3MFProgressCallback callback, void* userData);
+		void ClearProgressCallback();
+		// Returns true if the last callback call returned false
+		bool WasAborted();
+		// If Progress() returns false, the task calling it should try to abort
+		bool QueryCancelled();
+		bool Progress(double progress, ProgressIdentifier identifier);
+
+		static void GetProgressMessage(ProgressIdentifier progressIdentifier, const char ** progressString);
+
+		void PushLevel(double relativeStart, double relativeEnd);
+		std::pair<double, double> PopLevel();
+		void ResetLevels();
+	private:
+		Lib3MFProgressCallback m_progressCallback;
+		void* m_userData;
+		bool m_lastCallbackResult;
+		std::stack<std::pair<double, double>> m_levels;
+
+		std::pair<double, double> Level();
+		std::mutex m_callbackMutex;
+	};
+
+	typedef std::shared_ptr <CProgressMonitor> PProgressMonitor;
+};
+
+#endif // __NMR_PROGRESSMONITOR

Include/Common/3MF_ProgressTypes.h

@@ -0,0 +1,64 @@
+/*++
+
+Copyright (C) 2018 Autodesk Inc.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Abstract: Progress Types
+
+--*/
+
+#pragma once
+
+
+namespace NMR
+{
+	enum ProgressIdentifier {
+		PROGRESS_QUERYCANCELED = 0,
+		PROGRESS_DONE,
+		PROGRESS_CLEANUP,
+		PROGRESS_READSTREAM,
+		PROGRESS_EXTRACTOPCPACKAGE,
+		PROGRESS_READNONROOTMODELS,
+		PROGRESS_READROOTMODEL,
+		PROGRESS_READRESOURCES,
+		PROGRESS_READMESH,
+		PROGRESS_READSLICES,
+		PROGRESS_READBUILD,
+		PROGRESS_CREATEOPCPACKAGE,
+		PROGRESS_WRITEMODELSTOSTREAM,
+		PROGRESS_WRITEROOTMODEL,
+		PROGRESS_WRITENONROOTMODELS,
+		PROGRESS_WRITEATTACHMENTS,
+		PROGRESS_WRITECONTENTTYPES,
+		PROGRESS_WRITENOBJECTS,
+		PROGRESS_WRITENODES,
+		PROGRESS_WRITETRIANGLES,
+		PROGRESS_WRITESLICES
+	};
+	
+	// !!! Matches dll interface type, always modify both
+	// If the first parameter is -1, it does not indicate progress;In that case
+	// it must only be used to stop the execution of the calling function.
+	typedef bool(*Lib3MFProgressCallback)(int, ProgressIdentifier, void*);
+};

Include/Common/MeshInformation/NMR_MeshInformationContainer.h

@@ -35,7 +35,6 @@ This class provides a memory container for holding the texture information state
 #define __NMR_MESHINFORMATIONCONTAINER
 
 #include "Common/MeshInformation/NMR_MeshInformationTypes.h"
-#include "Common/NMR_ErrorConst.h"
 #include "Common/NMR_Types.h"
 #include "Common/NMR_Local.h"
 

Include/Common/NMR_ErrorConst.h

@@ -36,8 +36,15 @@ NMR_ErrorConst.h defines all error code constants.
 // This is the output value of a "uncatched exception"
 #define NMR_GENERICEXCEPTIONSTRING "uncatched exception"
 
+/*-------------------------------------------------------------------
+  Success / user interaction (0x0XXX)
+-------------------------------------------------------------------*/
+
 // Function has suceeded, there has been no error
-#define NMR_SUCCESS 0
+#define NMR_SUCCESS 0x0
+
+// Function was aborted by user
+#define NMR_USERABORTED 0x0001
 
 /*-------------------------------------------------------------------
   General error codes (0x1XXX)

Include/Common/Platform/NMR_Platform.h

@@ -39,13 +39,14 @@ classes.
 #include "Common/Platform/NMR_ExportStream.h"
 #include "Common/Platform/NMR_XmlReader.h"
 #include "Common/Platform/NMR_XmlWriter.h"
+#include "Common/3MF_ProgressMonitor.h"
 
 namespace NMR {
 
 	PImportStream fnCreateImportStreamInstance (_In_ const nfWChar * pwszFileName);
 	PExportStream fnCreateExportStreamInstance (_In_ const nfWChar * pwszFileName);
-	PXmlReader fnCreateXMLReaderInstance (_In_ PImportStream pImportStream);
-	PXmlWriter fnCreateXMLWriterInstance (_In_ PExportStream pExportStream);
+	PXmlReader fnCreateXMLReaderInstance (_In_ PImportStream pImportStream, CProgressMonitor * pProgressMonitor);
+	PXmlWriter fnCreateXMLWriterInstance (_In_ PExportStream pExportStream, CProgressMonitor * pProgressMonitor);
 
 }
 

Include/Common/Platform/NMR_XmlReader_Native.h

@@ -34,6 +34,7 @@ NMR_XMLReader_Native.h defines a XML reader class with a native XML parsing impl
 #define __NMR_XMLREADER_NATIVE
 
 #include "Common/Platform/NMR_XmlReader.h"
+#include "Common/3MF_ProgressMonitor.h"
 
 #include <memory>
 #include <vector>
@@ -74,6 +75,9 @@ namespace NMR {
 
 	class CXmlReader_Native : public CXmlReader {
 	private:
+		nfUint32 m_progressCounter;
+		CProgressMonitor* m_pProgressMonitor;
+
 		nfUint32 m_cbBufferCapacity;
 		// Allocated memory of current and next chunk
 		std::vector<nfWChar> m_UTF16Buffer1;
@@ -152,7 +156,7 @@ namespace NMR {
 		void pushEntity(_In_ nfWChar * pszwEntityStartChar, _In_ nfWChar * pszwEntityEndDelimiter, _In_ nfWChar * pszwNextEntityChar, _In_ nfByte nType, _In_ nfBool bParseForNamespaces, _In_ nfBool bEntityIsFinished);
 
 	public:
-		CXmlReader_Native(_In_ PImportStream pImportStream, _In_ nfUint32 cbBufferCapacity);
+		CXmlReader_Native(_In_ PImportStream pImportStream, _In_ nfUint32 cbBufferCapacity, _In_ CProgressMonitor* pProgressMonitor);
 		~CXmlReader_Native();
 
 		virtual void GetValue(_Outptr_result_buffer_maybenull_(*pcwchValue + 1)  const nfWChar ** ppwszValue, _Out_opt_  nfUint32 *pcwchValue);

Include/Model/COM/NMR_COMInterface_ModelFactory.h

@@ -37,6 +37,7 @@ COM Interface Implementation for the COM Model Factory class.
 
 #include "Model/COM/NMR_COMInterfaces.h" 
 #include "Model/Classes/NMR_Model.h" 
+#include "Common/3MF_ProgressTypes.h" 
 
 namespace NMR {
 
@@ -56,11 +57,13 @@ namespace NMR {
 		LIB3MFMETHOD(GetLastError) (_Out_ DWORD * pErrorCode, _Outptr_opt_ LPCSTR * pErrorMessage);
 
 		LIB3MFMETHOD(CreateModel) (_Outptr_ ILib3MFModel ** ppModel);
+
 		LIB3MFMETHOD(GetSpecVersion) (_Out_ DWORD * pMajorVersion, _Out_ DWORD * pMinorVersion);
 		LIB3MFMETHOD(GetInterfaceVersion) (_Out_ DWORD * pInterfaceVersionMajor, _Out_ DWORD * pInterfaceVersionMinor, _Out_ DWORD * pInterfaceVersionMicro);
 		LIB3MFMETHOD(QueryExtension) (_In_z_ LPCWSTR pwszExtensionUrl, _Out_ BOOL * pbIsSupported, _Out_opt_ DWORD * pExtensionInterfaceVersion);
 		LIB3MFMETHOD(QueryExtensionUTF8) (_In_z_ LPCSTR pszExtensionUrl, _Out_ BOOL * pbIsSupported, _Out_opt_ DWORD * pExtensionInterfaceVersion);
-		
+
+		LIB3MFMETHOD(RetrieveProgressMessage) (_In_ int progressIdentifier, _Out_ LPCSTR * progressMessage);
 
 		CCOMModelFactory();
 	};

Include/Model/COM/NMR_COMInterface_ModelReader.h

@@ -74,6 +74,8 @@ namespace NMR {
 
 		LIB3MFMETHOD(ReadFromCallback) (_In_ void * pReadCallback, _In_ nfUint64 nStreamSize, _In_opt_ void * pSeekCallback, _In_opt_ void * pUserData);
 
+		LIB3MFMETHOD(SetProgressCallback) (_In_ void * callback, _In_ void* userData);
+
 		CCOMModelReader();
 
 		void setReader(_In_ PModelReader pModelReader);

Include/Model/COM/NMR_COMInterface_ModelWriter.h

@@ -66,6 +66,8 @@ namespace NMR {
 		LIB3MFMETHOD(WriteToBuffer) (_Out_ BYTE * pBuffer, _In_ ULONG64 cbBufferSize);
 		LIB3MFMETHOD(WriteToCallback) (_In_ void * pWriteCallback, _In_opt_ void * pSeekCallback, _In_opt_ void * pUserData);
 
+		LIB3MFMETHOD(SetProgressCallback) (_In_ void * callback, _In_ void* userData);
+
 		CCOMModelWriter();
 		void setWriter(_In_ PModelWriter pModelWriter);
 	};