ACAPI_LibPart_SetDetails_ParamDef function signature

[Anonymous]

Hello,

the function signature of ACAPI_LibPart_SetDetails_ParamDef looks like this:

ACAPI_LibPart_GetSect_ParamDef (const API_LibPart *libPart, API_AddParType **addPars, double*a, double*b, GSHandle sect2DDrawHdl, GSHandle *sectionHdl, GS::UniString *password = nullptr);

Why is the type of the 2nd argument API_AddParType**? It looks like the function is actually expecting a GSHandle. If we try to use anything other than a GSHandle, for example a local array, our code breaks. Unfortunately the documentation only says

[in] Additive parameters of the Library Part

which is not very helpful.

Do we really need a GSHandle here? If so, are there other API functions that use such double pointers and expect a GSHandle?

[Ralph Wessel · Accepted solution]

A double pointer, or pointer to a pointer, is sometimes referred to as a "handle". GSHandle is is just an alias for the same thing, i.e. they are all actually synonymous. And yes, there are many more cases like this. You can use functions like BMGetHandleSize to get size allocated to the handle.

[Anonymous]

Thanks for the clarification. We're aware that GSHandle is just a char** as well. We just didn't know whether we had to allocate an actual handle (-> BMAllocateHandle) or not. A pointer to pointer could also be a pointer to an array or an array of pointers. This gets especially confusing if the same function signature uses both variants API_AddParType** and later GSHandle at the same time. The type alias at least makes it clear that we need a proper handle.

[Ralph Wessel]

That's true - it's not so easy to distinguish – particularly if the documentation isn't explicit. Generally speaking, a pointer to a pointer will be allocated as a handle, but there are exceptions. Best approach is to look at the example code with the dev-kit and see what they do. Otherwise, you can only run tests by calling functions that expect a handle and see if they fail.