[gdal-dev] GDAL/OGR C API, how should I be dealing with 'handles'

[Mateusz Loskot]

On 8 June 2015 at 13:07, jramm <jamessramm at gmail.com> wrote:
> Many C API functions return a typedef which is referred to as a handle. E.g.
>
>
> OGRFeatureH OGRLayerH OGRGeometryH
> These seem to occur when the C++ api returns a pointer. I have 3 questions:
>
> Why doesnt the C API return pointers?

H suffix denotes a handle.
Handles are defined as opaque pointer technique
(http://en.wikipedia.org/wiki/Opaque_pointer#C)
In fact, they are pointers.

> How should I pass these 'handles' around. Should I create pointers to them?

No, pass them around and treat them as C/C++ pointers.

> Do I need to free them?

If you mean free as calling C standard free() function, then no,
You should not invoke free with GDAL/OGR handle.

Typically, there is *Close* or *Destroy* function corresponding to particular
handle type, for example

GDALDatasetH h = GDALOpen(...);
...
GDALClose(h)

or

GDALColorTableH h = GDALCreateColorTable(...)
...
GDALDestroyColorTable(h)

You need to check C API reference.

Best regards,
-- 
Mateusz  Loskot, http://mateusz.loskot.net