topic Re: ACAPI_LibPart_SetDetails_ParamDef function signature in Archicad C++ API

ACAPI_LibPart_SetDetails_ParamDef function signature

Anonymous — Tue, 14 Sep 2021 11:43:00 GMT

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?

Re: ACAPI_LibPart_SetDetails_ParamDef function signature

Ralph Wessel — Mon, 19 Oct 2020 19:51:52 GMT

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.

Re: ACAPI_LibPart_SetDetails_ParamDef function signature

Anonymous — Tue, 20 Oct 2020 09:26:35 GMT

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.

Re: ACAPI_LibPart_SetDetails_ParamDef function signature

Ralph Wessel — Tue, 20 Oct 2020 12:20:08 GMT

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.