[cfinck] 68253: [SPOOLSS] Halfplement and document the undocumented but exported MarshallDownStructure API. Information about this API was exclusively gained by writing a custom XML file for rohita...

Author: cfinck
Date: Wed Jun 24 16:26:33 2015
New Revision: 68253

URL: http://svn.reactos.org/svn/reactos?rev=68253&view=rev
Log:
[SPOOLSS]
Halfplement and document the undocumented but exported MarshallDownStructure API.
Information about this API was exclusively gained by writing a custom XML file for
rohitab.com's API Monitor and monitoring calls under Windows.

I could figure out the parameters passed to the function, but don't really know what
most of them are for.
For me, the function does what it should and what I will soon need it for, but without
making use of cbSize, cbPerElementSize, cbStructureSize and bSomeBoolean.
A Code Review and additional hints are highly appreciated! My XML file for the API Monitor
is available on request.

Modified:
   
branches/colins-printing-for-freedom/reactos/win32ss/printing/base/spoolss/spoolss.spec
    branches/colins-printing-for-freedom/reactos/win32ss/printing/base/spoolss/tools.c
    branches/colins-printing-for-freedom/reactos/win32ss/printing/include/spoolss.h

Modified:
branches/colins-printing-for-freedom/reactos/win32ss/printing/base/spoolss/spoolss.spec
URL:
http://svn.reactos.org/svn/reactos/branches/colins-printing-for-freedom/rea…
==============================================================================
---
branches/colins-printing-for-freedom/reactos/win32ss/printing/base/spoolss/spoolss.spec	[iso-8859-1]
(original)
+++
branches/colins-printing-for-freedom/reactos/win32ss/printing/base/spoolss/spoolss.spec	[iso-8859-1]
Wed Jun 24 16:26:33 2015
@@ -96,7 +96,7 @@
 @ stub LoadDriverFiletoConvertDevmode
 @ stub LoadDriverWithVersion
 @ stub LogWmiTraceEvent
-@ stub MarshallDownStructure
+@ stdcall MarshallDownStructure(ptr ptr long long)
 @ stub MarshallDownStructuresArray
 @ stub MarshallUpStructure
 @ stub MarshallUpStructuresArray

Modified:
branches/colins-printing-for-freedom/reactos/win32ss/printing/base/spoolss/tools.c
URL:
http://svn.reactos.org/svn/reactos/branches/colins-printing-for-freedom/rea…
==============================================================================
---
branches/colins-printing-for-freedom/reactos/win32ss/printing/base/spoolss/tools.c	[iso-8859-1]
(original)
+++
branches/colins-printing-for-freedom/reactos/win32ss/printing/base/spoolss/tools.c	[iso-8859-1]
Wed Jun 24 16:26:33 2015
@@ -7,6 +7,56 @@
 
 #include "precomp.h"
 
+
+/**
+ * @name MarshallDownStructure
+ *
+ * Prepare a structure for marshalling/serialization by replacing absolute pointer
addresses in its fields by relative offsets.
+ *
+ * @param pStructure
+ * Pointer to the structure to operate on.
+ *
+ * @param pParameters
+ * Array of MARSHALL_DOWN_INFO elements containing information about the fields of the
structure as well as how to modify them.
+ * See the documentation on MARSHALL_DOWN_INFO for more information.
+ * You have to indicate the end of the array by setting the dwOffset field to MAXDWORD.
+ *
+ * @param cbStructureSize
+ * Apparently, this is the size in bytes of the structure given through pStructure under
Windows.
+ * This parameter is unused in my implementation.
+ *
+ * @param bSomeBoolean
+ * Unknown boolean value
+ *
+ * @return
+ * TRUE if the structure was successfully adjusted, FALSE otherwise.
+ */
+BOOL WINAPI
+MarshallDownStructure(PVOID pStructure, PMARSHALL_DOWN_INFO pParameters, DWORD
cbStructureSize, BOOL bSomeBoolean)
+{
+    // Sanity checks
+    if (!pStructure || !pParameters)
+    {
+        SetLastError(ERROR_INVALID_PARAMETER);
+        return FALSE;
+    }
+
+    // Loop until we reach an element with offset set to MAXDWORD.
+    while (pParameters->dwOffset != MAXDWORD)
+    {
+        if (pParameters->bAdjustAddress)
+        {
+            // Apply the byte offset on pStructure. There must be a pointer at this
position, whose address we're adjusting
+            // by subtracting the address of pStructure from it.
+            *((PULONG_PTR)((PBYTE)pStructure + pParameters->dwOffset)) -=
(ULONG_PTR)pStructure;
+        }
+
+        // Advance to the next element description.
+        pParameters++;
+    }
+
+    return TRUE;
+}
 
 /**
  * @name PackStrings

Modified: branches/colins-printing-for-freedom/reactos/win32ss/printing/include/spoolss.h
URL:
http://svn.reactos.org/svn/reactos/branches/colins-printing-for-freedom/rea…
==============================================================================
---
branches/colins-printing-for-freedom/reactos/win32ss/printing/include/spoolss.h	[iso-8859-1]
(original)
+++
branches/colins-printing-for-freedom/reactos/win32ss/printing/include/spoolss.h	[iso-8859-1]
Wed Jun 24 16:26:33 2015
@@ -8,10 +8,22 @@
 #ifndef _REACTOS_SPOOLSS_H
 #define _REACTOS_SPOOLSS_H
 
+typedef struct _MARSHALL_DOWN_INFO
+{
+    DWORD dwOffset;             /** Byte offset of this element within the structure or
MAXDWORD to indicate the end of the array */
+    DWORD cbSize;               /** Total size of this element in bytes under Windows.
Unused here, I don't know what we need this number for. */
+    DWORD cbPerElementSize;     /** If this element is a structure itself, this field
gives the size in bytes of each element of the structure.
+                                    Otherwise, this is the same as cbTotalSize. E.g. for
SYSTEMTIME, cbSize would be 16 and cbPerElementSize would be 2.
+                                    Unused here, I don't know what we need this
number for. */
+    BOOL bAdjustAddress;        /** TRUE if MarshallDownStructure shall adjust the
address of this element, FALSE if it shall leave this element untouched. */
+}
+MARSHALL_DOWN_INFO, *PMARSHALL_DOWN_INFO;
+
 PWSTR WINAPI AllocSplStr(PCWSTR pwszInput);
 PVOID WINAPI DllAllocSplMem(DWORD dwBytes);
 BOOL WINAPI DllFreeSplMem(PVOID pMem);
 BOOL WINAPI DllFreeSplStr(PWSTR pwszString);
+BOOL WINAPI MarshallDownStructure(PVOID pStructure, PMARSHALL_DOWN_INFO pParameters,
DWORD cbStructureSize, BOOL bSomeBoolean);
 PBYTE WINAPI PackStrings(PCWSTR* pSource, PBYTE pDest, PDWORD DestOffsets, PBYTE pEnd);
 PVOID WINAPI ReallocSplMem(PVOID pOldMem, DWORD cbOld, DWORD cbNew);
 BOOL WINAPI ReallocSplStr(PWSTR* ppwszString, PCWSTR pwszInput);