Kramer Electronics SP-14 - Manual (Page 20)

3.3 Guidelines for AV API Usage
The AV API was designed to be a generalised interface to control units and as such provides
access to a number of different parameter types. This is reflected in the functions that are
implemented for the various parameters. It is advisable to follow these guidelines when
implementing any user interface for controlling units.
3.3.1 Query Function
The purpose of query function is to ascertain which functions are available to a parameter.
This gives an idea as to what type parameter is. Secondly, the query function may improve
performance using the interface. For function that are not implemented there is little point in
calling that function. This is particularly important with the availability functions.
3.3.2 Parameter Availability Function
If the availability function for a parameter is implemented it should be called prior to using the
other function relating to that parameter. If the availability function returns false (0) the user
interface should indicate by some means that this parameter is not available. Note that
parameters may change their availability status based changes to other parameters or the
input signal etc.
3.3.3 Parameter Value Range
For parameters that map to a number (integer) the minimum and maximum values should be
obtained. These should be used by the user interface to restrict the user input to valid values.
If the minimum and maximum function are not implemented the parameter is either not a
numeric parameter or is read only.
3.3.4 Parameter Value Availability Function
The value availability function is used to restrict even further the valid values that may be set.
When implemented the value availability function should be called to verify the validity of a
value prior to calling the set functions.
If the value availability function is not implemented all values between the minimum and
maximum values inclusive are valid.
Note that parameter values may change their availability status based changes to other
parameters or the input signal etc.
3.3.5 Parameter Types
The different parameter types reflect the distinct usages of the API. For example, the picture
contrast parameter is a number (integer) and therefore requires functionality to allow the
contrast value to be read and changed. Whereas, a factory reset is an action and therefore
only requires a means to trigger that action. Some parameters are used to provide information
and implement only the get string function.
3.3.5.1 Parameter type: Info
Parameters that conform to the info type only implement the get string function. These are
parameters that provide status information in the form of a string, as is.
E.g. avPar_infoOutResolution, avPar_infoOutFrameRate, avPar_infoInResolution.
3.3.5.2 Parameter type: Action
Action parameters are used to trigger actions such as factory reset and channel resets. To
perform the action the set function is used with attribute set to avParamAttr_value and value
is set to zero. The availability function should be used prior, to ascertain if the action is
available.
3.3.5.3 Parameter type: Integer
The majority of parameters are numeric and are classed as integers. Some parameters that
do not appear to be numeric to the user are also of integer type. The get string function is