The System API is used to control and modify core aspects of the device such as the screen, OS and device capabilities. ## Enabling the API This API is part of the `coreapi` extension that is included automatically. :::ruby extensions: ["coreapi"] ## JavaScript Usage Be sure to review the [JavaScript API Usage](/guide/api_js) guide for important information about using this API in JavaScript. ## Ruby Usage Be sure to review the [Ruby API Usage](/guide/api_ruby) guide for important information about using this API in Ruby. ## Enabling the API There are two methods of enabling the System API: * Include all ebapi modules or * Include only the API modules you need For either of these methods, you'll need to include files from the `/Enterprise Browser/JavaScript Files/Enterprise Browser` directory on the computer that you installed the Enterprise Browser. ### Include all JS API modules To include all JS APIs, you must copy the ebapi-modules.js file to a location accessible by your app's files and include the JavaScript file in your app. For instance, to include the modules file in your index.html, with the file in the same directory as your index.html, you would add the following line to the <head> section of your index.html: :::html <script type="text/javascript" charset="utf-8" src="ebapi-modules.js"></script> > Note: that the pathing for this file is relative to the current page. This will define the EB class within the page. Any page you need to use the modules will need to have the .js file included in this fashion. ### Include only the modules you need To include single APIs, you must first include the `ebapi.js` in your HTML as well as the API file you want to use. For instance, to use the System API, I would add the following code to my HTML file(s), assuming the API files have been copied to the same directory as the HTML. :::html <script type="text/javascript" charset="utf-8" src="ebapi.js"></script> <script type="text/javascript" charset="utf-8" src="eb.system.js"></script> The ebapi.js file is necessary for all single API inclusions. The System API supports the following properties. It is internal property for using in debugger (signal for main window close). Platform where application is running. WM, CE, Win32, Android Returns true if there is a camera available on the device. Screen width in logical pixels (used for set coordinates). Screen height in logical pixels (used for set coordinates). Screen width in real pixels. Screen height in real pixels. Current screen orientation. The return value if the screen is in portrait mode. The return value if the screen is in landscape mode. Horizontal PPI (Pixels Per Inch). Vertical PPI (Pixels Per Inch). Primary email of phone owner. To access this property 'pim' capability must be enabled in your build.yml. Android Name(account name) of phone owner. To access this property 'pim' capability must be enabled in your build.yml. Android Push notifications device ID which may be used to receive push messages.To get this ID , Push service should be configured on the device. Please refer to Push documentation. Hardware based ID. It depends on capabilities configured for an application and has to remain same even across application uninstall/install. WM, CE, Android Name of device application running on. Examples: '9000' (BB), 'iPhone', 'dream' (Android). Version OS of device. Examples: '4.1' (Android). Current device locale Like 'en', 'ru' etc. Current device country code. Returns true if the application is running on a platform emulator. Returns true if the application is running on RhoSimulator. Returns true if calendar support is available. Returns true if the device supports Symbol device capabilities. APIs will indicate if the property or method is available on Symbol devices only. You can use this property to help your application decide when to take advantage of advanced Symbol capabilities. Returns true if the device supports Motorola device capabilities. APIs will indicate if the property or method is available on Motorola devices only. You can use this property to help your application decide when to take advantage of advanced Motorola capabilities. This property has been deprecated. It is recommended to use 'isSymbolDevice' property. The OEM Information string for the terminal. WM, CE, Android The Unique Unit IDentifier for the terminal. WM, CE, Android Set the application icon to have this badge number. Set to 0 (zero) to remove badge. iOS Set HTTP proxy parameters for using by Network module. Example: user:password@url:port . Support only basic authentication. Setting the property overrides http_proxy_uri (or http_proxy_host, http_proxy_port, http_proxy_user, http_proxy_password). To set proxy for WebKit for Windows Mobile/CE use config.xml settings. Android, iOS, WM, Win32 WM, Win32, Android Lock / unlock the window size change by the user. When running on RhoSimulator, this method is supported only for Windows OS. Win32 For Windows Mobile and Windows CE the keyboard can be manually shown or hidden as required. All other platforms only support 'automatic'. The default state for Windows Mobile and Windows CE is manual, for all other platforms it is automatic. WM Shows the on screen keyboard, after setting the keyboard to shown or hidden it will no longer appear / disappear automatically until you set this property to automatic. Hides the on screen keyboard, after setting the keyboard to shown or hidden it will no longer appear / disappear automatically until you set this property to automatic. This is most useful if your device has a hardware keyboard or you are scanning / capturing data to an input field. Automatically shows or hides the keyboard as needed by the application. Port of the local (embedded) HTTP server. This parameter is mainly for debug purposes. If not specified, the platform will detect a free port on the device and use that one. Get free local server port, available for binding. Screen auto rotate. Android, iOS Android Returns true if the device has touch screen capabilities. For Win32 desktop builds this API will return whether mouse support is available. Browser framework identity string. If true, then screen will go to sleep by system inactivity timeout. If false then screen never go to sleep while application is in foreground. Android, iOS WM, Android Use Network.hasNetwork to tell if the device is connected to the network. Use Network.hasWifiNetwork to tell if the device is connected to the wifi network. Use Network.hasCellNetwork to tell if device is connected to the cell network. Returns true if the device has sqlite capabilities (previously only BlackBerry did not support this). Use property names methods instead. Install an application. iOS, WM, Win32, Android WM, Win32, Android The url of an application to install on the device. Checks if the specified applicationName is installed on the device. iOS, WM, Win32, Android WM, Win32, Android The name of the application. Uninstall the application. Not Supported on Windows CE devices. WM, Win32, Android The name of the application. Return the command line parameters. At Android start parameters are returned as URL query string starting with '?', name-value delimiter '=' and name value pairs delimiter '&'. WM, CE, Win32, Android Open the application associated with the URL. Behavior may be different on different platforms and depend on installed software. For example, open URL with http:// prefix will execute the Web Browser installed on system and open URL in executed browser. Note: For opening pdf files on android devices it is necessary to add option "no_compression: [ pdf ]" to android section in build.yml Open the application associated with the URL. Behavior may be different on different platforms and depend on installed software. For example, open URL with http:// prefix will execute the Web Browser installed on system and open URL in executed browser. Note: Opening pdf files on Android devices is not supported. URL as string. Unzip file. The path to the file to be unzipped. Application should have write permissions to this folder. Password for the zip. Output file name. Used when decompressing gzip streams. Zip one file. Zip archive must placed to the folder where application can write files. The path to the specified zip. Application should have write permissions to this folder. The path to the file to be zipped. Password for the zip. Zip list of files. The path to the specified zip. Base path to the files to be zipped. List of file paths to be zipped. Password for the zip. Set a value in the device registry. Only applicable on Windows Mobile / Embedded Handheld and CE devices. When running on RhoSimulator, this method is supported only for Windows OS. Set a value in the device registry. Only applicable on Windows Mobile / Embedded Handheld and CE devices. WM Map of properties associated with the registry key being set. The hive name. Set the property in the HKEY_CLASSES_ROOT hive. Set the property in the HKEY_CURRENT_USER hive. Set the property in the HKEY_LOCAL_MACHINE hive. Set the property in the HKEY_USERS hive. The type. The type of the value being set is a string. The type of the value being set is a binary number. The type of the value being set is a natural number (DWORD) The type of the value being set is a multi line string. Separate your lines with \n (\\n in JavaScript) Full path of the key, including '\' separators as required. Remember to use '\\' in JavaScript to specify backslash. The name of the registry setting to be set. The registry value to be set. Whether or not to create a corresponding merge file, setting to true will cause your value to persist across a device clean boot. A .reg file is written to the \Application folder on the device to persist the setting. Whether or not the registry key was successfully set. Retrieve a value from the device registry. Only applicable on Windows Mobile / Embedded Handheld and CE devices. When running on RhoSimulator, this method is supported only for Windows OS. Retrieve a value from the device registry. Only applicable on Windows Mobile / Embedded Handheld and CE devices. WM Map of properties associated with the registry key being set. The hive name, see setRegistrySetting. Full path of the key, including '\' separators as required. Remember to use '\\' in JavaScript to specify backslash. The name of the setting to be retrieved. Registry value of the key. Deletes the specified value from the device registry. Only applicable on Windows Mobile / Embedded Handheld and CE devices. When running on RhoSimulator, this method is supported only for Windows OS. Deletes the specified value from the device registry. Only applicable on Windows Mobile / Embedded Handheld and CE devices. WM Map of properties associated with the registry key being set. The hive name, setRegistrySetting. Full path of the key, including '\' separators as required. Remember to use '\\' in JavaScript to specify backslash. The name of the setting to be deleted. If the registry value was set to be persistent, ie a corresponding .reg file was created in the \Application folder then setting true here will delete that .reg file. Whether or not the registry key was successfully deleted. Change application window position and size. Win32 Left corner of window. Top corner of window. Width of window. Height of window. Change application window position. Win32 Left corner of window. Top corner of window. Change application window size. Win32 Width of the window. Width of the of window. Bring application window to the top of the screen. WM Replace application bundle. Local path to bundle folder. See Build Application/Upgrade Application section to find out how to build bundle on computer. Update parameters. If true, when Application will not be automatically restarted after the replace bundle is finished. Delete folder. Path to folder. Set do not backup attribute for file. iOS Path to file. True set doNotBackup attribute to file (exclude this file from backup), false for remove doNotBackup attribute from file. Use Database.SQLite3.isBlobAttr: is model attribute is blob. Use Database.updateBlobAttribs: update model blob attributes list. Use System.locale property: Current device locale. Use Application.setLocale method: set application specific locale. Use Push.setPushNotification: Register push callback, the method to call upon receiving a push message. URL of the callback method. If empty, unregisters rhoconnect-push. Parameters which will be added to callback URL. Name of a push service client. Current values can be 'rhoconnect_push' or 'gcm' or 'legacy' or empty. The call will be applied to every push client. Use ScreenOrientation.setScreenOrientationEvent: Notify (call a callback method) when the screen rotates. iOS, Android, WM WM, Android URL of the callback method. If empty, unregisters notification callback. Parameters which will be added to callback URL. Use Application.quit: exit application. Use System.screenSleeping property: enable / disable phone sleeping. Start timer. (It's works only with Ruby) Timer interval. URL of the callback method. Parameters which will be added to callback URL. Stop timer. (It's works only with Ruby) URL of the callback method which identify the timer to stop. Use Network.setStatusNotify: set network notification callback. The url to the user-defined callback method. IOS. The network status polling period for systems that can not notify network status change immediately. Default value is 20 seconds. Use Network.clearStatusNotify: Clear network status callback. Use System.httpProxyURI property: To use client with the HTTP proxy. WM, CE, WIN32 Use System.httpProxyURI property: Stop using HTTP proxy that was set by the command line, rhoconfig.txt or set_http_proxy_url. WM, CE, WIN32 Use System.applicationIconBadge: Set the application icon to have this badge number. Set to 0 (zero) to remove badge.iOS only. iOS Run an application. iOS, WM, Win32, Android WM, Win32, Android The name of the application on the device to run. It depends from platform. On iOS it is BundleURLScheme of executed application. The name of the application on the device to run. Start parameters string. Executed Application can receive this string by getStartParams method. Parameter could be just value, or key-value pair separated by '=' sign. Please note that for each platform there are distinct ways to write several params at once. On Android parameters should be separated by an amperstand, on other platforms by a comma or a space. Not Implemented. False by default. Hide Splash Screen if delay is configured as -1 in rhoconfig.txt Android 1.0.0 iOS, WM, Win32, WP8, Android WM, Win32, Android
You can find out whether the device has access to several system-dependent features such as calendar, camera, touchscreen, etc.
Retrieve the version of the underlying Operating System.
You can ask the system to install or uninstall a different application. This feature is useful for installing sub-applications, custom upgrades, etc.
If necessary, you can read the embedded HTTP server's port, for debugging purposes.
If you ever need to build or extract zip archives, RhoMobile includes easy-to-use APIs for this task.
On devices running Windows Mobile, Windows CE, Windows Embedded Handheld and Windows Embedded CE it is possible to interact with the registry, this example shows how to do that.