[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/reac... ============================================================================== --- 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/reac... ============================================================================== --- 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/reac... ============================================================================== --- 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);
-
cfinck＠svn.reactos.org