This thread has been locked.

If you have a related question, please click the "Ask a related question" button in the top right corner. The newly created question will be automatically linked to this question.

IUNIVERSAL_Status

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.

  • A bit of background may be needed, and the docs can definitely be cleaned up.

    In general, the *_Status structs (in all XDM interfaces, including IUNIVERSAL) are algorithm 'output' from a control() call.  The mention of 'read only' in the doc is from the caller/app POV - the intent is that the app won't _set_ any of the *_Status fields (with the exception of .size) and will only read the struct after calling control().  (Later, we'll find the .data field is another exception to the 'read only' rule).

    Also, most XDM structs, including IUNIVERSAL structs, are extensible.  The overall intent with IUNIVERSAL is that each of these structs will be extended in an alg-specific way.  If the alg needs to define 'inputs' for control(), it should extend IUNIVERSAL_DynamicParams, if it wants to extend 'outputs' from control(), it should extend IUNIVERSAL_Status.

    For IUNIVERSAL in particular, the XDM-defined structs are intentionally minimal, and intended to be extended; so the 'base structs' are extremely sparse.

    Brad Griffis said:
    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.

    Yes, IUNIVERSAL_Status.extendedError provides more details when control() returns IUNIVERSAL_EFAIL, and is a 'read only' (from the caller/app's POV) output field.

    Brad Griffis said:
    What's the XDM1_BufDesc for?  I don't quite understand how it should be used, or even how it might be used!

    Another feature of all recent XDM interfaces is the *_Status->data field.  This field is an array of IN/OUT buffers - the buffers are provided by the caller/app, and can be read, and optionally written to by the codec.  (That's the IN/OUT part.)

    An example use case for the .data field is that the app can call control() with the cmd id of XDM_GETVERSION to get the alg's version.  The app must allocate the buffer to hold the version string, and construct the .data field to point at that buffer before calling control().  When control() returns, the data buffer is returned to the caller/app and has been filled by the alg with its version.  The 'ownership' comment is to describe that after control() returns, the alg doesn't own the buffer, shouldn't have any references to the buffer, and the app is allowed to free() that buffer at any point.

    XDM_GETVERSION is just one of many cmds which control() could be called with.  The alg can define its own specific commands as well - and the .data field is just to enable passing larger amounts of data between the app and alg.

    Hope that helps.  I'll try to beef up the docs with some of this description for the next XDAIS/CE release.

    Chris