Determining if a given API call is valid for a given device handle

[rtucker]

There are a number of functions which are only supported on particular members of a device family, e.g. bladerf_get_sampling and bladerf_set_sampling. Currently, there are two mechanisms to determine if a given function is supported:

1. Guess, based off of the return value of bladerf_get_board_name
2. Try it and see if it returns BLADERF_ERR_UNSUPPORTED

The first method is not good, as it is literally guesswork, and it also creates future issues if we end up implementing a function on a previously-unsupported board.

The second method is not good, as it may have side effects, and it basically turns into a bunch of boilerplate to populate a capabilities list.

Ref/inspired by: pothosware/SoapyBladeRF#19

[pk-mdt]

How about a reply code that developers can interpret as "not implemented"?

[rtucker]

@pk-r7 hmmm... what situations would warrant a BLADERF_ERR_NOT_IMPLEMENTED return instead of the current BLADERF_ERR_UNSUPPORTED?

also not sure how much this would help at runtime... the message that libbladeRF needs to communicate at runtime is "right now, this function is not supported with this device handle" and BLADERF_ERR_UNSUPPORTED is how that's currently communicated

[pk-mdt]

Yes I see that now, BLADERF_ERR_UNSUPPORTED should work, it appears the error handling in CubicSDR needs some work.

[rtucker]

Would something like this be helpful to implementers?

/**
 * Check if a libbladeRF API function is supported by a given device.
 * 
 * Given a device handle and a pointer to a libbladeRF function, this checks
 * to see if the function is supported and implemented for the device.
 * 
 * @param      dev   Device handle
 * @param      fn    Function pointer
 *
 * @return     true if the function exists and is supported, false otherwise
 */
API_EXPORT
bool CALL_CONV bladerf_is_function_supported(struct bladerf *dev, void *fn);

Usage would be something like:

if (bladerf_is_function_supported(dev, &bladerf_get_sampling)) {
  // this will likely succeed
  status = bladerf_get_sampling(dev, &sampling);
} else {
  // just skip it
  status = 0;
  sampling = BLADERF_SAMPLING_UNKNOWN;
}