Overview of System Functions
The Win32 API provides a comprehensive set of functions for managing and querying system-level information and resources. These functions allow applications to interact with the operating system kernel, retrieve hardware and software details, and control system behavior.
Process and Thread Management
While detailed process and thread functions are covered in their own category, system functions offer broader insights and control:
Description
Retrieves the process identifier for the specified process handle.
Parameters
Return Value
The process identifier (PID) or 0 if the function fails.
Example
DWORD pid = GetCurrentProcessId();
// Or to get PID from a handle
HANDLE hProcess = OpenProcess(PROCESS_QUERY_INFORMATION, FALSE, some_pid);
if (hProcess != NULL) {
DWORD queried_pid = GetProcessId(hProcess);
CloseHandle(hProcess);
}
System Information Retrieval
These functions are crucial for understanding the environment in which your application is running.
Description
Retrieves the NetBIOS name of the local computer.
Parameters
Return Value
Nonzero if the function succeeds, zero otherwise.
Description
Fills the specified structure with information about the current system (such as processor architecture and level).
Parameters
Return Value
None. The information is returned in the SYSTEM_INFO structure.
Example Structure
typedef struct _SYSTEM_INFO {
union {
DWORD dwOemId;
struct {
WORD wProcessorArchitecture;
WORD wReserved;
} DUMMYUNIONNAME;
} DUMMYUNIONNAME2;
DWORD dwPageSize;
LPVOID lpMinimumApplicationAddress;
LPVOID lpMaximumApplicationAddress;
DWORD_PTR dwActiveProcessorMask;
DWORD dwNumberOfProcessors;
DWORD dwProcessorType;
DWORD dwAllocationGranularity;
WORD wProcessorLevel;
WORD wProcessorRevision;
} SYSTEM_INFO, *LPSYSTEM_INFO;
Description
Retrieves the number of milliseconds that have elapsed since the system was started.
Return Value
The number of milliseconds.
Note
This value wraps around every 49.7 days.
Time and Date Functions
Manipulating and retrieving system time.
Description
Retrieves the current date and time in local time.
Parameters
Return Value
None. The information is returned in the SYSTEMTIME structure.
Description
Sets the current date and time in local time.
Parameters
Return Value
Nonzero if the function succeeds, zero otherwise.
Requires
Administrator privileges.
Environment Variables
Accessing and modifying environment variables.
Description
Retrieves the value of the specified environment variable for the current process.
Parameters
Return Value
The number of characters copied to the buffer, not including the null terminator. If the buffer is not large enough, the function returns the required buffer size in characters, including the null terminator. If the function fails, it returns 0.
Example
TCHAR pathBuffer[MAX_PATH];
DWORD pathLen = GetEnvironmentVariable(_T("PATH"), pathBuffer, MAX_PATH);
if (pathLen > 0 && pathLen < MAX_PATH) {
// Use pathBuffer
} else if (pathLen == 0) {
// Error occurred
} else {
// Buffer too small, pathLen contains required size
}
Description
Creates, modifies, or deletes a user-defined environment variable within the current process.
Parameters
Return Value
Nonzero if the function succeeds, zero otherwise.
Note
Changes made with this function affect only the current process and its child processes.
System Shutdown and Restart
Functions for initiating system power actions.
Description
Shuts down or restarts the computer. It can also log off the user or disable the system. This function can only be called by a process running under an account that has the SE_SHUTDOWN_NAME privilege.
Parameters
EWX_SHUTDOWN, EWX_REBOOT, EWX_LOGOFF)SHTDN_REASON_MAJOR_OPERATINGSYSTEM)Return Value
Nonzero if the function succeeds, zero otherwise.
Requires
Administrator privileges and appropriate privileges (e.g., SE_SHUTDOWN_NAME).