The upnotify utility (sdk_installdir/bin/upnotify) allows you to send and manage notifications from the command-line on UNIX. Specifically, it allows you to:
The upnotify utility is designed primarily for prototyping and testing applications that send notifications. For production applications, it is recommended that you use the COM interface or the C++ Notification API, which are described in the UP.SDK Developer's Guide.
upnotify, it is recommended that you set the UPSDK environment variable to the directory in which you installed the UP.SDK. If you don't set this variable, you will need to specify a lot of absolute paths at the command-line.
To use the upnotify utility to send secure notifications, you must first obtain and install a certificate as described in Installing certificates with upcerins.
The following is the syntax for upnotify:
subscriber_ID -u URL -a|-p [-e expiration]alert_type -i alert_title] HTTPS_timeout] [-H messenger_host]messenger_port] [-q|-d] [-n|-s]
| Option | Description |
|---|---|
-s subscriber_ID
| The ID of the subscriber to whom the notification is addressed. |
-u URL
| Specify the notification URL. For prefetch notifications, this is the URL of the digest that will be preloaded into the phone's cache; for alerts, this is the URL that will be fetched when the user requests the alert from the phone's status card. The URL must be hosted on the domain for which the certificate was issued. For more information, see Requesting certificates with CertMaker. |
|
-a
|
Set the notification type to alert. When adding an alert, the alert type and title must be specified using the |
|
-p
|
Set the notification type to prefetch. Note that the |
-e expiration
| Set the expiration period of the notification to the given number of seconds. If the UP.Link server cannot deliver the notification within this period of time, the notification will expire. If you omit this option, the expiration period defaults to the maximum allowed by the UP.Link server--which is 60 days by default. |
-y alert_type
| A string specifying the type of signal to issue to the subscriber. It consists of four characters, representing the device-dependent signal, sound, visual signal, and vibration signal, respectively. You can specify several values for each type of signal:
The dash ( The recommended alert_type string is:
You must specify the |
-i alert_title
| Specify the alert title string. This option is required when adding an alert; it is disallowed otherwise. |
-t HTTPS_timeout
|
Specify the amount of time (in seconds) before |
-H messenger_host
| Specify the name of the host on which the UP.Link Messenger is running. The Messenger is the UP.Link server component that handles notifications.
If you omit this parameter,
|
-P messenger_port
|
Specify the UP.Link server port number to communicate with. If you omit this, |
|
-q
|
Specify that a notification query is to be performed. If neither the |
|
-d
|
Specify that a notification delete is to be performed. If neither the |
-f cert_file
| Specify a full path to the file containing the certificate and key.
If you omit this option, and the environment variable |
-k cert_password
| Specify the password to use when decrypting the certificate file. This is the password you provided when you ran the CertMaker utility.
If you omit this option, |
|
-n
|
Specifies that the non-secure (HTTP-based) If you want to send non-secure notifications and you don't have a certificate, use this option. |
|
-S
|
Require that the secure (HTTPS-based)
This option disables failover to
Do not confuse this option with the lowercase |
|
-h
|
To send the alert notification depicted in Figure 2-3 to the subscriber with the following ID:
you could use the following upnotify call:
FIGURE 2-3. Alert notification in the UP.Phone Inbox
When the user chooses this alert and presses ACCEPT, the phone displays the Unwired Planet Developer Home card.
To send a prefetch notification that loads the following URL:
to the phone of the subscriber with the ID 85985209-411_updev.uplanet.com, set the UPSDK environment variable to the directory in which you installed the UP.SDK. Then use the following upnotify call:
If you do not specify the -k option, upnotify prompts you for a password.
After you enter the upnotify command and provide the certificate password, the command generates status messages. For example, the example command above generates the following messages:
To view the status of the notification in the preceding example, use the following upnotify command: