AppointmentItem Object

The AppointmentItem object represents an appointment in a calendar folder.

At a Glance

The AppointmentItem object is a subclass of the Message object and exposes all the same properties and methods, except for the Message object's Forward, Reply, and ReplyAll methods. In the following tables of properties and methods, those that are common with the Message object are linked to their descriptions for the Message object. Only the properties and methods unique to the AppointmentItem object are described in this section.

Properties

Methods

Remarks

An AppointmentItem object is distinguished from a Message object by its Type property containing IPM.Appointment.

New AppointmentItem objects can only be created by using the Add method on a Messages collection obtained from a Folder object reserved for calendar data:

  Dim objSession As Session 
  Dim objCalendarFolder As Folder 
  Dim objAppointments As Messages 
  Dim objNewAppointment As AppointmentItem 
 
  Set objCalendarFolder = objSession.GetDefaultFolder _ 
                                     (CdoDefaultFolderCalendar) 
  Set objAppointments = objCalendarFolder.Messages 
  Set objNewAppointment = objAppointments.Add 
 

An appointment can be obtained from its parent Messages collection using the collection's Item property. To get to the Messages collection in a folder, use the Folder object's Messages property. If you know an appointment's unique identifier, you can obtain it directly from the Session object's GetMessage method.

You can apply a MessageFilter object to a Messages collection containing appointments. However, the current version of CDO only supports filtering on the EndTime and StartTime properties. An attempt to filter on any other properties, including the inherited Message object properties, returns CdoE_TOO_COMPLEX.

You can turn an appointment into a meeting by setting its MeetingStatus property to CdoMeeting and sending it to one or more recipients. The appointment becomes a meeting as of the moment you call its Send method, at which time CDO instantiates a MeetingItem object and identifies you in the appointment's Organizer property. The MeetingItem object becomes a member of the Messages collection of each recipient's Inbox. They can treat it programmatically like the Message objects in the collection.

You should not send a meeting request for an appointment to any recipient that represents a distribution list, because the status of its individual members cannot be returned to you. You should only send the meeting request to single messaging users. You can determine if a messaging user is a distribution list by checking the DisplayType property of the AddressEntry object representing that user.

To cancel a meeting, you set the MeetingStatus property to CdoMeetingCanceled and send it to all the recipients. Once you have sent the cancellation you can release the underlying AppointmentItem object, typically by using the Set statement to assign it to Nothing. Note that simply releasing the appointment does not cancel the meeting, and in fact can produce unexpected behavior. You should always cancel first. Only the organizer of a meeting can cancel or release it.

If you organize and then cancel a meeting when your active calendar store is Microsoft® Outlook™, you must not only release the underlying AppointmentItem object but Delete it from the Messages collection as well. Failure to do this could cause unexpected results when working with the folders and their contents.

You can cause an appointment or meeting to become recurring by calling its GetRecurrencePattern method, which sets the IsRecurring property to True and returns a child RecurrencePattern object describing the recurrence characteristics. At first the RecurrencePattern object is populated with the default values indicated in its property descriptions, but you can change them as desired. The appointment or meeting can be restored to nonrecurring status with the ClearRecurrencePattern method, which also resets IsRecurring to False.

Making an appointment recurring does not create any additional AppointmentItem objects for the recurrences. But you may wish to instantiate an individual recurrence so that you can edit it and make it different from other recurrences in the series. You do this by using a MessageFilter object to restrict CdoPR_START_DATE and CdoPR_END_DATE to the start and end of the desired occurrence, and then calling the Messages collection's GetFirst method.

If you instantiate an individual recurrence and change one of its properties, and this property is subsequently modified on the original appointment, the modification to the original is not propagated to your recurrence. However, modifications on the original to properties which you have not changed in your recurrence are automatically propagated.

If any change is made to the original appointment's RecurrencePattern object after you have instantiated one or more individual recurrences, some or all of them may be automatically deleted. Microsoft® Outlook™ deletes all individual recurrences, while Microsoft Schedule+ deletes only those that are earlier than the new PatternStartDate or later than the new PatternEndDate. CDO does not automatically delete any individual recurrences.

If your calendar folder is in Microsoft Outlook and you change an individual recurrence's StartTime or EndTime property, the following rules are enforced:

• Two recurrences must not be on the same day.
• A recurrence must not be moved before a previous recurrence or after a subsequent recurrence.
• Recurrences must not be overlapped in time.

If these rules are not followed, Outlook returns CdoE_COLLISION on your next call to Send or Update.

An individual recurrence's GetRecurrencePattern method returns the same RecurrencePattern object as does the original appointment's GetRecurrencePattern. However, the individual recurrence is not the parent of the recurrence pattern. The original AppointmentItem object is the parent and in fact is obtained from the RecurrencePattern object through its Parent property:

  Dim objRecAppt As AppointmentItem ' an individual recurrence 
  Dim objOrigAppt As AppointmentItem ' the original appointment 
  Set objOrigAppt = objRecAppt.GetRecurrencePattern.Parent 
 

To edit an entire recurring series of appointments, you modify the appropriate properties on either the original AppointmentItem object or its child RecurrencePattern object. To edit an individual recurrence only, you instantiate it and modify its AppointmentItem properties. All changes take effect when you call the appointment's Send or Update method.

The original appointment's StartTime, EndTime, and AllDayEvent properties are disabled whenever its IsRecurring property is True. Any attempt to access them while in this state returns CdoE_NO_SUPPORT. You must use the recurrence pattern's PatternStartDate, PatternEndDate, StartTime, and EndTime properties to edit a recurring series.

Calendar folders are not supported in the public folders store provided with Microsoft® Exchange, and AppointmentItem and MeetingItem objects are stored as Message objects. An attempt to access a property or method specific to an appointment or meeting, such as Duration or GetAssociatedAppointment, returns CdoE_NO_SUPPORT. If you have declared an AppointmentItem object with early binding, for example Dim objAppt As AppointmentItem, CDO returns CdoE_NO_SUPPORT in this case. With late binding, Microsoft® Visual Basic® returns an error indicating no support.

An AppointmentItem object can be rendered into HTML hypertext using the CDO Rendering ObjectRenderer object. To specify this, set the object renderer's DataSource property to the AppointmentItem object itself. The individual properties that can be rendered with the RenderProperty method are indicated in the AppointmentItem and Message object property descriptions.

One or more appointments can also be rendered by the CDO Rendering CalendarView object's RenderAppointments method. The ContainerRenderer object's DataSource property must be set to the parent Messages collection and its CurrentView property to a calendar view.

An AppointmentItem object can also be rendered as the parent of a Recipients collection, using the ContainerRenderer object. The individual properties that can be rendered with the RenderProperty method are indicated in the AppointmentItem and Message object property descriptions.