Q How do I call a DLL or Win32® API function from my C# code if the function has a string (char*) output parameter? I can pass a string for an input parameter, but how do I get the returned string? Also, how do I call functions that require a struct or a callback, like GetWindowsRect and EnumWindows? I'm trying to convert from C++ and MFC, and I can't cope!
E. Nguyen
A One of the major benefits of Microsoft® .NET is that it provides a language-independent development system. You can write classes in Visual Basic®, C++, C#—whatever—and use them in other languages; you can even derive from classes in a different language. But what happens when you want to call some old-school unmanaged DLL? You have to somehow translate .NET objects into the structs, char*'s, and function pointers C expects. In techno lingo, your parameters must be marshaled. Marshaling is a big topic, but luckily you don't have to know much to get the job done.
To call a DLL function from C#, first you must provide a declaration, something programmers using Visual Basic have been doing for years. In C#, it's DllImport:
using System.Runtime.InteropServices; // DllImport
public class Win32 {
[DllImport("User32.Dll")]
public static extern void SetWindowText(int h, String s);
}
In C#, you use DllImport to tell the compiler where the entry point lives and bundle your wrapper functions inside a class. You can give this class any name you like; I chose Win32. You can even put the class inside a namespace, like I did in Figure 1. To compile Win32API.cs, type:
csc /t:library /out:Win32API.dll Win32API.cs
Now you have a Win32API.dll you can use in any C# project.
using Win32API;
int hwnd = // get it...
String s = "I'm so cute."
Win32.SetWindowText(hwnd, s);
The compiler knows to find SetWindowText in user32.dll and automatically converts your string to LPTSTR (TCHAR*) before calling. Amazing! How does .NET perform this magic? Every C# type has a default marshaling type. For strings, it's LPTSTR. But what happens if you try this for GetWindowText, where the string is an out parameter, not an in parameter? It doesn't work because strings are immutable. Really. You may not have noticed, but whenever you do something to a string, a new string is created. To modify the one and only actual string, you have to use StringBuilder:
using System.Text; // for StringBuilder
public class Win32 {
[DllImport("user32.dll")]
public static extern int GetWindowText(int hwnd,
StringBuilder buf, int nMaxCount);
}
The default marshaling type for StringBuilder is also LPTSTR, but now GetWindowText can modify your actual string.
int hwnd = // get it...
StringBuilder cb = new StringBuilder(256);
Win32.GetWindowText(hwnd, sb, sb.Capacity);
So the short answer to your first question is, use StringBuilder.
All that seems super, but what happens if the default marshaling type isn't what you want? For example, suppose you want to call GetClassName? Windows® gurus know that unlike most API functions, GetClassName takes LPSTR (char*), even in Unicode builds. If you pass a string, the common language runtime (CLR) will convert it to TCHARs—oops! Never fear, you can use MarshalAs to override the default:
[DllImport("user32.dll")]
public static extern int GetClassName(int hwnd,
[MarshalAs(UnmanagedType.LPStr)] StringBuilder buf,
int nMaxCount);
Now when you call GetClassName, .NET passes your string as an ANSI char, not a wide one. Whew!
So much for strings. What about structs and callbacks? As you might guess, .NET has a way to handle them, too. Take a simple sample, GetWindowRect. This function stuffs a RECT with a window's screen coordinates:
// in C/C++
RECT rc;
HWND hwnd = FindWindow("foo",NULL);
::GetWindowRect(hwnd, &rc);
How do you call GetWindowRect from C#? How do you pass the RECT? You do it as a C# struct, using another attribute, StructLayout.
[StructLayout(LayoutKind.Sequential)]
public struct RECT {
public int left;
public int top;
public int right;
public int bottom;
}
Once you have your struct defined, you can implement the wrapper like so:
[DllImport("user32.dll")]
public static extern int
GetWindowRect(int hwnd, ref RECT rc);
It's important to use ref so the CLR will pass your RECT as a reference so the function can modify your object, not a nameless stack copy. With GetWindowRect defined, you can call it like so:
RECT rc = new RECT();
int hwnd = // get it ...
Win32.GetWindowRect(hwnd, ref rc);
Note that you must use the ref in the call as well as the declaration—picky! The default marshaling type for C# structs is—what else?—LPStruct, so there's no need for MarshalAs. But if you made RECT a class instead of a struct, you'd have to implement the wrapper like this:
// if RECT is a class, not struct
[DllImport("user32.dll")]
public static extern int
GetWindowRect(int hwnd,
[MarshalAs(UnmanagedType.LPStruct)] RECT rc);
In C#, just like C++, there are lots of ways to do things. But System.Drawing already has a Rectangle struct for handling rectangles, so why reinvent the wheel?
[DllImport("user32.dll")]
public static extern int GetWindowRect(int hwnd, ref Rectangle rc);
The runtime already knows how to marshal a Rectangle as a Win32 RECT. Please note, however, that there's no need to call GetWindowRect (or Get/SetWindowText for that matter) in real code, since the Windows.Forms Control class has properties for this: Control.DisplayRectangle to get the window rectangle, and Control.Text to get or set the text.
Rectangle r = mywnd.DisplayRectangle;
mywnd.Text = "I'm so cute";
You only need the API wrappers I've shown if for some reason you only have an HWND, not a Control-derived object.
Strings, structs, Rectangles... what else? Oh yes, callbacks. How do you pass a callback from C# to unmanaged code? All you have to do is remember to say "delegate."
delegate bool EnumWindowsCB(int hwnd, int lparam);
Once you've declared your delegate/callback type, the wrapper goes like this:
[DllImport("user32")]
public static extern int
EnumWindows(EnumWindowsCB cb, int lparam);
Since the delegate line merely declares a delegate type, you have to provide an actual delegate in your class
// in your class
public static bool MyEWP(int hwnd, int lparam) {
// do something
return true;
}
then pass it to the wrapper like so:
EnumWindowsCB cb = new EnumWindowsCB(MyEWP);
Win32.EnumWindows(cb, 0);
Astute readers will notice I glossed over the problem of lparam. In C, if you give EnumWindows an LPARAM, Windows will notify your callback with it. Typically lparam is a pointer to some struct or class that contains context info that you need to do whatever it is you're doing. But remember, you can never say "pointer" in .NET! So what to do? In this case, you can declare your lparam as IntPtr and use a GCHandle to wrap it:
// lparam is IntPtr now
delegate bool EnumWindowsCB(int hwnd, IntPtr lparam);
// wrap object in GCHandle
MyClass obj = new MyClass();
GCHandle gch = GCHandle.Alloc(obj);
EnumWindowsCB cb = new EnumWindowsCB(MyEWP);
Win32.EnumWindows(cb, (IntPtr)gch);
gch.Free();
Don't forget to call Free when you're finished! Sometimes in C# you actually get to free your own memory, just like in the old days. To access the lparam "pointer" inside your enumerator, use GCHandle.Target.
public static bool MyEWP(int hwnd, IntPtr param) {
GCHandle gch = (GCHandle)param;
MyClass c = (MyClass)gch.Target;
// ... use it
return true;
}
Figure 2 shows a class I wrote that encapsulates EnumWindows in an array. Instead of fussing with delegates and callbacks, you can write the following:
WindowArray wins = new WindowArray();
foreach (int hwnd in wins) {
// do something
}
Pretty neat! Believe it or not, there's a method to all this madness. Everything makes sense once you get the hang of it. You can even use DllImport-style wrappers in managed C++. With .NET, you can move freely between managed and unmanaged worlds, as long as you do the proper translation. Most of the time you don't have to do anything; it just works. Occasionally, you need MarshalAs or a wrapper like GCHandle. For more on interop, read "Platform Invoke Tutorial" in the .NET documentation.
Figure 3 shows a little program I wrote. ListWin lists the top-level windows with switches so you can display HWNDs, class names, titles, and/or window rectangles, using RECT or Rectangle. Figure 4 shows a sample run. I stripped some of the code to save space here; as always, you can grab the full source from the link at the top of this article.
.gif)
Figure 4 ListWin Sample
Q I'm writing an app that backs up files to a network drive. My program works unless a user has Microsoft Outlook® open; then my program can't copy the mailbox file (mailbox.pst) because Outlook opens it with exclusive access. I want to be able to kill Outlook if it's running. How can I kill a process cleanly?
Jose Mercando
A A program called tskill.exe (see Figure 5) comes with newer versions of Windows and it does what you want.
.gif)
Figure 5 tskill
For example
tskill outlook
kills the running instance of Outlook. But if you want to write the code yourself, the safest way to kill a process is to post a WM_CLOSE message to its main window:
HWND hwnd = // get main window
PostMessage(hwnd, WM_CLOSE, 0, 0);
Once the message is posted, you usually should wait for the process to actually terminate:
HANDLE hp = OpenProcess(SYNCHRONIZE|PROCESS_TERMINATE,FALSE,pid);
WaitForSingleObject(hp, 5000); // wait up to 5 seconds
When the process terminates, it flips to the signaled state and WaitForSingleObject returns WAIT_OBJECT_0. If it returns something else, the process is either hung or still doing something. In that case, the only way to kill the process is to pull out the big bazooka, TerminateProcess.
if (WaitForSingleObject(hp, 5000) != WAIT_OBJECT_0)
TerminateProcess(hp,0); // Hasta la vista, baby!
If you want to be really nice, you can send the main window a WM_QUERYENDSESSION before you close. Apps receive this message when the user is about to end the session (log out) or when someone calls ExitWindows. Apps are suppose to prepare for imminent death. Typically this means presenting a dialog that says something like, "Um, pardon me, but the system is about to implode and if you want to save the last ten hours of changes you've made, this would be a good time; would you like to save now? (Yes/No/Cancel)." WM_QUERYENDSESSION can even reject death (for example if the user chooses Cancel), in which case life goes on. In code, it looks like this:
DWORD bOKToKill = FALSE;
SendMessageTimeout(hwnd, WM_QUERYENDSESSION, 0, 0,
SMTO_ABORTIFHUNG|SMTO_NOTIMEOUTIFNOTHUNG, 100, &bOKToKill);
if (bOKToKill) {
// post WM_CLOSE and wait, etc.
}
It's important to use SendMessageTimeout, not SendMessage, in case the process you're trying to close is hung. SMTO_NOTIMEOUTIFNOTHUNG is a flag that's only available in Windows 2000 and Windows XP that says, "don't timeout if the thread isn't hung." In other words, if the thread is processing normally then wait forever so the user can read the dialog and decide what to do. When the user makes his or her final decision, SendMessageTimeout will return with bOKToKill set appropriately. Naturally, all this assumes the other apps are well-behaved and process WM_QUERYENDSESSION as they're supposed to, which isn't always the case.
I wrote a program, kp.exe (see Figure 6), to kill a process just like tskill. It uses a class CFindKillProcess (see Figure 7) to find and kill the process:
CFindKillProcess fkp;
DWORD pid = fkp.FindProcess("outlook.exe");
fkp.KillProcess(pid);
FindProcess uses CProcessIterator and CProcessModuleIterator from last month's column to iterate the processes, looking for one whose first module (the EXE that started the process) matches the one you want to find:
CProcessIterator itp;
for (DWORD pid=itp.First(); pid; pid=itp.Next()) {
CProcessModuleIterator itm(pid);
HMODULE hModule = itm.First(); // .EXE
if (/* module name = what I'm looking for */) {
return pid;
}
}
FindProcess looks for "foo" or "foo.exe." If it finds the process, it returns the process ID, which you can then pass to CFindKillProcess::KillProcess. KillProcess encapsulates the close window/terminate logic I just sketched. It uses CMainWindowIterator from last month's column to iterate the main windows of the process (there can be more than one), posts a WM_CLOSE to each, then waits for the process to die. It has a BOOLean parameter that says whether to use TerminateProcess if the app doesn't die willingly. For details, see Figure 7.
Send questions and comments for Paul to cppqa@microsoft.com. |