System functions in Windows API

last modified July 16, 2020

In this part of the Windows API tutorial, we cover system functions. System functions receive information about the system and communicate with the system in various ways.

Screen size

The GetSystemMetrics() function retrieves various system metrics and system configuration settings.

The code example prints the screen size to the console.

The program needs the user32.lib library to compile.

We determine the screen resolution with the GetSystemMetrics() .

The screen size is 1280×800.

Locking workstation

The LockWorkStation() locks the workstation’s display.

The program needs the user32.lib to compile.

Computer name

The GetComputerNameEx() function retrieves a NetBIOS or DNS name associated with the local computer. The names are established at system startup.

The example prints the computer name to the console.

The MAX_COMPUTERNAME_LENGTH constant determines the maximum length of the computer name.

We get the name of the computer with the GetComputerNameW() function. The name is stored into the computerName array.

We run the code example.

Username

The GetUserNameW() function returns the user name.

The example prints the username to the console.

The Lmcons.h file has the definition of the ULEN constant.

The ULEN constant defines the maximum length of the username.

The GetUserNameW() function retrieves the username and stores it into the username array.

This is a sample output of the username.exe program.

Current directory

Current directory is a directory in which the user is located or it is working it. In Windows API, the SetCurrentDirectoryW() changes the current directory and the GetCurrentDirectoryW() retrieves the current directory.

In the code example, we change and print the current working directory. The program receives one command line argument—the directory to change into.

We use the MAX_PATH constant, which defines the maximum length of a system path.

An error message is printed if we do not pass an argument to the program.

We use the SetCurrentDirectoryW() to change to the directory, which is passed as an argument.

We get the current working directory with the GetCurrentDirectoryW() function call.

If the returned value is bigger than BUFSIZE , the buffer was too small.

Windows version

The Version Helper functions can be used to determine the current OS version.

We use the Version Helper functions to determine the OS version.

The helper functions are declared in the VersionHelpers.h file.

At the time of the writing, Pelles C did not have the IsWindows10OrGreater() defined in its SDK.

The IsWindows8Point1OrGreater() returns true if the current version is Windows 8.1 or greater.

This is a sample output of the program.

Memory

The GlobalMemoryStatusEx() retrieves information about the system’s current usage of both physical and virtual memory.

The program prints statistics about memory usage to the console.

The GlobalMemoryStatusEx() function stores information about memory status in the MEMORYSTATUSEX structure.

The GlobalMemoryStatusEx() function is executed; the information is stored in the structure.

The dwMemoryLoad member specifies the approximate percentage of physical memory in use.

The ullTotalPhys member specifies the actual physical memory in bytes.

The ullTotalPhys member specifies the amount of physical memory currently available in bytes.

The ullTotalVirtual member specifies the amount of the total virtual memory in bytes.

The ullAvailVirtual member specifies the amount of available virtual memory in bytes.

This is a sample output of the program.

Known Folders

Since Windows Vista, a new system is used for identifying important directories in Windows. It is known as Known Folders. Known folders uses a set of GUID (Globally unique identifier) values for referencing important folders.

The SHGetKnownFolderPath() function retrieves the full path of a known folder identified by the folder’s id.

The example determines the full path to the user’s Documents directory. We need to add shell32.lib and ole32.lib to the project libraries.

Due to some internal API issues, we need to include the initguid.h file; otherwise, the example does not compile. It fails with the Unresolved external symbol ‘FOLDERID_Documents’ error.

The SHGetKnownFolderPath() is used to determine the path to the Documents directory.

The SUCCEEDED macro can be used to determine whether the function call succeeded.

At the end, it is necessary to free the allocated memory with the CoTaskMemFree() function.

This is a sample output of the DocumentsDir.exe program.

Drive names

The GetLogicalDriveStringsW() function fills a buffer with strings that specify valid drives in the system.

The example prints valid drives in the system.

A drive name is a path type, so a MAX_PATH constant is relevant for its maximum length. The LogicalDrives is an array of strings which serves as a buffer for the GetLogicalDriveStringsW() function.

The GetLogicalDriveStringsW() is called. The buffer is filled with null-terminated strings, which represent device names. The first parameter of the function is the maximum size of the specified buffer. The buffer is the second parameter.

We go through the array of device names and print them to the console.

There are two drives on the system: C:\ and D:\ .

Free space

The GetDiskFreeSpaceExW() retrieves information about the amount of space available on a disk volume. The function gives three pieces of information: the total amount of space, the free amount of space, and the free space available to the user that is associated with the calling thread.

The example examines disk space on the C:\ drive.

The amounts are expressed in bytes; these can be very large numbers. The unsigned __int64 type is used, which is a positive 64-bit integer capable of storing very large values.

The GetDiskFreeSpaceExW() is called.

The three amounts are printed to the console with the wprintf() function. The values are expressed in MB.

This is a sample output of the FreeDiskSpace.exe program.

CPU speed

The CPU speed can be determined by examining a registry value. The value is written to registry during installation. We need to query the HARDWARE\DESCRIPTION\System\CentralProcessor\0 key.

The example determines the CPU speed.

The RegOpenKeyExW() function is used to open the provided registry key.

The value is read with the RegQueryValueExW() function.

The RegCloseKey() closes the registry handle.

This is a sample output of the CpuSpeed.exe program.

In this part of the Windows API tutorial, we have worked with several system functions.

Пошаговое руководство. Вызов API Windows (Visual Basic) Walkthrough: Calling Windows APIs (Visual Basic)

Windows API — это библиотеки динамической компоновки (DLL), которые являются частью операционной системы Windows. Windows APIs are dynamic-link libraries (DLLs) that are part of the Windows operating system. Они используются для выполнения задач, когда трудно писать эквивалентные процедуры. You use them to perform tasks when it is difficult to write equivalent procedures of your own. Например, Windows предоставляет функцию с именем FlashWindowEx , которая позволяет сделать строку заголовка для приложения альтернативой светлой и темной тени. For example, Windows provides a function named FlashWindowEx that lets you make the title bar for an application alternate between light and dark shades.

Преимущество использования API-интерфейсов Windows в коде состоит в том, что они могут сэкономить время разработки, поскольку они содержат десятки полезных функций, которые уже написаны и ожидают использования. The advantage of using Windows APIs in your code is that they can save development time because they contain dozens of useful functions that are already written and waiting to be used. Недостаток заключается в том, что API Windows может быть трудно работать с и унфоргивинг в случае неправильной работы. The disadvantage is that Windows APIs can be difficult to work with and unforgiving when things go wrong.

Интерфейсы API Windows представляют особую категорию взаимодействия. Windows APIs represent a special category of interoperability. Интерфейсы API Windows не используют управляемый код, не имеют встроенных библиотек типов и используют типы данных, отличные от используемых в Visual Studio. Windows APIs do not use managed code, do not have built-in type libraries, and use data types that are different than those used with Visual Studio. Из-за этих различий и, поскольку интерфейсы API Windows не являются объектами COM, взаимодействия с API Windows и платформа .NET Framework выполняются с помощью вызова неуправляемого кода или PInvoke. Because of these differences, and because Windows APIs are not COM objects, interoperability with Windows APIs and the .NET Framework is performed using platform invoke, or PInvoke. Платформенный вызов — это служба, которая позволяет управляемому коду вызывать неуправляемые функции, реализованные в библиотеках DLL. Platform invoke is a service that enables managed code to call unmanaged functions implemented in DLLs. Дополнительные сведения см. в разделе Использование неуправляемых функций DLL. For more information, see Consuming Unmanaged DLL Functions. Вы можете использовать PInvoke в Visual Basic, используя либо Declare инструкцию, либо применяя DllImport атрибут к пустой процедуре. You can use PInvoke in Visual Basic by using either the Declare statement or applying the DllImport attribute to an empty procedure.

Вызовы Windows API были важной частью Visual Basic программирования в прошлом, но они редко требуются для Visual Basic .NET. Windows API calls were an important part of Visual Basic programming in the past, but are seldom necessary with Visual Basic .NET. Везде, где это возможно, следует использовать управляемый код из платформа .NET Framework для выполнения задач, а не вызовов Windows API. Whenever possible, you should use managed code from the .NET Framework to perform tasks, instead of Windows API calls. В этом пошаговом руководстве содержатся сведения о ситуациях, в которых требуется использовать API Windows. This walkthrough provides information for those situations in which using Windows APIs is necessary.

Отображаемые на компьютере имена или расположения некоторых элементов пользовательского интерфейса Visual Studio могут отличаться от указанных в следующих инструкциях. Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. Это зависит от имеющегося выпуска Visual Studio и используемых параметров. The Visual Studio edition that you have and the settings that you use determine these elements. Дополнительные сведения см. в разделе Персонализация среды IDE. For more information, see Personalizing the IDE.

Вызовы API с помощью Declare API Calls Using Declare

Наиболее распространенным способом вызова API Windows является использование Declare инструкции. The most common way to call Windows APIs is by using the Declare statement.

Объявление процедуры DLL To declare a DLL procedure

Определите имя функции, которую необходимо вызвать, а также ее аргументы, типы аргументов и возвращаемое значение, а также имя и расположение библиотеки DLL, содержащей ее. Determine the name of the function you want to call, plus its arguments, argument types, and return value, as well as the name and location of the DLL that contains it.

Полные сведения о API Windows см. в документации по пакету SDK для Win32 в Windows API Platform SDK. For complete information about the Windows APIs, see the Win32 SDK documentation in the Platform SDK Windows API. Дополнительные сведения о константах, используемых API Windows, см. в файлах заголовков, таких как Windows. h, входящих в состав пакета Platform SDK. For more information about the constants that Windows APIs use, examine the header files such as Windows.h included with the Platform SDK.

Откройте новый проект приложения Windows, щелкнув создать в меню файл , а затем выбрав пункт проект. Open a new Windows Application project by clicking New on the File menu, and then clicking Project. Откроется диалоговое окно Новый проект . The New Project dialog box appears.

Выберите приложение Windows в списке шаблонов проектов Visual Basic. Select Windows Application from the list of Visual Basic project templates. Отобразится новый проект. The new project is displayed.

Добавьте следующую Declare функцию либо в класс, либо в модуль, в котором требуется использовать библиотеку DLL: Add the following Declare function either to the class or module in which you want to use the DLL:

Части инструкции DECLARE Parts of the Declare Statement

Declare Инструкция включает следующие элементы. The Declare statement includes the following elements.

Модификатор Auto Auto modifier

Auto Модификатор указывает среде выполнения преобразовать строку на основе имени метода в соответствии с правилами среды CLR (или именем псевдонима, если оно указано). The Auto modifier instructs the runtime to convert the string based on the method name according to common language runtime rules (or alias name if specified).

Ключевые слова lib и Alias Lib and Alias keywords

Имя, следующее за Function ключевым словом, — это имя, которое программа использует для доступа к импортируемой функции. The name following the Function keyword is the name your program uses to access the imported function. Оно может совпадать с реальным именем вызываемой функции, или можно использовать любое допустимое имя процедуры, а затем применить Alias ключевое слово, чтобы указать реальное имя вызываемой функции. It can be the same as the real name of the function you are calling, or you can use any valid procedure name and then employ the Alias keyword to specify the real name of the function you are calling.

Укажите Lib ключевое слово, а затем имя и расположение библиотеки DLL, содержащей вызываемую функцию. Specify the Lib keyword, followed by the name and location of the DLL that contains the function you are calling. Указывать путь к файлам, расположенным в системных каталогах Windows, не требуется. You do not need to specify the path for files located in the Windows system directories.

Используйте Alias ключевое слово, если имя вызываемой функции не является допустимым Visual Basic именем процедуры или конфликтует с именами других элементов в приложении. Use the Alias keyword if the name of the function you are calling is not a valid Visual Basic procedure name, or conflicts with the name of other items in your application. Alias Указывает на истинное имя вызываемой функции. Alias indicates the true name of the function being called.

Объявления аргументов и типов данных Argument and Data Type Declarations

Объявите аргументы и их типы данных. Declare the arguments and their data types. Эта часть может быть сложной, поскольку типы данных, используемые Windows, не соответствуют типам данных Visual Studio. This part can be challenging because the data types that Windows uses do not correspond to Visual Studio data types. Visual Basic выполняет большой объем работы, преобразуя аргументы в совместимые типы данных, процесс, называемый упаковкой. Visual Basic does a lot of the work for you by converting arguments to compatible data types, a process called marshaling. Можно явно управлять упаковкой аргументов с помощью MarshalAsAttribute атрибута, определенного в System.Runtime.InteropServices пространстве имен. You can explicitly control how arguments are marshaled by using the MarshalAsAttribute attribute defined in the System.Runtime.InteropServices namespace.

Предыдущие версии Visual Basic позволяли объявлять параметры As Any , то есть могут использоваться данные любого типа данных. Previous versions of Visual Basic allowed you to declare parameters As Any , meaning that data of any data type could be used. Visual Basic требует, чтобы для всех инструкций использовался конкретный тип данных Declare . Visual Basic requires that you use a specific data type for all Declare statements.

Константы Windows API Windows API Constants

Некоторые аргументы являются сочетаниями констант. Some arguments are combinations of constants. Например, API, MessageBox показанный в этом пошаговом руководстве, принимает целочисленный аргумент Typ с именем, который управляет отображением окна сообщения. For example, the MessageBox API shown in this walkthrough accepts an integer argument called Typ that controls how the message box is displayed. Можно определить числовое значение этих констант, изучив #define инструкции в файле WinUser. h. You can determine the numeric value of these constants by examining the #define statements in the file WinUser.h. Числовые значения обычно отображаются в шестнадцатеричном виде, поэтому для их добавления и преобразования в десятичный формат может потребоваться калькулятор. The numeric values are generally shown in hexadecimal, so you may want to use a calculator to add them and convert to decimal. Например, если вы хотите объединить константы для стиля с восклицательным знаком MB_ICONEXCLAMATION 0x00000030, а стиль «да/нет MB_YESNO », можно добавить числа и получить результат 0x00000034 или 52 Decimal. For example, if you want to combine the constants for the exclamation style MB_ICONEXCLAMATION 0x00000030 and the Yes/No style MB_YESNO 0x00000004, you can add the numbers and get a result of 0x00000034, or 52 decimal. Хотя вы можете использовать десятичный результат непосредственно, лучше объявить эти значения как константы в приложении и объединить их с помощью Or оператора. Although you can use the decimal result directly, it is better to declare these values as constants in your application and combine them using the Or operator.

Объявление констант для вызовов API Windows To declare constants for Windows API calls

Обратитесь к документации по функции Windows, которую вы вызываете. Consult the documentation for the Windows function you are calling. Определите имена констант, которые он использует, и имя h файла, содержащего числовые значения для этих констант. Determine the name of the constants it uses and the name of the .h file that contains the numeric values for these constants.

Используйте текстовый редактор, например Блокнот, для просмотра содержимого файла заголовка (. h) и поиска значений, связанных с используемыми константами. Use a text editor, such as Notepad, to view the contents of the header (.h) file, and find the values associated with the constants you are using. Например, MessageBox API использует константу MB_ICONQUESTION для отображения вопросительного знака в окне сообщения. For example, the MessageBox API uses the constant MB_ICONQUESTION to show a question mark in the message box. Определение для MB_ICONQUESTION находится в файле WinUser. h и выглядит следующим образом: The definition for MB_ICONQUESTION is in WinUser.h and appears as follows:

#define MB_ICONQUESTION 0x00000020L

Добавьте эквивалентные Const операторы в класс или модуль, чтобы сделать эти константы доступными для приложения. Add equivalent Const statements to your class or module to make these constants available to your application. Пример: For example:

Вызов процедуры DLL To call the DLL procedure

Добавьте кнопку с именем Button1 в форму запуска проекта, а затем дважды щелкните ее, чтобы просмотреть код. Add a button named Button1 to the startup form for your project, and then double-click it to view its code. Появится обработчик событий для кнопки. The event handler for the button is displayed.

Добавьте код в Click обработчик событий для добавленной кнопки, чтобы вызвать процедуру и предоставить соответствующие аргументы: Add code to the Click event handler for the button you added, to call the procedure and provide the appropriate arguments:

Запустите проект, нажав клавишу F5. Run the project by pressing F5. Появится окно сообщения с кнопками Да и нет . The message box is displayed with both Yes and No response buttons. Щелкните один из них. Click either one.

Маршалирование данных Data Marshaling

Visual Basic автоматически преобразует типы данных параметров и возвращаемые значения для вызовов API Windows, но можно использовать MarshalAs атрибут, чтобы явно указать неуправляемые типы данных, которые ОЖИДАЕТ API. Visual Basic automatically converts the data types of parameters and return values for Windows API calls, but you can use the MarshalAs attribute to explicitly specify unmanaged data types that an API expects. Дополнительные сведения о маршалинге взаимодействия см. в разделе Маршалинг взаимодействия. For more information about interop marshaling, see Interop Marshaling.

Использование Declare и MarshalAs в вызове API To use Declare and MarshalAs in an API call

Определите имя функции, которую необходимо вызвать, а также ее аргументы, типы данных и возвращаемое значение. Determine the name of the function you want to call, plus its arguments, data types, and return value.

Чтобы упростить доступ к MarshalAs атрибуту, добавьте Imports оператор в начало кода для класса или модуля, как показано в следующем примере: To simplify access to the MarshalAs attribute, add an Imports statement to the top of the code for the class or module, as in the following example:

Добавьте прототип функции для импортированной функции в класс или модуль, который вы используете, и примените MarshalAs атрибут к параметрам или возвращаемому значению. Add a function prototype for the imported function to the class or module you are using, and apply the MarshalAs attribute to the parameters or return value. В следующем примере вызов API, который принимает тип, void* маршалируется как AsAny : In the following example, an API call that expects the type void* is marshaled as AsAny :

Вызовы API с помощью DllImport API Calls Using DllImport

DllImport Атрибут предоставляет второй способ вызова функций в библиотеках DLL без библиотек типов. The DllImport attribute provides a second way to call functions in DLLs without type libraries. DllImport примерно эквивалентно использованию оператора, Declare но обеспечивает более полный контроль над вызовом функций. DllImport is roughly equivalent to using a Declare statement but provides more control over how functions are called.

DllImport С большинством вызовов API Windows можно использовать, если вызов ссылается на общий (иногда называемый статическим) метод. You can use DllImport with most Windows API calls as long as the call refers to a shared (sometimes called static) method. Нельзя использовать методы, для которых требуется экземпляр класса. You cannot use methods that require an instance of a class. В отличие от Declare инструкций DllImport вызовы не могут использовать MarshalAs атрибут. Unlike Declare statements, DllImport calls cannot use the MarshalAs attribute.

Вызов API Windows с помощью атрибута DllImport To call a Windows API using the DllImport attribute

Откройте новый проект приложения Windows, щелкнув создать в меню файл , а затем выбрав пункт проект. Open a new Windows Application project by clicking New on the File menu, and then clicking Project. Откроется диалоговое окно Новый проект . The New Project dialog box appears.

Выберите приложение Windows в списке шаблонов проектов Visual Basic. Select Windows Application from the list of Visual Basic project templates. Отобразится новый проект. The new project is displayed.

Добавьте кнопку с именем Button2 в форму запуска. Add a button named Button2 to the startup form.

Дважды щелкните, Button2 чтобы открыть представление кода для формы. Double-click Button2 to open the code view for the form.

Чтобы упростить доступ к DllImport , добавьте Imports оператор в начало кода для класса формы Startup: To simplify access to DllImport , add an Imports statement to the top of the code for the startup form class:

Объявите пустую функцию перед End Class оператором для формы и назовите функцию MoveFile . Declare an empty function preceding the End Class statement for the form, and name the function MoveFile .

Примените Public Shared модификаторы и к объявлению функции и задайте параметры в MoveFile зависимости от аргументов, используемых функцией Windows API: Apply the Public and Shared modifiers to the function declaration and set parameters for MoveFile based on the arguments the Windows API function uses:

Функция может иметь любое допустимое имя процедуры; DllImport атрибут указывает имя в библиотеке DLL. Your function can have any valid procedure name; the DllImport attribute specifies the name in the DLL. Он также обрабатывает упаковку взаимодействия для параметров и возвращаемых значений, поэтому можно выбирать типы данных Visual Studio, аналогичные типам данных, используемым API. It also handles interoperability marshaling for the parameters and return values, so you can choose Visual Studio data types that are similar to the data types the API uses.

Примените DllImport атрибут к пустой функции. Apply the DllImport attribute to the empty function. Первый параметр — это имя и расположение библиотеки DLL, содержащей вызываемую функцию. The first parameter is the name and location of the DLL containing the function you are calling. Указывать путь к файлам, расположенным в системных каталогах Windows, не требуется. You do not need to specify the path for files located in the Windows system directories. Второй параметр — это именованный аргумент, указывающий имя функции в API Windows. The second parameter is a named argument that specifies the name of the function in the Windows API. В этом примере DllImport атрибут принудительно MoveFile перенаправляет вызовы в MoveFileW в KERNEL32.DLL. In this example, the DllImport attribute forces calls to MoveFile to be forwarded to MoveFileW in KERNEL32.DLL. MoveFileW Метод копирует файл из пути src в путь dst . The MoveFileW method copies a file from the path src to the path dst .

Добавьте код в Button2_Click обработчик событий для вызова функции: Add code to the Button2_Click event handler to call the function:

Создайте файл с именем Test.txt и поместите его в каталог К:\тмп на жестком диске. Create a file named Test.txt and place it in the C:\Tmp directory on your hard drive. При необходимости создайте каталог tmp. Create the Tmp directory if necessary.

Нажмите клавишу F5 для запуска приложения. Press F5 to start the application. Откроется Главная форма. The main form appears.

Нажмите кнопку Button2. Click Button2. Если файл можно переместить, отображается сообщение «файл перемещен успешно». The message «The file was moved successfully» is displayed if the file can be moved.