(This article was originally published at the TweakUAC site.)

Version 2.1 (Updated 2008-Feb-24)

While porting our applications to Windows Vista, we had to overcome quite a few challenges related to the new security features of Vista (such as the User Account Control). We decided to make public several functions we’ve developed, to make it easier for other developers to solve such problems, too.

The functions we’ve developed are written in C++ (using Microsoft Visual Studio 2005), and packaged in the file VistaTools.cxx. Please note:

THIS CODE AND INFORMATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.

TERMS OF USE: You are free to use this file in any way you like, for both the commercial and non-commercial purposes, royalty-free, AS LONG AS you agree with the warranty disclaimer above, EXCEPT that you may not remove or modify the warranty statement and the copyright notice the file contains.

The file VistaTools.cxx contains the following functions:

BOOL IsVista();

Use IsVista() to determine whether the current process is running under Windows Vista (or a later version of Windows, whatever it will be).

Return Values:

If the function succeeds, and the current version of Windows is Vista or later, the return value is TRUE.

If the function fails, or if the current version of Windows is older than Vista (that is, if it is Windows XP, Windows 2000, Windows Server 2003, Windows 98, etc.) the return value is FALSE.

BOOL IsWow64();

Use IsWow64() to determine whether the current 32-bit process is running under 64-bit Windows (Vista or XP).

Return Values:

If the function succeeds, and the current version of Windows is x64, the return value is TRUE.

If the function fails, or if the current version of Windows is 32-bit, the return value is FALSE.

NOTE: While this function is not Vista specific (it works under XP as well), we include it here to be able to prevent execution of the 32-bit code under 64-bit Windows, when required.

HRESULT
GetElevationType( __out TOKEN_ELEVATION_TYPE * ptet );

Use GetElevationType() to determine the elevation type of the current process.

Parameters:

ptet – [out] Pointer to a variable that receives the elevation type of the current process.

The possible values are:

TokenElevationTypeDefault – User is not using a “split” token. This value indicates that either UAC is disabled, or the process is started by a standard user (not a member of the Administrators group).

The following two values can be returned only if both the UAC is enabled and the user is a member of the Administrator’s group (that is, the user has a “split” token):

TokenElevationTypeFull – the process is running elevated.

TokenElevationTypeLimited – the process is not running elevated.

Return Values:

If the function succeeds, the return value is S_OK. If the function fails, the return value is E_FAIL. To get extended error information, call GetLastError().

HRESULT
IsElevated( __out_opt BOOL * pbElevated = NULL );

Use IsElevated() to determine whether the current process is elevated or not.

Parameters:

pbElevated – [out] [optional] Pointer to a BOOL variable that, if non-NULL, receives the result.

The possible values are:

TRUE – the current process is elevated. This value indicates that either UAC is enabled, and the process was elevated by the administrator, or that UAC is disabled and the process was started by a user who is a member of the Administrators group.

FALSE – the current process is not elevated (limited). This value indicates that either UAC is enabled, and the process was started normally, without the elevation, or that UAC is disabled and the process was started by a standard user.

Return Values

If the function succeeds, and the current process is elevated, the return value is S_OK. If the function succeeds, and the current process is not elevated, the return value is S_FALSE. If the function fails, the return value is E_FAIL. To get extended error information, call GetLastError().

BOOL
RunElevated(
__in HWND hwnd,
__in LPCTSTR pszPath,
__in_opt LPCTSTR pszParameters = NULL,
__in_opt LPCTSTR pszDirectory = NULL );

Use RunElevated() to start an elevated process. This function calls ShellExecEx() with the verb “runas” to start the elevated process.

Parameters:

hwnd – [in] Window handle to any message boxes that the system might produce while executing this function.

pszPath -[in] Address of a null-terminated string that specifies the name of the executable file that should be used to start the process.

pszParameters – [in] [optional] Address of a null-terminated string that contains the command-line parameters for the process. If NULL, no parameters are passed to the process.

pszDirectory – [in] [optional] Address of a null-terminated string that specifies the name of the working directory. If NULL, the current directory is used as the working directory.

Return Values

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call GetLastError().

NOTE: This function will start a process elevated no matter which attribute (asInvoker, highestAvailable, or requireAdministrator) is specified in its manifest, and even if there is no such attribute at all.

BOOL
RunNonElevated(
__in HWND hwnd,
__in LPCTSTR pszPath,
__in_opt LPCTSTR pszParameters = NULL,
__in_opt LPCTSTR pszDirectory = NULL );

Use RunNonElevated() to start a non-elevated process. If the current process is not elevated, it calls ShellExecuteEx() to start the new process. If the current process is elevated, it injects itself into the (non-elevated) shell process, and starts a non-elevated process from there.

Parameters:

hwnd – [in] Window handle to any message boxes that the system might produce while executing this function.

pszPath – [in] Address of a null-terminated string that specifies the executable file that should be used to start the process.

pszParameters – [in] [optional] Address of a null-terminated string that contains the command-line parameters for the process. If NULL, no parameters are passed to the process.

pszDirectory – [in] [optional] Address of a null-terminated string that specifies the name of the working directory. If NULL, the current directory is used as the working directory.

Return Values

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call GetLastError().

NOTE: For this function to work, the application must be marked with the asInvoker or highestAvailable attributes in its manifest. If the executable to be started is marked as requireAdministrator, it will be started elevated!

How to use the file VistaTools.cxx

Make sure you have the latest Windows SDK (see msdn.microsoft.com for more information) or this file may not compile!

This file contains the Win32 stuff only, it can be used with or without other frameworks, such as MFC, ATL, etc.

This is a “combo” file that contains both the declarations (usually placed in the .h files) as well as the definitions (usually placed in the .cpp files) of the functions. To get the declarations only, include it as you would any .h file. To get both the declarations and definitions, define IMPLEMENT_VISTA_TOOLS before including the file. (The latter should be done once and only once per project).

For example, to use this file in a MFC project, create a file MyVistaTools.cpp that contains the following:

#include “StdAfx.h”

#define IMPLEMENT_VISTA_TOOLS
#include “VistaTools.cxx”

This would make MyVistaTools.cpp the implementation file of the VistaTools function for your project. Don’t forget to add MyVistaTools.cpp to your project! You can add VistaTools.cxx to your project, as well, but it should be excluded from the build, because its contents is compiled when it is included in MyVistaTools.cpp file with IMPLEMENT_VISTA_TOOLS defined, as shown above.

In other files of your project, where you need to use the functions declared in VistaTools.cxx, include it without defining IMPLEMENT_VISTA_TOOLS, just as you would include a .h file:

#include “VistaTools.cxx”

To use the function RunNonElevated(), this file must be compiled into a DLL. In such a case, define DLL_EXPORTS when compiling the DLL, and do not define DLL_EXPORTS when compiling the projects linking to the DLL.

If you don’t need to use RunNonElevated(), then this file may be a part of an EXE project. In such a case, define DONTWANT_RunNonElevated and NO_DLL_IMPORTS to make this file compile properly.

For an example of using VistaTools.cxx in a real project, see VistaElevator 2.0.

How do I download the file VistaTools.cxx?

Simply right-click on the link below and choose the Save target as command (or similar) to save it to your hard drive:

Download VistaTools.cxx

If you use this file in your own project, an acknowledgment will be appreciated, although it’s not required.

Enjoy!

Did you know? Our USB Encryption Software can protect any USB flash drive or any other external drive with a password and strong encryption. Try it free for 30 days! Read more…