Mikołaj Zalewski : shell32: Document the shell32 " mini-COM" functions.

[Alexandre Julliard]

Module: wine
Branch: master
Commit: 8fcc0bdf7888ce700fb8595a014649ce6d0bbd9a
URL:    http://source.winehq.org/git/?p=wine.git;a=commit;h=8fcc0bdf7888ce700fb8595a...

Author: Mikołaj Zalewski <mikolaj(a)zalewski.pl>
Date:   Fri Sep  8 21:11:01 2006 +0200

shell32: Document the shell32 "mini-COM" functions.

---

 dlls/shell32/shellole.c |   58 ++++++++++++++++++++++++++++++++++++++---------
 dlls/shell32/shellord.c |   47 +++++++++++++++++++++++++++++++++++++-
 2 files changed, 93 insertions(+), 12 deletions(-)

diff --git a/dlls/shell32/shellole.c b/dlls/shell32/shellole.c
index b16be1b..2576cbf 100644
--- a/dlls/shell32/shellole.c
+++ b/dlls/shell32/shellole.c
@@ -78,12 +78,6 @@ static const struct {
 	{NULL,NULL}
 };
 
-/*************************************************************************
- * SHCoCreateInstance [SHELL32.102]
- *
- * NOTES
- *     exported by ordinal
- */
 
 /* FIXME: this should be SHLWAPI.24 since we can't yet import by ordinal */
 
@@ -103,8 +97,22 @@ DWORD WINAPI __SHGUIDToStringW (REFGUID 
 
 }
 
-/************************************************************************/
-
+/*************************************************************************
+ * SHCoCreateInstance [SHELL32.102]
+ *
+ * Equivalent to CoCreateInstance. Under Windows 9x this function could sometimes
+ * use the shell32 built-in "mini-COM" without the need to load ole32.dll - see
+ * SHLoadOLE for details.
+ *
+ * Under wine if a "LoadWithoutCOM" value is present or the object resides in
+ * shell32.dll the function will load the object manually without the help of ole32
+ *
+ * NOTES
+ *     exported by ordinal
+ *
+ * SEE ALSO
+ *     CoCreateInstace, SHLoadOLE
+ */
 HRESULT WINAPI SHCoCreateInstance(
 	LPCWSTR aclsid,
 	const CLSID *clsid,
@@ -253,8 +261,16 @@ HRESULT WINAPI DllGetClassObject(REFCLSI
 /*************************************************************************
  * SHCLSIDFromString				[SHELL32.147]
  *
+ * Under Windows 9x this was an ANSI version of CLSIDFromString. It also allowed
+ * to avoid dependency on ole32.dll (see SHLoadOLE for details).
+ *
+ * Under Windows NT/2000/XP this is equivalent to CLSIDFromString
+ *
  * NOTES
  *     exported by ordinal
+ *
+ * SEE ALSO
+ *     CLSIDFromString, SHLoadOLE
  */
 DWORD WINAPI SHCLSIDFromStringA (LPCSTR clsid, CLSID *id)
 {
@@ -405,7 +421,9 @@ static const IMallocVtbl VT_Shell_IMallo
 /*************************************************************************
  *			 SHGetMalloc			[SHELL32.@]
  *
- * Return the shell IMalloc interface.
+ * Equivalent to CoGetMalloc(MEMCTX_TASK, ...). Under Windows 9x this function
+ * could use the shell32 built-in "mini-COM" without the need to load ole32.dll -
+ * see SHLoadOLE for details. 
  *
  * PARAMS
  *  lpmal [O] Destination for IMalloc interface.
@@ -415,8 +433,12 @@ static const IMallocVtbl VT_Shell_IMallo
  *  Failure. An HRESULT error code.
  *
  * NOTES
- *  This function will use CoGetMalloc() if OLE32.DLL is already loaded.
- *  If not it uses an internal implementation as a fallback.
+ *  wine contains an implementation of an allocator to use when ole32.dll is not
+ *  loaded but it is never used as ole32 is imported by shlwapi which is imported by
+ *  shell32
+ *
+ * SEE ALSO
+ *  CoGetMalloc, SHLoadOLE
  */
 HRESULT WINAPI SHGetMalloc(LPMALLOC *lpmal)
 {
@@ -446,8 +468,15 @@ HRESULT WINAPI SHGetMalloc(LPMALLOC *lpm
 /*************************************************************************
  * SHAlloc					[SHELL32.196]
  *
+ * Equivalent to CoTaskMemAlloc. Under Windows 9x this function could use
+ * the shell32 built-in "mini-COM" without the need to load ole32.dll -
+ * see SHLoadOLE for details. 
+ *
  * NOTES
  *     exported by ordinal
+ *
+ * SEE ALSO
+ *     CoTaskMemAlloc, SHLoadOLE
  */
 LPVOID WINAPI SHAlloc(DWORD len)
 {
@@ -464,8 +493,15 @@ LPVOID WINAPI SHAlloc(DWORD len)
 /*************************************************************************
  * SHFree					[SHELL32.195]
  *
+ * Equivalent to CoTaskMemFree. Under Windows 9x this function could use
+ * the shell32 built-in "mini-COM" without the need to load ole32.dll -
+ * see SHLoadOLE for details. 
+ *
  * NOTES
  *     exported by ordinal
+ *
+ * SEE ALSO
+ *     CoTaskMemFree, SHLoadOLE
  */
 void WINAPI SHFree(LPVOID pv)
 {
diff --git a/dlls/shell32/shellord.c b/dlls/shell32/shellord.c
index c1f953b..14ffcfd 100644
--- a/dlls/shell32/shellord.c
+++ b/dlls/shell32/shellord.c
@@ -438,8 +438,15 @@ int WINAPIV ShellMessageBoxA(
 /*************************************************************************
  * SHRegisterDragDrop				[SHELL32.86]
  *
+ * Probably equivalent to RegisterDragDrop but under Windows 9x it could use the
+ * shell32 built-in "mini-COM" without the need to load ole32.dll - see SHLoadOLE
+ * for details
+ *
  * NOTES
  *     exported by ordinal
+ *
+ * SEE ALSO
+ *     RegisterDragDrop, SHLoadOLE
  */
 HRESULT WINAPI SHRegisterDragDrop(
 	HWND hWnd,
@@ -452,8 +459,15 @@ HRESULT WINAPI SHRegisterDragDrop(
 /*************************************************************************
  * SHRevokeDragDrop				[SHELL32.87]
  *
+ * Probably equivalent to RevokeDragDrop but under Windows 9x it could use the
+ * shell32 built-in "mini-COM" without the need to load ole32.dll - see SHLoadOLE
+ * for details
+ *
  * NOTES
  *     exported by ordinal
+ *
+ * SEE ALSO
+ *     RevokeDragDrop, SHLoadOLE
  */
 HRESULT WINAPI SHRevokeDragDrop(HWND hWnd)
 {
@@ -464,8 +478,15 @@ HRESULT WINAPI SHRevokeDragDrop(HWND hWn
 /*************************************************************************
  * SHDoDragDrop					[SHELL32.88]
  *
+ * Probably equivalent to DoDragDrop but under Windows 9x it could use the
+ * shell32 built-in "mini-COM" without the need to load ole32.dll - see SHLoadOLE
+ * for details
+ *
  * NOTES
  *     exported by ordinal
+ *
+ * SEE ALSO
+ *     DoDragDrop, SHLoadOLE
  */
 HRESULT WINAPI SHDoDragDrop(
 	HWND hWnd,
@@ -1054,12 +1075,20 @@ HRESULT WINAPI SHGetInstanceExplorer (LP
 /*************************************************************************
  * SHFreeUnusedLibraries			[SHELL32.123]
  *
+ * Probably equivalent to CoFreeUnusedLibraries but under Windows 9x it could use
+ * the shell32 built-in "mini-COM" without the need to load ole32.dll - see SHLoadOLE
+ * for details
+ *
  * NOTES
- *  exported by name
+ *     exported by ordinal
+ *
+ * SEE ALSO
+ *     CoFreeUnusedLibraries, SHLoadOLE
  */
 void WINAPI SHFreeUnusedLibraries (void)
 {
 	FIXME("stub\n");
+	CoFreeUnusedLibraries();
 }
 /*************************************************************************
  * DAD_AutoScroll				[SHELL32.129]
@@ -1284,9 +1313,25 @@ HRESULT WINAPI SetAppStartingCursor(HWND
 {	FIXME("hwnd=%p 0x%04lx stub\n",u,v );
 	return 0;
 }
+
 /*************************************************************************
  * SHLoadOLE					[SHELL32.151]
  *
+ * To reduce the memory usage of Windows 95 it's shell32 contained an
+ * internal implementation of a part of COM (see e.g. SHGetMalloc, SHCoCreateInstance,
+ * SHRegisterDragDrop etc.) that allowed to use in-process STA objects without
+ * the need to load OLE32.DLL. If OLE32.DLL was already loaded, the SH* function
+ * would just call the Co* functions.
+ *
+ * The SHLoadOLE was called when OLE32.DLL was being loaded to transfer all the
+ * informations from the shell32 "mini-COM" to ole32.dll.
+ *
+ * See http://blogs.msdn.com/oldnewthing/archive/2004/07/05/173226.aspx for a
+ * detailed description.
+ *
+ * Under wine ole32.dll is always loaded as it is imported by shlwapi.dll which is
+ * imported by shell32 and no "mini-COM" is used (except for the "LoadWithoutCOM"
+ * hack in SHCoCreateInstance)
  */
 HRESULT WINAPI SHLoadOLE(LPARAM lParam)
 {	FIXME("0x%04lx stub\n",lParam);