C Handles - How to work with them?

Question

I have in some documentation for a plugin for Dreamweaver I am making that says the following:

void **connectionData

• The connectionData argument is a handle to the data that the agent wants Dreamweaver to pass to it when calling other API functions.

I have no other information than this from the manual in regard to connectionData. Thinking literally, I figured handle refered to a generic handle,however I am not able to find documentation on working with generic handles in regard to C.

HANDLE h = connectionData;

Does compile in my code. How exactly do I get the "secrets" inside this data structure/can someone explain how generic handles for C work?

Answer 1

Well, usually you are not supposed to get the secrets of handles; they are usually just a pointer to some internal structure inside the lib/API you are using and only the lib will know how to use it.

There is no generic rules or anything about handles, you'll have to use them as indicated by your lib's docs.

Answer 2

C developers use a "handle" data type when they specifically want to hide the internal data and keep API users from monkeying around with the implementation. A handle is sometimes just a pointer, but can also be an index into an internal lookup table.

In general, you should only use provided API functions with a handle, and learn the proper way to get the handle, understand its life cycle and how to properly dispose of it when you're done.

Answer 3

The way that this is defined, connectionData is a pointer to a pointer to something. Without knowing what is assigned to connectionData, you can't know anything else. The reason why your other statement worked is that HANDLE is probably a macro that expands to void*

To know the "Secrets," you would need to find out what struct (this is a guess - it could actually be any data type) connectionData points to, then look at the definition of that struct. I don't know how familiar you are with programming in general but a debugger allows you to easily look at the struct's fields while paused at a breakpoint.

However, as other people have said, you probably don't want to muck with the internals of whatever this points to, and only use API calls.