Hi all,
there's been some discussions about cleaning up how our APIs (SDK) deals
with return values. Right now, it's sort of a mess, with different APIs
using different standards (e.g. return a POD data type, return a
TSReturnCode, return an int etc.). There are a few suggestions on the
table, each which has pros and cons. I'd like to start the discussion on
this, so we can come to a consensus and make any changes sooner rather
than later.
Here are the ideas that I've heard so far:
1) Do nothing (or as little as possible).
2) Do nothing, other than making sure any outright wrong returns are
fixed (i.e. use of "int" when it should be TSReturnCode). Things return
POD values or pointers stays the same. See TS-271 for example.
3) Change all APIs to always return TSReturnCode. The prototype for many
functions would then change, to be like
TSReturnCode TSFooApi(type1 in_param1, type2 in _param2, type3
*out_param1, type4 *outparam2);
#3 is obviously the thing with the most work (and changes), and also is
slightly more cumbersome to use in some cases (i.e. where before
something could return a char*, where NULL means failure, we'd now pass
in a char** pointer, and return TSError on failure). Also, some APIs
that can never fail would always return TS_Success, which makes it
slightly more confusing to know when I need to check for a return value
or not (although, a plugin author can of course always check every APIs
return value).
On the positive side of #3 is that the APIs become very standardized,
and easier to remember. And there is no guess work as to what return
value means success or failure, or checking for the wrong return values.
Thoughts?
-- leif
P.s
If we go with option #1 or #2, there are a few new APIs that should most
likely change, since they currently use the #3 prototype. Not a big
deal, since there were added in the v2.1.x timeline, so there is no
compatibility that breaks.
