Supplementary Shell APIs

Module Description

Shell related functions... (ShellUtil.cpp)

Groups
	LINKDATA Flags
	Tray Support

Classes
struct	LINKDATA

Macros
#define	PACKVERSION(maj, min)   ((DWORD)MAKELONG( min,maj ))

Typedefs
typedef struct _LINKDATA *	PLINKDATA

Functions
bool	InitShellFunc (bool useOle=false, DWORD coFlag=COINIT_APARTMENTTHREADED)
void	DoneShellFunc ()
bool	ShellFuncInitialized ()
PVOID	ShellFreeEx (PVOID pBlk)
LPITEMIDLIST	GetPathNamePIDL (CSTR Dir, ULONG *pAttrib OPTIONAL=NULL)
bool	RecycleFile (CSTR Name, bool Confirm=true, bool Single=true)
DWORD	GetDLLVersion (CSTR FName)
HRESULT	Shell_CreateLink (CSTR LinkFilePathname, IN const PLINKDATA pLink)
HRESULT	Shell_ResolveLink (HWND hWnd, CSTR LinkFilePathname, OUT PLINKDATA pLink)
HRESULT	ShowShareFolderUI (HWND hParent, CSTR Path)
	Transmutable wrap for the strictly dynamic ntshrui.dll function. More...
HRESULT	CreateStreamOnFile (IN CSTR FName, OUT IStream **ppStrm, OPTOUT DWORD *pSize=NULL)

Variables
IMalloc *	ShMalloc

---

Class Documentation

LINKDATA

struct LINKDATA

LINKDATA contains the link details for Shell_CreateLink() and Shell_ResolveLink().
The Pathname and Flags members are mandatory.
Note: When used with Shell_ResolveLink(), string buffers should be >= MAX_PATH chars.

Definition at line 242 of file UtilFunc.h.

Class Members
LPTSTR	Pathname	Pathname of an existing target object the link refers to.
DWORD	Flags	Zero, or LDF_* flags ORed together for optional members. See LINKDATA Flags.
LPTSTR	Desc	[option] Description of link file (f.ex. a "friendly" name).
LPTSTR	Args	[option] Command-line arguments.
LPTSTR	IconPath	[option] Pathname of file containing the icon.
int	IconIndex	[option] Index of icon in IconPath.
LPTSTR	WorkingDir	[option] Working directory when process starts.
int	ShowCmd	[option] How to show the initial window.
WORD	Hotkey	[option] Hot key for the link.
LPITEMIDLIST	IdList	[option] Fully-qualified PIDL.

Macro Definition Documentation

PACKVERSION

#define PACKVERSION	(		maj,
			min
	)		((DWORD)MAKELONG( min,maj ))

See GetDLLVersion()

Definition at line 236 of file UtilFunc.h.

Typedef Documentation

PLINKDATA

typedef struct _LINKDATA * PLINKDATA

LINKDATA contains the link details for Shell_CreateLink() and Shell_ResolveLink().
The Pathname and Flags members are mandatory.
Note: When used with Shell_ResolveLink(), string buffers should be >= MAX_PATH chars.

Function Documentation

InitShellFunc()

bool InitShellFunc	(	bool	useOle = false,
		DWORD	coFlag = COINIT_APARTMENTTHREADED
	)

InitShellFunc calls CoGetMalloc(MEMCTX_TASK) and Ole/CoInitialize.

If useOle is true, OleInitialize is called, otherwise CoInitializeEx
is called with coFlag as the 2nd argument (see CoInitializeEx and COINIT).
If any of it fails, GetLastError tells you why.

Definition at line 37 of file ShellUtil.cpp.

DoneShellFunc()

void DoneShellFunc

(

)

DoneShellFunc knows to uninitialize correctly.

Definition at line 64 of file ShellUtil.cpp.

ShellFuncInitialized()

bool ShellFuncInitialized

(

)

True if InitShellFunc() was called.

Definition at line 24 of file ShellUtil.cpp.

ShellFreeEx()

PVOID ShellFreeEx

(

PVOID

pBlk

)

ShellFreeEx is a null-safe wrap for ShMalloc.

It checks both ShMalloc and pBlk before calling Free.
Returns NULL on success, or pBlk on failure (i.e. like LocalFree).

Side Effects

If ShMalloc is NULL, it is (re)initialized.

Definition at line 79 of file ShellUtil.cpp.

GetPathNamePIDL()

LPITEMIDLIST GetPathNamePIDL	(	CSTR	Dir,
		ULONG *pAttrib	OPTIONAL = NULL
	)

GetPathNamePIDL converts a pathname to an ITEMIDLIST.

Don't forget to free the PIDL with ShMalloc->Free() or ShellFreeEx() when done.
See also IShellFolder::ParseDisplayName()

Example:

InitShellFunc();
TCHAR sBuf[ MAX_PATH ];
ULONG Attr = SFGAO_FILESYSTEM;
LPITEMIDLIST pIdl = GetPathNamePIDL( "C:\\Windows\\System32", &Attr ); // <<==--
// Reciprocity test (reproduce original path string)...
if (SHGetPathFromIDList( pIdl, sBuf ))
    printf( "pIdl = '%s' {0x%08X}\n", sBuf, Attr );
pIdl = ShellFreeEx( pIdl );
DoneShellFunc();

RecycleFile()

bool RecycleFile	(	CSTR	Name,
		bool	Confirm = true,
		bool	Single = true
	)

RecycleFile moves one or more files to the recycle bin.

Parameters

Name	One or more file paths, null separated.
Confirm	Confirm deletion.
Single	If true, Name is treated as a simple string (not multi). If false, Name must follow the rules for multi-sz (double NUL term).

See also SHFileOperation(), newStr().

Definition at line 130 of file ShellUtil.cpp.

GetDLLVersion()

DWORD GetDLLVersion

(

CSTR

FName

)

GetDLLVersion returns the packed version number of a DLL, or 0 if the DLL doesn't export DllGetVersion().
The high word is it's major version, and low word it's minor.

Example:

if (GetDLLVersion("SHELL32") >= PACKVERSION(4,71)) ... 

See also PACKVERSION

Definition at line 156 of file ShellUtil.cpp.

Shell_CreateLink()

HRESULT Shell_CreateLink	(	CSTR	LinkFilePathname,
		IN const PLINKDATA	pLink
	)

Shell_CreateLink creates a classic shortcut lnk file.

Parameters

LinkFilePathname	Pathname of the .lnk file to create.
pLink	Pointer to a struct specifying the link details. See LINKDATA.

Returns

Returns S_OK, or a COM error code.

See also

Shell_ResolveLink(). Defined in ShellUtil.cpp

Shell_ResolveLink()

HRESULT Shell_ResolveLink	(	HWND	hWnd,
		CSTR	LinkFilePathname,
		OUT PLINKDATA	pLink
	)

Shell_ResolveLink resolves a classic lnk link file.

Parameters

LinkFilePathname	Pathname of the .lnk file to resolve.
hWnd	The window to own any query dialogs. Can be NULL.
pLink	Pointer to a struct recieving the link details. See LINKDATA.

Returns

Returns S_OK, or a COM error code.

See also

Shell_CreateLink(). Defined in ShellUtil.cpp

ShowShareFolderUI()

HRESULT ShowShareFolderUI	(	HWND	hParent,
		CSTR	Path
	)

Transmutable wrap for the strictly dynamic ntshrui.dll function.

Displays the Folder Sharing tab on the properties sheet for the specified folder.
This is a transmutable wrap for the strictly dynamic ntshrui.dll function.
See [MSDN] ShowShareFolderUI() for details.

Definition at line 368 of file ShellUtil.cpp.

CreateStreamOnFile()

HRESULT CreateStreamOnFile	(	IN CSTR	FName,
		OUT IStream **	ppStrm,
		OPTOUT DWORD *	pSize = NULL
	)

CreateStreamOnFile creates an IStream interface on a file.

The file is loaded into global memory, then CreateStreamOnHGlobal is used.
Hence, don't use it on files that are too large (use good judgement).
A file size limit of 4 GB is enforced, anything larger begets E_OUTOFMEMORY.
Note: This one pre-dates SHCreateStreamOnFile (which has more options).
Defined in ShellUtil.cpp

Variable Documentation

ShMalloc

IMalloc* ShMalloc

ShMalloc is initialized by InitShellFunc() and released by DoneShellFunc().

Definition at line 17 of file ShellUtil.cpp.