From a6f2b7dab1f4efde7952e8b8ee3f3f50bcf63753 Mon Sep 17 00:00:00 2001 From: Andreas Baumann Date: Sat, 28 Mar 2009 11:30:43 +0100 Subject: added documentation about console handling in the service --- docs/service/console_event_handling.txt | 320 ++++++++++++++++++++++++++++++++ 1 file changed, 320 insertions(+) create mode 100644 docs/service/console_event_handling.txt (limited to 'docs') diff --git a/docs/service/console_event_handling.txt b/docs/service/console_event_handling.txt new file mode 100644 index 0000000..2944ed1 --- /dev/null +++ b/docs/service/console_event_handling.txt @@ -0,0 +1,320 @@ + +Introduction + + Everyone programs console applications one time or the other. This + programming is more prevalent when people are learning to program, + especially while learning the DOS based C/C++ programming. However, + when one migrates to Windows programming, console application + development takes a back seat. But the Win32 console development holds + an important place, especially when the Win32 API contains a good + amount of API dedicated to console application development. If you have + noticed, even VC++, and latest development technologies like C#, also + supports console project development. Console applications are good + candidates for testing the core functionality of your Windows + application without the unnecessary overhead of a GUI. + + But there's always been a sense of helplessness in regard to how to + know when certain system related events have occurred, like when user + if logging off, or the system is being shutdown, or handling + control+break or control+C keyboard events, etc. For a Windows based + application, getting to know when such events occur is no problem since + they are having a message queue assigned to them that is polled, and + assuming that the concerned event is programmed for, it can be handled + pretty easily. But this isn't the case with a console application that + has no concept of a message queue. + + This article intends to discuss how you can handle all kinds of + console-based events in any console application. Once you have gone + through it, you will see for yourself how trivial this seemingly + helpless task is :) + +Setting Console Traps + + The first step in handling console application events is to setup an + even trap, technically referred to as installing an event handler. For + this purpose, we utilize the SetConsoleCtrlHandler Win32 API that is + prototyped as shown below: + [minus.gif] Collapse +BOOL SetConsoleCtrlHandler( + PHANDLER_ROUTINE HandlerRoutine, // handler function + + BOOL Add // add or remove handler + + ); + + The HandlerRoutine parameter is a pointer to a function that has the + following prototype: + [minus.gif] Collapse +BOOL WINAPI HandlerRoutine( + DWORD dwCtrlType // control signal type + +); + + All the HandlerRoutine takes is a DWORD parameter that tells what + console event has taken place. The parameter can take the following + values: + * CTRL_C_EVENT - occurs when the user presses CTRL+C, or when it is + sent by the GenerateConsoleCtrlEvent API. + * CTRL_BREAK_EVENT - occurs when the user presses CTRL+BREAK, or when + it is sent by the GenerateConsoleCtrlEvent API. + * CTRL_CLOSE_EVENT - occurs when attempt is made to close the + console, when the system sends the close signal to all processes + associated with a given console. + * CTRL_LOGOFF_EVENT - occurs when the user is logging off. One cannot + determine, however, which user is logging off. + * CTRL_SHUTDOWN_EVENT - occurs when the system is being shutdown, and + is typically sent to services. + + Upon receiving the event, the HandlerRoutine can either choose to do + some processing, or ignore the event. If the routine chooses not to + handle the event, it should return FALSE, and the system shall then + proceed to the next installed handler. But incase the routine does + handle the event, it should then return TRUE, after doing all the + processing it requires. The CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT and + CTRL_SHUTDOWN_EVENT are typically used to perform any cleanup that is + required by the application, and then call the ExitProcess API. Thus, + the system has has some timeouts associated with these three events, + which is 5 seconds for CTRL_CLOSE_EVENT, and 20 seconds for the other + two. If the process doesn't respond within the timeout period, Windows + shall then proceed to display the End Task dialog box to the user. If + the user proceeds to end the task, then the application will not have + any opportunity to perform cleanup. Thus, any cleanup that is required + should complete well within the timeout period. Below is an + exemplification of the handler routine: + [minus.gif] Collapse +BOOL WINAPI ConsoleHandler(DWORD CEvent) +{ + char mesg[128]; + + switch(CEvent) + { + case CTRL_C_EVENT: + MessageBox(NULL, + "CTRL+C received!","CEvent",MB_OK); + break; + case CTRL_BREAK_EVENT: + MessageBox(NULL, + "CTRL+BREAK received!","CEvent",MB_OK); + break; + case CTRL_CLOSE_EVENT: + MessageBox(NULL, + "Program being closed!","CEvent",MB_OK); + break; + case CTRL_LOGOFF_EVENT: + MessageBox(NULL, + "User is logging off!","CEvent",MB_OK); + break; + case CTRL_SHUTDOWN_EVENT: + MessageBox(NULL, + "User is logging off!","CEvent",MB_OK); + break; + + } + return TRUE; +} + + Now that we have seen how the handler routine works, lets see how to + install the handler. To do so, as mentioned earlier in the article, we + use the SetConsoleCtrlHandler API as shown below: + [minus.gif] Collapse +if (SetConsoleCtrlHandler( + (PHANDLER_ROUTINE)ConsoleHandler,TRUE)==FALSE) +{ + // unable to install handler... + + // display message to the user + + printf("Unable to install handler!\n"); + return -1; +} + + The first parameter is a function pointer of the type PHANDLER_ROUTINE, + whose prototype has been discussed earlier. The second parameter, if + set to TRUE, tries installing the handler, and if set to FALSE, + attempts the un-installation. If either attempts are successful, the + return value is TRUE. Otherwise FALSE is returned. + + So, that's all there is to handling the console application events. + After handler is installed, your application will receive the events as + and by they come, and when the execution is about to be terminated, the + handler maybe un-installed. Pretty easy, eh :) ? + +License + + This article has no explicit license attached to it but may contain + usage terms in the article text or the download files themselves. If in + doubt please contact the author via the discussion board below. + + A list of licenses authors might use can be found [232]here + +About the Author + + [233]Kumar Gaurav Khanna + + I hold Early Acheiver in MCSE 2000, MCSE NT 4.0, MCP+I, and actively + involved in programming using C/C++, .NET framework, C#, Win32 API, VB, + ASP and MFC. + I also have various publications to my credit at MSDN Online Peer + Journal, Windows Developer Journal (http://www.wdj.com/), Developer 2.0 + (http://www.developer2.com/), and PC Quest (http://www.pcquest.com/). + Occupation: Web Developer + Location: United States United States + +Other popular Win32/64 SDK & OS articles: + + * [234]Lock Windows Desktop + Restricting Windows access by hiding desktop windows and disabling + special keys. + * [235]Win32++: A Simple Alternative to MFC + A simple Windows Framework that beginners and intermediate + programmers can use as an alternative to MFC. It makes learning to + program for Windows easier. + * [236]Use member functions for C-style callbacks and threads - a + general solution + The article shows a general solution to redirect any C-style + callback into a member function using adapter objects + * [237]Windows 2000 Junction Points + Explains how reparse points are used to create filesystem links + * [238]Message Cracker Wizard for Win32 SDK Developers + A ClassWizard-like helper tool for using WINDOWSX.H message + crackers. + + IFRAME: [239]console_event_handling.aspx_files/ServeHTML_002.html + + [240]Article Top + [241]Sign Up to vote for this article + Your reason for this vote: + ____________________________________________________________ + ____________________________________________________________ + ____________________________________________________________ + ____________________________________________________________ + ____________________________________________________________ + + IFRAME: [242]console_event_handling.aspx_files/ServeLinks.html + + You must [243]Sign In to use this message board. + FAQ [244]FAQ Noise Tolerance[Medium...] Search [245]Search Messages + Set Options + Layout[Normal...............] Per page[25] + Msgs 1 to 11 of 11 (Total in Forum: 11) ([246]Refresh) FirstPrevNext + General [247]Lock computer member [248]Deepak Kumar Singh 3:04 7 Dec + '04 + Hi! + Good article. In case we want to handle the event of user locking the + computer (Ctl+Alt+DEL then 'Lock Computer') then how do we do that? + Lets say my application is a windows service! + Thanks, + Deepak + [249]Sign In·[250]View Thread·[251]PermaLink + General [252]Re: Lock computer member [253]Deepak Kumar Singh 20:13 7 + Dec '04 + Hi! + I got the answer my self. Unless you are really working with console + based applications, you should rather work with 'Winlogon Notification + Packages'. But they are not supported on Win NT and lower. + For more info see: + [254]http://msdn.microsoft.com/library/default.asp?url=/library/en-us/s + ecauthn/security/winlogon_notification_packages.asp[[255]^] + -- Deepak + [256]Sign In·[257]View Thread·[258]PermaLink + General [259]Nice, but ... suss Anonymous 16:12 9 Apr '03 + it only works if a console window exists. If you use it within a gui + application, you won't receive any messages. Furthermore it does not + work with Win95/98 and WinME. Or did anyone made other experiences? + [260]Sign In·[261]View Thread·[262]PermaLink 1.00/5 (2 votes) + General [263]MessageBox member [264]Sarwan Aggarwal 17:18 27 Aug '03 + Hi: + I like that MessageBox example code: + int MessageBox(0, char *msg, char *title, int type); + Which header do I include? My VC++ 6.0 does not recognize + MessageBox(). + Thanks. + Sarwan + Sarwan K. Aggarwal + [265]Sign In·[266]View Thread·[267]PermaLink + General [268]Re: MessageBox member [269]yjip 0:26 15 Nov '03 + you can look msdn ,that there are information sdk very much! + if you not see ,you can keep in touch with me my emailaddress : + 4915259@163.com + ok + yjip + [270]Sign In·[271]View Thread·[272]PermaLink + General [273]How can I pass control-break to console application? + member [274]Slimer 23:42 30 Mar '03 + How can I pass control-break to console application? + [275]Sign In·[276]View Thread·[277]PermaLink 1.50/5 (2 votes) + General [278]Argh! suss Anonymous 20:34 18 Feb '03 + Alright, the author mentions that when the program is about to be + closed, the handler is unisntalled... This may have something to do + with an issue I'm having... + I have a program that uses AllocConsole() to get a console. Most of the + entire program is all WinAPI, and the console is only used for quickly + adding large amounts of data. So I launch my app, it spawns a console, + the console is made into a child window... Now, if you click close, the + whole app goes down. Ctrl-C and the same... + I installed an insane amount of message handlers before learning about + the Console Control Handler. (Duh!)... Now that I'm using the control + handler to try and trap the events, the Ctrl-C problem is taken care + of. But no matter what, whenever you close it, the whole program goes + down. How do you stop this? I'd prefer the console just get freed + instead of killing the whole app! + Dead + [279]Sign In·[280]View Thread·[281]PermaLink 3.43/5 (4 votes) + General [282]Re: Argh! suss Anonymous 0:58 4 May '04 + in each of the console event handlers, you could call FreeConsole(), + This seemed to work for me, the only thing was there was a slight delay + between the close button being clicked and the console window being + destroyed. + [283]Sign In·[284]View Thread·[285]PermaLink 2.00/5 (1 vote) + General [286]how can i get the source code! suss Anonymous 23:26 14 Nov + '02 + This is a wonderful article but how can I get the source code. I + download it but I can not unzip it.Kindly send me the code. Thanks. + [287]Sign In·[288]View Thread·[289]PermaLink 1.00/5 (1 vote) + General [290]Sameple code Re: how can i get the source code! member + [291]SMuddasu 9:29 15 Nov '02 + BOOL CtrlHandler(DWORD fdwCtrlType) + { + switch (fdwCtrlType) + { + // Handle the CTRL+C signal. + case CTRL_C_EVENT: + Beep(1000, 1000); + return TRUE; + // CTRL+CLOSE: confirm that the user wants to exit. + case CTRL_CLOSE_EVENT: + return TRUE; + // Pass other signals to the next handler. + case CTRL_BREAK_EVENT: + case CTRL_LOGOFF_EVENT: + case CTRL_SHUTDOWN_EVENT: + default: + return FALSE; + } + } + void main(void) + { + BOOL fSuccess; + fSuccess = SetConsoleCtrlHandler( + (PHANDLER_ROUTINE) CtrlHandler, // handler function + TRUE); // add to list + if (! fSuccess) + cout << "Could not set control handler"); + } + Sagar + [292]Sign In·[293]View Thread·[294]PermaLink 1.25/5 (3 votes) + General [295]Where is the Source gone? member [296]silliconXP 18:14 31 + May '02 + This is a very good posting.it can even be better with the source + code.kindly to send me. + [297]Sign In·[298]View Thread·[299]PermaLink 3.11/5 (12 votes) + Last Visit: 5:35 27 Mar '09 Last Update: 5:35 27 Mar '09 + + General General News News Question Question Answer Answer + Joke Joke Rant Rant Admin Admin + [300]PermaLink | [301]Privacy | [302]Terms of Use + Last Updated: 29 May 2002 + Editor: [303]Nishant Sivakumar + Copyright 2002 by Kumar Gaurav Khanna + Everything else Copyright © [304]CodeProject, 1999-2009 + Web13 | [305]Advertise on the Code Project -- cgit v1.2.3-54-g00ecf