Defines | |
| #define | ALP_APP_ALARM "--alp-alarm" |
| The application is being launched because one of its alarms went off. | |
| #define | ALP_APP_ALARM_REASON "--alp-alarm-reason" |
| Indicate that reason for the alarm event. | |
| #define | ALP_APP_ALLOW_EARLY "--alp-allow-early" |
| Forces the application to be launched even if the system is not yet fully booted. | |
| #define | ALP_APP_BACKGROUNDED "--alp-backgrounded" |
| The application is no longer the primary UI app. | |
| #define | ALP_APP_CLOSE_SESSION "--alp-close-session" |
| The application is being launched so that it can close open postal service sessions. | |
| #define | ALP_APP_DEBUG "--alp-debug" |
| Indicates that the application should be prepared for debugging. | |
| #define | ALP_APP_DISPLAY "--alp-display" |
| The application should display a particular piece of data. | |
| #define | ALP_APP_EXCHANGE "--alp-exchange" |
| The application is being launched or relaunched to run an exchange handler. | |
| #define | ALP_APP_FIND "--alp-find" |
| The application should search for a particular term. | |
| #define | ALP_APP_FIND_CANCEL "--alp-find-cancel" |
| The application should cancel ongoing searches. | |
| #define | ALP_APP_NOTIFY "--alp-notify" |
| The application is being launched or relaunched to handle a notification. | |
| #define | ALP_APP_PRIMARY "--alp-primary" |
| The application is the new "primary" main UI app, and should display its full UI. | |
| #define | ALP_APP_PROP_BACKGROUNDING "backgrounding" |
| #define | ALP_APP_PROP_BG_PREFERRED "preferred" |
| #define | ALP_APP_PROP_BG_REQUIRED "required" |
| #define | ALP_APP_PROP_BG_SUPPORTED "supported" |
| #define | ALP_APP_PROP_BG_UNSUPPORTED "unsupported" |
| #define | ALP_APP_PROP_DELETE "delete-menu" |
| #define | ALP_APP_PROP_ENABLE_THEME "enable-theme" |
| #define | ALP_APP_PROP_HIDDEN "hidden" |
| #define | ALP_APP_PROP_ICON "icon" |
| #define | ALP_APP_PROP_JUMP_LIST "jump-list" |
| #define | ALP_APP_PROP_NAME "name" |
| #define | ALP_APP_PROP_PREVENT_COPY "prevent-copy" |
| #define | ALP_APP_PROP_PREVENT_DELETE "prevent-delete" |
| #define | ALP_APP_PROP_SETTINGS "settings-menu" |
| #define | ALP_APP_PROP_TRANSIENT "transient" |
| #define | ALP_APP_PROP_UPDATE "update-menu" |
| #define | ALP_APP_PROP_VENDOR "vendor" |
| #define | ALP_APP_PROP_VERSION "version" |
| #define | ALP_APP_SETTING_APPMGR_DIR "/alp/appmgr" |
| #define | ALP_APP_SETTING_DEFAULT_ORIENTATION "/alp/appmgr/default-orientation" |
| #define | ALP_APP_SETTING_DEFAULT_PRIMARY "/alp/appmgr/default-primary" |
| #define | ALP_APP_SETTING_DISABLE_PRIMARY "/alp/appmgr/disable-primary-launches" |
| #define | ALP_APP_SETTING_END_KEY_APP "/alp/appmgr/end-key-app" |
| #define | ALP_APP_SETTING_HOME_KEY_APP "/alp/appmgr/home-key-app" |
| #define | ALP_APP_SETTING_LONG_PRESS_APP "/alp/appmgr/long-press-app" |
| #define | ALP_APP_SETTING_OTHER_PRIMARY "/alp/appmgr/other-primary" |
| #define | ALP_APP_TRANSIENT "--alp-transient" |
| The application is being launched as transient, and should go away when the primary app changes. | |
| #define | ALP_NOTIFY_EVENT_APP_MEMORY_CRITICAL "/alp/appmgr/memory-critical" |
| #define | ALP_NOTIFY_EVENT_APP_MEMORY_CRITICAL_RECOVER "/alp/appmgr/memory-critical-recover" |
| #define | ALP_NOTIFY_EVENT_APP_MEMORY_LOW "/alp/appmgr/memory-low" |
| #define | ALP_NOTIFY_EVENT_APP_MEMORY_LOW_RECOVER "/alp/appmgr/memory-low-recover" |
| #define | ALP_STATUS_APP_BLOCKED ((alp_status_t)ALP_CLASS_APPSERVER | 0x000A0000) |
| #define | ALP_STATUS_APP_IPC ((alp_status_t)ALP_CLASS_APPSERVER | 0x00020000) |
| #define | ALP_STATUS_APP_LAUNCHPAD ((alp_status_t)ALP_CLASS_APPSERVER | 0x00090000) |
| #define | ALP_STATUS_APP_MEM ((alp_status_t)ALP_CLASS_APPSERVER | 0x00080000) |
| #define | ALP_STATUS_APP_MSG ((alp_status_t)ALP_CLASS_APPSERVER | 0x00060000) |
| #define | ALP_STATUS_APP_NO_CONTEXT ((alp_status_t)ALP_CLASS_APPSERVER | 0x00040000) |
| #define | ALP_STATUS_APP_NO_LAUNCHPAD ((alp_status_t)ALP_CLASS_APPSERVER | 0x00050000) |
| #define | ALP_STATUS_APP_NOT_FOUND ((alp_status_t)ALP_CLASS_APPSERVER | 0x00030000) |
| #define | ALP_STATUS_APP_NOT_READY ((alp_status_t)ALP_CLASS_APPSERVER | 0x000B0000) |
| #define | ALP_STATUS_APP_PARAM ((alp_status_t)ALP_CLASS_APPSERVER | 0x00010000) |
| #define | ALP_STATUS_APP_RUNNING ((alp_status_t)ALP_CLASS_APPSERVER | 0x00070000) |
| #define | PKG_ID_MAX_SIZE 256 |
Typedefs | |
| typedef void(* | AlpAppLaunchCompletionProc )(alp_status_t status, pid_t pid, gpointer cbData) |
| typedef void(* | AlpExitHandler )(gpointer cbData) |
| typedef void(* | AlpRelaunchHandler )(int argc, char *argv[], gpointer cbData) |
| typedef uint32_t | AlpWatcherRef |
Enumerations | |
| enum | AlpAppBackgroundingType { ALP_APP_BACKGROUND_UNSUPPORTED = 1, ALP_APP_BACKGROUND_SUPPORTED, ALP_APP_BACKGROUND_PREFERRED, ALP_APP_BACKGROUND_REQUIRED, ALP_APP_BACKGROUND_DEFAULT = ALP_APP_BACKGROUND_UNSUPPORTED } |
| Values for alp_app_set_backgrounding(); see documentation for backgrounding properties. More... | |
| enum | AlpAppMemoryState { ALP_APP_MEMORY_STATE_UNKNOWN = 0, ALP_APP_MEMORY_STATE_LOW = 1, ALP_APP_MEMORY_STATE_LOW_RECOVER = 2, ALP_APP_MEMORY_STATE_CRITICAL = 3, ALP_APP_MEMORY_STATE_CRITICAL_RECOVER = 4 } |
Functions | |
| alp_status_t | alp_app_add_exit_handler (AlpExitHandler procP, gpointer cbData) |
| Applications should call this API in order to add an exit handler to the list. | |
| alp_status_t | alp_app_current (char **outBundleID) |
| Obtain the package ID of the current primary app, if any. | |
| alp_status_t | alp_app_exit (const char *bundleID) |
| Request that the indicated application cease execution. | |
| alp_status_t | alp_app_get_backgrounding (AlpAppBackgroundingType *outBackgrounding) |
| Get the application's current backgrounding setting. | |
| gboolean | alp_app_is_primary (void) |
| Check if the calling app is currently running as primary. | |
| alp_status_t | alp_app_launch (const char *bundleID, int argc, char *const argv[], pid_t *outPID) |
| Sends a request to the appserver to launch the indicated app. | |
| alp_status_t | alp_app_launch_async (const char *bundleID, int argc, char *const argv[], AlpAppLaunchCompletionProc completionProc, gpointer cbData) |
| Sends a request to the appserver to launch the indicated app, without blocking. | |
| alp_status_t | alp_app_remove_exit_handler (AlpExitHandler procP) |
| Remove the indicated exit handler from the list. | |
| alp_status_t | alp_app_remove_exit_handler_with_data (AlpExitHandler procP, gpointer cbData) |
| Remove the indicated exit handler from the list which also matches a given data pointer. | |
| alp_status_t | alp_app_reset_system (void) |
| Causes the system to reboot. | |
| alp_status_t | alp_app_retire (const char *bundleID) |
| Request that the indicated primary application exit or move to the background. | |
| alp_status_t | alp_app_retire_transients (void) |
| Request that all transient apps be retired (as with alp_app_retire()). | |
| alp_status_t | alp_app_set_backgrounding (AlpAppBackgroundingType newBackgrounding) |
| Set the application's backgrounding setting. | |
| alp_status_t | alp_app_set_relaunch_handler (AlpRelaunchHandler procP, gpointer cbData) |
| Set the handler for launch arguments in case the app is launched while it is already running. | |
| alp_status_t | alp_app_watcher_add (const char *bundleID, AlpWatcherRef *outWatcherRef, gboolean *outAppRan) |
| Add a new watcher to notice when the indicated app is run. | |
| alp_status_t | alp_app_watcher_block (AlpWatcherRef watcherRef, gboolean blockLaunch) |
| Configure watcher to (not) prevent its target application from being launched. | |
| alp_status_t | alp_app_watcher_check (AlpWatcherRef watcherRef, gboolean *outAppRan) |
| Check if the indicated watcher's target app has been run since the watcher was added. | |
| alp_status_t | alp_app_watcher_remove (AlpWatcherRef watcherRef, gboolean *outAppRan) |
| Deallocate the indicated watcher, and check if its target app ran since the watcher was added. | |
| gboolean | alp_gremlins_is_running (void) |
| Check if the calling app is being tested by gremlins. | |
| int | alp_main (int argc, char *argv[]) |
| Standard alp application main prototype. | |
|
|
The application is being launched because one of its alarms went off. This option is followed by a number, which is the reference number of the alarm. |
|
|
Indicate that reason for the alarm event. This option is to be used in conjunction with the ALP_APP_ALARM launch option to indicate the reason for the alarm event. Since most alarm events will be "normal", this optional arg is only needed when the reason for alarm expiration is unusual. Some such unusual reasons are "time-change", where the system clock has been advanced resulting in scheduled alarm expiring earlier than expected, or "restart", where the alarm manager has been (re)started and now finds that one or more scheduled alarms have expired since the last time alarm manager was running. |
|
|
Forces the application to be launched even if the system is not yet fully booted.
|
|
|
The application is no longer the primary UI app. This launch argument is sent to primary apps when a new one is launched, and they are left running in the background instead of exiting (see alp_app_set_backgrounding()). The receiving app should hide its main UI. It can still do some UI if necessary (dialogs and such), but it is no longer the "main UI app". |
|
|
The application is being launched so that it can close open postal service sessions. This option is sent to an application to request that the application close an active postal service session that it has open, and then exit itself. When an applicaiton is launched with this argument, it should display only minimal UI, if any, and close it's open connections, and then exit. |
|
|
Indicates that the application should be prepared for debugging. After loading any shared libraries necessary for application execution, and before calling the app's main entrypoint, the launchpad should block and wait for a SIGUSER1 from the debugger. |
|
|
The application should display a particular piece of data. The data to be displayed is specified by the following argv parameter. Generally, the following parameter is obtained from the application itself as the result of a "Find" operation. |
|
|
The application is being launched or relaunched to run an exchange handler. The exchange request id encoded in argv[2]. |
|
|
The application should search for a particular term. First parameter (argv[2]) is a version number, currently "1.0". Second parameter (argv[3]) is a search term. (See alp_find_results_start()) |
|
|
The application should cancel ongoing searches. On receiving this launch parameter, the app should cancel all ongoing searches and alp_find_results_end(). Further find results submitted from the app will be ignored. |
|
|
The application is being launched or relaunched to handle a notification. The notification details are encoded in the ALP_NOTIFY_LAUNCH parameter. |
|
|
The application is the new "primary" main UI app, and should display its full UI. The current primary app will exit or move to the background. If the app is already running then it should still make sure its full UI is visible. |
|
|
|
|
|
This value for ALP_APP_PROP_BACKGROUNDING indicates the application prefers to run in the background while resources are available, but does not require it. Currently the appserver will not leave these applications running in the background. |
|
|
This value for ALP_APP_PROP_BACKGROUNDING indicates the application needs to be left running in the background in order to properly do its work. The appserver will try to always leave these applications running, so they need to be extremely careful with resource usage. |
|
|
This value for ALP_APP_PROP_BACKGROUNDING indicates the application can run in the background (i.e., not primary) but does not really use it for anything. Currently the appserver will not leave these applications running in the background. |
|
|
This is the default value for ALP_APP_PROP_BACKGROUNDING, and indicates the application only supports being launched as the primary application. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The application is being launched as transient, and should go away when the primary app changes. Transient applications are subordinate to the current primary UI application. While they may display UI, it should generally only be in a dialog box, etc. They are generally intended to appear to be a part of the current app. This is used, for example, when a prefs panel is launched by an app directly - the panel appears in a dialog over the app, giving the impression that the user has not "changed apps". Transient applications will receive an exit request or relaunch with ALP_APP_BACKGROUNDED when the primary application changes. This allows them to dismiss any UI automatically, preserving the conceptual association with the current primary app. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Values for alp_app_set_backgrounding(); see documentation for backgrounding properties.
|
|
|
|
|
||||||||||||
|
Applications should call this API in order to add an exit handler to the list. The callback routine is added to the list of handlers for the default application context. The list of handlers is executed when the application receives an exit request from the app server. The application should respond by performing any necessary cleanup, and returning from main(). The 'cbData' parameter is passed to the callback function when it is called. Exit handlers are guaranteed to execute in the opposite of the order in which they were added (most recently added handler executes first).
|
|
|
Obtain the package ID of the current primary app, if any. This call is used to obtain the identity of the currently running primary application. If there is no current primary application, it will yield a NULL string pointer (this happens for a moment if the primary app crashes). The string obtained via this API should be deallocated using g_free() when the caller is finished with it. Note that the resulting application is not guaranteed to be running when this call returns.
|
|
|
Request that the indicated application cease execution. This call will cause the appserver to send an exit request to the indicated app. If the application has not registered an exit handler, then it will receive a SIGTERM. If it does not cease execution within a certain time, the appserver will send it a SIGKILL. Applications with a genuine need for lengthy shutdown procedures should indicate in their package manifest that they require backgrounding, and then the appserver will generally relaunch them in the background instead of sending an exit request. If the application is not running, then the request is ignored. The request is sent using the default application context. NOTE: This API should be used sparingly, because the indicated application will be terminated, even if it would ordinarily continue execution in the background when displaced by a new primary app. If your goal is only to have the application give up its spot as the current primary app, then use alp_app_retire() or alp_app_launch() to run a new primary app instead. Note that a return value of ALP_STATUS_OK does not indicate that the application has exited, only that there was no error sending the request to the appserver.
|
|
|
Get the application's current backgrounding setting. This call will send a message to the app server to obtain the current backgrounding setting for the default application context.
|
|
|
Check if the calling app is currently running as primary.
|
|
||||||||||||||||||||
|
Sends a request to the appserver to launch the indicated app. If the specified app is already running, then it will have the option to obtain the new parameters via a calllback and update its state (by showing or hiding its main UI, for example). If it does not register the callback for this purpose, then it will receive an exit request and be relaunched with the new parameters. The app server will prepend the bundle name to the argv list, so the caller should only pass the extra stuff. If ALP_APP_PRIMARY is specified, then the current primary application will be retired (either moved to bg, quit, or terminated). The request is sent using the default application context. Note that this is a synchronous API which will block waiting for a result from the appserver. If outPID is specified, then it will block until the app registers with appserver. Otherwise, only until the appserver is finished handling the request. A return value of ALP_STATUS_OK does not guarantee that the launch will be entirely successful, only that there were no appserver errors in processing the request. Also note that this API must be called from the context of a running application. If it's necessary to call it from some other context (e.g., some other linux process), the caller will need to set up an application context using alp_app_setup() (and later deallocate it with alp_app_destroy()).
|
|
||||||||||||||||||||||||
|
Sends a request to the appserver to launch the indicated app, without blocking. Like alp_app_launch, but does not wait for a reply from the appserver. Note that by not waiting for a reply, this call is much less capable of indicating a launch failure than alp_app_launch().
|
|
|
Remove the indicated exit handler from the list. The indicated callback is removed from the list of handlers for the default application context. See alp_add_exit_handler() for more information on exit handlers.
|
|
||||||||||||
|
Remove the indicated exit handler from the list which also matches a given data pointer. The indicated callback is removed from the list of handlers for the default application context. Note that both the procedure pointer and cbData value must match in order for the handler to be removed from the list. This allows the same exithandler to be added multiple times without confusing the removal. See alp_add_exit_handler() for more information on exit handlers.
|
|
|
Causes the system to reboot. This tells the application server to reboot the system. Currently, it just calls system("reboot"), but eventually we'll hopefully exit all running apps, to give them a chance to tidy up, etc.
|
|
|
Request that the indicated primary application exit or move to the background. This call will cause the appserver to 'retire' the indicated app. If it is the current primary app, it will either receive an exit request or be relaunched in the background (according to its own preference). The request is sent using the default application context. Note that a return value of ALP_STATUS_OK does not indicate that the application has been retired, only that there was no error sending the request to the appserver.
|
|
|
Request that all transient apps be retired (as with alp_app_retire()). The request is sent using the default application context. Note that a return value of ALP_STATUS_OK does not indicate that the applications have been retired, only that there was no error sending the request to the appserver.
|
|
|
Set the application's backgrounding setting. This call will send a message to the app server to change the application's current "backgrounding setting". This affects whether or not the application will be relaunched with ALP_APP_BACKGROUNDED and left running "in the background" when it otherwise would receive an exit request (usually when a new primary application is launched, for example). Note that there are some potential concurrency issues here. The API may be called and return all after the appserver has already sent an exit request using the old preference, but before it is received by the application.
|
|
||||||||||||
|
Set the handler for launch arguments in case the app is launched while it is already running. This client-side application API sets up the specified callback procedure for the default application context to receive the new launch parameters if the app server receives a launch request for the application while it is already running. If no handler is registered, then the application will receive an exit request, and will be launched again with the new parameters. Registering a handler allows applications an easy way to simply adjust their state (showing or hiding UI, changing views, etc) to match the new requirements, rather than taking on the overhead of exiting and starting back up again.
|
|
||||||||||||||||
|
Add a new watcher to notice when the indicated app is run. This call causes the appserver to allocate a new "watcher" for the indicated application. The watcher will notice if the indicated app is run at anytime during the watcher's lifetime. Immediate feedback is provided via the "outAppRan" parameter in case the target application is already running.
|
|
||||||||||||
|
Configure watcher to (not) prevent its target application from being launched. This call will configure launch-blocking behavior for the indicated watcher. If the watcher is set to block launches, then the appserver will refuse any requests to launch the target app, and alp_app_launch() will return ALP_STATUS_APP_BLOCKED. Note that this will not absolutely guarantee that the application cannot start up, only that the app server will not start it (for example, it could still be started by running the native launchpad from the command line with the --direct option). However, this is pretty good for most cases.
|
|
||||||||||||
|
Check if the indicated watcher's target app has been run since the watcher was added. This call checks to see if the indicated watcher's target application has been run at any time since the watcher was added.
|
|
||||||||||||
|
Deallocate the indicated watcher, and check if its target app ran since the watcher was added. This call deallocates the indicated watcher, ceasing watching for the target app to be run. It also performs one final check to see if the target application was ever run during the (now finished) lifetime for the watcher.
|
|
|
Check if the calling app is being tested by gremlins.
|
|
||||||||||||
|
Standard alp application main prototype.
|
Generated on Wed Jul 30 07:06:44 2008 by Doxygen 1.4.6 for ALP SDK + Hiker Documentation
Copyright © 1999-2008 ACCESS CO., LTD. All rights reserved.