System and OS

System Library

system.getInfo( param )
Returns information about the system on which the application is running. The first argument param is a string that determines what is returned. Here are the valid values for param:

  • "name" returns the human readable name of the device. On iPhone, this would be the name of the phone as it appears in iTunes, e.g. "Steve's iPhone".
  • "model" returns the human readable model name, such as "iPhone".
  • "deviceID" returns the unique id of the device, e.g. IMEI or similar number
  • "environment" returns the environment that the app is running in. These include:
    • "simulator" the Corona Simulator
    • "device" the device or platform-specific simulator (e.g. Xcode simulator)
  • "platformName" returns the platform name, e.g. the OS name:
    • "Mac OS X"
    • "iPhone OS"
    • "Android"
  • "platformVersion" returns a string representation of the platform version. This is sometimes, but not always, a number -- for example a Droid X is currently returning "2.1-update1".
  • "version" returns the version of Corona used as it appears in the About box of the Corona Simulator.
  • "build" returns the Corona build string as it appears in the About box of the Corona Simulator.
  • "textureMemoryUsed" returns the texture memory usage (in bytes). Texture memory tends to be the most sharply limited resource in mobile development, since it runs out before normal memory.
  • "maxTextureSize" returns the maximum texture width or height supported by the device.
  • "architectureInfo" returns a string describing the underlying CPU architecture of the device the code is running on. Strings may be subject to changes in the future depending on the changing landscape of devices and CPUs.

system.getPreference( category, name )
Returns a preference value as a string. Valid values of category are:

  • "ui" for general application-level preferences. In this category, pass "language" for the name parameter to get the preferred language.
  • "locale" for locale preferences. In this category, valid name parameters include "country", "identifier", and "language".

system.getTimer()
Returns time in milliseconds since application launch.

system.openURL( url )
Opens url. NOTE: we may change this slightly.

Supported url formats for the iPhone:

  • Mail links: mailto:nobody@mycompany.com
  • Phone links: tel:415-867-5309
  • Web links: http://www.anscamobile.com

system.pathForFile( filename [, baseDirectory] )
Generates an absolute path using system-defined directories as the base (see System-defined directories below). A second, optional parameter baseDirectory specifies which base directory is used to construct the full path; its default value is system.ResourceDirectory. If the base directory is system.ResourceDirectory and the generated path points to a non-existent file, nil is returned.

system.setAccelerometerInterval( frequency )
Sets the frequency of accelerometer events that will be requested. The min frequency Corona allows without warning is 10 Hz and the max is 100 Hz, but the actual maximum that can be achieved depends on the available hardware. Unfortunately for the developer, testing has shown that if the requested value exceeds what the device allows, the resulting behavior may be unpredictable. For iOS a reasonable maximum is the frame update interval of the device (usually 30 or 60 Hz). Accelerometer events are a significant drain on battery, so only increase the frequency when you need faster responses as in games. Always try to lower the frequency whenever possible to conserve battery life.

system.setIdleTimer( enabled )
Controls whether the idle timer is enabled. If enabled is true, the timer will be active (default); inactive if false. When active, the idle timer dims the screen and eventually puts the device to sleep when no user activity occurs (e.g. screen touches).

system.setLocationAccuracy( distance )
Sets the desired accuracy of location events to distance meters. Note: the actual accuracy depends on the capabilities of the device and/or platform. On the iPhone, accuracy is limited to discrete distances: <10, 10, 100, 1000, and 3000. Higher accuracy (smaller distances) requires more battery life, so use larger distance to preserve battery life.

system.setLocationThreshold( distance )
Sets how much distance in meters must be travelled until the next location event is sent. Because location events involve hardware that can drain the battery, using larger threshold distances preserve battery life.

system.vibrate()
Vibrates the phone.

System-defined directories

The following are constants for base directories to be used with system.pathForFile().

system.DocumentsDirectory should be used for files that need to persist between application sessions. Under the simulator, the user's documents directory is used, e.g. "~/Documents"

system.TemporaryDirectory is a temporary directory. Files written to this directory are not guaranteed to exist in subsequent application sessions. They might exist or they might not.

system.ResourceDirectory is the directory where all application assets exist. On the simulator, this corresponds to files located in the assets folder of your project. For example, this is the default location where display.newImage() looks for image files. Note: you should never create, modify, or add files to this directory. Doing so will prevent the device from verifying the integrity of your application; in some cases, the device will treat your application as malware and refuse to launch your application.

Note

system.ResourceDirectory, as such, does not exist on Android. Android applications are packaged into an .apk, which is basically a ZIP file, and cannot be read as normal files. Assets fall into the following categories:

  • Images, which are loaded directly using native Android APIs.
  • Sounds, also loaded directly using native Android APIs.
  • Other data files that you want to access from your Corona app.

On iOS, system.pathForFile( "data.txt", system.ResourceDirectory ) returns a path to a file in the application resource bundle. This is a directory and files in it may be read normally. On Android, however, the application is delivered in a .apk file. It is not possible to use normal file I/O to access its contents. To allow Corona apps to include generic data files on Android, system.pathForFile has an additional behavior. It copies the resource file from the ZIP archive to a private storage directory associated with the application and then returns the path to that file. Note that the storage on an actual device may be limited. You should not use this facility for large files, and if the device runs out of space, then the data copy may fail.