POOM object

Description

The Pocket Outlook Object Manager (POOM) object provides an interface to the object store for the Pocket PC contact manager, appointment calendar, and task manager.

The POOM object interacts with other POOM-related objects listed in Table 15-4.

**Table 15-4: POOM and POOM-related objects**
Object	Description
POOM object	Main POOM object that provides an interface to other POOM-related objects, and lets you add and remove appointments, contacts, and tasks
POOMAppointment object	Gets and sets appointment recipients and recurrences
POOMContact object	Copies and displays contacts
POOMTask object	Copies and displays tasks, and gets and sets task recurrences
POOMRecurrence object	Used by the POOMAppointment and POOMTask objects to define recurring appointments and tasks
POOMRecipient object	Used by the POOMAppointment object to define the recipients of appointment notifications

The POOM object is the root object that lets you access all the other objects in the system. You use it to attach to the Pocket Outlook object manager running on the Pocket PC, to create and delete contacts, appointments, and tasks, and to receive and dispatch these objects (contacts, appointments, and tasks) using infrared queues.

You use the POOMContact, POOMAppointment, and POOMTask objects to specify the properties of objects, such as the e-mail address of a contact or the time of an appointment. All of these objects have functions that display the object on the Pocket PC and update any changes in the Pocket Outlook object manager’s repository.

The POOMAppointment and POOMTask objects also have functions that let you specify the details of recurring appointments and tasks, using the properties of the POOMRecurrence object.

POOMAppointment also lets you add and remove the names of recipients of an appointment (the individuals invited to a meeting).

Figure 15-1 displays the hierarchical relationships among the POOM-related objects.

Figure 15-1: Overview of POOM-related objects

Shown is a case diagram for system objects that help you use the Pocket Outlook Object Manager from a Pocket Builder application. The top level class is labeled POOM. The POOM Contact, POOM Appointment, and POOM Task classes inherit from the POOM class. POOM Recipient inherits from the POOM Appointment class, nd POOM Recurrence inherits from both the POOM Appointment class and the POOM Task class. Properties are displayed for each of the POOM related classes in the diagram.

Usage

You can add a POOM object to a window or user object by using the Insert>Object>POOM menu item or creating the object in a script.

Creating a POOM object To perform any POOM-related task, such as getting an appointment or creating a task, you must create a POOM object and attach to the Pocket Outlook object manager. You attach to the repository by calling the Login function. To ensure that the POOM object is removed from the device or emulator’s memory, call the Logoff function when you have finished working with the object manager.

When you call the Login function, you can optionally specify a window that will serve as the parent window for the Outlook session and will be used when you call the Display function. If you do not specify a window, the Pocket PC Contacts, Calendar, or Tasks window displays.

The following script creates a POOM object, attaches to the Pocket Outlook object manager, retrieves an array of appointments, and then detaches from the object manager:

// Global variable: POOM g_poom
POOMAppointment  myAppts[]
POOMTask         myTasks[]
POOMContact      myContacts[]
Integer li_rtn

g_poom = CREATE POOM

li_rtn = g_poom.login()

// Get appointments and display first in edit boxes

li_rtn = g_poom.getAppointments( myAppts )

sle_1.text = myAppts[1].subject

sle_2.text = STRING( myAppts[1].start, "[datetime]" )

sle_3.text = STRING( myAppts[1].end,   "[datetime]" )

sle_4.text = myAppts[1].location

…

g_poom.logoff()
DESTROY g_poom

The examples in the rest of this section assume that you have already attached to the Pocket Outlook object manager.

Modifying an item in the POOM repository To modify an existing item, you first obtain the item using one of the Get functions of the POOM object. For POOMAppointment, POOMContact, and POOMTask, the POOM object has four Get functions. For example, for contacts:

GetContact (index) gets a contact using its index in the object manager. It takes an integer and returns a POOMContact object.
GetContactFromOID (oid) gets a contact using its Windows CE object identifier (OID). It takes an unsigned long and returns a POOMContact object.

OIDs are not persistent You cannot use OIDs across POOM sessions. They are reassigned when the repository is backed up and at other times.
GetContacts (ref poomtask[]) gets an array of all the contacts in the repository and returns an integer.
GetContacts (matchcriteria, poomtask[]) gets an array of all the contacts in the repository that satisfy the match criteria and returns an integer.

Checking for valid objects When you use a function, such as GetContact or GetContactFromOID, that returns an object, use the IsValid function to ensure that a valid object was returned.

The following example changes the second e-mail address of the contact with index 23:

POOMContact mycontact

mycontact = g_poom.GetContact(23)
If IsValid(mycontact) then
   mycontact.email2address = "janedoe@netscape.net"
   mycontact.Update()
end if

Creating new objects You use the CREATE statement to create new objects. This example creates a new appointment, sets its subject, location, and start and end times, and specifies that the user should be reminded 15 minutes before the start time. The type of reminder is not specified in this example, so the system default will be used. You can specify the type of reminder with the ReminderOptions property.

integer li_rc
POOMAppointment appt
DateTime  dt

appt = CREATE POOMAppointment
appt.Subject = "Quick Team Meeting"
appt.Location = "Terry's Office"

// start the meeting 30 minutes from now and
// end it 15 minutes later
dt = datetime(today(), RelativeTime(now(), 30*60) )
appt.appointmentStart = dt
dt = datetime(today(), RelativeTime(now(), 45*60) )
appt.appointmentEnd = dt 
// set a reminder
appt.IsReminderSet = true
appt.ReminderMinutesBeforeStart = 15

// save the appointment in the repository and display it
li_rc = g_poom.Add( appt )

appt.display()POOMAppointment appt

You can add detailed notes to the object description only after it has been saved in the repository. The Body property sets a text annotation, and the BodyInk property sets an annotation in Pocket Word Ink (PWI) format. Setting either or both properties automatically updates the object. For example, if you add the following line to the previous example after the call to Add and before the call to Display, the text displays in the calendar:

appt.body = "Quick update on status”

Cloning an existing object When you modify an object, as described in “Modifying an item in the POOM repository”, you call the Update function to save your changes to the repository. If you call the Add function instead, a new object is added to the repository with the properties you change and all the properties of the original object. For example, if Mary Smith changes her last name to Smythe, and you want both names to be listed as contacts, you could use the following code, assuming Mary’s index in the contact list is 27:

POOMContact contact
contact = g_poom.GetContact(27)
If IsValid(contact) then
   contact.LastName = "Smythe"
   g_poom.Add( contact )
end if

Sending a cancellation notice You can use the Cancel function on an appointment to send a cancellation notice to the appointment’s recipients.

appt = g_poom.GetAppointment( 1 )

iRet = appt.Cancel()

Removing an existing object You can delete appointments, contacts, and tasks from the repository by calling the Remove function:

appt = g_poom.GetAppointment( 1 )

iRet = appt.Remove()

Creating and clearing a recurring appointment or task You create a POOMRecurrence object to set recurring properties for a valid appointment or task. The following code causes a task to be entered in the client Outlook calendar for 23 consecutive days:

POOMTask task

POOMRecurrence  recur

integer iRet

task = g_poom.GetTask( 1 )		// BY INDEX

if isValid(task) then

	// add the recurrence

	recur = CREATE POOMRecurrence

	recur.recurrencetype = RecursDaily!

	recur.Occurrences = 23

	iRet = task.SetRecurrence( recur )

	iRet = task.Update()

end if

You clear a recurrence pattern by calling ClearRecurrencePattern on the POOMRecurrence object for the repeating task or appointment:

task = g_poom.GetTask( 1 )		// BY INDEX

if isValid(task) then

	// clear the recurrence

	iRet = task.ClearRecurrencePattern()

	iRet = task.Update()

end if

Adding recipients to an appointment You add a recipient to an appointment by calling AddRecipient on a POOMAppointment object. The AddRecipient function can take string arguments for the name and address of a recipient, or can be passed a POOMRecipient object containing a recipient name and address. You must add recipients to an appointment one by one. However, if you use POOMRecipient objects exclusively to add appointment recipients, you can call GetRecipients on the POOMAppointment object to obtain an array of all the names on the recipient list and all the addresses where appointment notices are sent.

For more information

Properties and functions of the POOM object and its related objects are described in the PowerScript Reference and in the online Help.

For more information about the Pocket Outlook Object Model, see the Microsoft Web site.