What is hInstance

[Robert Husted]

Hi to all I have a few questions. There from Iczlion's tutorial 3

1)what is the deal with

               WinMain proto :DWORD,:DWORD,:DWORD,:DWORD,:
dose DWORD tell the amount of mem space alotted to what ever paramiter u put there?

2) What is hInstance and LPSTR

3) and how dose this work......WinMain proc hInst:HINSTANCE,hPrevInst:HINSTANCE,CmdLine:LPSTR,CmdShow:DWORD

well hope some one can help. I'll read tutorial 3 again, usually the 3rd time I get it.
           

[hutch--]

Robert,

The "instance" handle is returned by the operating system using the API call GetModuleHandle(). The handle is a DWORD value that contains the actual start address in memory of the EXE or DLL file. It is used by other API calls when specific information is required and the example is resource style API calls like LoadIcon() and similar that have the icon resource within the resource section of the EXE or DLL file.

By providing the Instance handle, the API call that uses it knws where to find the resource it is looking for.

The line you are asking about is a procedure entry and what makes it look different is it uses the C style of parameters instead of the native data sizes. They are converted in WINDOWS.INC with a set of equates. Each is DWORD in size.


WinMain proto :DWORD,:DWORD,:DWORD,:DWORD


This is the PROTOTYPE for the WinMain procedure and you are correct, each paraeter is DWORD in SIZE. The PROTOTYPE tells the assembler how big and how many parameters are used for the procedure.

The 4 arguments are a left over from old 16 bit Windows and most of them are not used any longer.


hInst:HINSTANCE              ; instance handle
hPrevInst:HINSTANCE        ; unused in 32 bit code
CmdLine:LPSTR                 ; not normally needed and can be obtained other ways
CmdShow:DWORD            ; not normally used.

[Robert Husted]

Thanks hutch the hInstance is still a bit hard to understand but the other two are real close to clear THANK YOU!!!!!!!!!!!!!!!

[hutch--]

Robert,

The instance handle is a bit lower level in that its a direct address. The hInstance for an EXE file is almost always 400000h but with a DLL it can be at different locations in memory depending on what is loaded. The address of a DLL is subject to what is called "re-location" so that it does not clash with other DLLs loaded in the same memory space.

You don't really have to worry about it at the moment, when you have time to play with PE file formats, you will get this stuff quick enough. At an application level, you get the instance handle from the GetModulehandle() API, usually store it as a global value in the .DATA? section and use it for API functions that require the instance handle.

[Robert Collins]

Is not the hInstance just the same as the hWnd? I always thought that whenever you launch an application you are in essense launching an 'instance' of that application and also that hPrevInstance was used to inform you wheather or not another instance of your application is running.

If hPrevInstance is not used in Win32 then how does one find out if there is another running instance of your application?

[pbrennick]

hInstance is the handle to the application or instance, hWnd is the handle to the window.  hInstance is usually obtained in the first 2 or three lines are the declaration of the code section (.code) and hWnd is obtained as the return value when the window is created just after you register its class (in the WinMain section or any other procedure used to register the class).

Paul

[Robert Collins]

hInstance is the handle to the application or instance, hWnd is the hadle to the window.  hInstance is usually obtained in the first 2 or three lines are the declaration of the code section (.code) and hWnd is obtained as the return value when the window is created just after you register its class (in the WinMain section).

Paul

OK, so if I have both the hInstance and the hWnd and I want to perform some API for example that requires the 'handle' then I must use 'hWnd' and not 'hInstance'. Is this correct?

Also, do you know about the 2nd question 'hPrevInstance' and determining if there is another instance of your application running?

[pbrennick]

Robert,

This is from the API (I searched and found this in WinMain's Details):

hPrevInstance

Identifies the previous instance of the application. For a Win32-based application, this parameter is always NULL. If you need to detect whether another instance already exists, create a named mutex using the CreateMutex function. If the GetLastError function returns ERROR_ALREADY_EXISTS, another instance of your application exists (it created the mutex).

AS you can see, in Win32 applications, it is always NULL.  I have read in other literature that it is always unreferenced and should not be used.  So, always NULL, okay?
Paul

[hutch--]

Paul is right here, if an application has a window, it will have a window handle but every application has a load address and that is the instance handle. The early examples in MASM32, both Iczelion's and my own constructed a WinMain but this is done in the program by calling the correct API functions first. Apart from familiarity for programmers back then, there is no point in constructing a WinMain.

Now the Microsoft API documentation does specify what type of handle it requires so it is a matter of using the correct handle that the API requires.

[donkey]

To understand exactly what hInstance is you have to understand a bit of the history of Windows, in particular the architecture of Win16. In Win16 the hModule and hInstance handles were very different, that's because every program ran in the same memory space. So if you had 2 programs using the same DLL Win16 would load it once and both would access that single memory location. This creates a problem however, since you need to keep some variables separate. Enter hInstance and hModule, the module handle was a pointer to a structure that described the actual DLL (ie code segment descriptors etc..), the instance handle was a pointer to your applications set of data. So, a program in Win16 would only have one module handle even if there were 5 instances of it running at the same time, each of the 5 would have different instance handles however. When Win32, with protected mode, came along each program now resided in it's own memory space and instance handles were now deprecated. However there were certain Win16 functions that were ported to Win32 like ShellExecute and WinExec that required an instance handle, so the good folks at Microsoft came up with a solution. Make both of them point to the base address of the executable within it's own memory space, this works since under the flat memory model data is mapped directly into the processes memory space, no segments to worry about. So you can absolutely say that hInstance is always the exact same as hModule, as for hPrevInstance, well, since that no longer applies to Win32 it will always be 0, as far as the current process is concerned it is the only instance of the current module that is running. Since typing is not strict in assembly the two are interchangeable, hInstance == hModule. :)

[tenkey]

OK, so if I have both the hInstance and the hWnd and I want to perform some API for example that requires the 'handle' then I must use 'hWnd' and not 'hInstance'. Is this correct?

No, you never use just a "handle". Each handle has a type - it can be a file handle, a window handle, a GDI object handle, a process handle, and some others. Controls and dialogs are windows, so their handles can be used as window handles. But a window handle is not a process handle, nor is it an instance/module handle.