source: branches/eraser6/Util/KernelAPI.cs @ 512

Revision 512, 29.0 KB checked in by lowjoel, 6 years ago (diff)

Add the ProcessorArchitecture? enum for the KernelAPI.SYSTEM_INFO structure (don't hardcode constants)

  • Property svn:keywords set to Id
Line 
1/*
2 * $Id$
3 * Copyright 2008 The Eraser Project
4 * Original Author: Joel Low <lowjoel@users.sourceforge.net>
5 * Modified By: Garrett Trant <gtrant@users.sourceforge.net>
6 *
7 * This file is part of Eraser.
8 *
9 * Eraser is free software: you can redistribute it and/or modify it under the
10 * terms of the GNU General Public License as published by the Free Software
11 * Foundation, either version 3 of the License, or (at your option) any later
12 * version.
13 *
14 * Eraser is distributed in the hope that it will be useful, but WITHOUT ANY
15 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
16 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
17 *
18 * A copy of the GNU General Public License can be found at
19 * <http://www.gnu.org/licenses/>.
20 */
21
22using System;
23using System.Collections.Generic;
24using System.Text;
25using System.Reflection;
26using System.Runtime.InteropServices;
27
28namespace Eraser.Util
29{
30    public static class KernelAPI
31    {
32        /// <summary>
33        /// Closes an open object handle.
34        /// </summary>
35        /// <param name="hObject">A valid handle to an open object.</param>
36        /// <returns>If the function succeeds, the return value is true. To get
37        /// extended error information, call Marshal.GetLastWin32Error().
38        ///
39        /// If the application is running under a debugger, the function will throw
40        /// an exception if it receives either a handle value that is not valid
41        /// or a pseudo-handle value. This can happen if you close a handle twice,
42        /// or if you call CloseHandle on a handle returned by the FindFirstFile
43        /// function.</returns>
44        [DllImport("Kernel32.dll", SetLastError = true)]
45        [return: MarshalAs(UnmanagedType.Bool)]
46        public static extern bool CloseHandle(IntPtr hObject);
47
48        /// <summary>
49        /// Retrieves a pseudo handle for the current process.
50        /// </summary>
51        /// <returns>A pseudo handle to the current process.</returns>
52        /// <remarks>A pseudo handle is a special constant, currently (HANDLE)-1,
53        /// that is interpreted as the current process handle. For compatibility
54        /// with future operating systems, it is best to call GetCurrentProcess
55        /// instead of hard-coding this constant value. The calling process can
56        /// use a pseudo handle to specify its own process whenever a process
57        /// handle is required. Pseudo handles are not inherited by child processes.
58        ///
59        /// This handle has the maximum possible access to the process object.
60        /// For systems that support security descriptors, this is the maximum
61        /// access allowed by the security descriptor for the calling process.
62        /// For systems that do not support security descriptors, this is
63        /// PROCESS_ALL_ACCESS. For more information, see Process Security and
64        /// Access Rights.
65        ///
66        /// A process can create a "real" handle to itself that is valid in the
67        /// context of other processes, or that can be inherited by other processes,
68        /// by specifying the pseudo handle as the source handle in a call to the
69        /// DuplicateHandle function. A process can also use the OpenProcess
70        /// function to open a real handle to itself.
71        ///
72        /// The pseudo handle need not be closed when it is no longer needed.
73        /// Calling the CloseHandle function with a pseudo handle has no effect.
74        /// If the pseudo handle is duplicated by DuplicateHandle, the duplicate
75        /// handle must be closed.</remarks>
76        [DllImport("Kernel32.dll", SetLastError = true)]
77        public static extern IntPtr GetCurrentProcess();
78
79        /// <summary>
80        /// Retrieves the process identifier of the calling process.
81        /// </summary>
82        /// <returns>The return value is the process identifier of the calling
83        /// process.</returns>
84        [DllImport("Kernel32.dll")]
85        public static extern uint GetCurrentProcessId();
86
87        /// <summary>
88        /// Retrieves a pseudo handle for the calling thread.
89        /// </summary>
90        /// <returns>The return value is a pseudo handle for the current thread.</returns>
91        [DllImport("Kernel32.dll", SetLastError = true)]
92        public static extern IntPtr GetCurrentThread();
93
94        /// <summary>
95        /// Retrieves the thread identifier of the calling thread.
96        /// </summary>
97        /// <returns>The return value is the thread identifier of the calling
98        /// thread.</returns>
99        [DllImport("Kernel32.dll")]
100        public static extern uint GetCurrentThreadId();
101
102        /// <summary>
103        /// Retrieves a handle to the heap of the calling process. This handle
104        /// can then be used in subsequent calls to the heap functions.
105        /// </summary>
106        /// <returns>If the function succeeds, the return value is a handle to
107        /// the calling process's heap.
108        ///
109        /// If the function fails, the return value is NULL. To get extended error
110        /// information, call Marshal.GetLastWin32Error.</returns>
111        [DllImport("Kernel32.dll", SetLastError = true)]
112        public static extern IntPtr GetProcessHeap();
113
114        /// <summary>
115        /// Retrieves timing information for the specified process.
116        /// </summary>
117        /// <param name="hThread">A handle to the process whose timing information
118        /// is sought. This handle must have the PROCESS_QUERY_INFORMATION access
119        /// right. For more information, see Thread Security and Access Rights.</param>
120        /// <param name="lpCreationTime">A reference to a long that receives the
121        /// creation time of the thread.</param>
122        /// <param name="lpExitTime">A reference to a long that receives the exit time
123        /// of the thread. If the thread has not exited, the value of field is
124        /// undefined.</param>
125        /// <param name="lpKernelTime">A reference to a long that receives the
126        /// amount of time that the thread has executed in kernel mode.</param>
127        /// <param name="lpUserTime">A reference to a long that receives the amount
128        /// of time that the thread has executed in user mode.</param>
129        /// <returns>If the function succeeds, the return value is nonzero.
130        ///
131        /// If the function fails, the return value is zero. To get extended error
132        /// information, call Marshal.GetLastWin32Error.</returns>
133        [DllImport("Kernel32.dll", SetLastError = true)]
134        [return: MarshalAs(UnmanagedType.Bool)]
135        public static extern bool GetProcessTimes(IntPtr hThread, out long lpCreationTime,
136           out long lpExitTime, out long lpKernelTime, out long lpUserTime);
137
138        /// <summary>
139        /// Retrieves the contents of the STARTUPINFO structure that was specified
140        /// when the calling process was created.
141        /// </summary>
142        /// <param name="lpStartupInfo">A pointer to a STARTUPINFO structure that
143        /// receives the startup information.</param>
144        [DllImport("Kernel32.dll", CharSet = CharSet.Unicode)]
145        public static extern void GetStartupInfo(out STARTUPINFO lpStartupInfo);
146
147        /// <summary>
148        /// Retrieves information about the current system.
149        /// </summary>
150        /// <param name="lpSystemInfo">A pointer to a SYSTEM_INFO structure that
151        /// receives the information.</param>
152        [DllImport("Kernel32.dll")]
153        public static extern void GetSystemInfo(out SYSTEM_INFO lpSystemInfo);
154
155        /// <summary>
156        /// Retrieves timing information for the specified thread.
157        /// </summary>
158        /// <param name="hThread">A handle to the thread whose timing information
159        /// is sought. This handle must have the THREAD_QUERY_INFORMATION access
160        /// right. For more information, see Thread Security and Access Rights.</param>
161        /// <param name="lpCreationTime">A reference to a long that receives the
162        /// creation time of the thread.</param>
163        /// <param name="lpExitTime">A reference to a long that receives the exit time
164        /// of the thread. If the thread has not exited, the value of field is
165        /// undefined.</param>
166        /// <param name="lpKernelTime">A reference to a long that receives the
167        /// amount of time that the thread has executed in kernel mode.</param>
168        /// <param name="lpUserTime">A reference to a long that receives the amount
169        /// of time that the thread has executed in user mode.</param>
170        /// <returns>If the function succeeds, the return value is nonzero.
171        ///
172        /// If the function fails, the return value is zero. To get extended error
173        /// information, call Marshal.GetLastWin32Error.</returns>
174        [DllImport("Kernel32.dll", SetLastError = true)]
175        [return: MarshalAs(UnmanagedType.Bool)]
176        public static extern bool GetThreadTimes(IntPtr hThread, out long lpCreationTime,
177           out long lpExitTime, out long lpKernelTime, out long lpUserTime);
178
179        /// <summary>
180        /// Retrieves the number of milliseconds that have elapsed since the system
181        /// was started, up to 49.7 days.
182        /// </summary>
183        /// <returns>The return value is the number of milliseconds that have elapsed
184        /// since the system was started.</returns>
185        /// <remarks>The resolution is limited to the resolution of the system timer.
186        /// This value is also affected by adjustments made by the GetSystemTimeAdjustment
187        /// function.
188        ///
189        /// The elapsed time is stored as a DWORD value. Therefore, the time will
190        /// wrap around to zero if the system is run continuously for 49.7 days.
191        /// To avoid this problem, use GetTickCount64. Otherwise, check for an
192        /// overflow condition when comparing times.
193        ///
194        /// If you need a higher resolution timer, use a multimedia timer or a
195        /// high-resolution timer.
196        ///
197        /// To obtain the time elapsed since the computer was started, retrieve
198        /// the System Up Time counter in the performance data in the registry key
199        /// HKEY_PERFORMANCE_DATA. The value returned is an 8-byte value. For more
200        /// information, see Performance Counters.</remarks>
201        [DllImport("Kernel32.dll")]
202        public static extern uint GetTickCount();
203
204        /// <summary>
205        /// Retrieves information about the system's current usage of both physical
206        /// and virtual memory.
207        /// </summary>
208        /// <param name="lpBuffer">A pointer to a MEMORYSTATUSEX structure that
209        /// receives information about current memory availability.</param>
210        /// <returns>If the function succeeds, the return value is nonzero.
211        /// If the function fails, the return value is zero. To get extended
212        /// error information, call Marshal.GetLastWin32Error.</returns>
213        [DllImport("Kernel32.dll", SetLastError = true)]
214        [return: MarshalAs(UnmanagedType.Bool)]
215        public static extern bool GlobalMemoryStatusEx(ref MEMORYSTATUSEX lpBuffer);
216
217        /// <summary>
218        /// The QueryPerformanceCounter function retrieves the current value of
219        /// the high-resolution performance counter.
220        /// </summary>
221        /// <param name="lpPerformanceCount">[out] Pointer to a variable that receives
222        /// the current performance-counter value, in counts.</param>
223        /// <returns>If the function succeeds, the return value is nonzero.
224        ///
225        /// If the function fails, the return value is zero. To get extended error
226        /// information, call Marshal.GetLastWin32Error. </returns>
227        [DllImport("Kernel32.dll", SetLastError = true)]
228        [return: MarshalAs(UnmanagedType.Bool)]
229        public static extern bool QueryPerformanceCounter(out long lpPerformanceCount);
230
231        /// <summary>
232        /// Contains information about the current state of both physical and
233        /// virtual memory, including extended memory. The GlobalMemoryStatusEx
234        /// function stores information in this structure.
235        /// </summary>
236        [StructLayout(LayoutKind.Sequential)]
237        public struct MEMORYSTATUSEX
238        {
239            /// <summary>
240            /// The size of the structure, in bytes. You must set this member
241            /// before calling GlobalMemoryStatusEx.
242            /// </summary>
243            public uint dwLength;
244
245            /// <summary>
246            /// A number between 0 and 100 that specifies the approximate percentage
247            /// of physical memory that is in use (0 indicates no memory use and
248            /// 100 indicates full memory use).
249            /// </summary>
250            public uint dwMemoryLoad;
251
252            /// <summary>
253            /// The amount of actual physical memory, in bytes.
254            /// </summary>
255            public ulong ullTotalPhys;
256
257            /// <summary>
258            /// The amount of physical memory currently available, in bytes. This
259            /// is the amount of physical memory that can be immediately reused
260            /// without having to write its contents to disk first. It is the sum
261            /// of the size of the standby, free, and zero lists.
262            /// </summary>
263            public ulong ullAvailPhys;
264
265            /// <summary>
266            /// The current committed memory limit for the system or the current
267            /// process, whichever is smaller, in bytes. To get the system-wide
268            /// committed memory limit, call GetPerformanceInfo.
269            /// </summary>
270            public ulong ullTotalPageFile;
271
272            /// <summary>
273            /// The maximum amount of memory the current process can commit, in
274            /// bytes. This value is equal to or smaller than the system-wide
275            /// available commit value. To calculate the system-wide available
276            /// commit value, call GetPerformanceInfo and subtract the value of
277            /// CommitTotal from the value of CommitLimit.
278            /// </summary>
279            public ulong ullAvailPageFile;
280
281            /// <summary>
282            /// The size of the user-mode portion of the virtual address space of
283            /// the calling process, in bytes. This value depends on the type of
284            /// process, the type of processor, and the configuration of the
285            /// operating system. For example, this value is approximately 2 GB
286            /// for most 32-bit processes on an x86 processor and approximately
287            /// 3 GB for 32-bit processes that are large address aware running on
288            /// a system with 4-gigabyte tuning enabled.
289            /// </summary>
290            public ulong ullTotalVirtual;
291
292            /// <summary>
293            /// The amount of unreserved and uncommitted memory currently in the
294            /// user-mode portion of the virtual address space of the calling
295            /// process, in bytes.
296            /// </summary>
297            public ulong ullAvailVirtual;
298
299            /// <summary>
300            /// Reserved. This value is always 0.
301            /// </summary>
302            private ulong ullAvailExtendedVirtual;
303        }
304
305        /// <summary>
306        /// Contains information about the current computer system. This includes
307        /// the architecture and type of the processor, the number of processors
308        /// in the system, the page size, and other such information.
309        /// </summary>
310        [StructLayout(LayoutKind.Sequential)]
311        public struct SYSTEM_INFO
312        {
313            /// <summary>
314            /// Represents a list of processor architectures.
315            /// </summary>
316            public enum ProcessorArchitecture : ushort
317            {
318                /// <summary>
319                /// x64 (AMD or Intel).
320                /// </summary>
321                PROCESSOR_ARCHITECTURE_AMD64 = 9,
322
323                /// <summary>
324                /// Intel Itanium Processor Family (IPF).
325                /// </summary>
326                PROCESSOR_ARCHITECTURE_IA64 = 6,
327
328                /// <summary>
329                /// x86.
330                /// </summary>
331                PROCESSOR_ARCHITECTURE_INTEL = 0,
332
333                /// <summary>
334                /// Unknown architecture.
335                /// </summary>
336                PROCESSOR_ARCHITECTURE_UNKNOWN = 0xffff
337            }
338
339            /// <summary>
340            /// The processor architecture of the installed operating system.
341            /// This member can be one of the ProcessorArchitecture values.
342            /// </summary>
343            public ProcessorArchitecture processorArchitecture;
344
345            /// <summary>
346            /// This member is reserved for future use.
347            /// </summary>
348            private const ushort reserved = 0;
349
350            /// <summary>
351            /// The page size and the granularity of page protection and commitment.
352            /// This is the page size used by the VirtualAlloc function.
353            /// </summary>
354            public uint pageSize;
355
356            /// <summary>
357            /// A pointer to the lowest memory address accessible to applications
358            /// and dynamic-link libraries (DLLs).
359            /// </summary>
360            public IntPtr minimumApplicationAddress;
361
362            /// <summary>
363            /// A pointer to the highest memory address accessible to applications
364            /// and DLLs.
365            /// </summary>
366            public IntPtr maximumApplicationAddress;
367
368            /// <summary>
369            /// A mask representing the set of processors configured into the system.
370            /// Bit 0 is processor 0; bit 31 is processor 31.
371            /// </summary>
372            public IntPtr activeProcessorMask;
373
374            /// <summary>
375            /// The number of processors in the system.
376            /// </summary>
377            public uint numberOfProcessors;
378
379            /// <summary>
380            /// An obsolete member that is retained for compatibility. Use the
381            /// wProcessorArchitecture, wProcessorLevel, and wProcessorRevision
382            /// members to determine the type of processor.
383            /// Name                        Value
384            /// PROCESSOR_INTEL_386         386
385            /// PROCESSOR_INTEL_486         486
386            /// PROCESSOR_INTEL_PENTIUM     586
387            /// PROCESSOR_INTEL_IA64        2200
388            /// PROCESSOR_AMD_X8664         8664
389            /// </summary>
390            public uint processorType;
391
392            /// <summary>
393            /// The granularity for the starting address at which virtual memory
394            /// can be allocated. For more information, see VirtualAlloc.
395            /// </summary>
396            public uint allocationGranularity;
397
398            /// <summary>
399            /// The architecture-dependent processor level. It should be used only
400            /// for display purposes. To determine the feature set of a processor,
401            /// use the IsProcessorFeaturePresent function.
402            ///
403            /// If wProcessorArchitecture is PROCESSOR_ARCHITECTURE_INTEL, wProcessorLevel
404            /// is defined by the CPU vendor.
405            /// If wProcessorArchitecture is PROCESSOR_ARCHITECTURE_IA64, wProcessorLevel
406            /// is set to 1.
407            /// </summary>
408            public ushort processorLevel;
409
410            /// <summary>
411            /// The architecture-dependent processor revision. The following table
412            /// shows how the revision value is assembled for each type of
413            /// processor architecture.
414            ///
415            /// Processor                   Value
416            /// Intel Pentium, Cyrix        The high byte is the model and the
417            /// or NextGen 586              low byte is the stepping. For example,
418            ///                             if the value is xxyy, the model number
419            ///                             and stepping can be displayed as follows:
420            ///                             Model xx, Stepping yy
421            /// Intel 80386 or 80486        A value of the form xxyz.
422            ///                             If xx is equal to 0xFF, y - 0xA is the model
423            ///                             number, and z is the stepping identifier.
424            ///
425            ///                             If xx is not equal to 0xFF, xx + 'A'
426            ///                             is the stepping letter and yz is the minor stepping.
427            /// </summary>
428            public ushort processorRevision;
429        }
430
431        /// <summary>
432        /// Specifies the window station, desktop, standard handles, and appearance
433        /// of the main window for a process at creation time.
434        /// </summary>
435        [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
436        public struct STARTUPINFO
437        {
438            /// <summary>
439            /// The size of the structure, in bytes.
440            /// </summary>
441            private uint cb;
442
443            /// <summary>
444            /// Reserved; must be NULL.
445            /// </summary>
446            private readonly IntPtr lpReserved;
447
448            /// <summary>
449            /// The name of the desktop, or the name of both the desktop and window
450            /// station for this process. A backslash in the string indicates that
451            /// the string includes both the desktop and window station names.
452            /// For more information, see Thread Connection to a Desktop.
453            /// </summary>
454            public string lpDesktop;
455
456            /// <summary>
457            /// For console processes, this is the title displayed in the title
458            /// bar if a new console window is created. If NULL, the name of the
459            /// executable file is used as the window title instead. This parameter
460            /// must be NULL for GUI or console processes that do not create a
461            /// new console window.
462            /// </summary>
463            public string lpTitle;
464
465            /// <summary>
466            /// If dwFlags specifies STARTF_USEPOSITION, this member is the x
467            /// offset of the upper left corner of a window if a new window is
468            /// created, in pixels. Otherwise, this member is ignored.
469            ///
470            /// The offset is from the upper left corner of the screen. For GUI
471            /// processes, the specified position is used the first time the
472            /// new process calls CreateWindow to create an overlapped window
473            /// if the x parameter of CreateWindow is CW_USEDEFAULT.
474            /// </summary>
475            public int dwX;
476
477            /// <summary>
478            /// If dwFlags specifies STARTF_USEPOSITION, this member is the y
479            /// offset of the upper left corner of a window if a new window is
480            /// created, in pixels. Otherwise, this member is ignored.
481            ///
482            /// The offset is from the upper left corner of the screen. For GUI
483            /// processes, the specified position is used the first time the new
484            /// process calls CreateWindow to create an overlapped window if the
485            /// y parameter of CreateWindow is CW_USEDEFAULT.
486            /// </summary>
487            public int dwY;
488
489            /// <summary>
490            /// If dwFlags specifies STARTF_USESIZE, this member is the width of
491            /// the window if a new window is created, in pixels. Otherwise,
492            /// this member is ignored.
493            ///
494            /// For GUI processes, this is used only the first time the new process
495            /// calls CreateWindow to create an overlapped window if the nWidth
496            /// parameter of CreateWindow is CW_USEDEFAULT.
497            /// </summary>
498            public int dwXSize;
499
500            /// <summary>
501            /// If dwFlags specifies STARTF_USESIZE, this member is the height of
502            /// the window if a new window is created, in pixels. Otherwise, this
503            /// member is ignored.
504            ///
505            /// For GUI processes, this is used only the first time the new process
506            /// calls CreateWindow to create an overlapped window if the nHeight
507            /// parameter of CreateWindow is CW_USEDEFAULT.
508            /// </summary>
509            public int dwYSize;
510
511            /// <summary>
512            /// If dwFlags specifies STARTF_USECOUNTCHARS, if a new console window
513            /// is created in a console process, this member specifies the screen
514            /// buffer width, in character columns. Otherwise, this member is ignored.
515            /// </summary>
516            public int dwXCountChars;
517
518            /// <summary>
519            /// If dwFlags specifies STARTF_USECOUNTCHARS, if a new console window
520            /// is created in a console process, this member specifies the screen
521            /// buffer height, in character rows. Otherwise, this member is ignored.
522            /// </summary>
523            public int dwYCountChars;
524
525            /// <summary>
526            /// If dwFlags specifies STARTF_USEFILLATTRIBUTE, this member is the
527            /// initial text and background colors if a new console window is
528            /// created in a console application. Otherwise, this member is ignored.
529            ///
530            /// This value can be any combination of the following values:
531            /// FOREGROUND_BLUE, FOREGROUND_GREEN, FOREGROUND_RED, FOREGROUND_INTENSITY,
532            /// BACKGROUND_BLUE, BACKGROUND_GREEN, BACKGROUND_RED, and BACKGROUND_INTENSITY.
533            ///
534            /// For example, the following combination of values produces red text
535            /// on a white background:
536            ///     FOREGROUND_RED| BACKGROUND_RED| BACKGROUND_GREEN| BACKGROUND_BLUE
537            /// </summary>
538            public int dwFillAttribute;
539
540            /// <summary>
541            /// A bit field that determines whether certain STARTUPINFO members
542            /// are used when the process creates a window.
543            /// </summary>
544            public int dwFlags;
545
546            /// <summary>
547            /// If dwFlags specifies STARTF_USESHOWWINDOW, this member can be any
548            /// of the SW_ constants defined in Winuser.h. Otherwise, this member is ignored.
549            ///
550            /// For GUI processes, wShowWindow specifies the default value the
551            /// first time ShowWindow is called. The nCmdShow parameter of ShowWindow
552            /// is ignored. In subsequent calls to ShowWindow, the wShowWindow member
553            /// is used if the nCmdShow parameter of ShowWindow is set to SW_SHOWDEFAULT.
554            /// </summary>
555            public short wShowWindow;
556
557            /// <summary>
558            /// Reserved for use by the C Run-time; must be zero.
559            /// </summary>
560            private const short cbReserved2 = 0;
561
562            /// <summary>
563            /// Reserved for use by the C Run-time; must be NULL.
564            /// </summary>
565            private readonly IntPtr lpReserved2;
566
567            /// <summary>
568            /// If dwFlags specifies STARTF_USESTDHANDLES, this member is the
569            /// standard input handle for the process. Otherwise, this member is
570            /// ignored and the default for standard input is the keyboard buffer.
571            /// </summary>
572            public IntPtr hStdInput;
573
574            /// <summary>
575            /// If dwFlags specifies STARTF_USESTDHANDLES, this member is the
576            /// standard output handle for the process. Otherwise, this member is
577            /// ignored and the default for standard output is the console window's
578            /// buffer.
579            /// </summary>
580            public IntPtr hStdOutput;
581
582            /// <summary>
583            /// If dwFlags specifies STARTF_USESTDHANDLES, this member is the
584            /// standard error handle for the process. Otherwise, this member is
585            /// ignored and the default for standard error is the console window's
586            /// buffer.
587            /// </summary>
588            public IntPtr hStdError;
589        }
590
591        /// <summary>
592        /// Enables an application to inform the system that it is in use, thereby
593        /// preventing the system from entering sleep or turning off the display
594        /// while the application is running.
595        /// </summary>
596        /// <param name="esFlags">The thread's execution requirements. This parameter
597        /// can be one or more of the EXECUTION_STATE values.</param>
598        /// <returns>If the function succeeds, the return value is the previous
599        /// thread execution state.
600        ///
601        /// If the function fails, the return value is NULL.</returns>
602        /// <remarks>The system automatically detects activities such as local keyboard
603        /// or mouse input, server activity, and changing window focus. Activities
604        /// that are not automatically detected include disk or CPU activity and
605        /// video display.
606        ///
607        /// Calling SetThreadExecutionState without ES_CONTINUOUS simply resets
608        /// the idle timer; to keep the display or system in the working state,
609        /// the thread must call SetThreadExecutionState periodically.
610        ///
611        /// To run properly on a power-managed computer, applications such as fax
612        /// servers, answering machines, backup agents, and network management
613        /// applications must use both ES_SYSTEM_REQUIRED and ES_CONTINUOUS when
614        /// they process events. Multimedia applications, such as video players
615        /// and presentation applications, must use ES_DISPLAY_REQUIRED when they
616        /// display video for long periods of time without user input. Applications
617        /// such as word processors, spreadsheets, browsers, and games do not need
618        /// to call SetThreadExecutionState.
619        ///
620        /// The ES_AWAYMODE_REQUIRED value should be used only when absolutely
621        /// necessary by media applications that require the system to perform
622        /// background tasks such as recording television content or streaming media
623        /// to other devices while the system appears to be sleeping. Applications
624        /// that do not require critical background processing or that run on
625        /// portable computers should not enable away mode because it prevents
626        /// the system from conserving power by entering true sleep.
627        ///
628        /// To enable away mode, an application uses both ES_AWAYMODE_REQUIRED and
629        /// ES_CONTINUOUS; to disable away mode, an application calls
630        /// SetThreadExecutionState with ES_CONTINUOUS and clears
631        /// ES_AWAYMODE_REQUIRED. When away mode is enabled, any operation that
632        /// would put the computer to sleep puts it in away mode instead. The computer
633        /// appears to be sleeping while the system continues to perform tasks that
634        /// do not require user input. Away mode does not affect the sleep idle
635        /// timer; to prevent the system from entering sleep when the timer expires,
636        /// an application must also set the ES_SYSTEM_REQUIRED value.
637        ///
638        /// The SetThreadExecutionState function cannot be used to prevent the user
639        /// from putting the computer to sleep. Applications should respect that
640        /// the user expects a certain behavior when they close the lid on their
641        /// laptop or press the power button.
642        ///
643        /// This function does not stop the screen saver from executing.
644        /// </remarks>
645        [DllImport("Kernel32.dll")]
646        public static extern EXECUTION_STATE SetThreadExecutionState(EXECUTION_STATE esFlags);
647
648        /// <summary>
649        /// Execution state values to be used in conjuction with SetThreadExecutionState
650        /// </summary>
651        public enum EXECUTION_STATE : uint
652        {
653            /// <summary>
654            /// Enables away mode. This value must be specified with ES_CONTINUOUS.
655            ///
656            /// Away mode should be used only by media-recording and media-distribution
657            /// applications that must perform critical background processing on
658            /// desktop computers while the computer appears to be sleeping.
659            /// See remarks.
660            ///
661            /// Windows Server 2003 and Windows XP/2000: ES_AWAYMODE_REQUIRED is
662            /// not supported.
663            /// </summary>
664            ES_AWAYMODE_REQUIRED = 0x00000040,
665   
666            /// <summary>
667            /// Informs the system that the state being set should remain in effect
668            /// until the next call that uses ES_CONTINUOUS and one of the other
669            /// state flags is cleared.
670            /// </summary>
671            ES_CONTINUOUS = 0x80000000,
672
673            /// <summary>
674            /// Forces the display to be on by resetting the display idle timer.
675            /// </summary>
676            ES_DISPLAY_REQUIRED = 0x00000002,
677
678            /// <summary>
679            /// Forces the system to be in the working state by resetting the system
680            /// idle timer.
681            /// </summary>
682            ES_SYSTEM_REQUIRED = 0x00000001,
683   
684            /// <summary>
685            /// This value is not supported. If ES_USER_PRESENT is combined with
686            /// other esFlags values, the call will fail and none of the specified
687            /// states will be set.
688            ///
689            /// Windows Server 2003 and Windows XP/2000: Informs the system that a
690            /// user is present and resets the display and system idle timers.
691            /// ES_USER_PRESENT must be called with ES_CONTINUOUS.
692            /// </summary>
693            ES_USER_PRESENT = 0x00000004
694        }
695    }
696}
Note: See TracBrowser for help on using the repository browser.