Chapter 18: Working with POOM

The Pocket Outlook Object Model is the gateway to Outlook-specific data. POOM is not only a fun word to say, but also a powerful resource for developers. POOM allows you to integrate seamlessly your mobile applications into the standard core applications found on every Pocket PC.

Working with Appointments

The last piece of Pocket Outlook data we have to examine is appointments. As with tasks and  contacts, the Pocket Outlook .NET component makes working with appointments anveasy task.

From the development standpoint, appointments offer a powerful way to integrate mobile  applications with back-end scheduling systems. From your application, through Pocket Outlook, ActiveSync, Outlook, and finally an enterprise server, you have a seamless path for the delivery  of appointment-related data. This functionality can be used to schedule maintenance, meetings, followups, or any task that is date and time specific.Appointment functionality is exposed to the .NET Compact Framework through the Pocket Outlook .NET component from InTheHand. This  component's Appointments property and Appointment object are the subjects to this section.

The Appointments Property

The Appointments property of the OutlookApplication object provides access to the collection  of appointments resident on a device. In actuality, the Appointments property provides an interface  to the Appointments folder. The underlying Pocket Outlook Object Model supplies access to this folder.  This property links through to an Items collection that contains the actual appointments. This section includes several examples of the Appointments property along with its Items collection.

The Appointment Object

Individual appointments are created and modified through the Appointment object. Commonly used  properties and methods for this object are shown in Tables 18-5 and 18-6 respectively.

Table 18-5. Commonly Used Properties of the Appointment Object

PROPERTY	DESCRIPTION
AllDayEvent	Specifies whether this is an all-day event
Body	Defines the notes accompanying an appointment
Categories	Specifies the categories for which this appointment is assigned
Duation	Indicates the length of the appointment
End	Specifies when the appointment ends
Location	Indicates where the appointment takes place
Reminder Set	Specifies whether a reminder is configured for an appointment
Start	Indicates when the appointment starts
Subject	Indicates the subject of an appointment

Table 18-6. Commonly Used Methods of the Appointment Object

METHOD	DESCRIPTION
Cancel	Sends a cancellation of a meeting request
Copy	Creates a copy of an existing appointment
Delete	Deletes an appointment
Display	Displays an appointment using the native Appointment interface
Save	Saves modifications made to an appointment
Send	Sends a meeting request to the recipient list for an appointment

While these tables serve well for reference purposes, a set of practical demonstrations follow that provide detailed examples of commonly performed appointment-related operations.

Retrieving All Appointments

Whether or not you retrieve all appointments is going to be dependent upon your applications. Typically, you won't, instead opting for a range of dates under  which the appointments fall. As with tasks and contacts, there are several ways that you can retrieve appointments:

• As a collection of all appointments 
   
• As a subset of all appointments
   
• As an individual appointment

We'll start by looking at how to retrieve all appointments. It's the simplest method, and while not the most commonly used approach, it's still utilized within mobile applications. Listing 18-21 demonstrates this process.

Listing 18-21. Retrieving All of the Appointments

Imports InTheHand.PocketOutlook

[at the module level]
Dim poApplication As New OutlookApplication
Dim myAppointments As OutlookItemCollection

Private Sub btnLoad_Click(ByVal sender As System.Object, _
  ByVal e As System.EventArgs) Handles btnLoad.Click

    ' Retrieve all of the appointments.
     myAppointments = poApplication.Appointments.Items

Endd

The keys to this example are as follows:

• The Imports statement, which must be located at the top of a module.
   
• The declaration statement for the OutlookApplication object.
   
• The declaration of the OutlookItemCollection object, which can hold a collection of any Outlook items. In this case, it will hold a collection of  appointments.
   
• Loading the collection of appointments from the OutlookApplication object, poApplication, into the OutlookItemCollection, myAppointments.

At this stage, the collection myAppointments contains a set of appointment objects, one for each appointment that resides on the device. You can loop through this collection to view information on specific appointments.

Retrieving Appointments for a Given Date

While you may at times retrieve a list of all appointments, more commonly your application will want only those appointments that fall within a certain range of dates.

Listing 18-22 demonstrates retrieving a subset of appointments. First, appointments for today  are grabbed. Next, appointments for tomorrow are retrieved. Finally, how to select appointments for the next week is shown.

Listing 18-22. Retrieving Appointments for Specific Dates

Imports InTheHand.PocketOutlook

[at the module level]
Dim poApplication As New OutlookApplication
Dim myAppointmens As OutlookItemCollection

Private Sub btnSelect_Click(ByVal sender As System.Object, _
   ByVal e As System.EventArgs) Handles btnSelect.Click

    Dim strQuery As String
    Dim tmpDate As Date

  ' Retrieve appointments for today.
    strQuery = "[Start] = " & _
    ControlChars.Quote & Date.Today.ToShortDateString & _
    ControlChars.Quote
    myAppointments = poApplication.Calendar.Items.Restrict(strQuery)

  ' Retrieve appointments for tomorrow.
    tmpDate = Date.Today.AddDays(1)
    strQuery = "[Start] = " & _
       ControlChars.Quote & tmpDate.Date.ToShortDateString & ControlChars.Quote
    myAppointments = poApplication.Calendar.Items.Restrict(strQuery)

    ' Retrieve appointments for this next week.
     tmpDate = Date.Today.AddDays(7)
     strQuery = "[Start] >= " & _
        ControlChars.Quote & Date.Today.ToShortDateString & ControlChars.Quote
     strQuery = strQuery & " AND [Start] < " & ControlChars.Quote & _
       tmpDate.Date.ToShortDateString & ControlChars.Quote
     myAppointments = poApplication.Calendar.Items.Restrict(strQuery

End Sub

The preparatory work for this example is identical to that required by the previous example. You have to include the Imports statement and the declaration of both the variables for OutlookApplication and OutlookItemCollection.

Each of the sections of code that select appointments for today, tomorrow, and the next week make use of the Restrict method to retrieve the appropriate data. As you can see, the key to  these Restrict statements is some creative date manipulations.

NOTE While this example focuses on restricting appointments by their start date, you can in fact restrict appointments based upon the values of any of their properties.

Displaying an Appointment

As you've already seen with tasks and contacts, POOM provides you with the ability to access the native application interface of its data types through your application. What users will see is an appointment, displayed in the Pocket PC appointment interface.

This functionality is provided by the Display method of the Appointment object. Listing 18-23 shows an example of this technique.

Listing 18-23. Displaying an Appointment

Imports InTheHand.PocketOutlook

[at the module level]
Dim poApplication As New OutlookApplication
Dim myAppointments As OutlookItemCollection

Private Sub btnDisplay_Click(ByVal sender As System.Object, _
   ByVal e As System.EventArgs) Handles btnDisplay.Click

    Dim myAppointment As Appointment

    ' Retrieve all of the appointments.
      myAppointments = poApplication.Appointments.Items

    ' Display the first appointment.
      myAppointment = myAppointments.Item(0)
      myAppointment.Display()

End Sub

As with both of the examples involving retrieving appointments, you need to add to your application declarations for the Imports statement and the variables for both  OutlookApplication and OutlookItemCollection.

At the bottom of Listing 18-23 you'll see the code used to display an appointment. First,a collection of all appointments is retrieved. Next, a single appointment is selected, in this case the first appointment, and this appointment is used to create an Appointment object. It's through this Appointment object that you gain access to the Display method, which causes the appointment to be displayed.

Adding an Appointment

Adding an appointment is a three-step process. First, you need to create a new appointment. Second, you need to configure the appointment. Third, you need to save the appointment. Listing 18-24 demonstrates this process.

Listing 18-24. Adding an Appointment

Imports InTheHand.PocketOutlook

[at the module level]
Dim poApplication As New OutlookApplication

Private Sub btnAdd_Click(ByVal sender As System.Object, _
   ByVal e As System.EventArgs) Handles btnAdd.Click

    Dim myAppointment As Appointment

    ' Create a new appointment.
     myAppointment = poApplication.CreateAppointment

    ' Configure the appointment.
      With myAppointment
        .Body = "This is a sample appointment."
        .Categories = "demo"
        .End = DateAdd(DateInterval.Hour, 1, Now)
        .Location = "New York"
        .Start = Now
        .Subject = "demo appointment"

        ' Finally, save the appointment.
            .Save()
          End With

End Sub

As with the previous appointment examples, you start by adding the Imports statement and declaring the variables for OutlookApplication and OutlookItemCollection.

At the bottom of Listing 18-24 is the code that performs the three steps required to add an  appointment. First, a call is made to the CreateAppointment method of the OutlookApplication object. Second, the properties of the new appointment are configured. Finally, the Appointment object's Save method is called to save the appointment.

Modifying an Appointment

The process of modifying an appointment is similar to adding an appointment,only instead of creating a new appointment, you load an existing appointment into an Appointment object. Listing 18-25 demonstrates this process.

Listing 18-25.Modifying an Existing Appointment

Imports InTheHand.PocketOutlook

[at the module level]
Dim poApplication As New OutlookApplication
Dim myAppointments As OutlookItemCollection

Private Sub btnModify_Click(ByVal sender As System.Object, _
   ByVal e As System.EventArgs) Handles btnModify.Click

    Dim myAppointment As Appointment

    ' Retrieve all of the appointment.
     myAppointments = poApplication.Appointments.Items

    ' Modify the first appointment.
     myAppointment = myAppointments.Item(0)
     With myAppointment
        .Body = "This is updated content."
        .Save()
    End With

End Sub

As with all of the previous appointment examples, you start by adding an Imports statement and declaring the variables for OutlookApplication and OutlookItemCollection. At the bottom of Listing 18-25, you'll find where theappointment is first retrieved.

In this example, all of the appointments are retrieved, but only the first appointment is loaded into the Appointment object.From this point, you're free to modify any of the Appointment object's properties.You finish the modification process by calling the Appointment object's Save method.

Now that you've seen the basics of working with appointments, let's put all of these techniques together into a comprehensive example.