• It is a Procedure Extension Template, so you add it to a local procedure in order to use and object in that procedure.
• Adds an Outlook object to a procedure for you, as well as declares the various Virtual methods of the class for callbacks, embedding code etc.
• Handles calling the Init() and Kill() methods to start Outlook and close it when done (the template allows you to do this yourself if you prefer).
• Provides a number of options for how Outlook will be initialised, such as whether the Outlook window will be visible and so on.
• It is optional, you can hand code adding and Outlook object if you prefer, however the template is the most frequent manner in which you will add an Outlook object to a procedure.
• Works with procedures that have a Window. For source code procedures you will need to add the object and call the Init() and Kill() methods manually.
   

1. Select the procedure which you want to add this template to.
2. Select "Properties..." from the "Edit" menu
3. Click the "Extensions" button
4. Click on the "Insert" button to add a new extension template
5. Select "Add_MSOutlook_Object" ( found under the "Class OfficeInside" group )
6. Click "Select", then "OK", then "OK" again...

General Tab:

Object Name:

This is the name of the Office Inside object that this template will create and implement.  Typically this would default to 'MyOutlook1', but you can change it if you would prefer to call the object something else.

Base1 Tab:

Initialise This Object:

This option allows you to select whether the template will generate code to initialise the object and when it will be initialised.

Event Handler:

When the Init() method is called it can optionally turn on event handling. This option allow this to be controlled from the template.

Base2 Tab:

Kill This Object:

The dropdown allows you to choose whether code is generated to Kill() the Outlook object (and close Outlook), as well as when that code should be called.

DeleteAppointment (string pEntryID)

Deletes the appointment identified by the pEntryID parameter from Outlook.

Note: This method does not prompt the user with a "are you sure you want to delete this record" message, you need to do that yourself if you want to, this method simply deletes the Appointment from Outlook.

Parameters

string pEntryID: The unique identifier used by Outlook for this entry. The EntryID is retrieved when calling GetAppointment() or GetAppointmentQ() and is also returned when you add a new entry by calling the InsertAppointment() method.

Return Values

Returns 1 for sucess and zero for failure.

Examples

    !--- Example 1: Simply Delete an Appointment using the EntryID to identify it:
    MyOutlook.DeleteAppointment(EntryID)

  

!--- Example 2: Fetch all appointments, and delete all non-recurring
!               appointments that have expired (already occurred)
MyCalendar         queue(oioCalendarQType1)
                   end
  code    
! Fill a queue with all Calendar entries
    MyOutlook.GetAppointmentsQ(MyCalendar)
    loop i = 1 to Records(MyCalendar)
        Get(MyCalendar, i)
        ! Delete expired, non recurring entries
        if not MyCalendar.IsRecurrings
            if Today() > MyCalendar.End_Date and Clock() > MyCalendar.End_Time
                ! Delete the appointment from Outlook
                MyOutlook.DeleteAppointment(MyCalendar.EntryID)
                ! Delete the appointment from the queue
                Delete(MyCalendar)                              
             end
        end
    end
  

See Also

DeleteContact, DeleteTask, DeleteAppointment

DeleteContact (string pEntryID)

Deletes a Contact (Address Book Entry) from Outlook when passed the unique EntryID that Outlook uses to identify the specific contact.

Note: This method does not prompt the user with a "are you sure you want to delete this record" message, you need to do that yourself if you want to, this method simply deletes the Contact from Outlook.

Parameters

string pEntryID: The unique identifier used by Outlook for this entry. The EntryID is retrieved when calling GetContact() or GetContactsQ() and is also returned when you add a new entry by calling the InsertContact() method.

Return Values

Returns 1 for success, or zero for failure.

Examples

EditContact_EntryID         string(255)
  code
    ! Delete a selected Contact
end

See Also

InsertContact, GetContact, GetContactsQ

DeleteTask (string pEntryID)

Deletes the task identified by the pEntryID parameter from Outlook.

Note: This method does not prompt the user with a "are you sure you want to delete this record" message, you need to do that yourself if you want to, this method simply deletes the Task from Outlook.

Parameters

string pEntryID: The unique identifier used by Outlook for this entry. The EntryID is retrieved when calling GetTask() or GetTasksQ() and is also returned when you add a new entry by calling the InsertTask() method.

Return Values

Returns 1 for success and zero for failure

Examples

!--- Fetch all Task, and delete all Tasks that are
!    older than the current date and time
TasksQ             queue(oioTaskQType1)
                   end
  code
    MyOutlook.GetTasksQ(TasksQ)
    loop i = 1 to Records(TasksQ)
        Get(TasksQ, i)
        if (Today() > TasksQ.StartDate_Date and Clock() > TasksQ.StartDate_Time)
            MyOutlook.DeleteTask(TasksQ.EntryID)
            Delete(TasksQ)
        end
    end

See Also

GetTask, GetTasksQ, InsertTask

DisplayContact (string pEntryID)

Displays the Contact with the passed EntryID in Outlook. This opens the Outlook Contact dialog, allowing the user to view and modify the Contact using the Outlook dialog itself.

Parameters

string pEntryID: The unique identifier used by Outlook for this entry. The EntryID is retrieved when calling GetTask() or GetTasksQ() and is also returned when you add a new entry by calling the InsertTask() method.

Return Values

Returns 1 for success and zero for failure

Examples

      if EditContact_EntryID = ''
          Message('Please select a Contact first...', 'Office Inside')
      else
          if MyOutlook1.DisplayContact(EditContact_EntryID) = false
              Message('Failed to display the Contact!', 'OfficeInside')
          end
      end

See Also

GetTask, GetTasksQ, InsertTask

ErrorTrap (string pErrorString, string pFunctionName)

This method is called when an error occurs. Office Inside provides embed points for this method (before parent call, and after parent call) where you can put code to deal with any errors Office Inside experiences (see the example code below - note that the text on a grey background is what the template generates, and the code after the parent call is an example of custom error handling).

By default any errors that Office Inside encounters will be dealt with as follows:

1. First, this ErrorTrap method is called, where you can act on the error message as shown in the example code above.
2. Second, Outlook might display a message of its own. You can suppress all messages by ticking the Suppress Error Messages check box in the procedure extension template.

Note 1: Even if you suppress error messages the ErrorTrap method will still be called.

Note 2: The Suppress Error Messages checkbox simply generates a line of code that sets the SuppressErrorMessages property to true.  You can set this property manually if you prefer.

Parameters

string pErrorString: A string containing the error message that the method passed to ErrorTrap. You can use this string to display the error to the user, and also to implement your own error handling based on which error occurred.

string pFunctionName: A string that contains the name of the Office Inside method that the error occured in.

Return Values

None. ErrorTrap is called by the class itself, typically it is only called by the class itself and you would embed code in it, but not call it yourself.

Examples

MyOutlook.ErrorTrap PROCEDURE(string pErrorString, string pFunctionName)
  code
    case pErrorString
    of 'Init Failed'
        Message('Sorry but there was an error using Outlook. Error ' |
              & Clip(pErrorString))
        Post(event:closewindow)
    end
    parent.ErrorTrap (pErrorString, pFunctionName)

See Also

EventItemSend ()

This event callback method is fired when Outlook sends an item (a Mail Message). You can use this event callback method to add code to perform some action (such as informing the user) when a send occurs.

This is a virtual method, which will fire automatically when the event occurs.  Microsoft Office fires this event, which in turn is picked up inside the Office Inside DLL, which in turn calls this method in your code.  Simply embed code in the provided embed point to deal with this event (if you wish to do so).

Parameters

None

Return Values

None

Examples

 MyOutlook.EventItemSend PROCEDURE()

code
    MessageStore.Sent = true              ! Update a record's sent status
    Access:MessageStore.Update()

See Also

EventItemSend, EventNewMail, EventOptionsPagesAdd, EventQuit, EventReminder, EventStartup

EventNewMail ()

This event callback method is fired when a new Mail Message is created in Outlook. You can use this event callback method to add code to perform some action (such as informing the user) when a new mail message is added to Outlook.

This is a virtual method, which will fire automatically when the event occurs.  Microsoft Office fires this event, which in turn is picked up inside the Office Inside DLL, which in turn calls this method in your code.  Simply embed code in the provided embed point to deal with this event (if you wish to do so).

Parameters

None

Return Values

None

Examples

 MyOutlook.EventItemSend PROCEDURE()
  code
    MessageStore.Sent = true              ! Update a record's sent status
    Access:MessageStore.Update()

See Also:

EventItemSend

EventOptionsPagesAdd ()

This event callback method is called when the Options page (window) in Office is displayed. You can use this (and the other Event methods) to trap when this even occurs are respond to it in your code.

This is a virtual method, which will fire automatically when the event occurs.  Microsoft Office fires this event, which in turn is picked up inside the Office Inside DLL, which in turn calls this method in your code.  Simply embed code in the provided embed point to deal with this event (if you wish to do so).

Parameters

None

Return Values

None

Examples

MyOutlook.EventOptionsPagesAdd PROCEDURE()
  code
    parent.EventOptionsPagesAdd()
    ! An Options page has been added, so take some action here

See Also

EventItemSend, EventNewMail, EventOptionsPagesAdd, EventQuit, EventReminder, EventStartup

EventQuit ()

This event callback method is fired when the user exits Outlook that the oiOutlook started.

This is a virtual method, which will fire automatically when the event occurs.  Microsoft Office fires this event, which in turn is picked up inside the Office Inside DLL, which in turn calls this method in your code.  Simply embed code in the provided embed point to deal with this event (if you wish to do so).

Parameters

None

Return Values

None

Examples

MyOutlook.EventQuit PROCEDURE()  
   code
    parent.EventQuit()
    Post(Event:Closewindow) ! The user closed Outlook, so close this window

See Also

EventItemSend, EventNewMail, EventOptionsPagesAdd, EventQuit, EventReminder, EventStartup

EventReminder ()

This event callback method is called when Outlook triggers a Reminder for a task. Reminders can display a message to the user, or play a sound to inform the user that their is a pending task.

This is a virtual method, which will fire automatically when the event occurs.  Microsoft Office fires this event, which in turn is picked up inside the Office Inside DLL, which in turn calls this method in your code.  Simply embed code in the provided embed point to deal with this event (if you wish to do so).

Parameters

None

Return Values

None

Examples

MyOutlook.EventReminder PROCEDURE()
  code

    parent.EventReminder()
    Message('Check your Outlook Tasks!') ! Inform the user

See Also

EventItemSend, EventNewMail, EventOptionsPagesAdd, EventQuit, EventReminder, EventStartup

EventStartup ()

This event callback method is called when Outlook starts up. You can use this method to execute any code that you want to happen the Outlook has first started.

This is a virtual method, which will fire automatically when the event occurs.  Microsoft Office fires this event, which in turn is picked up inside the Office Inside DLL, which in turn calls this method in your code.  Simply embed code in the provided embed point to deal with this event (if you wish to do so).

Parameters

None

Return Values

None

Examples

MyOutlook.EventStartup PROCEDURE()
   code

    parent.EventStartup()
    ! Call a routine to display some controls that relate to using Outlook
    Do ShowOutlookOptions

See Also

EventItemSend, EventNewMail, EventOptionsPagesAdd, EventQuit, EventReminder, EventStartup

GetAppointment (string pEntryID)

Whereas the GetAppointmentsQ method is used to read all appointments from Outlook into a Clarion queue, the GetAppointment method can be used to read a single appointment record, if you know its Outlook ID (which you pass as pEntryID)

• When you call this method the AppointmentProperties property is updated, see the Object Properties section below..
• See the Outlook_Calendar procedure in the offdemo.app example application for more info.

Note: Recurring Appointments
Outlook provides a number of options for recurring appointments, not all fields need to be filled in for every recurring appointment, in fact specific fields apply to specific types of appointments and if you insert or update an appointment with invalid values it will fail. See the Object Properties section below for the fields that these values are used in.

Recurring Appointments
	RecurrenceType Properties Used Example oio:RecursDaily Interval 10 (Every 10 days) DayOfWeekMask oio:Monday + oio:Friday (Mondays and Fridays) oio:RecursMonthly Interval 2 (Every two months) DayOfMonth 8 (The 8th day of every month) oio:RecursMonthNth Interval 2 (Every 2 months) Instance 1 (The first Tuesday and Wednesday, the days are specified below, this is just used for which instance of the days it will be). This is optional DayOfWeekMask oio:Tuesday + oio:Wednesday (Tuesday and Wednesday) oio:RecursWeekly Interval 3 (Every three weeks) DayOfWeekMask oio:Tuesday + oio:Wednesday (Tuesday and Wednesday) oio:RecursYearly DayOfMonth 12 (he 12th day of the month) MonthOfYear 2 (February. MonthOfYear is a number from 1 to 12 for the months January to December) oio:RecursYearNth Instance 3 (The third time this day occurs in the year, for example the third Tuesday in the year) DayOfWeekMask oio:Tuesday + oio:Wednesday + oio:Thursday (Tuesday, Wednesday and Thursday) MonthOfYear 3 (March. MonthOfYear is a number from 1 to 12 for the months January to December)

Parameters

string pEntryID: The Unique identifier that Outlook uses for this entry. This value is retrieved when calling InsertAppointment, and the EntryID field in the the queue is populated with this value when calling GetAppointmentsQ.

Return Values

Returns 1 for success and zero for failure.

Examples

This example gets an appointment and then deletes it if is it older than today's date and time.

  code
    MyOutlook.GetAppointment(appointmentID)    ! Fetch an appointment
    if Today() > MyOutlook.AppointmentProperties.End_Date and |
       Clock() > MyOutlook.AppointmentProperties.End_Time
        MyOutlook.DeleteAppointment(MyOutlook.AppointmentProperties.EntryID)
    end
        

Object Properties

This method populates the oiOutlook.AppointmentProperties member of the oiOutlook object with the details of the Appointment. AppointmentProperties is a group with the following fields:

See Also

InsertAppointment, GetAppointmentsQ, DeleteAppointment, UpdateAppointment

GetAppointmentsQ (*oioCalendarQType1 pQueue, <string pEntryID>)

This method is used to read appointments from Outlook, by filling a Clarion queue (as in the example code below). The queue filled is a oioCalendarQType1 queue. See Data Types below for a list of all fields in the queue and a description of each field and it's values.

Note: You should declare the queue using the type provided by Office Inside, as these queues may change in structure with additional field in future versions, and using the Type rather than redeclaring the queue ensures you maintain compatibility.

• If you pass an Outlook EntryID in the second (optional) parameter, then a single record is read and populated into the queue, we recommend using the GetAppointment method instead.
• See the Outlook_Calendar procedure in the offdemo.app or offdemo6.app example application for and example of using this method.

Note: Recurring Appointments
Outlook provides a number of options for recurring appointments, not all fields need to be filled in for every recurring appointment, in fact specific fields apply to specific types of appointments and if you insert or update an appointment with invalid values it will fail.

Parameters

*oioCalendarQType1 pQueue: A queue that is filled with the Appointments from Outlook. See the Data Types section below for a full description of the oioCalendarQType1 queue type, the fields that it contains and a description of each field and its values.

<string pEntryID>: An optional string that fills the queue with a single entry containing the Appointment that matches the passed EntryID. To retrieve a single record we recommend using the GetAppointment method instead.

Return Value

Returns 1 for success and zero for failure.

Examples

! This example fills a queue with all Appointments, then adds all
! recurring appointments to a new queue (MyEvents). It also deletes
! all appointments that are not recurring and where the appointment end
! date and time are older than today

MyCalendar         queue(oioCalendarQType1)
                   end
MyEvents           queue(oioCalendarQType1)
                   end

 code
    !--- Fill a queue with all Calendar entries
    MyOutlook.GetAppointmentsQ(MyCalendar)
    loop i = 1 to Records(MyCalendar)
        Get(MyCalendar, i)
        ! The queue fields contain the information for this Appointment (calendar entry)
        ! Example: Add recurring events to another queue
        if MyCalendar.IsRecurring
            MyEvents = MyCalendar
            Add(MyEvents)
        else
        ! Example: All expired, non recurring entries could be deleted
            if Today() > MyCalendar.End_Date and Clock() > MyCalendar.End_Time
                MyOutlook.DeleteAppointment(MyCalendar.EntryID)
                Delete(MyCalendar)
            end
        end
    end

Data Types

The oioCalendarQType1 queue type is provided for storing the data returned by this method. The table below lists the fields contained in the queue and describes each field.

oioCalendarQType1
	Field Name Type Description Subject string The Subject of the Task. StartDate_Date long Standard Clarion date for when the Task starts (optional) StartDate_Time long Standard Clarion time for when the Task starts EndDate_Date long Standard Clarion date for the Due Date for the Task EndDate_Time long Standard Clarion time when this Task is due CreationTime_Date long Standard Clarion date when this Task was created CreationTime_Time long Standard Clarion time when this Task was created LastModificationTime_Date long Standard Clarion date when this Task was last modified LastModificationTime_Time long Standard Clarion time when this Task was last modified Duration long Duration of this task in minutes Body string The body text describing this appointment's details Importance byte The importance of this appointment, can be one of three values:   oio:ImportanceHigh   oio:ImportanceNormal   oio:ImportanceLow AllDayEvent byte Set this to 1 for an all day event BusyStatus byte Can be set to one of the following values indicating the type of appointment:   oio:Free   oio:Tentative   oio:Busy   oio:OutOfOffice IsRecurring byte Set to 1 if this is a recurring event (such as birthday, anniversary etc.) Recurrence_Type long The type of recurrence, once of the following values:   oio:RecursDaily        (once a day)   oio:RecursWeekly      (once a week)   oio:RecursMonthly    (once a month)   oio:RecursMonthNth  (every N months*)   oio:RecursYearly      (once a year)   oio:RecursYearNth    (every N years*) *Where N is the number of months/years between recurrances Important: Each recurrance type only supports certain fields, and the field values must be correct, incorrect values will result in updates or insertion of the appoint failing. See the note above on Recurring Appointments for the fields used for each type and their values. Recurrence_DayOfMonth long The day of the month on which the Appointment recurs, a long value that stores the day, for example 15, for the 15th day of the month. Recurrence_DayOfWeekMask long The day of the week on which the Appointment recurs, can be one of the following values: oio:Sunday oio:Monday oio:Tuesday oio:Wednesday oio:Thursday oio:Friday oio:Saturday Note that you can add these values together. For example for an appointment every Monday, Wednesday and Friday: Recurrence_DayOfWeekMask = oio:Monday + oio:Wednesday + oio:Friday Recurrence_Duration long Duration of the appointment in minutes Recurrence_Instance long The instance of the day or of the month that this appointment recurs on. For example setting this to 3 could recur on the 3rd Tuesday of every month (depenant on the DayOfWeekMask value) Recurrence_Interval long The interval with which this appointment recurs. For example this could be set to 2 for an appointment that recurs every 2 days, month or years. Recurrence_MonthOfYear long The month of the year. A value from 1 to 12 representing January (1) to December (12) Recurrence_NoEndDate long Set to true (1) of the recurrance pattern has no end date Recurrence_Occurrences long The number of times this event will happen. For example setting this to 10 means that this event will occur 10 times before it expires. Recurrence_PatternStartDate long The date at which this recurrance pattern will start Recurrence_PatternStartTime long The time at which this recurrance pattern will start Recurrence_PatternEndDate long The date at which this recurrance pattern will end Recurrence_PatternEndTime long The time at which this recurrance pattern will end ReminderSet byte Set to true (1) if Outlook displays a reminder when the appointments occurs ReminderMinutesBeforeStart long The number of minutes before the appointment that the reminder is displayed Location string A string describing where the appointment takes place EntryID string A unique identifier for this Outlook item. Read Only

See Also

InsertAppointment, GetAppointment, DeleteAppointment, UpdateAppointment

GetContact (string pEntryID)

Retrieves a specific contact using the passed EntryID. Whereas the GetContactsQ method is used to read all contacts from Outlook into a Clarion queue, the GetContact method can be used to read a single contact record, if you know its Outloo