LaRoomy App Callback

Description

The purpose of the ILaRoomyAppCallback is to get notified of remote events when the user interacts with the app, to receive system notifications or a data response to a previously posted data request.

Usage

To use the callback, create a class which inherits from the ILaRoomyAppCallback interface.

  	
// define the callback for the remote app-user events
class RemoteEvents : public ILaroomyAppCallback
{
    // ...
};

In this class the desired methods can be overwritten to receive the appropriate events which are necessary for the specific application functionality. The override keyword should be used to make sure the syntax is correct and the respective method is overwritten.

  	
// define the callback for the remote app-user events
class RemoteEvents : public ILaroomyAppCallback
{
public:
    // receive connection state change info
    void onConnectionStateChanged(bool newState) override
    {
        if (newState)
        {
            // app connected
        }
        else
        {
            // app disconnected
        }
    }
    
    // receive switch state changes
    void onSwitchStateChanged(cID switchID, bool newState) override
    {
    	// if more than one switch is added, determine which one is toggled
        if (switchID == MY_FIRST_SWITCH_ID)
        {
            if (newState)
            {
                // switch is set to ON
            }
            else
            {
                // switch is set to OFF
            }
        }
        if (switchID == MY_SECOND_SWITCH_ID)
        {
            if (newState)
            {
                // switch is set to ON
            }
            else
            {
                // switch is set to OFF
            }
        }
    }
    
    /* other callback implementations */

};

Finally, an instance of this class must be added to the LaRoomy Api to get notified of events.

  	
void setup()
{
    // put your setup code here, to run once:
    
    /* other setup */
    
    // set the callback handler for remote events
    LaRoomyApi.setCallbackInterface(
        dynamic_cast<ILaroomyAppCallback *>(
            new RemoteEvents()));
    
    /* other setup */    

}

For an easier understanding this could be rewritten as:

  	
void setup()
{
    // put your setup code here, to run once:
    
    /* other setup */
    
    // create the class instance
    auto remoteEvents = new RemoteEvents();

    // add the class instance
    LaRoomyApi.setCallbackInterface(
        dynamic_cast<ILaroomyAppCallback*>(remoteEvents)
    );

    /* 
        NOTE: 
            The 'setCallbackInterface' method takes an ILaroomyAppCallback pointer as an argument,
            since the created class instance is from type 'RemoteEvents' this would be an error.
            But the RemoteEvents class inherits from the ILaroomyAppCallback, for this reason it
            is compatible but must be casted to the correct type.
            Here the 'dynamic_cast<..>(..)' is used. Why? If the RemoteEvents class inherits from
            more than one base class, the dynamic cast ensures that the correct method offset is
            called.
    */
    
    /* other setup */    

};

API Reference

This is a list of all available callback methods.

onConnectionStateChanged

  		
virtual void onConnectionStateChanged(bool newState);

This method is called when the Bluetooth connection state has changed.

Arguments:

newState - The new connection state.

onButtonPressed

  		
virtual void onButtonPressed(cID buttonID);

If a button in a Button Property was pressed in the app, this method is called.

Arguments:

buttonID - The ID of the property element. If more than one Button Property is used, this parameter can be used to determine which button was pressed.

onSwitchStateChanged

  		
virtual void onSwitchStateChanged(cID switchID, bool newState);

If a switch in a Switch Property is pressed, this method is called.

Arguments:

switchID - The ID of the property element. If more than one Switch Property is used, this parameter can be used to determine which switch was pressed.

newState - The new state of the Switch.

onLevelSelectorValueChanged

  		
virtual void onLevelSelectorValueChanged(cID levelSelectorID, unsigned int newValue);

When the slider of a LevelSelector Propery is moved, this method is called.

Arguments:

levelSelectorID - The ID of the property element. If more than one LevelSelector Property is used, this parameter can be used to determine which element's state has changed.

newValue - The new value of the LevelSelector.

onOptionSelectorIndexChanged

  		
virtual void onOptionSelectorIndexChanged(cID optionSelectorID, unsigned int newIndex);

This method is called when the selection of the OptionSelector Property has changed.

Arguments:

optionSelectorID - The ID of the property element. If more than one OptionSelector Property is used, this parameter can be used to determine which element's state has changed.

newIndex - The new selected index of the OptionSelector.

onRGBSelectorStateChanged

  		
virtual void onRGBSelectorStateChanged(cID rgbSelectorID, const RGBSelectorState& state);

When the configuration of the RGBSelector Property changes, this method is called.

Arguments:

rgbSelectorID - The ID of the property element. If more than one RGBSelector Property is used, this parameter can be used to determine which element's state has changed.

state - The new state of the RGBSelector. Type: RGBSelectorState

onExtendedLevelSelectorStateChanged

  		
virtual void onExtendedLevelSelectorStateChanged(cID extendedLevelSelectorID, const ExtendedLevelSelectorState& state);

When the state of an ExtendedLevelSelector Property changes, this method is called.

Arguments:

extendedLevelSelectorID - The ID of the property element. If more than one ExtendedLevelSelector Property is used, this parameter can be used to determine which element's state has changed.

state - The new state of the ExtendedLevelSelector. Type: ExtendedLevelSelectorState

onTimeSelectorStateChanged

  		
virtual void onTimeSelectorStateChanged(cID timeSelectorID, const TimeSelectorState& state);

When the time in a TimeSelector Property is changed by the user, this method is called.

Arguments:

timeSelectorID - The ID of the property element. If more than one TimeSelector Property is used, this parameter can be used to determine which element's state has changed.

state - The new state of the TimeSelector. Type: TimeSelectorState

onTimeFrameSelectorStateChanged

  		
virtual void onTimeFrameSelectorStateChanged(cID timeFrameSelectorID, const TimeFrameSelectorState& state);

When the time-frame in a TimeFrameSelector Property has changed, this method is invoked.

Arguments:

timeFrameSelectorID - The ID of the property element. If more than one TimeFrameSelector Property is used, this parameter can be used to determine which element's state has changed.

state - The new state of the TimeFrameSelector. Type: TimeFrameSelectorState

onDateSelectorStateChanged

  		
virtual void onDateSelectorStateChanged(cID dateSelectorID, const DateSelectorState& state);

If the user changes the date of a DateSelector Property inside the app, this method is called.

Arguments:

dateSelectorID - The ID of the property element. If more than one DateSelector Property is used, this parameter can be used to determine which element's state has changed.

state - The new state of the DateSelector. Type: DateSelectorState

onUnlockControlStateChanged

  		
virtual void onUnlockControlStateChanged(cID unlockControlID, const UnlockControlState& state);

When the state of an UnlockControl Property has changed, this method is called. This includes lock, unlock and pin-change operations.

Arguments:

unlockControlID - The ID of the property element. If more than one UnlockControl Property is used, this parameter can be used to determine which element's state has changed.

state - The new state of the UnlockControl Property. Type: UnlockControlState

onUnlockControlInvalidOperation

  		
void onUnlockControlInvalidOperation(cID unlockControlID, UnlockControlInvalidOperation invalidOperation);

If the user performs an invalid operation on an UnlockControl Property, like an unlock request with an invalid pin, this method is invoked to report the type of error.

Arguments:

unlockControlID - The ID of the property element. If more than one UnlockControl Property is used, this parameter can be used to determine the property this call in referring to.

invalidOperation - The invalid action. Type: UnlockControlInvalidOperation

onNavigatorStateChanged

  		
virtual void onNavigatorStateChanged(cID navigatorID, const NavigatorState& state);

When a navigation button is pressed or released in a NavigatorControl Property, this method is invoked.

Arguments:

navigatorID - The ID of the property element. If more than one NavigatorControl Property is used, this parameter can be used to determine the property this call in referring to.

state - The state of the NavigatorControl Property. Type: NavigatorState

onStringInterrogatorDataReceived

  		
virtual void onStringInterrogatorDataReceived(cID stringInterrogatorID, String& fieldOneContent, String& fieldTwoContent);

When the confirm button in a StringInterrogator Property is pressed by the user, this method is called with the content data of the text fields.

Arguments:

stringInterrogatorID - The ID of the property element. If more than one StringInterrogator Property is used, this parameter can be used to determine the property this call in referring to.

fieldOneContent - The text content of the first text field inside the StringInterrogator property.

fieldTwoContent - The text content of the second text field inside the StringInterrogator property.

onBindingTransmissionReceived

  		
virtual BindingResponseType onBindingTransmissionReceived(BindingTransmissionTypes bType, const String& key){
	return BindingResponseType::BINDING_FAIL_NOT_IMPLEMENTED;
}

This method is invoked on three cases: binding is enabled, released or this is an authentication transmission. If automatic handling of the binding functionality is activated with the enableInternalBindingHandler method of the LaRoomy Api, this callback method is not fired. If auto handling is not activited, this method is called and if it is overwritten in the callback, the transmission must be properly handled, this means it must be processed in relation to the BindingTransmissionType and the respective value must be returned to notify the app of the result. If auto-handling is not activated and the method is not overwritten, the device reports that binding is not supported. More Info..

Arguments:

bType - The purpose of the binding transmission. Type: BindingTransmissionTypes

key - The binding key (if included in the transmission) as string.

Return Value:

BindingResponseType - The appropriate response as a result of the processing of the BindingTransmissionType.

onPropertyLoadingComplete

  		
virtual void onPropertyLoadingComplete(PropertyLoadingType plt);

This method is called when the default property loading loop is finished. More info to the property loop.

Arguments:

plt - The way how the property data was loaded. Type: PropertyLoadingType

onFactoryResetRequest

  		
virtual void onFactoryResetRequest();

When the factory reset button on the DeviceSettingsPage is pressed by the user and the following dialog is positive confirmed, the app sends an factory reset command and this method is called. Do factory reset processing here if applicable.

onDeviceConnectionRestored

  		
virtual void onDeviceConnectionRestored(cID currentOpenedPropertyPageID);

When the connection to the device was suspended and the user resumes the app, the connection is restored without a loading or update cycle. This method is called to notify of that scenario. This callback method could be used to make some necessary updates of changes occurred while the app was disconnected. Please note that the property state will be updated by default from the LaRoomy Api. This could be disabled with the enableAutoRefreshStates method of the LaRoomy Api.

Arguments:

currentOpenedPropertyPageID - The ID of the current property page that is open when the user returns to the app or ID_DEVICE_MAIN_PAGE if the DeviceMainPage is open.

onBackNavigation

  		
virtual void onBackNavigation();

When the user has navigated to a ComplexPropertyPage and navigates back to the DeviceMainPage, this method is invoked.

onComplexPropertyPageInvoked

  		
virtual void onComplexPropertyPageInvoked(cID propertyID);

When the user navigates to a ComplexPropertyPage, this method is invoked.

Arguments:

propertyID - The ID of the Property-Element related to the page.

onDeviceSettingsPageInvoked

  		
virtual void onDeviceSettingsPageInvoked();

When the user navigates to the Device-Settings-Page, this method is invoked.

onTimeRequestResponse

  		
virtual void onTimeRequestResponse(unsigned int hours, unsigned int minutes, unsigned int seconds);

This is the response to a time request that was posted with the sendTimeRequest method of the LaRoomy Api.

Arguments:

hours - The current hours value.

minutes - The current minute value.

seconds - The current seconds value.

onDateRequestResponse

  		
virtual void onDateRequestResponse(unsigned int day, unsigned int month, unsigned int year);

This is the response to a date request that was posted with the sendDateRequest method of the LaRoomy Api.

Arguments:

day - The current day value.

month - The current month value.

year - The current year value.

onLanguageRequestResponse

  		
virtual void onLanguageRequestResponse(String langID);

This is the response to a language request that was posted with the sendLanguageRequest method of the LaRoomy Api.

Arguments:

langID - The current Language ID the app is running in. The Language ID is a 2-letter code in ISO 639-1 format. More Info.

onUIModeRequestResponse

  		
virtual void onUIModeRequestResponse(PUIMODEDATA pData);

This is the response to a UI-Mode info request that was posted with the sendUIModeRequest method of the LaRoomy Api.

Arguments:

pData - Pointer to a UIMODEDATA struct containing the UI Information.

Search This Blog

LaRoomy API