Vibration native extension sample

Note: By clicking the download link for any source examples on this page, you acknowledge that you have read and agree to the Adobe AIR SDK License Agreement. These files are considered Sample Code.

Note: Adobe recommends using the next version of Flash Builder for developing native extensions for Adobe AIR. Sign up now to get access to the prerelease of Flash Builder 4.6.

The Vibration class is a native extension for Adobe AIR. It allows AIR application developers, from ActionScript, to use the vibration feature of an Android or iOS mobile device.

The attached ZIP file contains:

• The ActionScript library in the directory VibrationActionScriptLibrary: This directory contains the Flash Builder project for creating the ActionScript side of the Vibration extension.
• The Android native library in the directory VibrationAndroidLibrary: This directory contains an Eclipse project for creating the Android native side of the Vibration extension. To build the Eclipse project, first copy FlashRuntimeExtension.jar from <AIR_SDK>/lib/android/FlashRuntimeExtensions.jar to the directory VibrationAndroidLibrary\libs.
  
• The iOS native library in the directory VibrationiOSLibrary: This directory contains an Xcode project for creating the iOS native side of the Vibration extension. To build the Xcode project, first copy FlashRuntimeExtension.h from <AIR_SDK>/include/FlashRuntimeExtensions.h to the directory
   VibrationiOSLibrary.
  
• A directory called ReadyToUseExtension: This directory contains everything the AIR application developer needs to use the native extension: the ANE file, the SWC file, and a text file that contains the extension ID.
• A directory called TestVibrationExtension: This directory contains a sample AIR application that uses the Vibration native extension.

The ActionScript library contains the Vibration class. The Vibration class provides the AIR application this public property and method:

• public static function get isSupported(): Boolean
• public function vibrate(duration:Number): void

The AIR application can create many instances of the Vibration class. However, the Vibration class creates only one ExtensionContext class instance that all the Vibration instances share.

To use the Vibration extension, an AIR application does the following:

• Checks if the extension is supported by calling isSupported.
• Causes the device to vibrate by calling vibrate(), specifying the duration of the vibration in milliseconds as a parameter.

For example:

Android applications

For an Android application, include the Vibration permission in your application descriptor file:

iOS applications

For an iOS application:

• The isSupported property always returns true. On iOS devices, no native API is available to determine whether the vibration feature is supported.
• The duration value passed to vibrate() is ignored. The device vibrates for a duration determined by iOS.

The Android native library is implemented in Java, using the native extension Java API. The native library includes the following classes:

• VibrationExtension implements FREExtension
• VibrationExtensionContext extends FREContext
• VibrationSupportedFunction, VibrationInitNativeCode, and VibrationVibrateFunction each implement FREFunction

The native library also contains examples of using these FREObject methods:

• getAsInt()
• newObject()

In its initialization, the native library uses the getActivity() method of the FREContext class to get the application's Android Activity. Using the returned Activity, the initialization method, which is VibrationInitNativeCodeFunction.call(), gets the vibration service:

Note: The call from the ActionScript side to ExtensionContext.createExtensionContext() must return before the native library can call methods of the object derived from the FREContext class. Therefore, the call vibExtContext.getActivity() occurs in the initialization function that the ActionScript side calls after the return from createExtensionContext(). The call to getActivity() cannot occur in the FREContext object constructor.

The iOS native library is implemented in Objective C, using the native extension C API. The native library contains examples of these native extension C APIs:

• The extension initializer and finalizer, using the signatures of FREInitializer() and FREFinalizer().
• The context initializer and finalizer, using the signatures of FREContextInitializer() and FREContextFinalizer().
• Native functions, using the signature of FREFunction(). The native functions are IsSupported(), InitNativeCode(), and VibrateDevice().
• FRENewObjectFromBool()

The function VibrateDevice() calls the iOS API AudioServicesPlaySystemSound() to vibrate the device. However, if the device does not support vibration, this iOS API call does nothing.

Note: In the iOS native implementation, no initialization is necessary, and so the initialization native function, InitNativeCode(), does nothing. However, the function is necessary because the Android native implementation requires an initialization function. Therefore, to make the extension’s ActionScript interface the same for all native implementations, the iOS native implementation provides the stub.

For more information about developing native extensions for Adobe AIR, see:

• Extending Adobe AIR
• Developing Native Extensions for Adobe AIR
• Adobe native extension samples

For more information about using a native extension in an AIR application, see:

• Using native extensions for Adobe AIR