telemetry interface is used to fetch telemetry
data.
A model implements one or more telemetry-classes. These are identified by an identifier (class ID) and a name. The telemetries also has a name and an identifier (telemetry ID).
This layout forms a two level hierarchy with classes and their telemetries. The class and telemetry ID's are represented as integers and must be part of a contiguous range starting from zero, i.e., the hierarchy can be viewed as a table with telemetries, where the row numbers (>= 0), represents the class ID's, and the column numbers (>=0) represents the telemetry ID's. For unknown ID's NULL should be returned.
Both telemetry_class_id and telemetry_id can be enumerated using the functions get_telemetry_class_name and get_telemetry_name by starting with an ID of zero and go upp until NULL is returned. A model should not log an error when an invalid ID is presented (but logging info on level 3 makes sense for debug purposes). Error handling for missing expected telemetry IDs should be handled in the model requesting and retrieving the telemetry value.
The get_telemetry_class_id function returns the telemetry_class_id for the telemetry class with name telemetry_class_name. If no telemetry class with that name is found or that telemetry class is not enabled a negative number is returned.
The get_telemetry_class_name returns the name of the corresponding telemetry_class_id. If no telemetry class is found with that id the value NULL is returned.
The get_telemetry_class_description can return a description string for the telemetry_class_id. If no telemetry class is found with that id the value NULL is returned.
The get_telemetry_id function returns the telemetry_id for the telemetry with name telemetry_name belonging to telemetry_class_id. If no telemetry with that name is found in the telemetry class a negative number is returned.
The get_telemetry_name returns the name of the corresponding telemetry_id belonging to telemetry_class_id. If no telemetry with that id is found in the telemetry class the value NULL is returned.
The get_telemetry_description can return a description string for the telemetry_id belonging to telemetry_class_id. If no telemetry with that id the value is found NULL is returned.
The get_value function returns the value for the telemetry_id within telemetry_class_id.
Note all known telemetry_classes are not always enabled in all models, i.e. get_telemetry_class_name can return a valid name for some telemetry_class_id but get_telemetry_id on that name may still return an invalid identifier if that telemetry_class is not enabled in the model.
Note that the identifiers may vary between invocations of the model and must not be stored between runs.
The command list-telemetry-classes can be helpful while developing with the telemetry-interface.
typedef int telemetry_class_id_t;
typedef int telemetry_id_t;
SIM_INTERFACE(telemetry) {
telemetry_class_id_t (*get_telemetry_class_id)(conf_object_t *obj,
const char *telemetry_class_name);
const char *(*get_telemetry_class_name)(conf_object_t *obj,
telemetry_class_id_t telemetry_class_id);
const char *(*get_telemetry_class_description)(conf_object_t *obj,
telemetry_class_id_t telemetry_class_id);
telemetry_id_t (*get_telemetry_id)(conf_object_t *obj,
telemetry_class_id_t telemetry_class_id,
const char *telemetry_name);
const char *(*get_telemetry_name)(conf_object_t *obj,
telemetry_class_id_t telemetry_class_id,
telemetry_id_t telemetry_id);
const char *(*get_telemetry_description)(conf_object_t *obj,
telemetry_class_id_t telemetry_class_id,
telemetry_id_t telemetry_id);
attr_value_t (*get_value)(conf_object_t *obj,
telemetry_class_id_t telemetry_class_id,
telemetry_id_t telemetry_id);
};
#define TELEMETRY_INTERFACE "telemetry"