Class PInvoke
public static class PInvoke- Inheritance
-
PInvoke
- Inherited Members
Fields
JOB_OBJECT_ASSIGN_PROCESS
public const uint JOB_OBJECT_ASSIGN_PROCESS = 1Field Value
JOB_OBJECT_MSG_ABNORMAL_EXIT_PROCESS
public const uint JOB_OBJECT_MSG_ABNORMAL_EXIT_PROCESS = 8Field Value
JOB_OBJECT_MSG_ACTIVE_PROCESS_LIMIT
public const uint JOB_OBJECT_MSG_ACTIVE_PROCESS_LIMIT = 3Field Value
JOB_OBJECT_MSG_ACTIVE_PROCESS_ZERO
public const uint JOB_OBJECT_MSG_ACTIVE_PROCESS_ZERO = 4Field Value
JOB_OBJECT_MSG_END_OF_JOB_TIME
public const uint JOB_OBJECT_MSG_END_OF_JOB_TIME = 1Field Value
JOB_OBJECT_MSG_END_OF_PROCESS_TIME
public const uint JOB_OBJECT_MSG_END_OF_PROCESS_TIME = 2Field Value
JOB_OBJECT_MSG_EXIT_PROCESS
public const uint JOB_OBJECT_MSG_EXIT_PROCESS = 7Field Value
JOB_OBJECT_MSG_JOB_MEMORY_LIMIT
public const uint JOB_OBJECT_MSG_JOB_MEMORY_LIMIT = 10Field Value
JOB_OBJECT_MSG_NEW_PROCESS
public const uint JOB_OBJECT_MSG_NEW_PROCESS = 6Field Value
JOB_OBJECT_MSG_PROCESS_MEMORY_LIMIT
public const uint JOB_OBJECT_MSG_PROCESS_MEMORY_LIMIT = 9Field Value
JOB_OBJECT_NET_RATE_CONTROL_MAX_DSCP_TAG
public const uint JOB_OBJECT_NET_RATE_CONTROL_MAX_DSCP_TAG = 64Field Value
JOB_OBJECT_QUERY
public const uint JOB_OBJECT_QUERY = 4Field Value
JOB_OBJECT_SET_ATTRIBUTES
public const uint JOB_OBJECT_SET_ATTRIBUTES = 2Field Value
JOB_OBJECT_SET_SECURITY_ATTRIBUTES
public const uint JOB_OBJECT_SET_SECURITY_ATTRIBUTES = 16Field Value
JOB_OBJECT_TERMINATE
public const uint JOB_OBJECT_TERMINATE = 8Field Value
Methods
AssignProcessToJobObject(SafeHandle, SafeHandle)
Assigns a process to an existing job object.
public static BOOL AssignProcessToJobObject(SafeHandle hJob, SafeHandle hProcess)Parameters
hJobSafeHandleA handle to the job object to which the process will be associated. The CreateJobObject or OpenJobObject function returns this handle. The handle must have the JOB_OBJECT_ASSIGN_PROCESS access right. For more information, see Job Object Security and Access Rights.
hProcessSafeHandleA handle to the process to associate with the job object. The handle must have the PROCESS_SET_QUOTA and PROCESS_TERMINATE access rights. For more information, see Process Security and Access Rights. If the process is already associated with a job, the job specified by hJob must be empty or it must be in the hierarchy of nested jobs to which the process already belongs, and it cannot have UI limits set (SetInformationJobObject with JobObjectBasicUIRestrictions). For more information, see Remarks. Windows 7, Windows Server 2008 R2, Windows XP with SP3, Windows Server 2008, Windows Vista and Windows Server 2003: The process must not already be assigned to a job; if it is, the function fails with ERROR_ACCESS_DENIED. This behavior changed starting in Windows 8 and Windows Server 2012. Terminal Services: All processes within a job must run within the same session as the job.
Returns
- BOOL
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
After you associate a process with a job object using AssignProcessToJobObject, the process is subject to the limits set for the job. To set limits for a job, use the SetInformationJobObject function. If the job has a user-mode time limit, and the time limit has been exhausted, AssignProcessToJobObject fails and the specified process is terminated. If the time limit would be exceeded by associating the process, AssignProcessToJobObject still succeeds. However, the time limit violation will be reported. If the job has an active process limit, and the limit would be exceeded by associating this process, AssignProcessToJobObject fails, and the specified process is terminated. Memory operations performed by a process associated with a job that has a memory limit are subject to the memory limit. Memory operations performed by the process before it was associated with the job are not examined by AssignProcessToJobObject. If the process is already running and the job has security limitations, AssignProcessToJobObject may fail. For example, if the primary token of the process contains the local administrators group, but the job object has the security limitation JOB_OBJECT_SECURITY_NO_ADMIN, the function fails. If the job has the security limitation JOB_OBJECT_SECURITY_ONLY_TOKEN, the process must be created suspended. To create a suspended process, call the CreateProcess function with the CREATE_SUSPENDED flag. A process can be associated with more than one job in a hierarchy of nested jobs. For priority class, affinity, commit charge, per-process execution time limit, scheduling class limit, and working set minimum and maximum, the process inherits an effective limit which is the most restrictive limit of all the jobs in its parent job chain. For other resource limits, the process inherits limits from its immediate job in the hierarchy. Accounting information is added to the immediate job and aggregated in each parent job in the job chain. By default, all child processes are associated with the immediate job and every job in the parent job chain. To create a child process that is not part of the same job chain, call the CreateProcess function with the CREATE_BREAKAWAY_FROM_JOB flag. The child process breaks away from every job in the job chain unless a job in the chain does not allow breakaway. In this case, the child process does not break away from that job or any job above it in the job chain. For more information, see Nested Jobs. Windows 7, Windows Server 2008 R2, Windows XP with SP3, Windows Server 2008, Windows Vista and Windows Server 2003: A process can be associated only with a single job. A process inherits limits from the job it is associated with and adds its accounting information to the job. If a process is associated with a job, all child processes it creates are associated with that job by default. To create a child process that is not part of the same job, call the CreateProcess function with the CREATE_BREAKAWAY_FROM_JOB flag. A process can be associated with more than one job starting in Windows 8 and Windows Server 2012. Windows 7, Windows Server 2008 R2, Windows Server 2008 and Windows Vista: If the process is being monitored by the Program Compatibility Assistant (PCA), it is placed into a compatibility job. Therefore, the process must be created using CREATE_BREAKAWAY_FROM_JOB before it can be placed in another job. Alternatively, you can embed an application manifest that specifies a User Account Control (UAC) level in your application and PCA will not add the process to the compatibility job. For more information, see Application Development Requirements for User Account Control Compatibility. If the job or any of its parent jobs in the job chain is terminating when AssignProcessToJob is called, the function fails. To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.
AssignProcessToJobObject(HANDLE, HANDLE)
Assigns a process to an existing job object.
public static extern BOOL AssignProcessToJobObject(HANDLE hJob, HANDLE hProcess)Parameters
hJobHANDLEA handle to the job object to which the process will be associated. The CreateJobObject or OpenJobObject function returns this handle. The handle must have the JOB_OBJECT_ASSIGN_PROCESS access right. For more information, see Job Object Security and Access Rights.
hProcessHANDLEA handle to the process to associate with the job object. The handle must have the PROCESS_SET_QUOTA and PROCESS_TERMINATE access rights. For more information, see Process Security and Access Rights. If the process is already associated with a job, the job specified by hJob must be empty or it must be in the hierarchy of nested jobs to which the process already belongs, and it cannot have UI limits set (SetInformationJobObject with JobObjectBasicUIRestrictions). For more information, see Remarks. Windows 7, Windows Server 2008 R2, Windows XP with SP3, Windows Server 2008, Windows Vista and Windows Server 2003: The process must not already be assigned to a job; if it is, the function fails with ERROR_ACCESS_DENIED. This behavior changed starting in Windows 8 and Windows Server 2012. Terminal Services: All processes within a job must run within the same session as the job.
Returns
- BOOL
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
After you associate a process with a job object using AssignProcessToJobObject, the process is subject to the limits set for the job. To set limits for a job, use the SetInformationJobObject function. If the job has a user-mode time limit, and the time limit has been exhausted, AssignProcessToJobObject fails and the specified process is terminated. If the time limit would be exceeded by associating the process, AssignProcessToJobObject still succeeds. However, the time limit violation will be reported. If the job has an active process limit, and the limit would be exceeded by associating this process, AssignProcessToJobObject fails, and the specified process is terminated. Memory operations performed by a process associated with a job that has a memory limit are subject to the memory limit. Memory operations performed by the process before it was associated with the job are not examined by AssignProcessToJobObject. If the process is already running and the job has security limitations, AssignProcessToJobObject may fail. For example, if the primary token of the process contains the local administrators group, but the job object has the security limitation JOB_OBJECT_SECURITY_NO_ADMIN, the function fails. If the job has the security limitation JOB_OBJECT_SECURITY_ONLY_TOKEN, the process must be created suspended. To create a suspended process, call the CreateProcess function with the CREATE_SUSPENDED flag. A process can be associated with more than one job in a hierarchy of nested jobs. For priority class, affinity, commit charge, per-process execution time limit, scheduling class limit, and working set minimum and maximum, the process inherits an effective limit which is the most restrictive limit of all the jobs in its parent job chain. For other resource limits, the process inherits limits from its immediate job in the hierarchy. Accounting information is added to the immediate job and aggregated in each parent job in the job chain. By default, all child processes are associated with the immediate job and every job in the parent job chain. To create a child process that is not part of the same job chain, call the CreateProcess function with the CREATE_BREAKAWAY_FROM_JOB flag. The child process breaks away from every job in the job chain unless a job in the chain does not allow breakaway. In this case, the child process does not break away from that job or any job above it in the job chain. For more information, see Nested Jobs. Windows 7, Windows Server 2008 R2, Windows XP with SP3, Windows Server 2008, Windows Vista and Windows Server 2003: A process can be associated only with a single job. A process inherits limits from the job it is associated with and adds its accounting information to the job. If a process is associated with a job, all child processes it creates are associated with that job by default. To create a child process that is not part of the same job, call the CreateProcess function with the CREATE_BREAKAWAY_FROM_JOB flag. A process can be associated with more than one job starting in Windows 8 and Windows Server 2012. Windows 7, Windows Server 2008 R2, Windows Server 2008 and Windows Vista: If the process is being monitored by the Program Compatibility Assistant (PCA), it is placed into a compatibility job. Therefore, the process must be created using CREATE_BREAKAWAY_FROM_JOB before it can be placed in another job. Alternatively, you can embed an application manifest that specifies a User Account Control (UAC) level in your application and PCA will not add the process to the compatibility job. For more information, see Application Development Requirements for User Account Control Compatibility. If the job or any of its parent jobs in the job chain is terminating when AssignProcessToJob is called, the function fails. To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.
CloseDesktop(HDESK)
Closes an open handle to a desktop object.
public static extern BOOL CloseDesktop(HDESK hDesktop)Parameters
hDesktopHDESKA handle to the desktop to be closed. This can be a handle returned by the CreateDesktop, OpenDesktop, or OpenInputDesktop functions. Do not specify the handle returned by the GetThreadDesktop function.
Returns
- BOOL
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The CloseDesktop function will fail if any thread in the calling process is using the specified desktop handle or if the handle refers to the initial desktop of the calling process.
CloseHandle(HANDLE)
Closes an open object handle.
public static extern BOOL CloseHandle(HANDLE hObject)Parameters
hObjectHANDLEA valid handle to an open object.
Returns
- BOOL
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError. If the application is running under a debugger, the function will throw an exception if it receives either a handle value that is not valid or a pseudo-handle value. This can happen if you close a handle twice, or if you call CloseHandle on a handle returned by the FindFirstFile function instead of calling the FindClose function.
Remarks
The CloseHandle function closes handles to the following objects:
This doc was truncated.
CloseWindowStation(HWINSTA)
Closes an open window station handle.
public static extern BOOL CloseWindowStation(HWINSTA hWinSta)Parameters
hWinStaHWINSTAA handle to the window station to be closed. This handle is returned by the CreateWindowStation or OpenWindowStation function. Do not specify the handle returned by the GetProcessWindowStation function.
Returns
- BOOL
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError. Windows Server 2003 and Windows XP/2000: This function does not set the last error code on failure.
Remarks
The CloseWindowStation function will fail if the handle being closed is for the window station assigned to the calling process.
CreateIoCompletionPort(SafeHandle, SafeHandle, nuint, uint)
Creates an input/output (I/O) completion port and associates it with a specified file handle, or creates an I/O completion port that is not yet associated with a file handle, allowing association at a later time.
public static SafeFileHandle CreateIoCompletionPort(SafeHandle FileHandle, SafeHandle ExistingCompletionPort, nuint CompletionKey, uint NumberOfConcurrentThreads)Parameters
FileHandleSafeHandleAn open file handle or INVALID_HANDLE_VALUE. The handle must be to an object that supports overlapped I/O. If a handle is provided, it has to have been opened for overlapped I/O completion. For example, you must specify the FILE_FLAG_OVERLAPPED flag when using the CreateFile function to obtain the handle. If INVALID_HANDLE_VALUE is specified, the function creates an I/O completion port without associating it with a file handle. In this case, the ExistingCompletionPort parameter must be NULL and the CompletionKey parameter is ignored.
ExistingCompletionPortSafeHandleA handle to an existing I/O completion port or NULL. If this parameter specifies an existing I/O completion port, the function associates it with the handle specified by the FileHandle parameter. The function returns the handle of the existing I/O completion port if successful; it does not create a new I/O completion port. If this parameter is NULL, the function creates a new I/O completion port and, if the FileHandle parameter is valid, associates it with the new I/O completion port. Otherwise no file handle association occurs. The function returns the handle to the new I/O completion port if successful.
CompletionKeynuintThe per-handle user-defined completion key that is included in every I/O completion packet for the specified file handle. For more information, see the Remarks section.
NumberOfConcurrentThreadsuintThe maximum number of threads that the operating system can allow to concurrently process I/O completion packets for the I/O completion port. This parameter is ignored if the ExistingCompletionPort parameter is not NULL. If this parameter is zero, the system allows as many concurrently running threads as there are processors in the system.
Returns
- SafeFileHandle
If the function succeeds, the return value is the handle to an I/O completion port:
This doc was truncated.
Remarks
The I/O system can be instructed to send I/O completion notification packets to I/O completion ports, where they are queued. The CreateIoCompletionPort function provides this functionality. An I/O completion port and its handle are associated with the process that created it and is not sharable between processes. However, a single handle is sharable between threads in the same process. CreateIoCompletionPort can be used in three distinct modes:
This doc was truncated.
CreateIoCompletionPort(HANDLE, HANDLE, nuint, uint)
Creates an input/output (I/O) completion port and associates it with a specified file handle, or creates an I/O completion port that is not yet associated with a file handle, allowing association at a later time.
public static extern HANDLE CreateIoCompletionPort(HANDLE FileHandle, HANDLE ExistingCompletionPort, nuint CompletionKey, uint NumberOfConcurrentThreads)Parameters
FileHandleHANDLEAn open file handle or INVALID_HANDLE_VALUE. The handle must be to an object that supports overlapped I/O. If a handle is provided, it has to have been opened for overlapped I/O completion. For example, you must specify the FILE_FLAG_OVERLAPPED flag when using the CreateFile function to obtain the handle. If INVALID_HANDLE_VALUE is specified, the function creates an I/O completion port without associating it with a file handle. In this case, the ExistingCompletionPort parameter must be NULL and the CompletionKey parameter is ignored.
ExistingCompletionPortHANDLEA handle to an existing I/O completion port or NULL. If this parameter specifies an existing I/O completion port, the function associates it with the handle specified by the FileHandle parameter. The function returns the handle of the existing I/O completion port if successful; it does not create a new I/O completion port. If this parameter is NULL, the function creates a new I/O completion port and, if the FileHandle parameter is valid, associates it with the new I/O completion port. Otherwise no file handle association occurs. The function returns the handle to the new I/O completion port if successful.
CompletionKeynuintThe per-handle user-defined completion key that is included in every I/O completion packet for the specified file handle. For more information, see the Remarks section.
NumberOfConcurrentThreadsuintThe maximum number of threads that the operating system can allow to concurrently process I/O completion packets for the I/O completion port. This parameter is ignored if the ExistingCompletionPort parameter is not NULL. If this parameter is zero, the system allows as many concurrently running threads as there are processors in the system.
Returns
- HANDLE
If the function succeeds, the return value is the handle to an I/O completion port:
This doc was truncated.
Remarks
The I/O system can be instructed to send I/O completion notification packets to I/O completion ports, where they are queued. The CreateIoCompletionPort function provides this functionality. An I/O completion port and its handle are associated with the process that created it and is not sharable between processes. However, a single handle is sharable between threads in the same process. CreateIoCompletionPort can be used in three distinct modes:
This doc was truncated.
CreateJobObject(SECURITY_ATTRIBUTES?, string)
Creates or opens a job object. (CreateJobObjectW)
public static SafeFileHandle CreateJobObject(SECURITY_ATTRIBUTES? lpJobAttributes, string lpName)Parameters
lpJobAttributesSECURITY_ATTRIBUTES?A pointer to a SECURITY_ATTRIBUTES structure that specifies the security descriptor for the job object and determines whether child processes can inherit the returned handle. If lpJobAttributes is NULL, the job object gets a default security descriptor and the handle cannot be inherited. The ACLs in the default security descriptor for a job object come from the primary or impersonation token of the creator.
lpNamestringThe name of the job. The name is limited to MAX_PATH characters. Name comparison is case-sensitive.
If lpName is NULL, the job is created without a name. If lpName matches the name of an existing event, semaphore, mutex, waitable timer, or file-mapping object, the function fails and the GetLastError function returns ERROR_INVALID_HANDLE. This occurs because these objects share the same namespace. The object can be created in a private namespace. For more information, see Object Namespaces. Terminal Services: The name can have a "Global\\" or "Local\\" prefix to explicitly create the object in the global or session namespace. The remainder of the name can contain any character except the backslash character (\\). For more information, see Kernel Object Namespaces.
Returns
- SafeFileHandle
If the function succeeds, the return value is a handle to the job object. The handle has the JOB_OBJECT_ALL_ACCESS access right. If the object existed before the function call, the function returns a handle to the existing job object and GetLastError returns ERROR_ALREADY_EXISTS. If the function fails, the return value is NULL. To get extended error information, call GetLastError.
Remarks
When a job is created, its accounting information is initialized to zero, all limits are inactive, and there are no associated processes. To assign a process to a job object, use the AssignProcessToJobObject function. To set limits for a job, use the SetInformationJobObject function. To query accounting information, use the QueryInformationJobObject function. All processes associated with a job must run in the same session. A job is associated with the session of the first process to be assigned to the job. Windows Server 2003 and Windows XP: A job is associated with the session of the process that created it. To close a job object handle, use the CloseHandle function. The job is destroyed when its last handle has been closed and all associated processes have exited. However, if the job has the JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE flag specified, closing the last job object handle terminates all associated processes and then destroys the job object itself. To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.
CreateJobObject(SECURITY_ATTRIBUTES*, PCWSTR)
Creates or opens a job object. (CreateJobObjectW)
public static extern HANDLE CreateJobObject(SECURITY_ATTRIBUTES* lpJobAttributes, PCWSTR lpName)Parameters
lpJobAttributesSECURITY_ATTRIBUTES*A pointer to a SECURITY_ATTRIBUTES structure that specifies the security descriptor for the job object and determines whether child processes can inherit the returned handle. If lpJobAttributes is NULL, the job object gets a default security descriptor and the handle cannot be inherited. The ACLs in the default security descriptor for a job object come from the primary or impersonation token of the creator.
lpNamePCWSTRThe name of the job. The name is limited to MAX_PATH characters. Name comparison is case-sensitive.
If lpName is NULL, the job is created without a name. If lpName matches the name of an existing event, semaphore, mutex, waitable timer, or file-mapping object, the function fails and the GetLastError function returns ERROR_INVALID_HANDLE. This occurs because these objects share the same namespace. The object can be created in a private namespace. For more information, see Object Namespaces. Terminal Services: The name can have a "Global\\" or "Local\\" prefix to explicitly create the object in the global or session namespace. The remainder of the name can contain any character except the backslash character (\\). For more information, see Kernel Object Namespaces.
Returns
- HANDLE
If the function succeeds, the return value is a handle to the job object. The handle has the JOB_OBJECT_ALL_ACCESS access right. If the object existed before the function call, the function returns a handle to the existing job object and GetLastError returns ERROR_ALREADY_EXISTS. If the function fails, the return value is NULL. To get extended error information, call GetLastError.
Remarks
When a job is created, its accounting information is initialized to zero, all limits are inactive, and there are no associated processes. To assign a process to a job object, use the AssignProcessToJobObject function. To set limits for a job, use the SetInformationJobObject function. To query accounting information, use the QueryInformationJobObject function. All processes associated with a job must run in the same session. A job is associated with the session of the first process to be assigned to the job. Windows Server 2003 and Windows XP: A job is associated with the session of the process that created it. To close a job object handle, use the CloseHandle function. The job is destroyed when its last handle has been closed and all associated processes have exited. However, if the job has the JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE flag specified, closing the last job object handle terminates all associated processes and then destroys the job object itself. To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.
FreeLibrary(HMODULE)
Frees the loaded dynamic-link library (DLL) module and, if necessary, decrements its reference count.
public static extern BOOL FreeLibrary(HMODULE hLibModule)Parameters
hLibModuleHMODULEA handle to the loaded library module. The LoadLibrary, LoadLibraryEx, GetModuleHandle, or GetModuleHandleEx function returns this handle.
Returns
- BOOL
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call the GetLastError function.
Remarks
The system maintains a per-process reference count for each loaded module. A module that was loaded at process initialization due to load-time dynamic linking has a reference count of one. The reference count for a module is incremented each time the module is loaded by a call to LoadLibrary. The reference count is also incremented by a call to LoadLibraryEx unless the module is being loaded for the first time and is being loaded as a data or image file. The reference count is decremented each time the FreeLibrary or FreeLibraryAndExitThread function is called for the module. When a module's reference count reaches zero or the process terminates, the system unloads the module from the address space of the process. Before unloading a library module, the system enables the module to detach from the process by calling the module's DllMain function, if it has one, with the DLL_PROCESS_DETACH value. Doing so gives the library module an opportunity to clean up resources allocated on behalf of the current process. After the entry-point function returns, the library module is removed from the address space of the current process. It is not safe to call FreeLibrary from DllMain. For more information, see the Remarks section in DllMain. Calling FreeLibrary does not affect other processes that are using the same module. Use caution when calling FreeLibrary with a handle returned by GetModuleHandle. The GetModuleHandle function does not increment a module's reference count, so passing this handle to FreeLibrary can cause a module to be unloaded prematurely. A thread that must unload the DLL in which it is executing and then terminate itself should call FreeLibraryAndExitThread instead of calling FreeLibrary and ExitThread separately. Otherwise, a race condition can occur. For details, see the Remarks section of FreeLibraryAndExitThread.
GetCurrentThreadId()
Retrieves the thread identifier of the calling thread.
public static extern uint GetCurrentThreadId()Returns
- uint
The return value is the thread identifier of the calling thread.
Remarks
Until the thread terminates, the thread identifier uniquely identifies the thread throughout the system.
GetProcessWindowStation()
Retrieves a handle to the current window station for the calling process.
public static extern HWINSTA GetProcessWindowStation()Returns
- HWINSTA
If the function succeeds, the return value is a handle to the window station. If the function fails, the return value is NULL. To get extended error information, call GetLastError.
Remarks
The system associates a window station with a process when the process is created. A process can use the SetProcessWindowStation function to change its window station. The calling process can use the returned handle in calls to the GetUserObjectInformation, GetUserObjectSecurity, SetUserObjectInformation, and SetUserObjectSecurity functions. Do not close the handle returned by this function. A service application is created with an associated window station and desktop, so there is no need to call a USER or GDI function to connect the service to a window station and desktop.
GetProcessWindowStation_SafeHandle()
Retrieves a handle to the current window station for the calling process.
public static CloseWindowStationSafeHandle GetProcessWindowStation_SafeHandle()Returns
- CloseWindowStationSafeHandle
If the function succeeds, the return value is a handle to the window station. If the function fails, the return value is NULL. To get extended error information, call GetLastError.
Remarks
The system associates a window station with a process when the process is created. A process can use the SetProcessWindowStation function to change its window station. The calling process can use the returned handle in calls to the GetUserObjectInformation, GetUserObjectSecurity, SetUserObjectInformation, and SetUserObjectSecurity functions. Do not close the handle returned by this function. A service application is created with an associated window station and desktop, so there is no need to call a USER or GDI function to connect the service to a window station and desktop.
GetThreadDesktop(uint)
Retrieves a handle to the desktop assigned to the specified thread.
public static extern HDESK GetThreadDesktop(uint dwThreadId)Parameters
dwThreadIduintThe thread identifier. The GetCurrentThreadId and CreateProcess functions return thread identifiers.
Returns
- HDESK
If the function succeeds, the return value is a handle to the desktop associated with the specified thread. You do not need to call the CloseDesktop function to close the returned handle. If the function fails, the return value is NULL. To get extended error information, call GetLastError.
Remarks
The system associates a desktop with a thread when that thread is created. A thread can use the SetThreadDesktop function to change its desktop. The desktop associated with a thread must be on the window station associated with the thread's process. The calling process can use the returned handle in calls to the GetUserObjectInformation, GetUserObjectSecurity, SetUserObjectInformation, and SetUserObjectSecurity functions. A service application is created with an associated window station and desktop, so there is no need to call a USER or GDI function to connect the service to a window station and desktop.
GetThreadDesktop_SafeHandle(uint)
Retrieves a handle to the desktop assigned to the specified thread.
public static CloseDesktopSafeHandle GetThreadDesktop_SafeHandle(uint dwThreadId)Parameters
dwThreadIduintThe thread identifier. The GetCurrentThreadId and CreateProcess functions return thread identifiers.
Returns
- CloseDesktopSafeHandle
If the function succeeds, the return value is a handle to the desktop associated with the specified thread. You do not need to call the CloseDesktop function to close the returned handle. If the function fails, the return value is NULL. To get extended error information, call GetLastError.
Remarks
The system associates a desktop with a thread when that thread is created. A thread can use the SetThreadDesktop function to change its desktop. The desktop associated with a thread must be on the window station associated with the thread's process. The calling process can use the returned handle in calls to the GetUserObjectInformation, GetUserObjectSecurity, SetUserObjectInformation, and SetUserObjectSecurity functions. A service application is created with an associated window station and desktop, so there is no need to call a USER or GDI function to connect the service to a window station and desktop.
LoadLibrary(string)
Loads the specified module into the address space of the calling process. (LoadLibraryW)
public static FreeLibrarySafeHandle LoadLibrary(string lpLibFileName)Parameters
lpLibFileNamestringThe name of the module. This can be either a library module (a .dll file) or an executable module (an .exe file). If the specified module is an executable module, static imports are not loaded; instead, the module is loaded as if by LoadLibraryEx with the `DONT_RESOLVE_DLL_REFERENCES` flag. The name specified is the file name of the module and is not related to the name stored in the library module itself, as specified by the LIBRARY keyword in the module-definition (.def) file. If the string specifies a full path, the function searches only that path for the module. If the string specifies a relative path or a module name without a path, the function uses a standard search strategy to find the module; for more information, see the Remarks. If the function cannot find the module, the function fails. When specifying a path, be sure to use backslashes (\\), not forward slashes (/). For more information about paths, see Naming a File or Directory. If the string specifies a module name without a path and the file name extension is omitted, the function appends the default library extension ".DLL" to the module name. To prevent the function from appending ".DLL" to the module name, include a trailing point character (.) in the module name string.
Returns
- FreeLibrarySafeHandle
If the function succeeds, the return value is a handle to the module. If the function fails, the return value is NULL. To get extended error information, call GetLastError.
Remarks
To enable or disable error messages displayed by the loader during DLL loads, use the SetErrorMode function. LoadLibrary can be used to load a library module into the address space of the process and return a handle that can be used in GetProcAddress to get the address of a DLL function. LoadLibrary can also be used to load other executable modules. For example, the function can specify an .exe file to get a handle that can be used in FindResource or LoadResource. However, do not use LoadLibrary to run an .exe file. Instead, use the CreateProcess function. If the specified module is a DLL that is not already loaded for the calling process, the system calls the DLL's DllMain function with the DLL_PROCESS_ATTACH value. If DllMain returns TRUE, LoadLibrary returns a handle to the module. If DllMain returns FALSE, the system unloads the DLL from the process address space and LoadLibrary returns NULL. It is not safe to call LoadLibrary from DllMain. For more information, see the Remarks section in DllMain. Module handles are not global or inheritable. A call to LoadLibrary by one process does not produce a handle that another process can use — for example, in calling GetProcAddress. The other process must make its own call to LoadLibrary for the module before calling GetProcAddress. If lpFileName does not include a path and there is more than one loaded module with the same base name and extension, the function returns a handle to the module that was loaded first. If no file name extension is specified in the lpFileName parameter, the default library extension .dll is appended. However, the file name string can include a trailing point character (.) to indicate that the module name has no extension. When no path is specified, the function searches for loaded modules whose base name matches the base name of the module to be loaded. If the name matches, the load succeeds. Otherwise, the function searches for the file. The first directory searched is the directory containing the image file used to create the calling process (for more information, see the CreateProcess function). Doing this allows private dynamic-link library (DLL) files associated with a process to be found without adding the process's installed directory to the PATH environment variable. If a relative path is specified, the entire relative path is appended to every token in the DLL search path list. To load a module from a relative path without searching any other path, use GetFullPathName to get a nonrelative path and call LoadLibrary with the nonrelative path. For more information on the DLL search order, see Dynamic-Link Library Search Order. The search path can be altered using the SetDllDirectory function. This solution is recommended instead of using SetCurrentDirectory or hard-coding the full path to the DLL. If a path is specified and there is a redirection file for the application, the function searches for the module in the application's directory. If the module exists in the application's directory, LoadLibrary ignores the specified path and loads the module from the application's directory. If the module does not exist in the application's directory, LoadLibrary loads the module from the specified directory. For more information, see Dynamic Link Library Redirection. If you call LoadLibrary with the name of an assembly without a path specification and the assembly is listed in the system compatible manifest, the call is automatically redirected to the side-by-side assembly. The system maintains a per-process reference count on all loaded modules. Calling LoadLibrary increments the reference count. Calling the FreeLibrary or FreeLibraryAndExitThread function decrements the reference count. The system unloads a module when its reference count reaches zero or when the process terminates (regardless of the reference count). Windows Server 2003 and Windows XP: The Visual C++ compiler supports a syntax that enables you to declare thread-local variables: _declspec(thread). If you use this syntax in a DLL, you will not be able to load the DLL explicitly using LoadLibrary on versions of Windows prior to Windows Vista. If your DLL will be loaded explicitly, you must use the thread local storage functions instead of _declspec(thread). For an example, see Using Thread Local Storage in a Dynamic Link Library.
Security Remarks
Do not use the SearchPath function to retrieve a path to a DLL for a subsequent LoadLibrary call. The SearchPath function uses a different search order than LoadLibrary and it does not use safe process search mode unless this is explicitly enabled by calling SetSearchPathMode with BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE. Therefore, SearchPath is likely to first search the user’s current working directory for the specified DLL. If an attacker has copied a malicious version of a DLL into the current working directory, the path retrieved by SearchPath will point to the malicious DLL, which LoadLibrary will then load. Do not make assumptions about the operating system version based on a LoadLibrary call that searches for a DLL. If the application is running in an environment where the DLL is legitimately not present but a malicious version of the DLL is in the search path, the malicious version of the DLL may be loaded. Instead, use the recommended techniques described in Getting the System Version.LoadLibrary(PCWSTR)
Loads the specified module into the address space of the calling process. (LoadLibraryW)
public static extern HMODULE LoadLibrary(PCWSTR lpLibFileName)Parameters
lpLibFileNamePCWSTRThe name of the module. This can be either a library module (a .dll file) or an executable module (an .exe file). If the specified module is an executable module, static imports are not loaded; instead, the module is loaded as if by LoadLibraryEx with the `DONT_RESOLVE_DLL_REFERENCES` flag. The name specified is the file name of the module and is not related to the name stored in the library module itself, as specified by the LIBRARY keyword in the module-definition (.def) file. If the string specifies a full path, the function searches only that path for the module. If the string specifies a relative path or a module name without a path, the function uses a standard search strategy to find the module; for more information, see the Remarks. If the function cannot find the module, the function fails. When specifying a path, be sure to use backslashes (\\), not forward slashes (/). For more information about paths, see Naming a File or Directory. If the string specifies a module name without a path and the file name extension is omitted, the function appends the default library extension ".DLL" to the module name. To prevent the function from appending ".DLL" to the module name, include a trailing point character (.) in the module name string.
Returns
- HMODULE
If the function succeeds, the return value is a handle to the module. If the function fails, the return value is NULL. To get extended error information, call GetLastError.
Remarks
To enable or disable error messages displayed by the loader during DLL loads, use the SetErrorMode function. LoadLibrary can be used to load a library module into the address space of the process and return a handle that can be used in GetProcAddress to get the address of a DLL function. LoadLibrary can also be used to load other executable modules. For example, the function can specify an .exe file to get a handle that can be used in FindResource or LoadResource. However, do not use LoadLibrary to run an .exe file. Instead, use the CreateProcess function. If the specified module is a DLL that is not already loaded for the calling process, the system calls the DLL's DllMain function with the DLL_PROCESS_ATTACH value. If DllMain returns TRUE, LoadLibrary returns a handle to the module. If DllMain returns FALSE, the system unloads the DLL from the process address space and LoadLibrary returns NULL. It is not safe to call LoadLibrary from DllMain. For more information, see the Remarks section in DllMain. Module handles are not global or inheritable. A call to LoadLibrary by one process does not produce a handle that another process can use — for example, in calling GetProcAddress. The other process must make its own call to LoadLibrary for the module before calling GetProcAddress. If lpFileName does not include a path and there is more than one loaded module with the same base name and extension, the function returns a handle to the module that was loaded first. If no file name extension is specified in the lpFileName parameter, the default library extension .dll is appended. However, the file name string can include a trailing point character (.) to indicate that the module name has no extension. When no path is specified, the function searches for loaded modules whose base name matches the base name of the module to be loaded. If the name matches, the load succeeds. Otherwise, the function searches for the file. The first directory searched is the directory containing the image file used to create the calling process (for more information, see the CreateProcess function). Doing this allows private dynamic-link library (DLL) files associated with a process to be found without adding the process's installed directory to the PATH environment variable. If a relative path is specified, the entire relative path is appended to every token in the DLL search path list. To load a module from a relative path without searching any other path, use GetFullPathName to get a nonrelative path and call LoadLibrary with the nonrelative path. For more information on the DLL search order, see Dynamic-Link Library Search Order. The search path can be altered using the SetDllDirectory function. This solution is recommended instead of using SetCurrentDirectory or hard-coding the full path to the DLL. If a path is specified and there is a redirection file for the application, the function searches for the module in the application's directory. If the module exists in the application's directory, LoadLibrary ignores the specified path and loads the module from the application's directory. If the module does not exist in the application's directory, LoadLibrary loads the module from the specified directory. For more information, see Dynamic Link Library Redirection. If you call LoadLibrary with the name of an assembly without a path specification and the assembly is listed in the system compatible manifest, the call is automatically redirected to the side-by-side assembly. The system maintains a per-process reference count on all loaded modules. Calling LoadLibrary increments the reference count. Calling the FreeLibrary or FreeLibraryAndExitThread function decrements the reference count. The system unloads a module when its reference count reaches zero or when the process terminates (regardless of the reference count). Windows Server 2003 and Windows XP: The Visual C++ compiler supports a syntax that enables you to declare thread-local variables: _declspec(thread). If you use this syntax in a DLL, you will not be able to load the DLL explicitly using LoadLibrary on versions of Windows prior to Windows Vista. If your DLL will be loaded explicitly, you must use the thread local storage functions instead of _declspec(thread). For an example, see Using Thread Local Storage in a Dynamic Link Library.
Security Remarks
Do not use the SearchPath function to retrieve a path to a DLL for a subsequent LoadLibrary call. The SearchPath function uses a different search order than LoadLibrary and it does not use safe process search mode unless this is explicitly enabled by calling SetSearchPathMode with BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE. Therefore, SearchPath is likely to first search the user’s current working directory for the specified DLL. If an attacker has copied a malicious version of a DLL into the current working directory, the path retrieved by SearchPath will point to the malicious DLL, which LoadLibrary will then load. Do not make assumptions about the operating system version based on a LoadLibrary call that searches for a DLL. If the application is running in an environment where the DLL is legitimately not present but a malicious version of the DLL is in the search path, the malicious version of the DLL may be loaded. Instead, use the recommended techniques described in Getting the System Version.OpenJobObject(uint, BOOL, string)
Opens an existing job object. (OpenJobObjectW)
public static SafeFileHandle OpenJobObject(uint dwDesiredAccess, BOOL bInheritHandle, string lpName)Parameters
dwDesiredAccessuintThe access to the job object. This parameter can be one or more of the job object access rights. This access right is checked against any security descriptor for the object.
bInheritHandleBOOLIf this value is TRUE, processes created by this process will inherit the handle. Otherwise, the processes do not inherit this handle.
lpNamestringThe name of the job to be opened. Name comparisons are case sensitive. This function can open objects in a private namespace. For more information, see Object Namespaces. Terminal Services: The name can have a "Global\\" or "Local\\" prefix to explicitly open the object in the global or session namespace. The remainder of the name can contain any character except the backslash character (\\). For more information, see Kernel Object Namespaces.
Returns
- SafeFileHandle
If the function succeeds, the return value is a handle to the job. The handle provides the requested access to the job. If the function fails, the return value is NULL. To get extended error information, call GetLastError.
Remarks
To associate a process with a job, use the AssignProcessToJobObject function. To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.
OpenJobObject(uint, BOOL, PCWSTR)
Opens an existing job object. (OpenJobObjectW)
public static extern HANDLE OpenJobObject(uint dwDesiredAccess, BOOL bInheritHandle, PCWSTR lpName)Parameters
dwDesiredAccessuintThe access to the job object. This parameter can be one or more of the job object access rights. This access right is checked against any security descriptor for the object.
bInheritHandleBOOLIf this value is TRUE, processes created by this process will inherit the handle. Otherwise, the processes do not inherit this handle.
lpNamePCWSTRThe name of the job to be opened. Name comparisons are case sensitive. This function can open objects in a private namespace. For more information, see Object Namespaces. Terminal Services: The name can have a "Global\\" or "Local\\" prefix to explicitly open the object in the global or session namespace. The remainder of the name can contain any character except the backslash character (\\). For more information, see Kernel Object Namespaces.
Returns
- HANDLE
If the function succeeds, the return value is a handle to the job. The handle provides the requested access to the job. If the function fails, the return value is NULL. To get extended error information, call GetLastError.
Remarks
To associate a process with a job, use the AssignProcessToJobObject function. To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.
QueryInformationJobObject(SafeHandle, JOBOBJECTINFOCLASS, void*, uint, uint*)
Retrieves limit and job state information from the job object.
public static BOOL QueryInformationJobObject(SafeHandle hJob, JOBOBJECTINFOCLASS JobObjectInformationClass, void* lpJobObjectInformation, uint cbJobObjectInformationLength, uint* lpReturnLength)Parameters
hJobSafeHandleA handle to the job whose information is being queried. The CreateJobObject or OpenJobObject function returns this handle. The handle must have the JOB_OBJECT_QUERY access right. For more information, see Job Object Security and Access Rights.
If this value is NULL and the calling process is associated with a job, the job associated with the calling process is used. If the job is nested, the immediate job of the calling process is used.
JobObjectInformationClassJOBOBJECTINFOCLASSlpJobObjectInformationvoid*The limit or job state information. The format of this data depends on the value of the JobObjectInfoClass parameter.
cbJobObjectInformationLengthuintThe count of the job information being queried, in bytes. This value depends on the value of the JobObjectInfoClass parameter.
lpReturnLengthuint*A pointer to a variable that receives the length of data written to the structure pointed to by the lpJobObjectInfo parameter. Specify NULL to not receive this information.
Returns
- BOOL
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Use QueryInformationJobObject to obtain the current limits and modify them. Use the SetInformationJobObject function to set new limits. To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.
QueryInformationJobObject(HANDLE, JOBOBJECTINFOCLASS, void*, uint, uint*)
Retrieves limit and job state information from the job object.
public static extern BOOL QueryInformationJobObject(HANDLE hJob, JOBOBJECTINFOCLASS JobObjectInformationClass, void* lpJobObjectInformation, uint cbJobObjectInformationLength, uint* lpReturnLength)Parameters
hJobHANDLEA handle to the job whose information is being queried. The CreateJobObject or OpenJobObject function returns this handle. The handle must have the JOB_OBJECT_QUERY access right. For more information, see Job Object Security and Access Rights.
If this value is NULL and the calling process is associated with a job, the job associated with the calling process is used. If the job is nested, the immediate job of the calling process is used.
JobObjectInformationClassJOBOBJECTINFOCLASSlpJobObjectInformationvoid*The limit or job state information. The format of this data depends on the value of the JobObjectInfoClass parameter.
cbJobObjectInformationLengthuintThe count of the job information being queried, in bytes. This value depends on the value of the JobObjectInfoClass parameter.
lpReturnLengthuint*A pointer to a variable that receives the length of data written to the structure pointed to by the lpJobObjectInfo parameter. Specify NULL to not receive this information.
Returns
- BOOL
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Use QueryInformationJobObject to obtain the current limits and modify them. Use the SetInformationJobObject function to set new limits. To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.
SetInformationJobObject(SafeHandle, JOBOBJECTINFOCLASS, void*, uint)
Sets limits for a job object.
public static BOOL SetInformationJobObject(SafeHandle hJob, JOBOBJECTINFOCLASS JobObjectInformationClass, void* lpJobObjectInformation, uint cbJobObjectInformationLength)Parameters
hJobSafeHandleA handle to the job whose limits are being set. The CreateJobObject or OpenJobObject function returns this handle. The handle must have the JOB_OBJECT_SET_ATTRIBUTES access right. For more information, see Job Object Security and Access Rights.
JobObjectInformationClassJOBOBJECTINFOCLASSlpJobObjectInformationvoid*The limits or job state to be set for the job. The format of this data depends on the value of JobObjectInfoClass.
cbJobObjectInformationLengthuintThe size of the job information being set, in bytes.
Returns
- BOOL
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Use the SetInformationJobObject function to set several limits in a single call. To establish the limits one at a time or change a subset of the limits, call the QueryInformationJobObject function to obtain the current limits, modify these limits, and then call SetInformationJobObject. You must set security limits individually for each process associated with a job object, rather than setting them for the job object itself. For information, see Process Security and Access Rights. Windows Server 2003 and Windows XP: Use the SetInformationJobObject function to set security limits for the job object. To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.
SetInformationJobObject(HANDLE, JOBOBJECTINFOCLASS, void*, uint)
Sets limits for a job object.
public static extern BOOL SetInformationJobObject(HANDLE hJob, JOBOBJECTINFOCLASS JobObjectInformationClass, void* lpJobObjectInformation, uint cbJobObjectInformationLength)Parameters
hJobHANDLEA handle to the job whose limits are being set. The CreateJobObject or OpenJobObject function returns this handle. The handle must have the JOB_OBJECT_SET_ATTRIBUTES access right. For more information, see Job Object Security and Access Rights.
JobObjectInformationClassJOBOBJECTINFOCLASSlpJobObjectInformationvoid*The limits or job state to be set for the job. The format of this data depends on the value of JobObjectInfoClass.
cbJobObjectInformationLengthuintThe size of the job information being set, in bytes.
Returns
- BOOL
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Use the SetInformationJobObject function to set several limits in a single call. To establish the limits one at a time or change a subset of the limits, call the QueryInformationJobObject function to obtain the current limits, modify these limits, and then call SetInformationJobObject. You must set security limits individually for each process associated with a job object, rather than setting them for the job object itself. For information, see Process Security and Access Rights. Windows Server 2003 and Windows XP: Use the SetInformationJobObject function to set security limits for the job object. To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.
TerminateJobObject(SafeHandle, uint)
Terminates all processes currently associated with the job.
public static BOOL TerminateJobObject(SafeHandle hJob, uint uExitCode)Parameters
hJobSafeHandleA handle to the job whose processes will be terminated. The CreateJobObject or OpenJobObject function returns this handle. This handle must have the JOB_OBJECT_TERMINATE access right. For more information, see Job Object Security and Access Rights. The handle for each process in the job object must have the PROCESS_TERMINATE access right. For more information, see Process Security and Access Rights.
uExitCodeuintThe exit code to be used by all processes and threads in the job object. Use the GetExitCodeProcess function to retrieve each process's exit value. Use the GetExitCodeThread function to retrieve each thread's exit value.
Returns
- BOOL
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
It is not possible for any of the processes associated with the job to postpone or handle the termination. It is as if TerminateProcess were called for each process associated with the job. Terminating a nested job additionally terminates all child job objects. Resources used by the terminated jobs are charged up the parent job chain in the hierarchy. To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.
TerminateJobObject(HANDLE, uint)
Terminates all processes currently associated with the job.
public static extern BOOL TerminateJobObject(HANDLE hJob, uint uExitCode)Parameters
hJobHANDLEA handle to the job whose processes will be terminated. The CreateJobObject or OpenJobObject function returns this handle. This handle must have the JOB_OBJECT_TERMINATE access right. For more information, see Job Object Security and Access Rights. The handle for each process in the job object must have the PROCESS_TERMINATE access right. For more information, see Process Security and Access Rights.
uExitCodeuintThe exit code to be used by all processes and threads in the job object. Use the GetExitCodeProcess function to retrieve each process's exit value. Use the GetExitCodeThread function to retrieve each thread's exit value.
Returns
- BOOL
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
It is not possible for any of the processes associated with the job to postpone or handle the termination. It is as if TerminateProcess were called for each process associated with the job. Terminating a nested job additionally terminates all child job objects. Resources used by the terminated jobs are charged up the parent job chain in the hierarchy. To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.