Critical Description
As has been discussed on the dev@ mailing list, we should clean up some of our APIs. I'm filing this bug here to track the discussion that has been had so far.
The general consensus is that we'll stick to two types of signatures. The first one will presumably be the common one:
1) For any API that can fail (e.g. due to bad input, wrong types, or errors internally etc.), we'll stick to an interface of the form
TSReturnCode TSSomeAPI(int in_param1, char *n_param2, int *out_param1, char **out_param2);
we might want to consider adding some new error types to TSReturnCode as well, right now it's only error or success. One addition could be BAD_INPUT for example. But, we'll consistently use TSReturnCode only for indicating some sort of failures (i.e. no overloading of NULL pointers, -1, 0 etc. for a returned POD to mean failure).
2) For APIs that can not fail (quoting amc: "I promise to return something useful, or I will not return at all"), we allow the API to return a POD type. For Get() and Set() methods, we indicate this promise by dropping the Get() or Set() part of the name For example, TSMimeHdrLengthGet() becomes:
int TSMimeHdrLength(TSMBuffer bufp, TSMLoc obj)
This API can currently not fail in a release build, in debug builds, we should change such non-failing APIs to use ink_assert() on the sanity checks. The example above is particularly "bad" IMO, since it returns a length of -1 to mean that the assert failed. In the implementation of this new version of the API, we'd have asserts like
int
TSMimeHdrLengthGet(TSMBuffer bufp, TSMLoc obj)
{
ink_assert(sdk_sanity_check_mbuffer(bufp) == TS_SUCCESS);
ink_assert(sdk_sanity_check_mime_hdr_handle(obj) == TS_SUCCESS);
...
We should make sure that we "group" similar APIs together properly, i.e. it makes no sense for dealing with (e.g.) TSMimeHdrFieldGet() as a can-fail API, and TSMimeHdrFieldFind() as one that can not fail.