Kernel-User Base APIs
Processes
CreateProcessW
Creates a new process and its primary thread. The new process runs in the same address space as the calling process unless otherwise specified.
Parameters
- lpApplicationName(PCWSTR): The name of the module to be executed.
- lpCommandLine(PWSTR): The command line string.
- lpProcessAttributes(LPSECURITY_ATTRIBUTES): Security attributes for the process.
- lpThreadAttributes(LPSECURITY_ATTRIBUTES): Security attributes for the thread.
- bInheritHandles(BOOL): Inherit handles flag.
- dwCreationFlags(DWORD): Creation flags.
- lpEnvironment(LPVOID): Environment block.
- lpCurrentDirectory(PCWSTR): Current directory.
- lpStartupInfo(LPSTARTUPINFOW): Startup information.
- lpProcessInformation(LPPROCESS_INFORMATION): Process information output.
Return Value
Returns a non-zero value if the function succeeds, or zero if the function fails. If the function succeeds, the values returned in the PROCESS_INFORMATION structure are used to identify the new process and its primary thread.
Remarks
This function is the primary entry point for creating new processes in Windows. It offers extensive control over process creation, including security attributes, inheritance, and execution environment.
GetCurrentProcessId
Retrieves the identifier of the current process.
Return Value
The return value is the process identifier of the calling process.
Threads
CreateThread
Creates a thread to execute within the virtual address space of the calling process.
Parameters
- lpThreadAttributes(LPSECURITY_ATTRIBUTES): Security attributes for the thread.
- dwStackSize(DWORD): The initial size, in bytes, of the stack for the thread.
- lpStartAddress(LPTHREAD_START_ROUTINE): Pointer to the application-defined function.
- lpParameter(LPVOID): Pointer to a variable to be passed to the thread function.
- dwCreationFlags(DWORD): Flags that control the creation of the thread.
- lpThreadId(LPDWORD): Pointer to a variable that receives the thread identifier.
Return Value
If the function succeeds, the return value is the handle to the newly created thread. If the function fails, the return value is NULL.
GetCurrentThreadId
Retrieves the thread identifier of the calling thread.
Return Value
The return value is the thread identifier of the calling thread.
Memory Management
VirtualAlloc
Reserves, commits, or changes the state of a region of pages in the virtual address space of the calling process.
Parameters
- lpAddress(LPVOID): The starting address of the region of memory to be allocated.
- dwSize(SIZE_T): The size, in bytes, of the region of memory to allocate.
- flAllocationType(DWORD): The type of memory allocation.
- flProtect(DWORD): The memory protection for the region of pages to be allocated.
Return Value
If the function succeeds, the return value is the base address of the allocated region of pages. If the function fails, the return value is NULL.
HeapAlloc
Allocates a block of memory from a heap. The allocated memory is uninitialized.
Parameters
- hHeap(HANDLE): A handle to the heap that was created by a call to the HeapCreate function.
- dwFlags(DWORD): The allocation type.
- dwBytes(SIZE_T): The number of bytes to be allocated.
Return Value
If the function succeeds, and dwFlags does not specify HEAP_NO_SERIALIZE, the return value is a pointer to the memory block that was allocated. If the function succeeds, and dwFlags specifies HEAP_NO_SERIALIZE, the return value is a pointer to the allocated memory block. If the function fails, the return value is NULL.
Inter-Process Communication (IPC)
CreatePipe
Creates an anonymous pipe, which consists of two handles: one for the read end of the pipe and one for the write end of the pipe.
Parameters
- hReadPipe(PHANDLE): Pointer to the handle to the read end of the pipe.
- hWritePipe(PHANDLE): Pointer to the handle to the write end of the pipe.
- lpPipeAttributes(LPSECURITY_ATTRIBUTES): Pointer to a
SECURITY_ATTRIBUTESstructure. - nSize(DWORD): The size, in bytes, of the buffer for the pipe.
Return Value
If the function succeeds, the return value is a non-zero value. If the function fails, the return value is zero.
CreateEventW
Creates or opens a named or unnamed event object.
Parameters
- lpEventAttributes(LPSECURITY_ATTRIBUTES): Security attributes.
- bManualReset(BOOL): If this parameter is TRUE, the function creates an event object with a manual-reset behavior.
- bInitialState(BOOL): If this parameter is TRUE, the initial state of the event object is signaled; otherwise, it is nonsignaled.
- lpName(PCWSTR): The name of the event object.
Return Value
If the function succeeds, the return value is a handle to the newly created or opened event object. If the function fails, the return value is NULL.
Synchronization Objects
CreateMutexW
Creates or opens a mutex object.
Parameters
- lpMutexAttributes(LPSECURITY_ATTRIBUTES): Security attributes.
- bInitialOwner(BOOL): If TRUE, the calling thread is granted initial ownership of the mutex.
- lpName(PCWSTR): The name of the mutex object.
Return Value
If the function succeeds, the return value is a handle to the newly created or opened mutex object. If the function fails, the return value is NULL.
WaitForSingleObject
Waits until the specified object is in the signaled state or the time-out interval elapses.
Parameters
- hHandle(HANDLE): A handle to the synchronization object.
- dwMilliseconds(DWORD): The time-out interval in milliseconds.
Return Value
If the function succeeds, the return value indicates the event that caused the function to return. If the function fails, the return value is WAIT_FAILED.
Error Handling
GetLastError
Retrieves the last error code set by a thread.
Return Value
The return value is the last error code set by the thread. ERROR_SUCCESS (0) is returned if no error is set.
FormatMessageW
Formats a message string.
Parameters
- dwFlags(DWORD): Flags that control the message formatting.
- lpSource(LPCVOID): Specifies the source of the message string.
- dwMessageId(DWORD): The message identifier.
- dwLanguageId(DWORD): The language identifier.
- lpBuffer(LPWSTR): Pointer to a buffer that receives the formatted message string.
- nSize(DWORD): The maximum size of the buffer pointed to by lpBuffer, in characters.
- Arguments(va_list*): Pointer to an array of message arguments.
Return Value
If the function succeeds, the return value is the number of characters in the formatted message, not including the terminating null character. If the function fails, the return value is 0.