Main Page | Modules | Namespace List | Class Hierarchy | Data Structures | Directories | File List | Namespace Members | Data Fields | Globals

Application Manager


Modules

 Private

Defines

#define ALP_STATUS_APP_PARAM   ((alp_status_t)ALP_CLASS_APPSERVER | 0x00010000)
#define ALP_STATUS_APP_IPC   ((alp_status_t)ALP_CLASS_APPSERVER | 0x00020000)
#define ALP_STATUS_APP_NOT_FOUND   ((alp_status_t)ALP_CLASS_APPSERVER | 0x00030000)
#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_MSG   ((alp_status_t)ALP_CLASS_APPSERVER | 0x00060000)
#define ALP_STATUS_APP_RUNNING   ((alp_status_t)ALP_CLASS_APPSERVER | 0x00070000)
#define ALP_STATUS_APP_MEM   ((alp_status_t)ALP_CLASS_APPSERVER | 0x00080000)
#define ALP_STATUS_APP_LAUNCHPAD   ((alp_status_t)ALP_CLASS_APPSERVER | 0x00090000)
#define ALP_STATUS_APP_BLOCKED   ((alp_status_t)ALP_CLASS_APPSERVER | 0x000A0000)
#define ALP_APP_PROP_NAME   "name"
#define ALP_APP_PROP_VENDOR   "vendor"
#define ALP_APP_PROP_BACKGROUNDING   "backgrounding"
#define ALP_APP_PROP_HIDDEN   "hidden"
#define ALP_APP_PROP_JUMP_LIST   "jump-list"
#define ALP_APP_PROP_ENABLE_THEME   "enable-theme"
#define ALP_APP_PROP_TRANSIENT   "transient"
#define ALP_APP_PROP_UPDATE   "update-menu"
#define ALP_APP_PROP_SETTINGS   "settings-menu"
#define ALP_APP_PROP_PREVENT_DELETE   "prevent-delete"
#define ALP_APP_PROP_PREVENT_COPY   "prevent-copy"
#define ALP_APP_PROP_ICON   "icon"
#define ALP_APP_PROP_VERSION   "version"
#define ALP_APP_PROP_BG_UNSUPPORTED   "unsupported"
 This is the default value for ALP_APP_PROP_BACKGROUNDING, and indicates the application only supports being launched as the primary application.
#define ALP_APP_PROP_BG_SUPPORTED   "supported"
 This value for ALP_APP_PROP_BACKGROUNDING indicates the application can run in the background (i.e.
#define ALP_APP_PROP_BG_PREFERRED   "preferred"
 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.
#define ALP_APP_PROP_BG_REQUIRED   "required"
 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.
#define PKG_ID_MAX_LEN   256
#define ALP_APP_PRIMARY   "--alp-primary"
 The application is the new "primary" main UI app, and should display its full UI.
#define ALP_APP_BACKGROUNDED   "--alp-backgrounded"
 The application is no longer the primary UI app.
#define ALP_APP_DISPLAY   "--alp-display"
 The application should display a particular piece of data.
#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_DEBUG   "--alp-debug"
 Indicates that the application should be prepared for debugging.
#define ALP_APP_NOTIFY   "--alp-notify"
 The application is being launched or relaunched to handle a notification.
#define ALP_APP_EXCHANGE   "--alp-exchange"
 The application is being launched or relaunched to run an exchange handler.
#define ALP_APP_ALARM   "--alp-alarm"
 The application is being launched because one of its alarms went off.
#define ALP_APP_ALERT   "--alp-alert"
 The application is being launched in order to receive an attention event.
#define ALP_APP_TRANSIENT   "--alp-transient"
 The application is being launched as transient, and should go away when the primary app changes.
#define ALP_APP_SERVER_TRACE   ALP_TRACE_DEFINE(ALP_CLASS_APPSERVER, 1)
#define ALP_APP_CLIENT_TRACE   ALP_TRACE_DEFINE(ALP_CLASS_APPSERVER, 2)
#define ALP_APP_TEST_TRACE   ALP_TRACE_DEFINE(ALP_CLASS_APPSERVER, 3)
#define ALP_APP_LAUNCHPAD_SCHEME_SIZE   16
#define ALP_APP_LAUNCH_FLAGS_STICKY   (ALP_APP_LAUNCH_FLAG_TRANSIENT | ALP_APP_LAUNCH_FLAG_DEBUG | ALP_APP_LAUNCH_FLAG_LAUNCHPAD)
 These launch flags should always remain set for an.
#define ALP_APP_LAUNCH_FLAGS_DEFAULT   (ALP_APP_LAUNCH_FLAG_NONE)
 This represents the default launchflags for an app. Background run, no debugging, diagnostics, etc.
#define ALP_APP_DIAG_UNEXPECTED_EXIT   "Application quit unexpectedly."
#define ALP_APP_DIAG_CLEAN_EXIT   "Application quit cleanly."
#define ALP_APP_DIAG_MISSING_LAUNCPAD   "Can't find launchpad for scheme, not launching."
#define ALP_APP_NO_DEFAULT_APP   "--no-default-app"
#define ALP_APP_NO_DEFAULTS   "--no-defaults"
#define ALP_APP_NO_DAEMON   "--no-daemon"
#define ALP_APP_DEFAULT_PRIMARY   "--default-primary"

Typedefs

typedef void(* AlpRelaunchHandler )(int argc, char *argv[], gpointer cbData)
typedef void(* AlpExitHandler )(gpointer cbData)
typedef uint32_t AlpWatcherRef
typedef void(* AlpDiagnosticHandler )(const char *appID, const char *diagStr, void *cbData)
typedef void(* AlpThemeUpdateProc )(void)
typedef _AlpAppContext AlpAppContext

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  AlpAppLaunchFlags {
  ALP_APP_LAUNCH_FLAG_NONE = 0, ALP_APP_LAUNCH_FLAG_DEBUG = (1 << 0), ALP_APP_LAUNCH_FLAG_PRIMARY = (1 << 1), ALP_APP_LAUNCH_FLAG_LAUNCHPAD = (1 << 2),
  ALP_APP_LAUNCH_FLAG_DIAGNOSTIC = (1 << 3), ALP_APP_LAUNCH_FLAG_TRANSIENT = (1 << 4), ALP_APP_LAUNCH_FLAG_ERROR = (1 << 5)
}

Functions

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[])
 Sends a request to the appserver to launch the indicated app, without blocking.
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_exit (const char *bundleID)
 Request that the indicated application cease execution.
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_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_block (AlpWatcherRef watcherRef, gboolean blockLaunch)
 Configure watcher to (not) prevent its target application from being launched.
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.
alp_status_t alp_app_current (char **outBundleID)
 Obtain the package ID of the current primary app, if any.
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_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_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_theme_update (void)
 Causes all running apps to reload the theme.
alp_status_t alp_app_reset_system (void)
 Causes the system to reboot.
alp_status_t alp_app_launch_full (AlpAppContext *context, const char *appID, int argc, char *const argv[], pid_t *outPID)
 More flexible PDK version of alp_app_launch.
AlpAppContextalp_app_setup (const char *appID, guint32 flags, const char *scheme)
 Sets up a default connection to the application server, & registers the app.
void alp_app_destroy (AlpAppContext *context, int result)
 Unregisters app & closes the connection opened by alp_app_setup().
void alp_app_abandon (AlpAppContext *context)
 Close IPC connection & deallocate context without unregistering with appserver.
void alp_app_set_default_context (AlpAppContext *context)
 Sets the default application context.
void alp_app_register (AlpAppContext *context, const char *appID, guint32 flags, const char *scheme)
 Re-register a relaunched application with the appserver.
alp_status_t alp_app_flush (AlpAppContext *context)
 Ensure appserver has handled any pending messages for the given context.
guint32 alp_app_parse_launch_flags (guint32 launchFlags, int argc, char *const argv[])
 Parse default ALP launch arguments and return a bit flag representation.
void alp_app_set_diagnostic_handler (AlpAppContext *context, AlpDiagnosticHandler procP, void *cbData)
 Set a handler to receive diagnostic messages from appserver.
alp_status_t alp_app_get_jump_list (int *count, char ***appIDs, gboolean **isRunnings)
 Get the current list of applications in the "jump list".
void alp_app_free_argv (int argc, char *argv[])
 Deallocate a dynamically allocated argc/argv style argument list.
void alp_app_debug_break (void)
 Halt execution, fork a new gnome-terminal, and attach gdb to the app.
void alp_app_set_theme_update_proc (AlpAppContext *context, AlpThemeUpdateProc proc)
 Set the procedure used to update the app's theme when a theme update message is received.


Define Documentation

#define ALP_APP_ALARM   "--alp-alarm"
 

The application is being launched because one of its alarms went off.

This parameter is followed by a number, which is the reference number of the alarm.

#define ALP_APP_ALERT   "--alp-alert"
 

The application is being launched in order to receive an attention event.

This parameter will be followed by additional arguments that should specify the action to taken and the identity of the alert on which to apply the specified action. If the default alert launch convention is used, this parameter will be followed by the action argument string "goto", the alert source app-id, the alert type name and finally by the alert handle. The last three arguments specify the identity of the attention alert.

#define ALP_APP_BACKGROUNDED   "--alp-backgrounded"
 

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".

#define ALP_APP_CLIENT_TRACE   ALP_TRACE_DEFINE(ALP_CLASS_APPSERVER, 2)
 

#define ALP_APP_DEBUG   "--alp-debug"
 

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.

#define ALP_APP_DEFAULT_PRIMARY   "--default-primary"
 

#define ALP_APP_DIAG_CLEAN_EXIT   "Application quit cleanly."
 

#define ALP_APP_DIAG_MISSING_LAUNCPAD   "Can't find launchpad for scheme, not launching."
 

#define ALP_APP_DIAG_UNEXPECTED_EXIT   "Application quit unexpectedly."
 

#define ALP_APP_DISPLAY   "--alp-display"
 

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.

#define ALP_APP_EXCHANGE   "--alp-exchange"
 

The application is being launched or relaunched to run an exchange handler.

The exchange request id encoded in argv[2].

#define ALP_APP_FIND   "--alp-find"
 

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())

#define ALP_APP_FIND_CANCEL   "--alp-find-cancel"
 

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.

#define ALP_APP_LAUNCH_FLAGS_DEFAULT   (ALP_APP_LAUNCH_FLAG_NONE)
 

This represents the default launchflags for an app. Background run, no debugging, diagnostics, etc.

#define ALP_APP_LAUNCH_FLAGS_STICKY   (ALP_APP_LAUNCH_FLAG_TRANSIENT | ALP_APP_LAUNCH_FLAG_DEBUG | ALP_APP_LAUNCH_FLAG_LAUNCHPAD)
 

These launch flags should always remain set for an.

#define ALP_APP_LAUNCHPAD_SCHEME_SIZE   16
 

#define ALP_APP_NO_DAEMON   "--no-daemon"
 

#define ALP_APP_NO_DEFAULT_APP   "--no-default-app"
 

#define ALP_APP_NO_DEFAULTS   "--no-defaults"
 

#define ALP_APP_NOTIFY   "--alp-notify"
 

The application is being launched or relaunched to handle a notification.

The notification details are encoded in the ALP_NOTIFY_LAUNCH parameter.

#define ALP_APP_PRIMARY   "--alp-primary"
 

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.

#define ALP_APP_PROP_BACKGROUNDING   "backgrounding"
 

#define ALP_APP_PROP_BG_PREFERRED   "preferred"
 

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.

#define ALP_APP_PROP_BG_REQUIRED   "required"
 

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.

#define ALP_APP_PROP_BG_SUPPORTED   "supported"
 

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.

#define ALP_APP_PROP_BG_UNSUPPORTED   "unsupported"
 

This is the default value for ALP_APP_PROP_BACKGROUNDING, and indicates the application only supports being launched as the primary application.

#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_SERVER_TRACE   ALP_TRACE_DEFINE(ALP_CLASS_APPSERVER, 1)
 

#define ALP_APP_TEST_TRACE   ALP_TRACE_DEFINE(ALP_CLASS_APPSERVER, 3)
 

#define ALP_APP_TRANSIENT   "--alp-transient"
 

The application is being launched as transient, and should go away when the primary app changes.

Transient applications are subordinate to the current main 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.

#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_PARAM   ((alp_status_t)ALP_CLASS_APPSERVER | 0x00010000)
 

#define ALP_STATUS_APP_RUNNING   ((alp_status_t)ALP_CLASS_APPSERVER | 0x00070000)
 

#define PKG_ID_MAX_LEN   256
 


Typedef Documentation

typedef struct _AlpAppContext AlpAppContext
 

typedef void(* AlpDiagnosticHandler)(const char *appID, const char *diagStr, void *cbData)
 

typedef void(* AlpExitHandler)(gpointer cbData)
 

typedef void(* AlpRelaunchHandler)(int argc, char *argv[], gpointer cbData)
 

typedef void(* AlpThemeUpdateProc)(void)
 

typedef uint32_t AlpWatcherRef
 


Enumeration Type Documentation

enum AlpAppBackgroundingType
 

Values for alp_app_set_backgrounding(); see documentation for backgrounding properties.

Enumerator:
ALP_APP_BACKGROUND_UNSUPPORTED 
ALP_APP_BACKGROUND_SUPPORTED 
ALP_APP_BACKGROUND_PREFERRED 
ALP_APP_BACKGROUND_REQUIRED 
ALP_APP_BACKGROUND_DEFAULT 

enum AlpAppLaunchFlags
 

Enumerator:
ALP_APP_LAUNCH_FLAG_NONE 
ALP_APP_LAUNCH_FLAG_DEBUG 
ALP_APP_LAUNCH_FLAG_PRIMARY 
ALP_APP_LAUNCH_FLAG_LAUNCHPAD 
ALP_APP_LAUNCH_FLAG_DIAGNOSTIC 
ALP_APP_LAUNCH_FLAG_TRANSIENT 
ALP_APP_LAUNCH_FLAG_ERROR 


Function Documentation

void alp_app_abandon AlpAppContext context  ) 
 

Close IPC connection & deallocate context without unregistering with appserver.

This obscure API is used by the native launchpad to close an app context's IPC connection (and deallocate the memory) without unregistering with the appserver. This is needed when forking in order to prevent the child process from sharing the parent's IPC connection.

Parameters:
[in] context The app context whose server connection is to be closed, or NULL for the default context.

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.

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).

Parameters:
[in] procP A pointer to the exit handler to call.
[in] cbData A caller-defined pointer which is passed to the handler.
Returns:
Yields ALP_STATUS_OK on success, or an error code on failure.

alp_status_t alp_app_current char **  outBundleID  ) 
 

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.

Parameters:
[out] outBundleID Receives the bundle name of the currently running primary application, or NULL if there is none.
Returns:
Yields ALP_STATUS_OK on success.

void alp_app_debug_break void   ) 
 

Halt execution, fork a new gnome-terminal, and attach gdb to the app.

This API is a vague equivalent of the old PalmOS DbgBreak(). It's intended to make it slightly easier to debug apps until we get the real debugging infrastructure in place. Once that happens, this API will probably disappear.

This call will create a child process in which it opens a new terminal, runs GDB, and attaches to the parent app. Meanwhile, the parent sleeps for a few seconds to give the debugger a chance to catch up.

void alp_app_destroy AlpAppContext context,
int  result
 

Unregisters app & closes the connection opened by alp_app_setup().

This API is the reverse of alp_app_setup(). It unregisters the context with the appserver, closes the IPC connection, and deallocates the AlpAppContext structure. It's generally called by launchpads on behalf of the launched application, when it terminates. In order for app termination to be considered 'graceful' by the appserver, this API must be called to close the connection.

Parameters:
[in] context The app context for the terminating application.
[in] result The app's exit status (e.g., as returned from main()).

alp_status_t alp_app_exit const char *  bundleID  ) 
 

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.

Parameters:
[in] bundleID The name of the bundle containing the application to be quit. If NULL, the current primary application will be retired.
Returns:
Yields ALP_STATUS_OK on success, or an error code if there is a problem sending the message to the app server.

alp_status_t alp_app_flush AlpAppContext context  ) 
 

Ensure appserver has handled any pending messages for the given context.

This API is used by unit tests to help with synchronization. It sends a synchronous no-op message to the appserver, and waits for a reply. This ensures that the appserver has received and handled any pending messages for the given context.

Parameters:
[in] context The app context to be registered.
Returns:
Returns an alp_status_t indicating success or failure.

void alp_app_free_argv int  argc,
char *  argv[]
 

Deallocate a dynamically allocated argc/argv style argument list.

Ignores null string pointers, so the caller can zero out any argv[] elements that should not be deallocated.

Parameters:
[in] argc The number of strings in the argv array.
[in] argv An array of char* containing launch arguments for the application.

alp_status_t alp_app_get_jump_list int *  count,
char ***  appIDs,
gboolean **  isRunnings
 

Get the current list of applications in the "jump list".

This call sends a request through the default application context, and returns the current contents of the Jump List. The result is an array of char*, where each string is the bundle ID of an application in the current jump list. The 'isRunnings' array contains boolean values indicating whether or not each of the apps in 'appIDs' was running when the data was packed up. The result lists are variable length, and sorted in order of launch (most recently launched first). The jumplist application is expected to sort through the data and decide what is the appropriate subset to display.

Note that the jump list will not necessarily contain *all* running apps. Only those that have not fallen off the list since being launched with ALP_APP_PRIMARY. Apps that are never launched as primary are not added to the jump list unless they specify "always" for the jump-list property in their manifest.

The result strings and arrays should be all be freed by the caller using g_free() (or alp_app_free_argv()).

Parameters:
[out] count Receives the number of elements in appIDs and isRunnings.
[out] appIDs Receives an array of char*, containing bundle IDs for the jump list apps.
[out] isRunnings Receives an array of gboolean, indicating whether or not each app is running.
Returns:
Yields ALP_STATUS_OK on success, or an error code if there is a problem with the request.

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.

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()).

Parameters:
[in] bundleID The name of the bundle containing the application to be launched.
[in] argc The number of strings in the argv array.
[in] argv An array of char* containing launch arguments for the application.
[out] outPID NULL, or a pointer to pid_t to receive the app's process ID once it registers with the app server.
Returns:
Yields ALP_STATUS_OK on success, or an error code if there is a problem launching the application.

alp_status_t alp_app_launch_async const char *  bundleID,
int  argc,
char *const   argv[]
 

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().

Parameters:
[in] bundleID The name of the bundle containing the application to be launched.
[in] argc The number of strings in the argv array.
[in] argv An array of char* containing launch arguments for the application.
Returns:
Yields ALP_STATUS_OK on success, or an error code (usually ALP_STATUS_APP_NO_CONTEXT or ALP_STATUS_APP_IPC).

alp_status_t alp_app_launch_full AlpAppContext context,
const char *  appID,
int  argc,
char *const   argv[],
pid_t *  outPID
 

More flexible PDK version of alp_app_launch.

This API has all the options. It allows the caller to specify the context from which the launch should be executed, and the blocking behavior can also be controlled. If NULL is passed for outPID, then this call will not block to wait for a response from appserver, ala alp_app_launch_async() (keep in mind that the result code will be somewhat less useful in this case).

Parameters:
[in] context The AlpAppContext* to use to send the launch request.
[in] appID The name of the bundle containing the application to be launched.
[in] argc The number of strings in the argv array.
[in] argv An array of char* containing launch arguments for the application.
[out] outPID a pointer to pid_t to receive the app's process ID once it registers with the app server, or NULL to not wait for a response.
Returns:
Yields ALP_STATUS_OK on success, or an error code if there is a problem sending the message to the app server. If outPID is non-null, then this API will wait for a response from the appserver, and will also return an error if there was a problem launching the application.

guint32 alp_app_parse_launch_flags guint32  launchFlags,
int  argc,
char *const   argv[]
 

Parse default ALP launch arguments and return a bit flag representation.

This utility routine is used by launchpads, the app server, and the client-side code to parse the standard arguments passed to the app and set appropriate launch flags in the result, which provide a more compact and easily accessible representation.

Parameters:
[in] launchFlags The current launch flags. Needed (for example) when neither ALP_APP_PRIMARY or ALP_APP_BACKGROUNDED is specified.
[in] argc The number of strings in the argv array.
[in] argv An array of char* containing launch arguments for the application.
Returns:
Returns a bitfield representing some of the standard parameters in the argv array.

void alp_app_register AlpAppContext context,
const char *  appID,
guint32  flags,
const char *  scheme
 

Re-register a relaunched application with the appserver.

This API should only be called in response to a launch request from the app server (either an initial launch, or a relaunch). If it is called otherwise, it could result in pending launch requests being accidentally dropped from the appserver's internal queue (since they are normally removed when the app registration is received). Since the appserver client libraries pretty much take care of this, use of this API is mostly limited to testing.

This API is generally called (via alp_app_setup) on behalf of a newly launched application by the launchpad's setup code before calling into the application's main() entrypoint. It is also called by the client-side libappserver code directly in the case of an application relaunch. It must be called from the context of the registering application.

Parameters:
[in] context The app context to be registered, obtained by calling alp_app_setup().
[in] appID The name of the bundle containing the application.
[in] flags Standard launch flags indicating the app's mode of execution.
[in] scheme The bundle type for received launch requests. Used only when registering as a launchpad.

alp_status_t alp_app_remove_exit_handler AlpExitHandler  procP  ) 
 

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.

Parameters:
[in] procP A pointer to the exit handler to remove.
Returns:
Yields ALP_STATUS_OK on success, or an error code if the indicated handler/data is not found in 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.

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.

Parameters:
[in] procP A pointer to the exit handler to remove.
[in] cbData A caller-defined pointer which is passed to the handler.
Returns:
Yields ALP_STATUS_OK on success, or an error code if the indicated handler/data is not found in the list.

alp_status_t alp_app_reset_system void   ) 
 

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.

Returns:
Yields ALP_STATUS_OK on success, or an error code if there was a problem communicating with appserver.

alp_status_t alp_app_retire const char *  bundleID  ) 
 

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.

Parameters:
[in] bundleID The name of the bundle containing the application to retire. If NULL, the current primary application will be retired.
Returns:
Yields ALP_STATUS_OK on success, or an error code if there is a problem sending the message to the app server.

alp_status_t alp_app_set_backgrounding AlpAppBackgroundingType  newBackgrounding  ) 
 

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.

Parameters:
[in] newBackgrounding The new backgrounding setting for the app.
Returns:
Yields ALP_STATUS_OK on success, or an error code if there is a problem sending the message to the app server.

void alp_app_set_default_context AlpAppContext context  ) 
 

Sets the default application context.

The default application context is used internally by many of the app-level SDK APIs to encapsulate the connection to the app server, callback handlers for various app events, etc.

Parameters:
[in] context The new default application context.

void alp_app_set_diagnostic_handler AlpAppContext context,
AlpDiagnosticHandler  procP,
void *  cbData
 

Set a handler to receive diagnostic messages from appserver.

This API is used by diagnostic code to set a handler for diagnostic messages received from the app server. Applications register to receive these messages by setting the ALP_APP_LAUNCH_FLAG_DIAGNOSTIC flag when registering. Then, when they arrive, the client-side libappserver code will call this handler.

Parameters:
[in] context The app context for which to set the diagnostic handler.
[in] procP A pointer to the diagnostic handler to call.
[in] cbData A caller-defined pointer which is passed to the handler.

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.

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.

Parameters:
[in] procP A pointer to the relaunch handler to call.
[in] cbData A caller-defined pointer which is passed to the handler.
Returns:
Yields ALP_STATUS_OK on success, or an error code on failure.

void alp_app_set_theme_update_proc AlpAppContext context,
AlpThemeUpdateProc  proc
 

Set the procedure used to update the app's theme when a theme update message is received.

This API is necessary in order to prevent appserver from having to link to GTK+ in order to update the theme. The alternative would mean pulling GTK+ into many system daemons which do not need it. This routine is used by alp_max_gtk_init() to make sure that the proper theme update routine is called for MAX apps (and any other UI which uses GTK+ and calls alp_max_gtk_init().

Parameters:
[in] context The app context for which to set the theme update procedure. Pass NULL for the default context.
[in] proc A pointer to the prcedure to call when a theme update message is received.

AlpAppContext* alp_app_setup const char *  appID,
guint32  flags,
const char *  scheme
 

Sets up a default connection to the application server, & registers the app.

This API is generally called on behalf of apps during launch by the launchpad just before beginning application execution. Various system services (not true applications) may also call it (along with alp_app_destroy()) in order to "pose" as an application and take advantage of various application based services (e.g., calling alp_app_launch() and receiving relaunch callbacks and exit requests). In the latter case, the "appID" parameter is not required to represent a valid bundle.

This call initializes the 2-way connection with the app server, and causes the app to be added to the server's list of active applications. Many APIs require this connection in order to function properly (alp_app_launch(), alp_app_exit(), alp_app_register(), alp_app_flush(), etc.). If there is no default app context, then the newly allocated context will become the default.

The launch flags are used to describe the newly launched application's mode of execution. These are a combination of the ALP_APP_LAUNCH_FLAG_* constants from appmgr_pdk.h, and usually come from alp_app_parse_launch_flags(), which parses the application's argv array and returns the appropriate set of bits. Note that these bits describe the newly launched application's mode of execution ONLY. They have no relation to any other apps which might have launched this one, or which the new one may launch (i.e., they are not propagated between apps).

Parameters:
[in] appID The name of the bundle containing the application.
[in] flags Standard launch flags indicating the app's mode of execution.
[in] scheme The bundle type for received launch requests. Used only when registering as a launchpad.
Returns:
Returns a newly allocated AlpAppContext structure encapsulating the appserver connection & associated app state.

alp_status_t alp_app_theme_update void   ) 
 

Causes all running apps to reload the theme.

This tells the application server that the current theme has been changed, which results in theme update messages being sent to all running apps.

Returns:
Yields ALP_STATUS_OK on success, or an error code if there was a problem communicating with appserver.

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.

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.

Parameters:
[in] bundleID The bundle name of the application to watch for.
[out] outWatcherRef Receives a reference to the newly allocated watcher.
[out] outAppRan Set to TRUE if the target application has run since the watcher was added.
Returns:
Yields ALP_STATUS_OK on success.

alp_status_t alp_app_watcher_block AlpWatcherRef  watcherRef,
gboolean  blockLaunch
 

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.

Parameters:
[in] watcherRef The AlpWatcherRef for the watcher to check.
[in] blockLaunch Pass TRUE to block launches, or FALSE to not block launches.
Returns:
Yields ALP_STATUS_OK on success.

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.

This call checks to see if the indicated watcher's target application has been run at any time since the watcher was added.

Parameters:
[in] watcherRef The AlpWatcherRef for the watcher to check.
[out] outAppRan Set to TRUE if the watcher's target application has run since the watcher was added.
Returns:
Yields ALP_STATUS_OK on success.

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.

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.

Parameters:
[in] watcherRef The AlpWatcherRef for the watcher to deallocate.
[out] outAppRan If not NULL, this is set to TRUE if the target application was run at any time during the watcher's lifetime.
Returns:
Yields ALP_STATUS_OK on success.


Generated on Sat Dec 16 20:29:50 2006 for hiker-0.9 by  doxygen 1.4.4