(MASM x86) In assembly, what is the difference between heap handle and pointer to the heap?

I actually have two questions that are somewhat connected.

1. In assembly, what is the difference between heap handle and pointer to the heap?
2. Can the heap handle be determined from the pointer to the heap?

The Windows functions I am using are:

• GetProcessHeap
• HeapAlloc
• HeapFree

I am using the Irvine32 library, and Visual Studio 2022 as my IDE. Here is the code I will be using to talk about the questions:

; main.asm
INCLUDE Irvine32.inc
.386
.model flat, stdcall
.stack 4096
ExitProcess PROTO, dwExitCode: DWORD
.data
testString BYTE "HELLO", 0
.code
main PROC
MOV esi, OFFSET testString
CALL StringHeapAlloc
INVOKE ExitProcess, 0
main ENDP
; --------------------------------------------------------------------
; StringHeapAlloc
;
; This function will allocate memory in the heap and copy, a given
; string, into the allocated memory location.
; RECEIVES: ESI
; RETURNS:  EAX contains the heap handle;
;			EBX contains the array address
; REQUIRES: ESI contains the address to the string being copied
; --------------------------------------------------------------------
StringHeapAlloc PROC USES esi
.data
MAX_STRING_SIZE = 20
; Dynamic Memory Information
hHandle DWORD ?				; contains the heap handle
pHeap DWORD ?				; contains the pointer to the memory allocated
dwFlag DWORD HEAP_ZERO_MEMORY		; contains the flags for allocating memory
dwByte DWORD MAX_STRING_SIZE + 1	; contains the number of bytes to allocate
.code
; gets heap handle for heap allocation
INVOKE GetProcessHeap
MOV hHandle, eax			; storing heap handle
; allocates memory in the heap for the string
INVOKE HeapAlloc, hHandle, dwFlag, dwByte
MOV pHeap, eax				; storing pointer to array
; copies string into the allocated memory
INVOKE Str_copy, esi, pHeap
; returning heap handle and pointer to handle
MOV eax, hHandle
MOV ebx, pHeap
RET
StringHeapAlloc ENDP
END main

Q1

In assembly, the method of dynamic memory allocation I am using is:

1. Use GetProcessHeap to generate a heap handle.
2. Allocate memory using HeapAlloc. (this step will give me a pointer to the heap)
3. Do something with the memory.
4. Free the memory using HeapFree.

I understand that the pointer to the heap is just the address to a specific memory location that was allocated. I do not quite understand what the heap handle is. I did a bit of investigation using VS debugger, and found that:

• When GetProcessHeap is executed, it returns the heap handle to the EAX register.
  After GetProcessHeap is executed.

• When HeapAlloc is executed, it returns the pointer to the heap to the EAX register.
  After HeapAlloc is executed.

The heap handle is 006E0000. The pointer to the heap is 006E6568. I noticed that the heap handle seems to be within the pointer to the heap every time I ran the code. If we were thinking of this analogously, is the heap handle like a street with houses that have addresses 19000, and the pointer to the heaps like the addresses to the residents on that street (19000, 19001, etc.)?

Q2

Can I always derive the heap handle from the pointer to the heap? In the example, where I ran the code, the heap handle was 006E0000 and the pointer to the heap was 006E6568. Is the heap handle always the first 4 bytes in the pointer to the heap?

To free the memory, I would need to use HeapFree. However, that function requires that I have the heap handle and pointer to the heap. Right now, every time I dynamically allocate memory, I store the heap handles in an array containing heap handles and the pointers to the heap to an array containing pointers. If the heap handle can be derived then I could get rid of that extra array to store heap handles.

Edit: Changed EDX to ESI in the main function. The offset of testString should be stored in ESI for StringHeapAlloc to work.

Edit: Completed documentation of StringHeapAlloc function and added "MOV eax, hHandle" and "MOV ebx, pHeap" at end of StringHeapAlloc function. It should not affect the original questions.

Handles of all kinds are just values. They can be pointers but in some cases are just integers. (Pointers are generally [preferred because they allow different types of handles to type-differentiate in languages that have the concept of type - like C).

The point of the above is that you do not worry about what sort of structure backs a pointer. It is simply a value stored by the calling code and understood by the called code.

Note that most windows handles are of the form

struct HNAME__ { int unused };
typedef HNAME__ * HNAME;

but you never use the 'HNAME__' struct, you simply use the HNAME value the API hands you.