Changelog
- dlls/shell32/pidl.c
Add some comments to functions and minor fixes
- dlls/shell32/shell32.spec
Export already existing (but still undocumented) functions ILCreateFromPathA/W
License: X11
Rolf Kalbermatter
Index: dlls/shell32/pidl.c
===================================================================
RCS file: /home/wine/wine/dlls/shell32/pidl.c,v
retrieving revision 1.89
diff -u -r1.89 pidl.c
--- dlls/shell32/pidl.c 17 Sep 2003 04:17:33 -0000 1.89
+++ dlls/shell32/pidl.c 19 Sep 2003 10:50:50 -0000
@@ -349,46 +349,59 @@
return ret;
}
-HRESULT WINAPI SHILCreateFromPathA (LPCSTR path, LPITEMIDLIST * ppidl, DWORD * attributes)
-{ LPSHELLFOLDER sf;
+/*************************************************************************
+ * SHILCreateFromPath [SHELL32.28]
+ *
+ * Create an ItemIDList from a path
+ *
+ * PARAMS
+ * path [I]
+ * ppidl [O]
+ * attributes [I/O] requested attributes on call and actual attributes when
+ * the function returns
+ *
+ * RETURNS
+ * NO_ERROR if successful, or an OLE errer code otherwise
+ *
+ * NOTES
+ * Wrapper for IShellFolder_ParseDisplayName().
+ */
+HRESULT WINAPI SHILCreateFromPathA(LPCSTR path, LPITEMIDLIST * ppidl, DWORD * attributes)
+{
+ LPSHELLFOLDER sf;
WCHAR lpszDisplayName[MAX_PATH];
DWORD pchEaten;
HRESULT ret = E_FAIL;
- TRACE_(shell)("%s %p 0x%08lx\n",path,ppidl,attributes?*attributes:0);
+ TRACE_(shell)("%s %p 0x%08lx\n", path, ppidl, attributes ? *attributes : 0);
- if (!MultiByteToWideChar( CP_ACP, 0, path, -1, lpszDisplayName, MAX_PATH ))
- lpszDisplayName[MAX_PATH-1] = 0;
+ if (!MultiByteToWideChar(CP_ACP, 0, path, -1, lpszDisplayName, MAX_PATH))
+ lpszDisplayName[MAX_PATH-1] = 0;
if (SUCCEEDED (SHGetDesktopFolder(&sf)))
{
- ret = IShellFolder_ParseDisplayName(sf,0, NULL,lpszDisplayName,&pchEaten,ppidl,attributes);
+ ret = IShellFolder_ParseDisplayName(sf, 0, NULL, lpszDisplayName, &pchEaten, ppidl, attributes);
IShellFolder_Release(sf);
}
return ret;
}
-HRESULT WINAPI SHILCreateFromPathW (LPCWSTR path, LPITEMIDLIST * ppidl, DWORD * attributes)
-{ LPSHELLFOLDER sf;
+HRESULT WINAPI SHILCreateFromPathW(LPCWSTR path, LPITEMIDLIST * ppidl, DWORD * attributes)
+{
+ LPSHELLFOLDER sf;
DWORD pchEaten;
HRESULT ret = E_FAIL;
- TRACE_(shell)("%s %p 0x%08lx\n",debugstr_w(path),ppidl,attributes?*attributes:0);
+ TRACE_(shell)("%s %p 0x%08lx\n", debugstr_w(path), ppidl, attributes ? *attributes : 0);
if (SUCCEEDED (SHGetDesktopFolder(&sf)))
{
- ret = IShellFolder_ParseDisplayName(sf,0, NULL, (LPWSTR) path, &pchEaten, ppidl, attributes);
+ ret = IShellFolder_ParseDisplayName(sf, 0, NULL, (LPWSTR)path, &pchEaten, ppidl, attributes);
IShellFolder_Release(sf);
}
return ret;
}
-/*************************************************************************
- * SHILCreateFromPath [SHELL32.28]
- *
- * NOTES
- * Wrapper for IShellFolder_ParseDisplayName().
- */
HRESULT WINAPI SHILCreateFromPathAW (LPCVOID path, LPITEMIDLIST * ppidl, DWORD * attributes)
{
if ( SHELL_OsIsUnicode())
@@ -397,30 +410,48 @@
}
/*************************************************************************
- * SHCloneSpecialIDList [SHELL32.89]
+ * SHCloneSpecialIDList [SHELL32.89]
*
- * PARAMETERS
- * hwndOwner [in]
- * nFolder [in] CSIDL_xxxxx ??
+ * Create an ItemIDList to one of the special folders.
+
+ * PARAMS
+ * hwndOwner [in]
+ * nFolder [in] CSIDL_xxxxx
+ * fCreate [in] Create folder if it does not exist
*
* RETURNS
- * pidl ??
+ * Success: The newly created pidl
+ * Failure: NULL, if inputs are invalid.
+ *
* NOTES
- * exported by ordinal
+ * exported by ordinal.
+ * Caller is responsible for deallocating the returned ItemIDList with the
+ * shells IMalloc interface, aka ILFree.
*/
-LPITEMIDLIST WINAPI SHCloneSpecialIDList(HWND hwndOwner,DWORD nFolder,DWORD x3)
+LPITEMIDLIST WINAPI SHCloneSpecialIDList(HWND hwndOwner, DWORD nFolder, BOOL fCreate)
{ LPITEMIDLIST ppidl;
- WARN_(shell)("(hwnd=%p,csidl=0x%lx,0x%lx):semi-stub.\n",
- hwndOwner,nFolder,x3);
+ TRACE_(shell)("(hwnd=%p,csidl=0x%lx,%s).\n", hwndOwner, nFolder, fCreate ? "T" : "F");
- SHGetSpecialFolderLocation(hwndOwner, nFolder, &ppidl);
+ if (fCreate)
+ nFolder |= CSIDL_FLAG_CREATE;
+ SHGetSpecialFolderLocation(hwndOwner, nFolder, &ppidl);
return ppidl;
}
/*************************************************************************
- * ILGlobalClone [SHELL32.20]
+ * ILGlobalClone [SHELL32.20]
+ *
+ * Clones an ItemIDList using Alloc.
+ *
+ * PARAMS
+ * pidl [I] ItemIDList to clone
*
+ * RETURNS
+ * Newly allocated ItemIDList.
+ *
+ * NOTES
+ * exported by ordinal.
*/
LPITEMIDLIST WINAPI ILGlobalClone(LPCITEMIDLIST pidl)
{ DWORD len;
@@ -483,13 +514,26 @@
return FALSE;
}
/*************************************************************************
- * ILIsParent [SHELL32.23]
+ * ILIsParent [SHELL32.23]
+ *
+ * Verifies that pidlParent is indeed the (immediate) parent of pidlChild.
*
- * parent=a/b child=a/b/c -> true, c is in folder a/b
- * child=a/b/c/d -> false if bImmediate is true, d is not in folder a/b
- * child=a/b/c/d -> true if bImmediate is false, d is in a subfolder of a/b
+ * PARAMS
+ * pidlParent [I]
+ * pidlChild [I]
+ * bImmediate [I] only return true if the parent is the direct parent
+ * of the child
+ *
+ * RETURNS
+ * True if the parent ItemIDlist is a complete part of the child ItemIdList,
+ * False otherwise.
+ *
+ * NOTES
+ * parent = a/b, child = a/b/c -> true, c is in folder a/b
+ * child = a/b/c/d -> false if bImmediate is true, d is not in folder a/b
+ * child = a/b/c/d -> true if bImmediate is false, d is in a subfolder of a/b
*/
-BOOL WINAPI ILIsParent( LPCITEMIDLIST pidlParent, LPCITEMIDLIST pidlChild, BOOL bImmediate)
+BOOL WINAPI ILIsParent(LPCITEMIDLIST pidlParent, LPCITEMIDLIST pidlChild, BOOL bImmediate)
{
char szData1[MAX_PATH];
char szData2[MAX_PATH];
@@ -511,26 +555,33 @@
pChild = ILGetNext(pChild);
}
- if ( pParent->mkid.cb || ! pChild->mkid.cb) /* child shorter or has equal length to parent */
+ if ( pParent->mkid.cb || ! pChild->mkid.cb) /* child shorter or has equal length to parent */
return FALSE;
- if ( ILGetNext(pChild)->mkid.cb && bImmediate) /* not immediate descent */
+ if ( ILGetNext(pChild)->mkid.cb && bImmediate) /* not immediate descent */
return FALSE;
return TRUE;
}
/*************************************************************************
- * ILFindChild [SHELL32.24]
+ * ILFindChild [SHELL32.24]
*
- * NOTES
* Compares elements from pidl1 and pidl2.
*
- * pidl1 is desktop pidl2
- * pidl1 shorter pidl2 pointer to first different element of pidl2
- * if there was at least one equal element
- * pidl2 shorter pidl1 0
- * pidl2 equal pidl1 pointer to last 0x00-element of pidl2
+ * PARAMS
+ * pidl1 [I]
+ * pidl2 [I]
+ *
+ * RETURNS
+ * pidl1 is desktop pidl2
+ * pidl1 shorter pidl2 pointer to first different element of pidl2
+ * if there was at least one equal element
+ * pidl2 shorter pidl1 0
+ * pidl2 equal pidl1 pointer to last 0x00-element of pidl2
+ *
+ * NOTES
+ * exported by ordinal.
*/
LPITEMIDLIST WINAPI ILFindChild(LPCITEMIDLIST pidl1, LPCITEMIDLIST pidl2)
{
@@ -580,14 +631,25 @@
}
/*************************************************************************
- * ILCombine [SHELL32.25]
+ * ILCombine [SHELL32.25]
+ *
+ * Concatenates two complex ItemIDLists.
+ *
+ * PARAMS
+ * pidl1 [I] first complex ItemIDLists
+ * pidl2 [I] complex ItemIDLists to append
+ *
+ * RETURNS
+ * if both pidl's == NULL NULL
+ * if pidl1 == NULL cloned pidl2
+ * if pidl2 == NULL cloned pidl1
+ * otherwise new pidl with pidl2 appended to pidl1
*
* NOTES
- * Concatenates two complex idlists.
- * The pidl is the first one, pidlsub the next one
- * Does not destroy the passed in idlists!
+ * exported by ordinal.
+ * Does not destroy the passed in ItemIDLists!
*/
-LPITEMIDLIST WINAPI ILCombine(LPCITEMIDLIST pidl1,LPCITEMIDLIST pidl2)
+LPITEMIDLIST WINAPI ILCombine(LPCITEMIDLIST pidl1, LPCITEMIDLIST pidl2)
{
DWORD len1,len2;
LPITEMIDLIST pidlNew;
@@ -654,14 +716,15 @@
}
/*************************************************************************
- * ILGetSize [SHELL32.152]
- * gets the byte size of an idlist including zero terminator (pidl)
+ * ILGetSize [SHELL32.152]
*
- * PARAMETERS
- * pidl ITEMIDLIST
+ * Gets the byte size of an ItemIDList including zero terminator
+ *
+ * PARAMS
+ * pidl [I] ItemIDList
*
* RETURNS
- * size of pidl
+ * size of pidl in bytes
*
* NOTES
* exported by ordinal
@@ -683,14 +746,20 @@
}
/*************************************************************************
- * ILGetNext [SHELL32.153]
- * gets the next simple pidl of a complex pidl
+ * ILGetNext [SHELL32.153]
+ *
+ * Gets the next ItemID of an ItemIDList
*
- * observed return values:
+ * PARAMS
+ * pidl [I] ItemIDList
+ *
+ * RETURNS
* null -> null
* desktop -> null
* simple pidl -> pointer to 0x0000 element
*
+ * NOTES
+ * exported by ordinal.
*/
LPITEMIDLIST WINAPI ILGetNext(LPCITEMIDLIST pidl)
{
@@ -710,16 +779,23 @@
}
return NULL;
}
+
/*************************************************************************
- * ILAppend [SHELL32.154]
+ * ILAppend [SHELL32.154]
+ *
+ * Adds the single ItemID item to the ItemIDList indicated by pidl.
+ * If bEnd is FALSE, inserts the item in the front of the list,
+ * otherwise it adds the item to the end. (???)
+ *
+ * PARAMS
+ * pidl [I] ItemIDList to extend
+ * item [I] ItemID to prepend/append
+ * bEnd [I] Indicates if the item should be appended
*
* NOTES
- * Adds the single item to the idlist indicated by pidl.
- * if bEnd is 0, adds the item to the front of the list,
- * otherwise adds the item to the end. (???)
* Destroys the passed in idlist! (???)
*/
-LPITEMIDLIST WINAPI ILAppend(LPITEMIDLIST pidl,LPCITEMIDLIST item,BOOL bEnd)
+LPITEMIDLIST WINAPI ILAppend(LPITEMIDLIST pidl, LPCITEMIDLIST item, BOOL bEnd)
{
LPITEMIDLIST idlRet;
@@ -738,23 +814,27 @@
if (bEnd)
{
- idlRet=ILCombine(pidl,item);
+ idlRet = ILCombine(pidl, item);
}
else
{
- idlRet=ILCombine(item,pidl);
+ idlRet = ILCombine(item, pidl);
}
SHFree(pidl);
return idlRet;
}
+
/*************************************************************************
- * ILFree [SHELL32.155]
+ * ILFree [SHELL32.155]
+ *
+ * Frees memory (if not NULL) allocated by SHMalloc allocator
+ *
+ * PARAMS
+ * pidl [I]
*
* NOTES
- * free_check_ptr - frees memory (if not NULL)
- * allocated by SHMalloc allocator
- * exported by ordinal
+ * exported by ordinal
*/
DWORD WINAPI ILFree(LPITEMIDLIST pidl)
{
@@ -764,49 +844,76 @@
SHFree(pidl);
return TRUE;
}
+
/*************************************************************************
- * ILGlobalFree [SHELL32.156]
+ * ILGlobalFree [SHELL32.156]
+ *
+ * Frees memory (if not NULL) allocated by Alloc allocator
+ *
+ * PARAMS
+ * pidl [I]
*
+ * NOTES
+ * exported by ordinal.
*/
void WINAPI ILGlobalFree( LPITEMIDLIST pidl)
{
- TRACE("%p\n",pidl);
+ TRACE("%p\n", pidl);
if(!pidl) return;
Free(pidl);
}
+
/*************************************************************************
- * ILCreateFromPath [SHELL32.157]
+ * ILCreateFromPathA [SHELL32.189]
+ *
+ * Creates a complex ItemIDList from a path and returns it.
*
+ * PARAMS
+ * path [I]
+ *
+ * RETURNS
+ * the newly created complex ItemIDList or NULL if failed
+ *
+ * NOTES
+ * exported by ordinal.
*/
+
LPITEMIDLIST WINAPI ILCreateFromPathA (LPCSTR path)
{
- LPITEMIDLIST pidlnew;
- DWORD attributes = 0;
+ LPITEMIDLIST pidlnew = NULL;
- TRACE_(shell)("%s\n",path);
+ TRACE_(shell)("%s\n", debugstr_a(path));
- if (SUCCEEDED (SHILCreateFromPathA (path, &pidlnew, &attributes)))
+ if (SUCCEEDED(SHILCreateFromPathA(path, &pidlnew, NULL)))
return pidlnew;
- return FALSE;
+ return NULL;
}
+
+/*************************************************************************
+ * ILCreateFromPathW [SHELL32.190]
+ */
LPITEMIDLIST WINAPI ILCreateFromPathW (LPCWSTR path)
{
- LPITEMIDLIST pidlnew;
- DWORD attributes = 0;
+ LPITEMIDLIST pidlnew = NULL;
- TRACE_(shell)("%s\n",debugstr_w(path));
+ TRACE_(shell)("%s\n", debugstr_w(path));
- if (SUCCEEDED (SHILCreateFromPathW (path, &pidlnew, &attributes)))
+ if (SUCCEEDED(SHILCreateFromPathW(path, &pidlnew, NULL)))
return pidlnew;
- return FALSE;
+ return NULL;
}
+
+/*************************************************************************
+ * ILCreateFromPath [SHELL32.157]
+ */
LPITEMIDLIST WINAPI ILCreateFromPathAW (LPCVOID path)
{
if ( SHELL_OsIsUnicode())
return ILCreateFromPathW (path);
return ILCreateFromPathA (path);
}
+
/*************************************************************************
* _ILParsePathW [internal]
*
Index: dlls/shell32/shell32.spec
===================================================================
RCS file: /home/wine/wine/dlls/shell32/shell32.spec,v
retrieving revision 1.75
diff -u -r1.75 shell32.spec
--- dlls/shell32/shell32.spec 21 Aug 2003 21:26:07 -0000 1.75
+++ dlls/shell32/shell32.spec 19 Sep 2003 10:59:21 -0000
@@ -89,9 +89,9 @@
95 stdcall SHLogILFromFSIL (ptr)
96 stdcall StrRetToStrN (ptr long ptr ptr) StrRetToStrNAW
97 stdcall SHWaitForFileToOpen (long long long)
- 98 stdcall SHGetRealIDL (long long long)
+ 98 stdcall -noname SHGetRealIDL (ptr ptr ptr)
99 stdcall SetAppStartingCursor (long long)
100 stdcall SHRestricted(long)
102 stdcall SHCoCreateInstance(ptr ptr long ptr ptr)
@@ -174,6 +174,8 @@
184 stdcall ArrangeWindows(long long long long long)
185 stub SHHandleDiskFull
186 stdcall ILGetDisplayNameEx(ptr ptr ptr long)
+ 189 stdcall -noname ILCreateFromPathA(str)
+ 190 stdcall -noname ILCreateFromPathW(wstr)
195 stdcall SHFree(ptr)
196 stdcall SHAlloc(long)
197 stub SHGlobalDefect
