Win32Threading

BOOL CallRemoteFunction(
    REMOTE_CALL_RETURN * prcrRet,
    LPVOID lpvFuncAddress,
    DWORD dwExtra,
    INT iParms,
    ...)


Calls a function in the target process. Returns TRUE if the call succeeds, FALSE otherwise. The function must exist inside the currently opened process. dwExtra can be a combination of RCE_NOTHING, RCE_STDCALL, RCE_FLOAT, and RCE_DOUBLE. RCE_FLOAT and RCE_DOUBLE can not be used together. The return value is stored in prcrRet, which must not be NULL.
    iParms is the number of parameters to pass to the function. Note that any 64-bit parameters must be counted twice. For example, if there is only one parameter, and it is a UINT64 type, iParms will be 2 rather than 1.


HANDLE CreateRemoteThread(
    HANDLE hProcess,
    LPVOID lpStartAddress,
    LPVOID lpParameter,
    LPDWORD lpThreadId)


Creates a thread that runs in the virtual address space of another process. If the target process is being debugged and the returned HANDLE is to be used in WaitForSingleObject, this function must be called on a separate script thread. In all other cases, this can be called on any thread. lpThreadId can be NULL. If the function fails, the return value is NULL.


DWORD CreateRemoteThreadAndGetReturn(
    BOOL * pbSuccess,
    HANDLE hProcess,
    LPVOID lpStartAddress,
    LPVOID lpParameter)


Creates a thread that runs in the virtual address space of another process and returns the return value of that thread (which will be the return value of the function called in the remote process). This is safe to call on any thread, regardless of whether or not the target process is being debugged. lpThreadId can be NULL. If the function fails, the BOOL to which pbSuccess points is set to FALSE. This function can only call __stdcall functions that accept one parameter, and the return is stored as a DWORD. If the target function has any other return type, the DWORD returned by this function can be explicitly cast to that type, unless the type is 64 bits in size.


HANDLE CreateThread(
    const _TCHAR * ptcFunc,
    DWORD dwParm)


Calls the script function specified by ptcFunc on a new thread and returns a HANDLE to that thread. The target function must be in the format DWORD [function]( DWORD dwParm ). dwParm is passed to the script function specified by ptcFunc.
When using multithreaded scripts, care should be taken to avoid standard thread-related deadlocks caused by multiple threads waiting on each other for exclusive access to resources, specifically ďsynchronizedĒ functions.


HANDLE GetCurrentThread()


Retrieves a pseudo handle for the current thread.


DWORD GetCurrentThreadId()


Retrieves the thread identifier of the calling thread.


LPVOID GetEproc(
    DWORD dwId)


returns a pointer to the specified processí EPROCESS structure or NULL if the process ID is invalid.


BOOL GetExitCodeThread(
    HANDLE hThread,
    LPDWORD lpExitCode)


Retrieves the termination status of the specified thread. The termination status is the value returned by the function called on the specified thread.


BOOL GetThreadContext(
    HANDLE hThread,
    LPCONTEXT lpContext)


Retrieves the context of the specified thread. The thread must be suspended. The function allows a selective context to be retrieved based on the value of the ContextFlags member of the CONTEXT structure. The thread handle identified by the hThread parameter is typically being debugged, but the function can also operate when it is not being debugged.


INT GetThreadPriority(
    HANDLE hThread)


Retrieves the priority value for the specified thread. This value, together with the priority class of the threadís process, determines the threadís base-priority level.


HANDLE OpenProcess(
    DWORD dwDesiredAccess,
    DWORD dwProcessId)


Opens an existing process object. If the function succeeds, the return value is an open handle to the specified process. If the function fails, the return value is NULL. The returned HANDLE must be closed with CloseHandle when no longer needed.
dwDesiredAccess can be any combination of the following:
    PROCESS_ALL_ACCESS: All possible access rights for a process object.
    PROCESS_CREATE_PROCESS: Required to create a process.
    PROCESS_CREATE_THREAD: Required to create a thread.
    PROCESS_DUP_HANDLE: Required to duplicate a handle.
    PROCESS_QUERY_INFORMATION: Required to retrieve certain information about a process, such as its token, exit code, and priority class.
    PROCESS_SET_QUOTA: Required to set memory limits.
    PROCESS_SET_INFORMATION: Required to set certain information about a process, such as its priority class.
    PROCESS_TERMINATE: Required to terminate a process.
    PROCESS_VM_OPERATION: Required to perform an operation on the address space of a process (see VirtualProtectEx and WriteProcessMemory).
    PROCESS_VM_READ: Required to read memory in a process using ReadProcessMemory.
    PROCESS_VM_WRITE: Required to write to memory in a process using WriteProcessMemory.
    SYNCHRONIZE: Required to wait for the process to terminate using the wait functions (specifically WaitForSingleObject).


HANDLE OpenThread(
    DWORD dwDesiredAccess,
    BOOL bInheritHandle,
    DWORD dwThreadId)


Opens an existing thread object. If the function succeeds, the return value is an open handle to the specified thread. If the function fails, the return value is NULL.
dwDesiredAccess can be one or more of the following values:
    SYNCHRONIZE: Enables the use of the thread handle in any of the wait functions such as WaitForSingleObject.
    THREAD_ALL_ACCESS: All possible access rights for a thread object.
    THREAD_DIRECT_IMPERSONATION: Required for a server thread that impersonates a client.
    THREAD_GET_CONTEXT: Required to read the context of a thread using GetThreadContext.
    THREAD_IMPERSONATE: Required to use a threadís security information directly without calling it by using a communication mechanism that provides impersonation services.
    THREAD_QUERY_INFORMATION: Required to read certain information from the thread object, such as the exit code (see GetExitCodeThread).
    THREAD_SET_CONTEXT: Required to write the context of a thread using SetThreadContext.
    THREAD_SET_INFORMATION: Required to set certain information in the thread object.
    THREAD_SET_THREAD_TOKEN: Required to set the impersonation token for a thread.
    THREAD_SUSPEND_RESUME: Required to suspend or resume a thread (see SuspendThread and ResumeThread).
    THREAD_TERMINATE: Required to terminate a thread.


DWORD ResumeThread(
    HANDLE hThread)


Decrements a threadís suspend count. When the suspend count is decremented to zero, the execution of the thread is resumed.


BOOL SetThreadContext(
    HANDLE hThread,
    const LPCONTEXT lpContext)


Sets the context for the specified thread. The thread must be suspended. The function allows the selective context to be set based on the value of the ContextFlags member of the context structure. The thread handle identified by the hThread parameter is typically being debugged, but the function can also operate even when it is not being debugged.


BOOL SetThreadPriority(
    HANDLE hThread,
    int nPriority)


sets the priority value for the specified thread.
nPriority can be one of the following values:
    THREAD_PRIORITY_TIME_CRITICAL: Indicates 3 points above normal priority.
    THREAD_PRIORITY_HIGHEST: Indicates 2 points above normal priority.
    THREAD_PRIORITY_ABOVE_NORMAL: Indicates 1 point above normal priority.
    THREAD_PRIORITY_NORMAL: Indicates normal priority.
    THREAD_PRIORITY_BELOW_NORMAL: Indicates 1 point below normal priority.
    THREAD_PRIORITY_LOWEST: Indicates 2 points below normal priority.
    THREAD_PRIORITY_ABOVE_IDLE: Indicates 3 points below normal priority.
    THREAD_PRIORITY_IDLE: Indicates 4 points below normal priority.


DWORD SuspendThread(
    HANDLE hThread)


Suspends the specified thread. If the function succeeds, execution of the specified thread is suspended and the threadís suspend count is incremented. Suspending a thread causes the thread to stop executing user-mode (application) code. Returns -1 on failure, or the threadís suspend count otherwise. Each call of SuspendThread must be matched with a call to ResumeThread.


BOOL TerminateThread(
    HANDLE hThread,
    DWORD dwExitCode)


TerminateThread is used to cause a thread to exit. When this occurs, the target thread has no chance to execute any user-mode code and its initial stack is not deallocated. DLLs attached to the thread are not notified that the thread is terminating.

TerminateThread is a dangerous function that should only be used in the most extreme cases. You should call TerminateThread only if you know exactly what the target thread is doing, and you control all of the code that the target thread could possibly be running at the time of the termination.


DWORD WaitForSingleObject(
    HANDLE hHandle,
    DWORD dwMilliseconds)


Returns when the specified object is in the signaled state or the time-out interval elapses. Primarily used to wait for threads (created by CreateThread) to end.
The WaitForSingleObject function can wait for the following objects:
    Threads (see CreateThread and OpenThread)
    Processes (see OpenProcess)

If the function succeeds, the return value indicates the event that caused the function to return. It can be one of the following values:
    WAIT_ABANDONED (0x00000080): The specified object is a mutex object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to nonsignaled.
    WAIT_OBJECT_0 (0x00000000): The state of the specified object is signaled.
    WAIT_TIMEOUT (0x00000102): The time-out interval elapsed, and the objectís state is nonsignaled.


Copyright © 2006 Shawn (L. Spiro) Wilcoxen