User defined onRead and onWrite functions

Every parameter has three function pointers to allo user defined actions on read, write and setToDefault. This is useful for e.g.

• The parametervalue is not stored in a variable, but in a structure.
• After write of filter-settings the integrator must be reinitialized.
• The paramtervalue must be scaled before display.
• The parameter should perform an action on write.

If no customized action is neccessary, the default action must be linked. This default action is dependant of the datatype of the parameter. For every useable datatype a default action is defined:

• signed char: ReadFunction_STD_I8, WriteFunction_STD_I8, SetToDefaultFunction_STD_I8
• unsigned char: ReadFunction_STD_U8, WriteFunction_STD_U8, SetToDefaultFunction_STD_U8
• signed word: ReadFunction_STD_I16, WriteFunction_STD_I16, SetToDefaultFunction_STD_I16
• unsigned word: ReadFunction_STD_U16, WriteFunction_STD_U16, SetToDefaultFunction_STD_U16
• signed int: ReadFunction_STD_I32, WriteFunction_STD_I32, SetToDefaultFunction_STD_I32
• unsigned int: ReadFunction_STD_U32, WriteFunction_STD_U32, SetToDefaultFunction_STD_U32
• signed long: ReadFunction_STD_I64, WriteFunction_STD_I64, SetToDefaultFunction_STD_I64
• unsigned long: ReadFunction_STD_U64, WriteFunction_STD_U64, SetToDefaultFunction_STD_U64
• float: ReadFunction_STD_F32, WriteFunction_STD_F32, SetToDefaultFunction_STD_F32
• string: ReadFunction_STD_STR, WriteFunction_STD_STR, SetToDefaultFunction_STD_STR

Read and write functions have as return value the number of processed bytes. In case of 0 as return value an error occured.

Type safety of the callbacks

The macros ParameterU16(), ParameterF32(), ... check the three callbacks at compile time. A callback is accepted, if its first argument is

• the typed parameter of the same datatype, e.g. Parameter_U16* for ParameterU16(). All standard functions (ReadFunction_STD_U16, ...) are of this kind.
• the datatype independent Parameter*, e.g. WriteFunction_STD_Const and SetToDefaultFunction_STD_Const for read-only parameters.

Every other callback causes a compile error "controlling expression type ... not compatible with any generic association type", e.g.

• a standard function of another datatype (ReadFunction_STD_U32 in ParameterU16()),
• a callback with an incomplete parameter list (all 7 resp. 4 arguments are mandatory),
• a callback with void* ptThis,
• a callback casted to (ReadFunction*). A cast is not needed anymore and must be removed.

Assignment of the typed parameters:

• signed char / unsigned char: Parameter_I8 / Parameter_U8 (also ReadFunction_STD_U8_BitWise)
• signed word / unsigned word: Parameter_I16 / Parameter_U16
• signed int / unsigned int: Parameter_I32 / Parameter_U32
• signed long / unsigned long: Parameter_I64 / Parameter_U64
• float: Parameter_F32 (also ReadFunction_STD_I32Q16, the value is stored as float)
• string: Parameter_STR

User defined callbacks should use the typed parameter of their datatype. Then a standard function of the same datatype can be called without cast, and ptThis->Data is already of the type ParaData_<T>*. IsValidForRead, IsValidForWrite and IsValidForSetToDefault accept every parameter type.

static int32_t WriteFunction_UserName(Parameter_STR* ptThis, const ParameterRequest* ptRequest)
{
    int32_t ret;
 
    ret = WriteFunction_STD_STR(ptThis, ptRequest);
    LogMessageDyn("User name changed", LOGMESSAGE_OPTION_DEBUG);
    return ret;
}

Examples

Example for a onWrite Function of a ParameterU8():

int32_t WriteFunction_Run(Parameter_U8* ptThis, const ParameterRequest* ptRequest)
{
    uint8_t val;
    
    if (IsValidForWrite(ptThis, ptRequest) == false)
        return 0;
 
    val = ((uint8_t*)ptRequest->pData)[0];
   
    switch(val) 
    {
        case 0:
            Stop();     
            break;
        case 1:
            if (IsRunning()) 
                return 0;           
            Run();
            break;
        default:
            return 0;
    }
 
    return GetDataTypeSize(TYPE_uint8);
}

If the written value is 1, the device is started. If 0 the device stopps. The value is not written ot a variable, only the action is performed. In the same parameter the state of the device is read with this onRead function:

int32_t ReadFunction_Run(Parameter_U8* ptThis, const ParameterRequest* ptRequest)
{
    if (IsValidForRead(ptThis, ptRequest) == false)
        return 0;
 
    if (get_state() & RUN_FLAG)
    {
        ((uint8_t*)ptRequest->pData)[0] = 1;
    }
    else
    {
        ((uint8_t*)ptRequest->pData)[0] = 0;
    }
    
    return GetDataTypeSize(TYPE_uint8);
}