Error message querying function(s)?

[marcoskirsch]

As we try to define how clients get error messages in the API.

There are 2 use cases:

1. Retrieve the error message given an error code. This is a simple lookup table. E.g. "The specified value is invalid".
2. Retrieve the error message for the last error that occurred in the driver. This may contain contextual information. E.g. "The specified value is invalid. Property: Range. Valid values: 0-10. Requested value: 11"

NI drivers go through great lenghts to provide helpful contextual information (second use case). I view the first use case as "nice to have" in the API, vendors could optionally provide a big header file.

We need to decide

• Do we want both use cases supported?
• If yes, do we support both use cases with a single function or do we have two easier-to-use functions?
• For the second use case, should it clear the error upon retrieval or should we have a separate clear function? Both of these options have ramifications:
  • If you retrieve a partial string, is it cleared? (makes me think we need explicit clearing)
  • If an error comes in and the previous one wasn't retrieved, do we overwrite the previous one?
• Should error handling functions return errors? Things get tricky when they do so I'm inclined to say no.

Here's what a proposed set of functions could look like:

// Retrieves the error message that last occurred. Includes contextual information.
// Error message is retrieved from either TLS or session-global storage. This is up to implementation.
void foo_last_error_message(
    foo_session sessionHandle,
    char* error_message,
    size_t error_message_size,
    size_t* actual_error_message_size
);

// Clears the last error message.
void foo_clear_last_error_message(
    foo_session sessionHandle
);

// Retrieves the error message that correponds to the error code.
void foo_error_message(
   int32_t error_code,
    char* error_message,
    size_t error_message_size,
    size_t* actual_error_message_size
);

[joseph-mueller]

Yup, we like it.

Couple of questions/possible refinements:

1. Should we go ahead and pass the session to the foo_error_message? As we discussed a couple of weeks ago it adds consistency and could be potentially used for some obscure reason by the function.

2. Do we really need foo_clear_last_error_message? Seems the client gets the same affect by just calling foo_last_error_message with a null error_message buffer (or with a real one and ignoring the result).

BTW, is it a session or a sessionHandle? Some latent Hungarian notation :) ?

[joseph-mueller]

Discussion 10/16

• Note that last_error_message really is the last, so clearing is optional, but useful if the client wants to confirm no-errors.
• Keep the clear_last_error function for that case.
• foo_error_message, does not need a session (consistent with VXIp&p)

Conclusion 10/16, Joe will do a PR.