Windows API32 documentation

[RuiLoureiro]

Hi all

   I have the help file Win32 Programmer's reference. I read some topics. I didn't read it deeply. However, I noticed, in some cases, it seems to be «sheets of poems». In this way, i can say «its not a good programming tool» because I think that a good programming tool is a set of good data\variable structures and a good set of procedures to lead with it, a good organization, good documentation and a good assembler with a good documentation, too.It is my particular opinion, of course. I respect other opinions.
   For example, i looked for memory management functions. I found GlobalAlloc, GlobalLock, GlobalHandle, GlobalFree, etc. To simplify, we can say that this functions can be seen in the format «output FUNCTIONNAME(input1, input2,...)» the output and inputs can have «the size of a train!»- it doesn't matter, to understand the essencial.

Thereafter [ ] means my comments and « » parts of documentation.

«A process can use the GlobalAlloc and LocalAlloc to allocate memory. In ... Win32 API, the local heap = the global heap. ... there is no difference between the memory objects allocated by these functions»

[I cut words without meaning. eg: its raining and it is wet. Rain imply wet ]

We can see(the essencial):
[In all cases: «If the function fails, the return value is NULL»]
--------------------------------------------------------------------------------
HGLOBAL GlobalHandle( pMem )

pMem = Points to the first byte of the global memory block. This pointer is returned by the GlobalLock function.

[This seems (should) to be: This pointer is returned by the GlobalLock [or GlobalAlloc if uFlags= GMEM_FIXED ] ... and  points to the first byte of the global memory block. Its is a conversion function.].

Return Values: ...is the handle of the specified global memory.

«GlobalLock: handle into a pointer [and ???]; GlobalHandle: the pointer back into a handle».
--------------------------------------------------------------------------------
LPVOID GlobalLock( hMem )
Return Values: ...is a pointer to the first byte of the memory block

«with the GMEM_FIXED flag ... the value of the returned pointer is equal to the value of the specified handle».[So, hMem = pMem if uFlags= GMEM_FIXED]

«...locks a global memory ... returns a pointer to the first byte ... The memory block ... cannot be moved or discarded»
--------------------------------------------------------------------------------
HGLOBAL GlobalAlloc( uFlags, dwBytes)

«dwBytes= number of bytes to allocate»
uFlags= GMEM_FIXED     fixed memory.
      = GMEM_MOVEABLE  moveable memory. The return value is a pointer to the
      memory block [sometimes is block, sometimes is object.]
        «This flag cannot be combined with the GMEM_FIXED» [ => obviously
         ! one thing is fixed or movable. It cannot be both, unless ... !].
      «return value is the handle».«32-bit private to the calling process»
      «Translate handle into pointer, use the GlobalLock»
      = GPTR  [ GMEM_FIXED and GMEM_ZEROINIT ]
      = GHND  [ GMEM_MOVEABLE and GMEM_ZEROINIT ]
               «GMEM_ZEROINIT = initializes memory contents to zero»

[uFlags=GMEM_FIXED =>] Allocates fixed memory. The return value is a pointer to the memory block. To access the memory, the calling process simply casts the return value to a pointer.

Return Values: ...is the handle of ... allocated memory.
--------------------------------------------------------------------------------
HGLOBAL GlobalFree( hMem )

[hMem = ...This handle is returned by either the GlobalAlloc or GlobalReAlloc]
--------------------------------------------------------------------------------
Conclusion: confused !

Has anyboby a good Win32 programmer´s reference about this issue ?
Best regards

[Vortex]

I have the help file Win32 Programmer's reference. I read some topics. I didn't read it deeply. However, I noticed, in some cases, it seems to be «sheets of poems». In this way, i can say «its not a good programming tool» because I think that a good programming tool is a set of good data\variable structures and a good set of procedures to lead with it, a good organization, good documentation and a good assembler with a good documentation

RuiLoureiro,

The architecture of windows is complicated,so you can't expect a win32 reference documenting all the functions in a simple way. There are a lot of topics related to win32 programming, you should study them step by step. Don't hesitate to post your questions, there will be peoples ready to help you.

[RuiLoureiro]

Hi
   Vortex,

   What are all functions to allocate system memmory ? What they return ?
   Can we call GlobalAlloc with uFlags = GMEM_DISCARDABLE ?

Regards

[Vortex]

Hi RuiLoureiro,

You shoudl be carefull with the flag GMEM_DISCARDABLE. Quote from win32.hlp

GMEM_DISCARDABLE   Allocates discardable memory. This flag cannot be combined with the GMEM_FIXED flag. Some Win32-based applications may ignore this flag.

As you mentioned, GlobalAlloc can be used to allocate memory. There are also the HeapAlloc and VirtualAlloc functions for memory allocation.

[RuiLoureiro]

Hi Vortex
    Whats the difference between GlobalAlloc and LocalAlloc if the heap is the same ?


Regards

[Vortex]

Hi RuiLoureiro,

Quote from Win32.hlp

The LocalAlloc function allocates the specified number of bytes from the heap. In the linear Win32 API environment, there is no difference between the local heap and the global heap.

[hutch--]

RuiLoureiro,

You can go to the forum web site and get the reference material yourself. Just check the top right corner of the forum for the link. This means you will have the reference material on your local machine which is much faster to work with. This way when members help you out, you have the reference to use it properly.

[roticv]

f0dder's point of view would be that LocalAlloc/GlobalAlloc is bad and it is better to use HeapAlloc.  :toothy http://f0dder.schwump.net/memalloc.htm

[hutch--]

For all of the "hoo hah" GlobalAlloc using the fixed memory flag allocates so fast you cannot get a timing on it. Any of the other flags are out of date as they represent technology that is a left over from 16 bit Windows.

GlobalAlloc comfortably handles memory allocation well over the 1 gigabyte mark and it does that just as fast so there is no general rule that excludes it in performance terms.

When you need large quantities of small allocations, it is very had to go past OLE string memory as it is designed to do exactly that from a preallocated string pool. It is designed and used by the operating system for UNICODE display so it needs to be both fast and flexible.

Windows has multiple strategies for allocating memory and this is exactly the reason why general reductionist theories are of no real use in code design, you effectively dial in what you need on the basis of the task you are going to perform, not on some second hand opinion that does not have the technical backing of the operating system.

[raymond]

RuiLoureiro

Don't despair. My first impressions when I started with Win32 was that this Reference material was written in hieroglyphs!!! :bdg After a while, you will learn to read only what is essential.

You must realize that it was written primarily for C/C++ programmers which is the base language for MS. In assembly, there is no need to "cast" a handle to a pointer. :tdown

Raymond

[RuiLoureiro]

Hi
   Thank you Vortex, Roticv and Raymond !

   A special thanks to Mr. Steeve Hutch ( --sson ) to your topic about the links on the top right corner and the information that otherwise i couldn't get easier. I am not only new in forums ( this is the first ), also in debates [and some day, i shall go to present my candidature to write something that looks like good in my english! ] It's not easy ! As my name indicate, i usually write in portuguese. When i write in the present tense something that is obvious it belongs to the past or so, you must use an appropriate translator.

   Hey, raymond, about Win32 Reference i found out! They demummify it elsewhere.
It´s the true reason! (Ah! Ah! Ah!)

   Seriously, the question about memory allocation is an intriguing one. They give information for a set of functions GlobalZZZZ and for a set LocalZZZZ. And they says: «A process can use the GlobalAlloc and LocalAlloc to allocate memory. In Win32 API, the local heap = the global heap. ... there is no difference between the memory objects allocated by these functions». So, if « there is no difference between the memory objects allocated by these functions» and «local heap = the global heap», we should conclude that the two sets of functions do the same thing ( but what is the best ?). Today, i read a lot of stuff about this issue and i didn't find out nothing relevant. So, I go to take down the functions GlobalZZZ and HeapXXX! And i go "to cook" all well.

Stay well
Regards

[rea]

By the way, that thing, about the global = local is because where not the same for 16 bit Windows, If Im not wrong.

They only provide the same functions in the win32 api for let the anterior aplications access the same  interface.. but yes, they will only have one set of names for the functions if they whant it.... by instance, would be nice look at the entry point of the global and local functions for see if the entry point is really the same or there is a repetition of code ;).... (because they have stated that is the same function ...)

[sluggy]

Rui,
while ultimately the memory does all come from the same heap, how the OS handles that memory allocation and the context is different between the various types of call. Check here and especially here for a more indepth description.

[RuiLoureiro]

Hi all

Raymond,
   Yesterday, after i have putting my answer i went to the links where i discovered who is Mr. Raymond ! But i think, Mr. Raymond, you are a young because you (should)have a young spirit in spite of your age. This is very good. I have a boy in fourth year at university. He follows mathematics, may be because i was a teacher of mathematics in a high school for 6 years ( genetic problems?). Now, he gives me lessons in some matters but in programming questions he needs my helps. It's very interesting to find persons like you. I don't like to play golf and tennis. I was a football player, but not professional. But my kid likes tennis.
   ForTran is what we have in common. But my first program was about 1979 to project and analise a communication anttena (more than 1000 punched cards, rolls of output sheets). In windows programming i am sure you can teach me a lot of things i need to learn to make a good program, some day. For now i am studying what and how to do. I am in a planning phase.

«"cast" a handle to a pointer»: may be this «throw a handle into a pointer» ? It means the same as «cast fire over water» ? It is to ... laugh !
«search yourself, make yourself»

   about this little topic, i can say that all i know was constructed by me. But, as we know, in many cases, there are some undocumented details that makes the difference, and we don't know where to look for. We look for, we search and we don't find interesting or relevant things: the details we want.

Vortex,
   Your last answer don't "cast" light through the issue. I know you have many works about windows programming and i think you know more than what is written in documentation. As Mr. Hutch explained, GlobalAlloc should be used with fixed memory flag only. So, I had reason when i put my question.

Mark Larson page

   In code design, there are cases when we are interested in fast code;
   There are cases when we want the less code possible, etc.
   In my case, i am not concerned about both cases.
   I don't want to write a program which can be hard to understand, with too
   many unnecessary names. But I saw good information there and some of it
   is already my current practice.

Hi, Xor Stance, Rea, Sluggy

   Well-seen ! Can it depend on context ? Are The entry points the same ?

Stay well
Regards

[tenkey]

«"cast" a handle to a pointer»: may be this «throw a handle into a pointer» ? It means the same as «cast fire over water» ? It is to ... laugh !
«search yourself, make yourself»

The image I usually have of "casting" types is pouring plastic, plaster, or hot liquid metal into a cast, to mold it into the desired shape.