Platform

Detailed Description

Abstract interfaces for platform specific implementations.

• Bridges
  • Support Table
  • Application Orientation
  • Status Bar
  • Navigation Bar
  • Audio Volume
  • Device Information
  • Power Management
  • Device Type
  • Locale
  • App Life Cycle
  • Secure Storage
  • Network Information
  • Telephony Information
  • Web Browser
  • Deprecated Web View
  • Closed Captions Status
  • Closed Captions Styling
• Native Views
  • Web Views

Bridges

The convention used by You.i Engine is to call abstrations of platform features bridges. Bridges privide application developers a C++ interface to avoid intgrating with each platform directly. Since bridges wrap platform functionality, they are not implemented for platforms which do no have the relevant hardware, or platform API. For example the CYIApplicationStatusBarBridge can be used to configure the status bar, and is only available on mobile platforms which have status bars.

Each bridge class must be accessed through a locator class. Depending on bridge availability, the associated locator class will provide a valid instance of the bridge or a value of null if one is not available. Bridge instances are not created until requested through the locator. They are cleaned up automamatically by the system when the application is terminated.

Support Table

The table below illustrates the bridges that are available on 10-Foot and Mobile platforms (shown in green).

Bridge Locator	Application UI			Audio	Device			System Information	App Life Cycle	Storage	Network	Communications	Web		Accessibility Information
Platform	Application Orientation	Status Bar	Navigation Bar	Audio Volume	Device Information	Power Management	Device Type	Locale	App Life Cycle	Secure Storage	Network Information	Telephony Information	Web Browser	Web View	Closed Captions Status	Closed Captions Styling
Mobile
iOS	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	No
Android	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	API >= 19	No
10-Foot
Apple tvOS	No	No	No	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes	No	No	No	Yes	No
UWP	No	No	No	No	Yes	No	Yes	Yes	Yes	Yes	Yes	No	No	No	No	Yes
Playstation 3	No	No	No	No	Yes	No	Yes	Yes	No	Yes	Yes	No	No	No	Yes	Yes
Playstation 4	No	No	No	No	Yes	No	Yes	Yes	Yes	Yes	Yes	No	No	No	Yes	Yes
Tizen	No	No	No	Yes	Yes	No	Yes	Yes	No	Yes	Yes	No	No	No	Yes	No
Development
Windows (VS2013)	No	No	No	No	Yes	No	Yes	Yes	No	Yes	Yes	No	No	No	No	No
Mac OS X	No	No	No	No	Yes	No	Yes	Yes	No	Yes	Yes	No	No	No	No	No
Linux	No	No	No	No	Yes	No	Yes	Yes	No	Yes	Yes	No	No	No	No	No

Application Orientation

The CYIApplicationOrientationBridge can be used to set an application's YIViewProperty::Orientation. This bridge is available on all mobile platforms.

#include <platform/YiApplicationOrientationBridge.h>
#include <platform/YiApplicationUIBridgeLocator.h>
#include <view/YiViewProperty.h>

static void LockAppToLandscape()
{
    CYIApplicationOrientationBridge *pBridge = CYIApplicationUIBridgeLocator::GetApplicationOrientationBridge();
    if (pBridge)
    {
        pBridge->SetOrientation(YIViewProperty::LANDSCAPE);
    }
}

Status Bar

The CYIApplicationStatusBarBridge can be used to set the visibility of the device's status bar. This bridge is available on all mobile platforms.

#include <platform/YiApplicationStatusBarBridge.h>
#include <platform/YiApplicationUIBridgeLocator.h>
#include <view/YiViewProperty.h>

static void HideStatusBar()
{
    CYIApplicationStatusBarBridge *pBridge = CYIApplicationUIBridgeLocator::GetApplicationStatusBarBridge();
    if (pBridge)
    {
        pBridge->SetStatusBarVisibility(YIViewProperty::STATUSBAR_HIDDEN);
    }
}

Navigation Bar

The CYIApplicationNavigationBarBridge can be used to set the system's navigation bar visibility to either YIViewProperty::NAVIGATIONBAR_VISIBLE, or YIViewProperty::NAVIGATIONBAR_HIDDEN. This bridge is available only on the Android mobile platform.

#include <platform/YiApplicationNavigationBarBridge.h>
#include <platform/YiApplicationUIBridgeLocator.h>
#include <view/YiViewProperty.h>

static void HideNavigationBar()
{
    CYIApplicationNavigationBarBridge *pBridge = CYIApplicationUIBridgeLocator::GetApplicationNavigationBarBridge();
    if (pBridge)
    {
        pBridge->SetNavigationBarVisibility(YIViewProperty::NAVIGATIONBAR_HIDDEN);
    }
}

Audio Volume

The CYIAudioVolumeBridge supports the query and manipulation of the platform's audio volume settings. The audio volume can be observed by calling CYIAudioVolumeBridge::StartObservingVolumeChanges. This bridge is available on iOS, tvOS, Android, and Tizen.

Note

On iOS and tvOS the volume may only be changed by a MPVolumeView, or in the case of tvOS though the tvOS remote.

#include <platform/YiAudioBridgeLocator.h>
#include <platform/YiAudioVolumeBridge.h>

class VolumeListener : public CYISignalHandler
{
public:
    VolumeListener()
    {
        CYIAudioVolumeBridge *pBridge = CYIAudioBridgeLocator::GetAudioVolumeBridge();
        if (pBridge)
        {
            pBridge->PlatformVolumeChanged.Connect(*this, &VolumeListener::OnVolumeChanged);
            pBridge->StartObservingVolumeChanges();
        }
    }

    void OnVolumeChanged()
    {
        float fVolume;
        CYIAudioVolumeBridge *pBridge = CYIAudioBridgeLocator::GetAudioVolumeBridge();
        if (pBridge)
        {
            if (pBridge->GetVolume(fVolume))
            {
                YI_LOGE(LOG_TAG, "Volume changed to %.2f", fVolume);
            }
        }
    }
};

Device Information

The CYIDeviceInformationBridge provides system information about the device on which the application is running.

#include <platform/YiDeviceBridgeLocator.h>
#include <platform/YiDeviceInformationBridge.h>

static void LogDeviceInformation()
{
    CYIDeviceInformationBridge *pBridge = CYIDeviceBridgeLocator::GetDeviceInformationBridge();
    if (pBridge)
    {
        YI_LOGI(LOG_TAG, "Device model:           %s", pBridge->GetDeviceModel().GetData());
        YI_LOGI(LOG_TAG, "Device UID:             %s", pBridge->GetDeviceUID().GetData());
        YI_LOGI(LOG_TAG, "Device OS:              %s", pBridge->GetDeviceOSName().GetData());
        YI_LOGI(LOG_TAG, "Device OS vertion:      %s", pBridge->GetOSVersion().GetData());
        const CYIString hardwareBackButtonStatus = CYIString::FromBool(pBridge->HasHardwareBackButton());
        YI_LOGI(LOG_TAG, "Device has back button: %s", hardwareBackButtonStatus.GetData());
    }
}

Power Management

The CYIDevicePowerManagementBridge allows applications to keep screens on during long periods on inactivity. This bridge is available only on mobile platforms. Allows mobile devices to stay on during long period of inactivity.

#include <platform/YiDeviceBridgeLocator.h>
#include <platform/YiDevicePowerManagementBridge.h>

static void KeepScreenOn()
{
    CYIDevicePowerManagementBridge *pBridge = CYIDeviceBridgeLocator::GetDevicePowerManagementBridge();
    if (pBridge)
    {
        pBridge->KeepDeviceScreenOn(true);
    }
}

Device Type

The CYIDeviceTypeBridge can be used to obtain the type of device your application is running on. The bridge is available on all platforms. This bridge will return a CYIDeviceTypeBridge::DEVICE_TYPE. The bridge can also be used to to configure the size cutoff for each device type. The cutoff is used when the type cannot be determined though other means.

#include <platform/YiDeviceBridgeLocator.h>
#include <platform/YiDevicePowerManagementBridge.h>

static CYIDeviceTypeBridge::DEVICE_TYPE GetDeviceType()
{
    CYIDeviceTypeBridge *pBridge = CYIDeviceBridgeLocator::GetDeviceTypeBridge();
    if (pBridge)
    {
        return pBridge->GetDeviceType();
    }
    else
    {
        return CYIDeviceTypeBridge::UNKNOWN;
    }
}

Locale

The CYILocaleBridge provides the locale of the system on which the application is running. It will be expressed with a language code and a country code. The language will be a 2 character ISO-639-1 code and the country code is a 2 character ISO-3166-1 code.

#include <platform/YiLocaleBridge.h>
#include <platform/YiSystemInformationBridgeLocator.h>

static void LogSystemLocale()
{
    CYILocaleBridge *pBridge = CYISystemInformationBridgeLocator::GetLocaleBridge();
    if (pBridge)
    {
        CYIString languageCode, countryCode;
        if (pBridge->GetLocale(languageCode, countryCode))
        {
            YI_LOGI(LOG_TAG, "System locale is %s-%s", languageCode.GetData(), countryCode.GetData());
        }
    }
}

App Life Cycle

CYIAppLifeCycleBridge provides indications of when the application enters the background and foreground.

#include <platform/YiAppLifeCycleBridge.h>
#include <platform/YiAppLifeCycleBridgeLocator.h>

class AppLifeCylceListener : public CYISignalHandler
{
public:
    AppLifeCylceListener()
    {
        CYIAppLifeCycleBridge *pBridge = CYIAppLifeCycleBridgeLocator::GetAppLifeCycleBridge();
        if (pBridge)
        {
            pBridge->ForegroundEntered.Connect(*this, &AppLifeCylceListener::OnForegroundEntered);
            pBridge->BackgroundEntered.Connect(*this, &AppLifeCylceListener::OnBackgroundEntered);
        }
    }

    void OnForegroundEntered()
    {
        YI_LOGE(LOG_TAG, "Foreground entered");
    }
    
    void OnBackgroundEntered()
    {
        YI_LOGE(LOG_TAG, "Foreground entered");
    }
};

Secure Storage

You.i Engine provides a solution for each platform to store data securely. The CYISecureStorageBridge class uses an AES-128 bit encryption algorithm that will ensure that data is stored in a secure manner. There are some storage limitations on some platforms. Check the OS API documentation for each platform.

#include <platform/YiSecureStorageBridge.h>
#include <platform/YiStorageBridgeLocator.h>

static const CYIString PASSWORD_STORE_NAME = "PasswordStore";
static const CYIString PASSWORD_KEY_NAME = "password";

class SecureStorageUser
{
    void InitializeSecureStorage()
    {
        CYISecureStorageBridge *pBridge = CYIStorageBridgeLocator::GetSecureStorageBridge(PASSWORD_STORE_NAME);
        if (pBridge)
        {
            //Set the encryption key required by AES.
            pBridge->SetEncryptionKey("MyEncryptionKey");
        }
    }

    void SetPassword(const CYIString &password)
    {
        CYISecureStorageBridge *pBridge = CYIStorageBridgeLocator::GetSecureStorageBridge(PASSWORD_STORE_NAME);
        if (pBridge)
        {
            //Stores the value on the platform's device.
            pBridge->StoreValue(PASSWORD_KEY_NAME, password);
        }
        else
        {
            //Secure storage is not available on this platform, fall back to in memory storage
            m_password = password;
        }
    }

    CYIString GetPassword()
    {
        CYISecureStorageBridge *pBridge = CYIStorageBridgeLocator::GetSecureStorageBridge(PASSWORD_STORE_NAME);
        if (pBridge)
        {
            return pBridge->RetrieveValue(PASSWORD_KEY_NAME);
        }
        else
        {
            //Secure storage is not available on this platform, fall back to in memory storage
            return m_password;
        }
    }

    CYIString m_password;
};

Network Information

The CYINetworkInformationBridge listens to the state of the network. The network state can be observed by calling CYINetworkInformationBridge::StartNetworkStateListener. When the network state changes the emitted by the CYINetworkInformationBridge::NetworkStateChanged signal will emit the old and new CYINetworkInformationBridge::NETWORK_TYPE. The current network state can also be retrieved using CYINetworkInformationBridge::GetNetworkType(). This bridge is available on all platforms.

#include <network/YiNetworkBridgeLocator.h>
#include <network/YiNetworkInformationBridge.h>

class NetworkStateListener : public CYISignalHandler
{
public:
    NetworkStateListener()
    {
        CYINetworkInformationBridge *pBridge = CYINetworkBridgeLocator::GetNetworkInformationBridge();
        if (pBridge)
        {
            pBridge->NetworkStateChanged.Connect(*this, &NetworkStateListener::OnNetworkStateChanged);
            pBridge->StartNetworkStateListener();
        }
    }

    void OnNetworkStateChanged(const CYINetworkInformationBridge::NETWORK_TYPE eNewNetworkType, const CYINetworkInformationBridge::NETWORK_TYPE eOldNetworkType)
    {
        YI_LOGE(LOG_TAG, "Network state changed from %d, to %d", eOldNetworkType, eNewNetworkType);
    }
};

Telephony Information

the CYITelephonyInformationBridge can be used to listen to the state of phone calls. The state of calls can be observed by calling CYITelephonyInformationBridge::StartObservingCallStateChanges. When the state of a phone call changes the CYITelephonyInformationBridge::CallStateChanged signal will be emitted with the CYITelephonyInformationBridge::CALL_STATE. This bridge is only available on mobile platforms.

#include <platform/YiCommunicationsBridgeLocator.h>
#include <platform/YiTelephonyInformationBridge.h>

class TelephonyStateListener : public CYISignalHandler
{
public:
    TelephonyStateListener()
    {
        CYITelephonyInformationBridge *pBridge = CYICommunicationsBridgeLocator::GetTelephonyInformationBridge();
        if (pBridge)
        {
            pBridge->CallStateChanged.Connect(*this, &TelephonyStateListener::OnCallStateChanged);
            pBridge->StartObservingCallStateChanges();
        }
    }

    void OnCallStateChanged(const CYITelephonyInformationBridge::CALL_STATE eNewCallState)
    {
        YI_LOGE(LOG_TAG, "Call state changed to %d", eNewCallState);
    }
};

Web Browser

The CYIWebBrowserBridge opens a web browser as an external application. This bridge is available on all mobile platforms.

#include <platform/YiWebBridgeLocator.h>
#include <platform/YiWebBrowserBridge.h>

static void OpenYouiTVInBrowser()
{
    CYIWebBrowserBridge *pBridge = CYIWebBridgeLocator::GetWebBrowserBridge();
    if (pBridge)
    {
        pBridge->OpenWebBrowser(CYIUrl("http://www.youi.tv"));
    }
}

Deprecated Web View

Deprecated:

This class has been deprecated and may be removed in a future release. The CYIWebViewController class should be used instead.

The yi::deprecated::CYIWebViewBridge opens a web view from within the application. This bridge is available on all mobile platforms.

This bridge is instantiated through the CYIWebBridgeLocator class.

Closed Captions Status

The CYIClosedCaptionsStatusBridge provides access to the operating system setting for whether closed captioning is enabled. The status can be queried and notifications are available for when the status is changed.

#include <platform/YiAccessibilityInformationBridgeLocator.h>
#include <platform/YiClosedCaptionsStatusBridge.h>

class ClosedCaptionsStateListener : public CYISignalHandler
{
public:
    ClosedCaptionsStateListener()
    {
        CYIClosedCaptionsStatusBridge *pBridge = CYIAccessibilityInformationBridgeLocator::GetClosedCaptionsStatusBridge();
        if (pBridge)
        {
            pBridge->ClosedCaptionsStatusChanged.Connect(*this, &ClosedCaptionsStateListener::OnClosedCaptionStatusChanged);
            pBridge->StartObservingStatusChanges();
        }
    }

    void OnClosedCaptionStatusChanged(bool bClosedCaptionsEnabled)
    {
        CYIString state;
        if(bClosedCaptionsEnabled)
        {
            state = "enabled";
        }
        else
        {
            state = "disabled";
        }
        YI_LOGE(LOG_TAG, "Closed captions have been %s.", state.GetData());
    }
};

Closed Captions Styling

Provides access to the operating system settings for closed captioning style.

#include <platform/YiAccessibilityInformationBridgeLocator.h>
#include <player/YiClosedCaptionsStylingBridge.h>

static CYIClosedCaptionsStylingBridge::Style GetClosedCaptionsStyle()
{
    CYIClosedCaptionsStylingBridge *pBridge = CYIAccessibilityInformationBridgeLocator::GetClosedCaptionsStylingBridge();
    if (pBridge)
    {
        return pBridge->GetClosedCaptionsStyle();
    }
    else
    {
        return CYIClosedCaptionsStylingBridge::GetDefaultStyle();
    }
}

Native Views

Native platform views can be added to You.i Engine applications using CYIPlatformView. The CYIPlatformView is a specialized view which combines the uses of an engine view (created through view templates) and a native platform view. The position and bounds of the native view will be set to the size of the CYIPlatformView. The CYIPlatformView supports programatically swapping out the CYIPlatformViewProxy at any time. The user can use the CYIPlatformView and timelines on the CYIPlatformView to position and animate the native platform view. Native platform views can be used on iOS, and Android handsets and tablets.

CYIPlatformView is a view created by the engine through view templates. Once the CYIPlatformView is initialized, the user must then externally create the native platform view and create a CYIPlatformViewProxy. The CYIPlatformViewProxy can be created by calling CYIPlatformViewProxy::CreateIfSupported(). Once the proxy is created, a handle to the native view can be set using CYIPlatformViewProxy::SetPlatformViewHandle(). The CYIPlatformViewProxy takes a CYIPlatformViewHandle. On Android a CYIPlatformViewHandleAndroid, and on iOS a CYIPlatformViewHandleIOS which are wrappers for android.view.View and UIView respectively.

Note

The CYIPlatformViewHandleAndroid takes a JNI object refererence to an android View.

    jobject view = GetNativePlatformView();
    CYIPlatformViewHandleAndroid viewHandle(view);

    UIView *view = GetNativePlatformView();
    CYIPlatformViewHandleIOS viewHandle(view);

    CYIPlatformView *pPlatformView = pSceneViewMain->GetNode<CYIPlatformView>("ViewName");
    std::unique_ptr<CYIPlatformViewProxy> pViewProxy = CYIPlatformViewProxy::CreateIfSupported();

    if (pViewProxy)
    {
        pViewProxy->SetPlatformViewHandle(viewHandle);
        pPlatformView->SetViewProxy(pViewProxy.get());
    }

Web Views

Web views can be added to You.i Engine applications using CYIWebView. CYIWebView automatically creates an instance of CYIWebViewController on supported platforms. A CYIPlatformView is used to display the web content, and the CYIPlatformViewProxy for each web view can be retreived from a CYIWebViewController. Web views can be used on iOS, and Android handsets and tablets.

    CYIWebView *pWebView = pSceneViewMain->GetNode<CYIWebView>("ViewName");
    CYIWebViewController *pWebViewController = pWebView->GetWebViewController();
    if (pWebViewController)
    {
        pWebViewController->LoadUrl(CYIUrl("http://www.youi.tv"));
    }

Namespaces
	yi::deprecated
	Deprecated classes.

Classes
class	CYIConnectivity
	A class used to perform active network connectivity checks. More...
class	CYINetworkBridgeLocator
class	CYINetworkInformationBridge
	CYINetworkInformationBridge contains functions relating to device network state. More...
class	CYIAccessibilityInformationBridgeLocator
	Instantiates bridges having to do with accessibility options. The bridge instances are deleted automatically when the application is terminated. More...
class	CYIApplicationNavigationBarBridge
	Interacts with the system's navigation bar. More...
class	CYIApplicationOrientationBridge
	Interacts with the application's orientation functionality. More...
class	CYIApplicationStatusBarBridge
	Interacts with the applications status bar. More...
class	CYIApplicationUIBridgeLocator
	Instantiates the application user interface oriented bridges; the instance will be deleted automatically when the application is terminated. The CYIApplicationNavigationBarBridge is available only on Android. More...
class	CYIAppLifeCycleBridge
	Provides a means for apps to signal components that the app has entered the foreground or background. More...
class	CYIAppLifeCycleBridgeLocator
	Instantiates the CYIAppLifeCycleBridge; the instance will be deleted automatically when the application is terminated. More...
class	CYIAudioBridgeLocator
	Instantiates the audio oriented bridges; the instance will be deleted automatically when the application is terminated. More...
class	CYIAudioVolumeBridge
	Volume bridge which supports the manipulation of the platform's audio volume settings. More...
class	CYIClosedCaptionsStatusBridge
	A bridge which reports operating system closed captions settings. More...
class	CYICommunicationsBridgeLocator
	Instantiates the communications oriented bridges; the instance will be deleted automatically when the application is terminated. More...
class	CYIDeviceBridgeLocator
	Instantiates the device oriented bridges; the instance will be deleted automatically when the application is terminated. More...
class	CYIDeviceInformationBridge
	Provides information about the device running the application. More...
class	CYIDevicePowerManagementBridge
	Utility functions for accessing device power management features. More...
class	CYIDeviceTypeBridge
	A bridge which provides the type of device that the application is currently running on. More...
class	CYIInputBridgeLocator
	Instantiates the input bridges; the instance will be deleted automatically when the application is terminated. More...
class	CYILocaleBridge
	Utility function to retrieve the current system locale. More...
class	CYIPlatformView
	CYIPlatformView is a specialized view which combines the uses of an engine view (created through view templates) and a native platform view. This allows users to better integrate native platform views with applications created by You.i Engine. The user can also use values and timelines taken from view templates to position or animate the native platform view. More...
class	CYIPlatformViewHandle
	The CYIPlatformViewHandle is a wrapper object that holds on to the native platform view. More...
class	CYIPlatformViewHandleAndroid
	The CYIPlatformViewHandleAndroid is a wrapper object which holds on to an Android native platform view. More...
class	CYIPlatformViewHandleIOS
	The CYIPlatformViewHandleIOS is a wrapper object which holds on to an iOS native platform view. More...
class	CYIPlatformViewProxy
	A proxy representation for a platform-native view. More...
class	CYISecureStorageBridge
	This class is used to securely store a specific key-value pair. More...
class	CYIStorageBridgeLocator
	Instantiates the device storage oriented bridges; the instance will be deleted automatically when the application is terminated. More...
class	CYISystemInformationBridgeLocator
	Instantiates the system information oriented bridges; the instance will be deleted automatically when the application is terminated. More...
class	CYITelephonyInformationBridge
	Telephony bridge which supports listening to the state of phone calls. More...
class	CYIWebBridgeLocator
	Instantiates the web browser oriented bridges; the instance will be deleted automatically when the application is terminated. More...
class	CYIWebBrowserBridge
	Utility to open a web browser as an external application. This is in contrast to a CYIWebViewBridge which can be used to open a web view in the same process as the application. More...
class	CYIWebView
	A visual representation of web content with basic navigation controls. More...
class	CYIWebViewController
	Provides an interface to a platform web view, if available. More...
class	CYIClosedCaptionsStylingBridge
	A bridge which reports operating system closed captions style. More...