Azure IoT C SDK: Understanding IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK

Question

I'm trying to understand the IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK of the Azure IoT C SDK.

Unfortunately, except for the azure.github.io documentation, I cannot find any other useful resources. And the documentation itself is neither very detailed nor clear or exhaustive.

Is there any documentation about how the content of the payload parameter looks? Or does anyone know about this from implementing an Azure IoT Hub connection before?

From experimenting, it looks like when update_state (DEVICE_TWIN_UPDATE_STATE) is DEVICE_TWIN_UPDATE_COMPLETE a JSON is contained which is an object with a desired and a reported member. When update_state is DEVICE_TWIN_UPDATE_PARTIAL it seems payload just contains a JSON with the desired properties.

What's confusing me now is that the description of DEVICE_TWIN_UPDATE_STATE in the documentation

Enumeration passed to application callback to receive IoT Hub device or module twin data indicating whether the full twin or just partial update was received.

and for IOTHUB_CLIENT_DEVICE_TWIN_CALLBACK, parameter update_state

Whether application has received a full twin or just a patch update.

makes me expect something different. It sounds to me like when DEVICE_TWIN_UPDATE_COMPLETE is set, that payload should contain a JSON with the complete desired properties of the twin, and when DEVICE_TWIN_UPDATE_PARTIAL is set payload should contain a JSON with the partial desired properties of the twin (i.e. only the properties that changed).

Can anybody shine a light on this matter?