ACCESS Developer Network | Command-Line Tools | Access, Command, Alert, Application, Linux

ACCESS Linux Platform—whether in the Simulator or on a real device—contains a basic Linux shell that can be accessed from a terminal window. When working with Scratchbox, simply enter commands into the Terminal window you used to launch Scratchbox from (be sure to log in as "root" first). If you have a real ACCESS Linux Platform device that is connected (typically via USB) to your desktop computer, you can telnet to that device (the IP address is often 192.168.2.101) and enter commands through the telnet session.

Application Launching and Debugging ^TOP^

The alp_app command-line tool can be used to launch and/or command-line debug your ACCESS Linux Platform applications. It can also be used to manipulate the application and various parts of the system. Typing alp_app on the command line with no options will display basic help text.

Table 4.1 Using alp_appÂ

Function	Command	Notes
Launch an application	`alp_app --launch` app_name launch_args...	If you don't supply any launch arguments, the "`--alp-primary`" launch code is assumed. If you really do want to launch your application with no arguments, use: `alp_app --launch` app_name `--force`
Launch and application for debugging	`alp_app --debug` app_name launch_args	Return PID
Terminate a running application	`alp_app --exit` app_name
Retire a primary application	`alp_app --retire` app_name
List available applications	`alp_app --list`	Applications are stored in `/opt/alp/bundles/`
Wait until the Application Server is available	`alp_app --wait`
Set an environment variable inside the native application launcher	`alp_app --setenv` variable_name variable_value
Display the name of the current primary application	`alp_app --current`
Reboot the system	`alp_app --reboot`
Exit all applications and terminate the Application Server	`alp_app --shutdown`
Begin "gesture mode", and display all gestures received	`alp_app --gesture`

When using alp_app, if the supplied application name does not include a ":", then the string "bar:com.access.apps." is automatically prepended. Thus, the command:

alp_app --exit test

will terminate the application named "bar:com.access.apps.test".

Exploring and Manipulating Global Settings ^TOP^

Occasionally it can be helpful to explore the current values of various global settings, and even to alter those values. ACCESS Linux Platform includes the alp_settings command-line tool for just this purpose. It runs in the Simulator or on a real device (use it from a telnet session).

Use this tool like this:

alp_settings options...

The options can be:

--install file_name

--base-dir base_directory

--crypto

--set key_name --value value --type type

When using the --set option, the "--type type" clause is optional and can be omitted. Valid types are: "int", "integer", "bool", "boolean", and "string".

--delete-tree directory

--delete key_name

--get key_name

--Get key_name

--uid user_id

--list pattern

--mode mode

--no-notify

--quiet

As an example, here is a sample alp_settings command:

alp_settings --set /alp/input_methods/soft_keyboard/override_qwerty --value TRUE

Working with Alerts ^TOP^

In the Simulator or on an ACCESS Linux Platform device to which you are connected using telnet you can use the alp_alert command to exercise the Attention Manager. You can use it to post alerts, display the contents of the alert database, remove all alerts from the database, and the like.

The basic syntax of the alp_alert command is as follows:

alp_alert [OPTION...] prop1=value1, ..., propN=valueN

The specific format of the alp_alert command when used to list, post, update, and delete alerts is discussed in the following sections.

Listing Alerts ^TOP^

You can list the contents of the alert database, formatted for easy readability, with the -l (or --list) option.

Listing 4.1 An alert listing

~ # alp_alert --list 
Alert Id:Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ 2 
Ã¾Ã¾Ã¾Ã¾Ã¾ Source:Ã¾Ã¾ bar:com.access.apps.alarmtest 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ Type:Ã¾Ã¾ alp/alarmtest/alarm 
Ã¾Ã¾Ã¾Ã¾Ã¾ Handle:Ã¾Ã¾ aUniqueString 
Ã¾Ã¾Ã¾Ã¾Ã¾ Metric:Ã¾Ã¾ 0 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ State:Ã¾Ã¾ 00000005 <TBD> 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ Attr:Ã¾Ã¾ 000700ff <TBD> 
Ã¾ Prio Class:Ã¾Ã¾ 2 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ User:Ã¾Ã¾ 0 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ Group:Ã¾Ã¾ 0 
Ã¾Ã¾Ã¾Ã¾ Created:Ã¾Ã¾ Tue Oct 30 17:29:39 2007 
Ã¾Ã¾Ã¾Ã¾ Updated:Ã¾Ã¾ Wed Oct 31 11:46:12 2007 
 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ Start:Ã¾Ã¾ Tue Oct 30 17:29:39 2007 
 
Ã¾ Properties: 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ image:Ã¾Ã¾Ã¾ 'alp-stock-telephony-app' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ text-6:Ã¾Ã¾Ã¾ 'text-6' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ text-5:Ã¾Ã¾Ã¾ 'text-5' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ text-4:Ã¾Ã¾Ã¾ 'text-4' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ smarttext-3:Ã¾Ã¾Ã¾ 'http://www.google.com' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ smarttext-2:Ã¾Ã¾Ã¾ '(650) 555-1212' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ markup-1:Ã¾Ã¾Ã¾ 'mark<u>up</u>-1' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ title:Ã¾Ã¾Ã¾ 'title' 
 
Alert Id:Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ 3 
Ã¾Ã¾Ã¾Ã¾Ã¾ Source:Ã¾Ã¾ bar:com.access.apps.worldclock 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ Type:Ã¾Ã¾ /alp/alarm/clock 
Ã¾Ã¾Ã¾Ã¾Ã¾ Handle:Ã¾Ã¾ 0 
Ã¾Ã¾Ã¾Ã¾Ã¾ Metric:Ã¾Ã¾ 0 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ State:Ã¾Ã¾ 00000007 <TBD> 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ Attr:Ã¾Ã¾ 000700ff <TBD> 
Ã¾ Prio Class:Ã¾Ã¾ 2 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ User:Ã¾Ã¾ 0 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ Group:Ã¾Ã¾ 0 
Ã¾Ã¾Ã¾Ã¾ Created:Ã¾Ã¾ Wed Oct 31 11:49:01 2007 
Ã¾Ã¾Ã¾Ã¾ Updated:Ã¾Ã¾ Wed Oct 31 11:49:01 2007 
 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ Start:Ã¾Ã¾ Wed Oct 31 11:49:01 2007 
 
Ã¾ Properties: 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ action-button-3:Ã¾Ã¾Ã¾ 'goto' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ action-button-2:Ã¾Ã¾Ã¾ 'snooze 9' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ action-button-1:Ã¾Ã¾Ã¾ 'clear' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ button-1:Ã¾Ã¾Ã¾ 'Off' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ smarttext-4:Ã¾Ã¾Ã¾ 'AlarmÃ¾ 1' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ text-3:Ã¾Ã¾Ã¾ 'Los Angeles' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ text-2:Ã¾Ã¾Ã¾ 'Wednesday 10/31/07' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ text-1:Ã¾Ã¾Ã¾ '11:49 am' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ nag-interval:Ã¾Ã¾Ã¾ '300' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ vibrate-pattern:Ã¾Ã¾Ã¾ 'alp-stock-off' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ alert-tone-repeat-count:Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ '5' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ alert-tone-url:Ã¾Ã¾Ã¾ 'file:///usr/share/sounds/
system/Alarm.mp3' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ image:Ã¾Ã¾Ã¾ 'alp-stock-clock-app' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ action-default:Ã¾Ã¾Ã¾ 'snooze 9' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ icon:Ã¾Ã¾Ã¾ 'alp-stock-clock-app' 
Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾Ã¾ title:Ã¾Ã¾Ã¾ 'Alarm'

You can list a specific alert by indicating the application ID (for example, bar:com.access.apps.worldclock), like this:

alp_alert -l bar:com.access.apps.worldclock

If there is more than one alert in the list with the same application ID, you can further narrow the listing by including the all or part (always starting from the beginning) of the alert type, separating this from the application ID by a comma, like this:

alp_alert -l bar:com.access.apps.worldclock,alp/alarm

Finally, you can "dump" the contents of the alert database with the ---dump option.This presents the contents of the database in a more concise format; one that is a little less readable but is in fact formatted as if you were posting them to the database using the alp_alert command (and, in fact, you can cut and paste the result of the --dump option to repost an alert). Listing 4.2 shows a dump of the alert database. Note that the contents of the database in this listing are the same as in Listing 4.1.

IMPORTANT: The --dump option cannot be shortened to -d; the -d option is the short form of --delete, which deletes entries from the alert database.

Listing 4.2 A more concise alert listing

~ # alp_alert --dump 
alp_alert -p bar:com.access.apps.alarmtest,alp/alarmtest/alarm,aUniqueString -P 
2Ã¾ image='alp-stock-telephony-app' text-6='text-6' text-5='text-5' text-
4='text-4' smarttext-3='http://www.google.com' smarttext-2='(650) 555-1212' 
markup-1='mark<u>up</u>-1' title='title' 
alp_alert -p bar:com.access.apps.worldclock,/alp/alarm/clock,0 -P 2Ã¾ action-
button-3='goto' action-button-2='snooze 9' action-button-1='clear' button-
1='Off' smarttext-4='AlarmÃ¾ 1' text-3='Los Angeles' text-2='Wednesday 10/31/07' 
text-1='11:49 am' nag-interval='300' vibrate-pattern='alp-stock-off' alert-
tone-repeat-count='5' alert-tone-url='file:///usr/share/sounds/system/
Alarm.mp3' image='alp-stock-clock-app' action-default='snooze 9' icon='alp-
stock-clock-app' title='Alarm'

Posting Alerts ^TOP^

To post an alert to the database (which, depending upon the options you specify will usually cause the alert to be displayed on-screen), you use the --post (or -p) command. This command takes the following general form:

alp_alert -p source,alert-type,handle [options...] prop1=value1, ..., propN=valueN

The various parameters to this command are as follows:

source: The ID of the application posting the alert. More importantly, this is the ID of the application that will be launched if the user elects to "Go To" the application from the alert dialog. For example, bar:com.access.apps.worldclock.
alert-type: The event name. This is an application-defined string that names the event type.
handle: An application-defined string intended to help the application associate the alert with the actual event's data.
options: Zero or more options that affect the way that the alert is posted. These options are:
properties: Specify values for the alert's properties (title, text fields, buttons, and the like) by specifying the property name, followed by an equals sign, followed by the property value. Note that the property values usually are strings and should therefore be enclosed in quotes (unless the string contains no spaces or other special characters that might be misconstrued by the command-line interpreter. Examples include:

See Listing 4.2 for complete examples of how to post alerts.

Updating Alerts ^TOP^

The process of updating an alert mirrors that used when posting an alert. The only differences are:

Use the --update (or -U) command, rather than --post.
Supply the source, alert type, and handle for an existing alert.
Only specify those properties that you wish to change.

For instance, to change the title of the first alert listed in Listing 4.1, use the following command (all on one line):

alp_alert -u bar:com.access.apps.alarmtest,alp/
alarmtest/alarm,aUniqueString title='new title'

In addition to properties, you can update any of the options discussed under "Posting Alerts." You can also update multiple properties and options with a single update command.

Deleting Alerts ^TOP^

You can delete individual alerts with the --delete (or -d) command, or you can erase the entire alerts database with the --wipe command. The --wipe command takes no parameters. The --delete command must be followed by the source, alert type, and handle that together uniquely identify the alert to be deleted, like this (enter the command all on one line):

alp_alert -d bar:com.access.apps.alarmtest,alp/
alarmtest/alarm,aUniqueString

Application Signing ^TOP^

The ACCESS Linux Platform SDK includes the Sign Tool, which creates a digital signature and applies it to a bundle. Signatures on ACCESS Linux Platform bundles are used to verify that the contents of a bundle have been in the physical presence of someone who controls the signing key pair, and that the contents have not been modified since that time. Note that a signature applied to an executable in an installed bundle does not automatically imply that the code itself is more or less trusted. It does, however, provide a high degree of assurance as to the integrity of a bundle's contents and in some cases, a high degree of confidence in the identity of the signer. These two components, the identity of the signer and the integrity of the bundle's contents, are used by the Security Policy Framework to determine the degree to which a bundle is signed.

The Sign Tool requires the following to exist before it can function:

A bundle.
An X.509 certificate and private key.

The following section discusses the use of the signtool command. For more information on the ACCESS Linux Platform security architecture and the reasons why you might or might not want to sign an ACCESS Linux Platform application, see the Security chapter of ACCESS Linux Platform Application Programming.

The Sign Tool Command Line Interface ^TOP^

The Sign Tool runs from within Scratchbox. Its basic usage is:

signtool bundle_directory root_certificate_hash certificate_file 
private_key_file passphrase app_name

where:

bundle_directory: The directory path of where the bundle to be signed resides.For instance, ~/myApps/MiniPlayer/build/alp-device/com.access.apps.miniplayer.
root_certificate_hash: A hash of the root certificate. To get this hash you would run the following command on the root certificate:; Supply the output of the above command as the Sign Tool root_certificate_hash parameter. Note that if the root certificate changes, you'll need to supply the hash of the new root certificate when signing bundles.

NOTE: For testing purposes, you can supply the hash of the test certificate supplied with the ACCESS Linux Platform SDK.

certificate_file: The file containing the X.509 certificate.
private_key_file: The file containing the private key.
passphrase: The passphrase of the private key.
app_name: The name of the application (i.e. calendar, memo, etc.).

Signing With the Test Certificate and Key ^TOP^

ACCESS Linux Platform applications created using the templates provided with the ACCESS Development Suite are automatically signed using the test certificate (which acts as the root certificate for testing purposes) and key when the application is built; the template makefiles contain a step that does this for you. This certificate and key is provided for testing purposes only, and can be found in the samples directory:

/scratchbox/ALP/samples/key
/scratchbox/ALP/samples/certificate

NOTE: The above paths assume that you are within Scratchbox. From outside of Scratchbox, you can find the key and certificate in the /opt/alp-dev/sdk/samples/ directory.

In addition to the private key and certificate, Sign Tool needs the path to the directory containing your bundle, the name of your application, and a passphrase. The passphrase used with the self-signed test private key and certificate is "accesstest" (without the quotes).

As an example of how signtool is used, the following command would be used to sign the MiniPlayer application:

signtool build/alp-device/com.access.apps.miniplayer `openssl dgst -sha1 -
binary /scratchbox/ALP/samples/certificate | openssl enc -base64` /scratchbox/
ALP/samples/certificate /scratchbox/ALP/samples/key accesstest miniplayer

If you prefer, you can precompute the root hash value and pass that in instead of recalculating it every time you run signtool. But be mindful of the fact that if the root certificate changes, you'll need to precompute and then supply the hash of the new root certificate.

Note that the above command should be entered all on one line, and that "backquotes," rather than single quotes, should be used to surround the portion that generates the root certificate hash. As well, you need to be in the directory containing the MiniPlayer application (such as ~/myApps/MiniPlayer) before issuing the above command.

Creating Bundles ^TOP^

ACCESS Linux Platform applications are packaged into "bundles." Bundles are very easy to pass around as a single file, while still allowing their contents to be explored without costly overhead. ACCESS Linux Platform bundles are packaged using the ".bar" file is the format.

The ACCESS Linux Platform SDK includes bartender, a Perl script that packs a folder into the .bar package format, or unpacks a .bar file into a folder. This script is a thin layer of argument checking around a few Cramfs commands. (Cramfs is a compressed ROM filesystem.)

Invoke the bartender command from within Scratchbox. In Scratchbox, it is located in the /scratchbox/tools/bin/ directory. Its basic usage is:

bartender [pack | unpack] directory .bar-file

Creating a Bundle ^TOP^

Before you can invoke the bartender command, you must prepare a directory that contains the files that make up your bundle. This directory must contain a manifest file named Manifest.xml (see ACCESS Linux Platform Application Programming for more on manifest files and the structure of bundles). As well, the name of the directory must match the name specified by the name parameter of the manifest element. That is, if the manifest looks like this:

<manifest name="com.access.apps.sample"> 
	<application> 
		<name>Sample</name> 
		<icon>icon_sample.png</icon> 
</application> 
</manifest>

The directory in which the manifest file (and all of the other files that will be wrapped up into the bundle) must be named com.access.apps.sample.

Once you have created the directory, simply enter the following command (substituting the path to your directory for myfolder, and providing a proper name for your bundle in place of mypackage.bar):

bartender pack myfolder mypackage.bar

This will use the /usr/bin/mkcramfs command to put the contents of myfolder into the bundle file mypackage.bar.

Unpacking a Bundle ^TOP^

Unpacking a bundle is as simple as creating one. Given an existing bundle named mypackage.bar, you can unpack it into a directory named myfolder with the following command:

bartender unpack myfolder mypackage.bar

The above command uses the /usr/bin/cramfsck command to extract the contents of mypackage.bar into the directory named myfolder. Note that if the named directory already exists, it will not be overwritten.