I want to make sure I understand this structure and how it should be used. First, the definition we supply is:
"Defines instance status parameters (read-only)."
From what I can tell the primary use case would be for reporting errors. The control() function would return IUNIVERSAL_EFAIL and the extendedError field would be used for giving further info. Is that right? That being the case, it would be read-only to the application, i.e. the control() function would write to the extendedError field. (Confusion on this later.)
What's the XDM1_BufDesc for? I don't quite understand how it should be used, or even how it might be used! The post-condition of the control() function mentions the following:
"If a buffer was provided in the status->data
field, it
is owned by the calling application."
So is that saying the control() function should not modify the buffers described in the XDM1_BufDesc? Earlier I came to the conclusion that this IUNIVERSAL_Status struct was read-only to the app and should be written only by the control() function. However, the post-condition indicates that the status->data field is owned by the application. When it says the buffer is owned by the calling application, does that imply the control() function should not modify that buffer?
Hopefully I've at least got the primary use case down, but I'm a bit confused by how the XDM1_BufDesc is used and who writes what to it and the corresponding data buffer(s) it describes.