[Cover] [Previous Section] [Next Section] [Index]
Current chapter: Interacting with Other HDML Services
Section 50 out of 67 total sections , Section 3 out of 4 sections in this chapter

Issuing requests to registered services

Your service can call registered services to send mail, retrieve or add address book entries, or add To Do entries.

To request registered services, use the following URL:

The following sections describe how to issue requests to specific categories of registered services.


Sending email with the registered email service

Service Registry-compliant email services (such as UP.Mail) provide interfaces that allow other services to send email messages on the user's behalf. To send an email message using the user's registered email service, you specify a task with the following options:

where SUB specifies the UP.Mail subroutine to call. To send an email, it must be set to sendMsg (the email send subroutine). You can specify the following fields for the VARS option

Argument  Description 
TO  

The email address for the message (required). 

SUBJ  

The subject of the message (optional). 

MT  

The text of the message (optional). 

A Service Registry-compliant email service displays the message that you instruct it to send, allowing the user to confirm the address and content. This ensures that a malicious service cannot send a message without the user's knowledge.

For example, the following HDML deck invokes the registered email service (UP.Mail in this case) to send a simple message to Developer Support at Unwired Planet. The interface is depicted in Figure 7-1

FIGURE  7-1.     Sending mail with UP.Mail


Using the registered address book service

Service Registry-compliant address book services (such as UP.Organizer) provide interfaces that allow other services to do the following:

The following sections describe how to use these interfaces.


Picking addresses from a registered address book

To prompt the user to select an address from a registered address book, specify an HDML task as follows:

where SUB specifies the UP.Organizer subroutine to call. To request an address, it must be set to pickAddr (the address book selection subroutine). You must also specify one of the following address book fields for the GET argument:

Argument  Description 
GET  

Specifies the address book field the address book returns to the first variable in the RECEIVE list, either fax, phone (prompts the user to choose between home or work), or email. 

You must specify the RECEIVE option with variables for each value to be returned when you request the address book URL. If the address book cannot provide the value specified by the GET argument, it returns empty strings for all RECEIVE variables, and the device displays an error message.

For example, the following HDML deck invokes the registered address book service (UP.Organizer in this case) to select an address and display it (see Figure 7-2):

FIGURE  7-2.     Picking an address with UP.Organizer

IMPORTANT     You must specify the DEST option on a single line (in other words, you cannot use line breaks within this value). The example above includes a line break simply because of page size limitations.


Adding addresses to a registered address book

To add an entry to a registered address book, specify an HDML task as follows:

where SUB specifies the UP.Organizer subroutine to call. To add an address, it must be set to addAddr (the address book insertion subroutine). You can specify any combination of one or more of the following address book fields for the VARS option:

Argument  Description 
FIRST  

URL-escaped string specifying the first name. 

LAST  

URL-escaped string specifying the last name. 

EMAIL  

The internet email address. 

FAX  

URL-escaped string specifying the fax phone number (for example, a string in the format NNN-NNN-NNNN). 

WORK  

URL-escaped string specifying the work phone number (for example, a string in the format NNN-NNN-NNNN). 

HOME  

URL-escaped string specifying the home phone number (for example, a string in the format NNN-NNN-NNNN). 

HOME2  

URL-escaped string specifying the second home phone number (for example, a string in the format NNN-NNN-NNNN). 

CELL  

URL-escaped string specifying the cell phone number (for example, a string in the format NNN-NNN-NNNN). 

PAGER  

URL-escaped string specifying the pager phone number (for example, a string in the format NNN-NNN-NNNN). 

PRIMARYNUMBER  

A flag identifying the primary contact number, one of the following values: 

w:  work (default)
h:  home
c:  cell
p:  pager
a:  alternate (home2) 

COMPANY  

URL-escaped string specifying the company name. 

COMPANYSTREET  

URL-escaped string specifying the company street address. 

COMPANYCITY  

URL-escaped string specifying the company city. 

COMPANYSTATE  

URL-escaped string specifying the company state. 

COMPANYZIP  

URL-escaped string specifying the company zip code (for example, a string in the format NNNNN or NNNNN-NNNN). 

COMPANYCOUNTRY  

URL-escaped string specifying the company country. 

HOMESTREET  

URL-escaped string specifying the home street address 

HOMECITY  

URL-escaped string specifying the home city. 

HOMESTATE  

URL-escaped text specifying the home state. 

HOMEZIP  

URL-escaped string specifying the home zip code (for example, a string in the format NNNNN or NNNNN-NNNN). 

HOMECOUNTRY  

URL-escaped string specifying the home country. 

For example, suppose you want to add an entry to the address book. You could use an HDML deck similar to the following. Figure 7-3 depicts the resulting interface.

FIGURE  7-3.     Adding an address to UP.Organizer


Using the registered To Do service

Service Registry-compliant To Do services (such as UP.Organizer) provide interfaces that allow other services to do the following:


Adding call entries to a registered To Do service

To add a call to a registered To Do service, specify an HDML task as follows:

where SUB specifies the UP.Organizer subroutine to call. To add a call, it must be set to addCall (the To Do call insertion subroutine). You can optionally specify either of the following fields for the VARS option:

Argument  Description 
TEXT  

The name of the person to call. 

PHONE  

The phone number to call. 

IMPORTANT     If you do not specify the TEXT or PHONE arguments, the device prompts the user to enter the appropriate values.

For example, suppose you want to add a call to the To Do list. You could use an HDML deck similar to the following. Figure 7-4 depicts the resulting interface.

FIGURE  7-4.     Adding a call to the UP.Organizer To Do list


Adding task entries to a registered To Do service

To add a task to a registered To Do service, specify an HDML task as follows:

where SUB specifies the UP.Organizer subroutine to call. To add a To Do item, it must be set to addToDo (the To Do task insertion subroutine). You must also specify the following field for the VARS option:

Argument  Description 
TEXT  

The text of the To Do item to add. 

For example, suppose you want to add a task to the To Do list. You could use an HDML deck similar to the following. Figure 7-4 depicts the resulting interface.

FIGURE  7-5.     Adding a task to the UP.Organizer To Do list

[Cover] [Previous Section] [Next Section] [Index]
Current chapter: Interacting with Other HDML Services
Section 50 out of 67 total sections , Section 3 out of 4 sections in this chapter

Copyright © 1999, Unwired Planet, Inc. All rights reserved.