Visual Basic Win32 Shell Routines
Undocumented Windows: Overview
     
Posted:   Wednesday August 6, 1997
Updated:   Monday December 26, 2011
     
Applies to:   VB4-32, VB5, VB6
Developed with:   VB4-32, Windows 95
OS restrictions:   None
Author:   Brad Martinez
     

Related:  

SHChangeNotifyRegister: Receive Shell Change Notifications
Undocumented Windows: Shell Dialogs
Undocumented Windows: Format Disk Dialog
Undocumented Windows: Change Icon Dialog
Undocumented Windows: Path Functions
       
 Introduction
To assist Windows in delivering its system services, it relies on undocumented APIs. All of the Shell32.dll functions demonstrated are exported only by ordinal (NONAME) and are not known to be documented by Microsoft. As a result, they are most likely not supported by Microsoft and may very well not be included in future versions of Shell32.dll, may or may not use the same ordinal numbers for the same API, or may add or remove parameters. Therefore, use them at your own risk. Note that these ordinals have been tested only against Windows 95 and NT4. Initial testing indicates none missing in Windows 98, however note that Windows 98 has duplicated some of these as standard non-ordinal Shell APIs.

The SHFormatDrive syntax was provided by Joe LeVasseur. The syntax and description of all other functions below was derived and tested by Brad Martinez, who has provided the following explanations of the APIs and their usage.


From what may have been their original exported name in the debug version of the library, these undocumented API functions have been renamed to a slightly more intuitive name (since only the ordinals are shown in an export dump of Shell32.dll). It is suggested that developers who decide to implement these functions maintain the names that are used here to avoid confusion.

APIs by Category / Ordinal Numbers

Ord Hidden name pb Renamed to Operation Performed
59 _RestartDialog 12 SHRestartSystemMB Displays the "System Settings Change" reboot message box
60 ? 4 SHShutDownDialog Displays the Shut Down dialog (Start/Shut Down)
61 ? 24 SHRunDialog Displays the Run dialog (Start/Run)
62 _PickIconDlg 16 SHChangeIconDialog Allows choosing form amongst a files icons.
31 _PathFindExtension 4 SHGetExtension Returns pointer to the last dot in szPath and the string following it.
32 _PathAddBackslash 4 SHAddBackslash Inserts a backslash before the first null char in szPath.
34 _PathFindFileName 4 SHGetFileName Returns a pointer to the string in szPath after the last backslash.
35 _PathRemoveFileSpec 4 SHGetPath Returns a pointer to the string in szPath before the last backslash.
40 _PathIsRelative 4 SHPathIsRelative Returns non-zero if szPath does not evaluate to a UNC path.
43 _PathIsExe 4 SHPathIsExe Returns non-zero if szPath has an executable extension.
45 _PathFileExists 4 SHFileExists Returns non-zero if szPath is valid absolute UNC path.
52 _PathGetArgs 4 SHGetPathArgs Returns a pointer to the string after first space in szPath.
55 _PathQuoteSpaces 4 SHAddPathQuotes Adds quotes if the path or file contains a space
56 _PathUnquoteSpaces 4 SHRemovePathQuotes Removes quotes from quoted paths\filename
92 _PathGetintPath 4 SHGetShortPathName Fills szPath w/ its DOS (8.3) file system string.

pb refers to parameter bytes .... that is, the number of bytes passed in the calls as parameters.

These are but a small portion of the ordinal undocumented APIs .... just those that are presently demonstrated in the associated VBnet demo pages. As time goes on, more will be added.

IMPORTANT NOTE: Unlike most documented Win32 API functions, the functions that accept string parameters (all but SHShutDownDialog) expect strings in either the ANSI or Unicode character sets depending on the Windows platform the function is called from (i.e. there are no separate ANSI "A" or Wide "W" function versions as in the documented APIs).

In order for a function to return an accurate value (and reduce the potential for a fatal exception), the function must be passed ANSI strings when called in Win95, and must be passed Unicode strings when called in WinNT. Note the explicit use of the global "bIsWinNT" flag throughout the demos, and the corresponding calls to VBs StrConv function (in the wrapper routine CheckString) to convert the ANSI strings to their Unicode equivalent when bIsWinNT evaluates to True (this is the same as using the MultiByteToWideChar API on those strings).

If it is discovered that any of the information in this demo proves to be inaccurate or incomplete, Brad Martinez and/or VBnet would appreciate notification at either of the email addresses below, so that the required corrections can be made. And if anyone has insight into the purpose of the "unknown" variables in the declares below, again, please let us know. Finally, this demo would not have happened if it weren't for the function prototypes found at Chris Becke's site. I thank him for making this information available. Enjoy!.

Brad Martinez
http://www.mvps.org/btmtz/
Comments: to Brad to VBnet

The code for all undocumented sample apps was developed and tested by Brad using VB4.0a-32 on both Win95 v4.00.950a and WinNT v4.0 Server SP2, and then again by Randy (who often can't leave well-enough alone and broke his example into smaller topical pieces for posting here) with VB5.0 under Win95 4.00.950b (OSR2).

NOTE: The following is for information and completeness only; each Windows by the Numbers sample app will have the required declaration code for that routine.


Dialog Functions (sorted by ordinal)

The "System Settings Change" message box ("You must restart your computer before the new settings will take effect.")

Declare Function SHRestartSystemMB Lib "shell32" Alias "#59" _
(ByVal hOwner As Long, _
ByVal sExtraPrompt As String, _
ByVal uFlags As Long) As Long

hOwner = Message box owner; specify 0& for the desktop (will be top-level)
sPrompt = Specified prompt string placed above the default prompt. The default string can not be defeated, but additional explanation can be provided to the user.
uFlags = Based on the OS, can be the following values:

WinNT
Appears to use ExitWindowsEx uFlags values and behave accordingly:
Public Const EWX_LOGOFF = 0
Public Const EWX_SHUTDOWN = 1 'NT: needs SE_SHUTDOWN_NAME privilege (no default prompt)
Public Const EWX_REBOOT = 2 'NT: needs SE_SHUTDOWN_NAME privilege
Public Const EWX_FORCE = 4
Public Const EWX_POWEROFF = 8 'NT: needs SE_SHUTDOWN_NAME privilege

Win95
Any Yes selection produces the equivalent to ExitWindowsEx(EWX_FORCE, 0&) (?), i.e. no WM_QUERYENDSESSION or WM_ENDSESSION is sent! Other than noted below, it was found that any other value shuts the system down (no reboot) and includes the default prompt.

Shuts the system down (no reboot) and does not include the default prompt.
Public Const shrsExitNoDefPrompt = 1

Reboots the system and includes the default prompt.
Public Const shrsRebootSystem = 2     ' = EWX_REBOOT

Return values: Yes = 6 (vbYes), No = 7 (vbNo)


The "Shut Down" dialog (i.e. Start menu / Shut Down)

Declare Function SHShutDownDialog Lib "shell32" Alias "#60" _
(ByVal YourGuess As Long) As Long


The "Run" dialog (i.e. Start menu / Run)

Declare Function SHRunDialog Lib "shell32" Alias "#61" _
(ByVal hOwner As Long, _
ByVal Unknown1 As Long, _
ByVal Unknown2 As Long, _
ByVal szTitle As String, _
ByVal szPrompt As String, _
ByVal uFlags As Long) As Long

hOwner = Dialog owner; specify 0& for the desktop (will be top-level)
Unknown1 = ?
Unknown2 = ?, non-zero causes GPF! strings are ok...(?)
szTitle = Dialog title, specify vbNullString for default ("Run")
szPrompt = Dialog prompt, specify vbNullString for default ("Type the name of a program ...")

If uFlags is the following constant, the string from the last-run program will not appear in the dialogs combo box (that's all I found...)
Public Const shrdNoMRUString = &H2    '2nd bit is set

If there is some way to set and return the command line, I didn't find it... Always returns 0 (?)


The "Change Icon" dialog

Declare Function SHChangeIconDialog Lib "shell32" Alias "#62" _
(ByVal hOwner As Long, _
ByVal szFilename As String, _
ByVal Reserved As Long, _
lpIconIndex As Long) As Long

hOwner = Dialog owner; specify 0& for the desktop (will be top-level)
szFilename = The initially-displayed filename, filled on selection. Should be allocated to MAX_PATH (260) in order to receive the selected filename's path.
Reserved = ???
lpIconIndex = Pointer (index) to any initially-selected icon index in a file containing multiple icons. On icon selection, lpIconIndex returns the index of the selected icon.

Returns non-zero on select, zero if cancelled.


Path functions (sorted by ordinal):

Declare Function SHGetExtension Lib "shell32" Alias "#31" _
(ByVal szPath As String) As Long

Returns pointer to the last dot in szPath and the string following it (includes the dot with the extension). Returns 0 if szPath contains no dot. For the function to succeed, szPath should be null terminated and be allocated to MAX_PATH bytes (260). Does not check szPath for validity. (could be called "GetStrAtLastDot")


Declare Function SHAddBackslash Lib "shell32" Alias "#32" _
(ByVal szPath As String) As Long

Inserts a backslash before the first null char in szPath. szPath is unchanged if it already contains a backslash before the first null char or contains no null char at all. Returns pointer to ??? Does not check szPath for validity. (the name almost fits...)


Declare Function SHGetFileName Lib "shell32" Alias "#34" _
(ByVal szPath As String) As Long

Returns a pointer to the string in szPath after the last backslash. Returns 0 if szPath contains no backslash or no char follows the last backslash. For the function to succeed, szPath should be null terminated and be allocated to MAX_PATH bytes (260). Does not check szPath for validity. (could be called "GetStrAfterLastBackslash")


Declare Function SHGetPath Lib "shell32" Alias "#35" _
(ByVal szPath As String) As Long

Returns a pointer to the string in szPath before the last backslash. Returns 0 if szPath contains no backslash or no char follows the last backslash. For the function to succeed, szPath should be null terminated and be allocated to MAX_PATH bytes (260). Does not check szPath for validity. (could be called "GetStrBeforeLastBackslash")


Declare Function SHPathIsRelative Lib "shell32" Alias "#40" _
(ByVal szPath As String) As Long

Returns non-zero if szPath does not evaluate to a UNC path (if either the first char is not a backslash "\" or the 2nd char is not a colon ":"). Does not check szPath for validity. (the name almost fits...)


Declare Function SHPathIsExe Lib "shell32" Alias "#43" _
(ByVal szPath As String) As Long

Returns non-zero if szPath has an executable extension (if last 4 char are either ".exe", ".com", ".bat" or ".pif"). Does not check szPath for validity. (could have been called "HasExeExtension")


Declare Function SHFileExists Lib "shell32" Alias "#45" _
(ByVal szPath As String) As Long

Returns non-zero if szPath is valid absolute UNC path. Accepts file, folder or network paths. Returns True for a relative path only if it exists in the current directory. (the name actually fits...)


Declare Function SHGetPathArgs Lib "shell32" Alias "#52" _
(ByVal szPath As String) As Long

Returns a pointer to the string after first space in szPath. Returns null pointer if szPath contains no space or no char following the first space. For the function to succeed, szPath should be null terminated and be allocated to MAX_PATH bytes (260). Does not check szPath for validity. (could be called "GetStrAfterFirstSpace")


Declare Function SHAddPathQuotes Lib "shell32" Alias "#55" _
(ByVal szPath As String) As Long

Returns a pointer to a string embraced in quotes if the original passed string contained a space. Returns the original string otherwise. Does not check szPath for validity. (could be called "AddQuotesIfPathHasASpace")


Declare Function SHRemovePathQuotes Lib "shell32" Alias "#56" _
(ByVal szPath As String) As Long

Returns a pointer to a string without embracing quotes if the original passed string contained was originally quoted. Returns the original string otherwise. Does not check szPath for validity. (could be called "RemoveQuotesIfPathHasASpace")


Declare Function SHGetShortPathName Lib "shell32" Alias "#92" _
(ByVal szPath As String) As Long

Fills szPath with its DOS (8.3) file system string. If successful, returns non-zero (sometimes is a pointer to szPath, sometimes not!) Returns zero if path is invalid. szPath must be a valid, absolute path. Returns non-zero for a relative path only if it exists in the current directory. For the function to work correctly, szPath should be null terminated and be allocated to MAX_PATH bytes (260). (the name definitely fits.)


Undocumented Non-Ordinal Functions

Declare Function SHFormatDrive Lib "shell32" _
(ByVal hwndOwner As Long, _
ByVal iDrive As Long, _
ByVal iCapacity As Long, _
ByVal iFormatType As Long) As Long

hOwner = Dialog owner; specify 0& for the desktop (will be top-level)
iDrive = The drive number to format. Drive A=0, B=1 (if present, otherwise C=1), and so on.
iCapacity = Can be the following values:

Public Const SHFD_CAPACITY_DEFAULT = 0 ' default drive capacity
Public Const SHFD_CAPACITY_360 = 3 ' 360KB, applies to 5.25" drives only
Public Const SHFD_CAPACITY_720 = 5 ' 720KB, applies to 3.5" drives only

iFormatType = Based on the OS, can be the following values:

WinNT
Public Const SHFD_FORMAT_FULL = 0 ' full format
Public Const SHFD_FORMAT_QUICK = 1 ' quick format

Win95
Public Const SHFD_FORMAT_QUICK = 0 ' quick format
Public Const SHFD_FORMAT_FULL = 1 ' full format
Public Const SHFD_FORMAT_SYSONLY = 2 ' copies system files only

Return vals: Operation cancelled by user: -2   ( - vbCancel )
                   Operation successful = 6   ( vbYes )

The return values do not indicate any options chosen by the user (Quick, No Label, Copy System Files), nor the type of format performed (Quick, Full, System Only)


 
 

PayPal Link
Make payments with PayPal - it's fast, free and secure!

 
 
 
 

Copyright 1996-2011 VBnet and Randy Birch. All Rights Reserved.
Terms of Use  |  Your Privacy

 

Hit Counter