Vote for this Product at ClarionShop
  
Buy now at ClarionShop


www.capesoft.com
c3pa approved
     


Microsoft Outlook Functionality


Contents
 

Getting Started With Outlook
  Quick Start guides - Recommended Reading
       Mail Folders and Messages
        Contacts, Tasks and Appointments
 Examples
Templates

  

Classes
   The oiOutlook Class
         Methods
         Methods listed by Usage (Category) - New
         Equates
         Data Types 

 DLL Functions

 
 

Useful References
       Tips & FAQs
       Outlook and Security (How to Get Rid of Those Stupid Outlook Security Popups).
      Distribution: What to Ship with your Application 
       Licensing
Return to the Main Office Inside Docs
     


 Getting Started with Outlook (Quick Start guide)

Office Inside provides a set of templates and objects that makes interfacing and exchanging data with Microsoft Outlook easy. With Office Inside you can easily:

One of the best ways to get acquainted with Office Inside in general, and the Outlook functionality in particular is the main Office Inside example application. This demonstrates the basic functionality that you would typically add to your application, such retrieving, updating, inserting and deleting Mail, Contacts, Tasks and Calendar entries from Outlook.

Outlook functionality falls into four separate sections:

Office Inside provides functions to very simply handle each of these categories, all of which is demonstrated in the Quick Start below!

--------

 Quick Start Guides

The classes are much less intimidating than they look, a quick useful application can be built in a few minutes, without a huge amount of effort:

  1. Add the global extension
  2. Add an Office Inside object using the local extension
  3. Add a few lines of code to do the work….

Now we will look at how to access the various types of data provided by Outlook in each of the QuickStart Guides below.

--------

 Mail Folders and Messages

Fetching the Folders

Fetching a Message

Example Code

MailFolders    queue(oioFolderNameQType)
             end
MailMessages queue(oioFolderItemsQType)
             end
curFolder    long
curMail      long
  messageHtml  &string
messageText   &string
retVal        long
AttachmentsQ   queue(oioAttachmentsQ)
               end
  code

!--- First Fetch a list of all Mail folders
MyOutlook.GetMailFoldersQ(MailFolders)

messageText &= new string(32000)
messageHtml &= new string(64000)

!--- Now loop through the queue and fetch the mail items
loop curFolder = 1 to Records(MailFolders)
    Get(MailFolders, curFolder) MyOutlook.GetMailItemsQ(MailMessages, MailFolders.EntryID)
    !--- You can now loop through the MailMessages queue to retrieve each message using
    ! The GetEmailBody() method to get the body of the mail and the
    ! GetMailAttachmentsQ() to get a list of all attachments
    loop curMail = 1 to Records(MailMessages)
        Get(MailMessages, curMail)
        retVal = MyOutlook.GetEmailBody(MailMessages.EntryID, messageText, false)
        if retVal = -1
            ! An error occured, the COM interface failed to fetch the data
        elsif retVal > 0
            ! The emailText string was too small, so it was truncated, resize and fetch again
            Dispose(messageText)
            messageText&= new string(retVal)
            retVal = GetEmailBody(MailMessages.EntryID, messageText, false)
            if retVal <> 0
                ! Failed to fetch the message body.
            end
        end

        retVal = MyOutlook.GetEmailBody(MailMessages.EntryID, messageHtml, true)
        ! Handle errors and resizing here in the same fashion as above
        myOutlook.GetMailAttachmetsQ(AttachmentsQ, MailMessages.EntryID)
        !--- This is where you would store or process the contents of the message, the attachments etc.
        ! for example you can call the SaveAttachment()method to save the attachments to disk.
        ! See the section below for more information on Attachment Handling
    end
end
Free(MailFolders)
Free(MailMessages)
Dispose(messageText)
Dispose(messageHtml)

Fetching and Saving Attachments

You can fetch a list of all attachments for a particular Mail message using the GetMailFoldersQ() method, which takes a oioAttachmentsQ queue and populates it with a list of all attachments for a particular mail:

AttachmentsQ queue(oioAttachmentsQ)
             end
i            long
savePath     string(File:MaxFileName)
  code

MyOutlook.GetMailAttachmetsQ(AttachmentsQ, MailMessages.EntryID)
savePath = LongPath() & '\Attachments\'
!--- Save All Attachments
MyOutlook.SaveAtttachment(MailMessages.EntryID, 0, savePath, AttachmentsQ.FileName)

!--- Can also save individual attachments, for example save attachments that are not EXEs:
loop i = 1 to Records(AttachmentsQ)
    Get(AttachmentsQ, i)
    if not Instring('.exe', Lower(AttachmentQ.FileName), 1, 1)
        MyOutlook.SaveAtttachment(MailMessages.EntryID, AttachmentsQ._Index, |
                                  savePath, AttachmentsQ.FileName)
    end
end
Free(MailAttachments)

Sending Mail

    There are two ways of sending mail provided by Office Inside:

    1. oi_SendEmail() This is a global function, not a method, it can be called from anywhere and creates and destroys the object each time it is called (not recommended for most scenarios).
    2. The oiOutlook.SendEmail() method, which is used by the above class, can be used to send mail using an oiOutlook object.

      While call oi_SendMail makes sending mail simple, becuase it creates and destroy the oiOutlook object, and does the initialisation each time that it is called, it should not be used to send multiple messages. Call oi_SendMail where you just need to send a single, occational message. For sending a number of mail messages, or a batch of mail etc. the SendMail() method is a better alternative.

--------

 Contacts, Tasks and Appointments

Contacts, Tasks and Appointments are all managed in a very similar manner. The following methods are used to manage the various entries:

As you can see above, for fetching entries there are two approachs:

  1. Fetch a specific entry by calling GetTask(), GetAppointment() or GetContact() and then access the retrieved data using the properties of the class:
    oiOutlook.TaskProperties
    oiOutlook.AppointmentProperties
    oiOutlook.ContactProperties

    The entries can then be updated or deleted by using the appropriate method: UpdateContact(), UpdateAppointment(), UpdateTask() to update the entry and DeleteContact(), DeleteAppointment(), DeleteTask() to delete the entry.
  2. Fetch all entries by calling GetTasksQ(), GetAppointmentsQ() or GetContactsQ() and use the provided queue types:
    oioTasksQType1
    oioCalendarQType1
    oioContactsQType1

    Note: All properties and queues are documented under the relevant methods, see the specific method documentation for more information.

Example Code for Option 1: Fetching (and updating) specific entries using the class properties.

code

! Get a specific task by EntryID
myOutlook.GetTask(TaskEntryID)
! Delete the task if it has passed it's due date
if Today() > myOutlook.TaskProperties.StartDate_Date and |
    Clock() > myOutlook.TaskProperties.StartDate_Time
    myOutlook.DeleteTask(TaskEntryID)
else
    ! The properties can also be modified and the Task entry updated
    myOutlook.TaskProperties.Subject = 'Soccer Ball Collection'
    myOutlook.TaskProperties.Body = 'Collect new soccer balls from supplier'
    ! oio:ImportanceHigh or oio:ImportanceNormal or oio:ImportanceLow
    myOutlook.TaskProperties.Importance = oio:ImportanceHigh
    myOutlook.TaskProperties.StartDate_Date = Date(12, 10, 2007)
    ! Set the time to 15h30, 3:30PM
    myOutlook.TaskProperties.StartDate_Time = (15*60 + 30)*6000
    myOutlook.TaskProperties.ReminderSet = true
    myOutlook.TaskProperties.ReminderTime_Date = Date(12, 10, 2007)
    ! Reminder an hour before the event at 2:30PM (14h30)    
    myOutlook.TaskProperties.ReminderTime_Time = (14*60 + 30)*6000
    myOutlook.TaskProperties.ReminderPlaySound = true
    myOutlook.TaskProperties.ReminderSoundFile = '.\Reminder.wav'
    myOutlook.TaskProperties.LastModificationTime_Date = Today()
    myOutlook.TaskProperties.LastModificationTime_Time = Clock()   
    myOutlook.UpdateTask(TaskEntryID)
end

Example Code for Option 2: Fetching all entries using the queue types.

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: All recurring events could be added 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

 

See the documentation for the following methods for more examples and information:

 

Examples

The examples demonstrate everything used in the QuickStart guide and much, much more. The main example is a great place to get aquinted with the functionality of Office Inside and the Outlook classes. We highly recommend it as a "first stop", a great deal of the code that you need already exists in the example application, and it demonstrates how the objects are most commonly used, as well as provides a good foundation for copying-and-pasting code into your own application to get started.

You can find the examples in your Clarion\3rdparty\Examples\Office\ folder. The main example is the Demo example, which demonstrates all the core functionality of Office Inside. In particular the Clarion 6 version demonstrates all the lastest and greatest features and additions, as well as some Clarion 6 specific functionality.

 Templates

Template : Add_MSOutlook_Object
  Summary  
  • 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.
     
What does it do?
This template is used to add MS Outlook functionality to a procedure in your app.
 
Prerequisites
You need to have added the Activate_Office_Inside global extension template before you can add this template to a procedure.
 
How do I implement it?
  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...

 

What are my options?





 

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.

 
     

 

 

 Classes

This section describes the various classes which make up "Office Inside".  Each class contains methods and properties, which are documented below.  Each method is documented by giving the method name, the parameters, an example of how to code the method, a list describing what the method does, and additional comments below.

The oiOutlook Class - Introduction

The oiOutlook class is a "wrapper" class, which is used by the templates and by other classes as the "communication" layer between Office Inside and MS Outlook.  Should you wish to write code which communicates "directly" with MS Outlook, this is the class you're looking for.

The oiOutlook Class - Methods Grouped by Usage

The table below lists methods grouped by usage rather than in alphabetical order. For example all methods for handling mail are grouped together, all methods for handling contacts are groups together and so on. This is a good place to start if you know what you need to do, but aren't sure what to use to do it.

For an alphabetical listing of the class methods, see the next section - The oiOutlook Class - Alphabetical Listing of Methods.

oiOutlook Class Methods - Grouped by Use
 

   Appointments

  GetAppointment Fetches a single, specific appointment.
  GetAppointmentsQ Fills a queue with all the Outlook Appointments.
  DeleteAppointment Removes an appointment from the Outlook Calendar
  InsertAppointment Adds an entry to the Outlook Appointments.
  UpdateAppointment Update an Outlook Appointment entry.

  Contacts
  GetContact Fetchs a single Contact entry.
  GetContactsQ Fills a queue with all the Outlook Contacts.
  DeleteContact Removes a Contact from the Address Book
  InsertContact Adds an entry to the Outlook Contacts.
  UpdateContact Update and Outlook Contact entry.

  Tasks
  GetTask Retrieves a specific Outlook Task entry.
  GetTasksQ Fills a queue with all Outlook Tasks entries.
  DeleteTask Deletes a task from Outlook
  InsertTask Adds an entry to the Outlook Tasks.
  UpdateTask Update an Outlook Task entry.

  Email
  GetMailFoldersQ Fills a queue with a list of all mail folders (or all folders).
  GetMailItemsQ Fills a queue with a list of all items in a specific folder.
  GetEmailBody Retrieves the actual body of a specific email (HTML and Text)
  GetMailAttachmentsQ Fills a queue for the attachments for a specific mail message
  SaveAttachment Save an attachment from an email in Outlook to a file.
  SaveAs Save the Mail Item to disk in a variety of format.s
  SendEmail Send an email using Outlook.

 Event Callbacks
  EventItemSend Event callback when an item (mail) is sent by Outlook.
  EventNewMail This event callback is called when a new mail is created.
  EventOptionsPagesAdd Event callback when the Options window in Outlook is opened.
  EventQuit Event allowing you to trap when Outlook closes.
  EventReminder Event for when Outlook triggers a Reminder.
  EventStartup Event that Outlook fires on startup.

 Object and Errors
  Init Initialises the object and sets the event handling on or off.
  Kill Kills the object, deallocates memory and closes Outlook.
  ErrorTrap Called when an error occurs, provides centralised error handling.
 
     

The oiOutlook Class - Alphabetical Listing of Methods

The table below list the same class methods as above, but in alphabetical order.

oiOutlook Class Methods
 
DeleteAppointment
Removes an appointment from the Outlook Calendar
DeleteContact
Removes a Contact from the Address Book
DeleteTask
Deletes a task from Outlook
DisplayContact
Displays the Outlook Contact window.
ErrorTrap
Called when an error occurs, to provide additional information for your program to trap and handle errors
EventItemSend
A callback method, allows you to trap when an item is sent by Outlook and execute code in your program in response to the event.
EventNewMail
This event callback is called when a new mail is created.
EventOptionsPagesAdd
Event callback for when the Options window in Outlook is opened.
EventQuit
Event allowing you to trap when Outlook closes.
EventReminder
Event for when Outlook triggers a Reminder.
EventStartup
Event that Outlook fires on startup.
GetAppointment
Fetches a single, specific appointment.
GetAppointmentsQ
Fills a queue with all the Outlook Appointments.
GetContact
Fetchs a single Contact entry.
GetContactsQ
Fills a queue with all the Outlook Contacts.
GetEmailBody
Retrieves the actual body of a specific email (used to get the body of a message after calling GetMailItemsQ to get mesasge etc.)
GetMailAttachmentsQ
Fills a queue for the attachments for a specific mail message
GetMailFoldersQ
Fills a queue with a list of all mail folders. Can also be used to retrieve a list of all Outlook folders, as well as just the mail folders.
GetMailItemsQ
Fills a queue with a list of all items in a specific folder.
GetTask
Retrieves a specific Outlook Task entry.
GetTasksQ
Fills a queue with all Outlook Tasks entries.
Init
Called to initialise the oiOutlook function and start Outlook. Sets the default state of Outlook (whether it is shown and the window position) as well as whether event callbacks are on etc.
InsertAppointment
Adds an entry to the Outlook Appointments.
InsertContact
Adds an entry to the Outlook Contacts.
InsertTask
Adds an entry to the Outlook Tasks.
Kill
Kills the oiOutlook object, cleans up allocated memory and closes Outlook.
SaveAttachment
Save an attachment from an email in Outlook to a file.
SaveAs Save the Mail Item to disk in a variety of format.s
SendEmail
Send an email using Outlook.
UpdateAppointment
Update an Outlook Appointment entry.
UpdateContact
Update and Outlook Contact entry.
UpdateTask
Update an Outlook Task entry.
 
     

oiOutlook Class - Method Documentation

This section describes each method listed above, how it is used, the parameters, return values, date types and related properties of the class that the object uses. In addition each method has an example of using the method, along with a list of related methods in the "See Also" section. Where the method uses specific data types they are listed along with the method, and each field described where applicable.

--------

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 occured)
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 sucess, 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 sucess 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 occured.

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:

oiOutlook.AppointmentProperties fields
 
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 recurrance, 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, 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.

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

*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 recurrance, 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