• 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.

 Generic Access to Outlook Items

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.

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.

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 Outlook ID (which you pass as pEntryID). When you call this method the ContactProperties property is updated, as demonstrated below (this property is a group and contains numerous fields). See the Object Properties section below for a description of each field that the ContactProperties group contains.

Parameters

string pEntryID: The unique identifier used by Outlook for this entry. For existing Contact entries you can retrieve this value by calling GetContactsQ, which will retrieve all Contacts, along with their EntryIDs. For new entries the EntryID is returned as a string by the InsertContact() method.

Return Value

Returns 1 for success and zero for failure.

Examples

EditContact_EntryID       string(255) 
EditContact_FirstName     string(100) 
EditContact_LastName      string(100) 
EditContact_CompanyName   string(100) 
EditContact_Email1Address string(50) 
  code 
    ! Fetch an existing Contact that has been selected 
    ! (and the EntryID populated into EditContact_EntryID) 
    if EditContact_EntryID = '' 
        Message('Please select a Contact first...', 'Office Inside')
    else 
        if not MyOutlook1.GetContact(EditContact_EntryID)
            Message('Error fetching contact', 'Office Inside', Icon:Exclamation)
        else EditContact_FirstName = MyOutlook1.ContactProperties.FirstName 
            EditContact_LastName = MyOutlook1.ContactProperties.LastName 
            EditContact_CompanyName = MyOutlook1.ContactProperties.CompanyName 
            EditContact_Email1Address = MyOutlook1.ContactProperties.Categories 
        end 
    end

Object Properties

The oiOutlook.ContactProperties group stores the details for each contact. You can use these fields to get the details for the contact, as well as updating the fields and then calling UpdateContact to update the contact itself. Fields that are read-only have been clearly labelled as such in the description section.

See Also

GetContactsQ, InsertContact, DeleteContact, UpdateContact, GetAppointment, GetTask

GetContactsQ (*oioContactsQType1 pQueue, <string pEntryID>)

This method is used to read addresses from Outlook, by filling a Clarion queue (as in the example code below). 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 GetContact method instead. See the Outlook_AddressBook procedure in the offdemo.app example application for more info.

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. The oioContactQType1 queue structure and field description is listed below in the Data Types section

Parameters

*oioContactsQType1 pQueue: A queue of the type oioContactsQType1 which stores the fields for each contact. The queue should be declared using the oioContactsQType1, rather than simply declaring a queue that has the same fields, as the oioContactsQType1 may change between version as new fields are added etc.

<string pEntryID>: A optional parameter that limits the method to only fetching the contact with the EntryID that matches the the pEntryID parameter. For fetching a single contact it is recommended that you call the GetContact method instead, which does not require a queue, and simply populates the oiOutlook.ContactProperties group with the contact data.

Return Value

Returns 1 for success and zero for failure.

Examples

ContactsQ          queue(oioContactsQType1)
                   end
startTime          long
  code
    ! Fetch all contacts
    Setcursor(cursor:wait)
    startTime = Clock()

    Window{prop:text} = 'Please wait, reading addresses...'
    MyOutlook1.GetContactsQ(ContactsQ)
    Sort(ContactsQ, +ContactsQ.FirstName, +ContactsQ.LastName)
    Window{prop:text} = 'Outlook Address Book'

    Message('Read ' & Records(ContactsQ) & ' addresses in ' |
           & ((Clock() - startTime)/100) & ' seconds.', 'Office Inside')
    SetCursor()

    ! If the queue is used to populate a list. select the first
    ! entry now that it has been filled
    Select(?List1, 1)
    Post(Event:Newselection, ?List1)

Data Types

See Also

GetContact, InsertContact, DeleteContact, GetAppointmentsQ, GetTasksQ

GetEmailBody (string pEntryID, byte pHtml=false)

This method is limited to 20,000 characters and is deprecated. Please use the new GetEmailBody method listed above. This method is included for backward compatibility only.

Returns the body (in text, or html) for the email identified by pEntryID.  Use the GetMailItemsQ method to get a list of emails and their EntryID's and the GetFolderQ method to get a list of all email folders.

See the Outlook_ReadEmailFolders procedure in the offdemo.app example application for more info.

Parameters

string pEntryID: A string containing the unique identifier used by Outlook for this entry (mail message). Each item in Outlook has a unique identifier that is returned when retrieving items from Outlook. This property is always created by Outlook as is read only.

byte pHtml: If set to true (1) then the HTML content of the email is fetched, if set to false (0) then the Text only version is retrieved.

Return Value

The method returns a string that contains the contents of the email, either as text, or as HTML, depending on the value of the pHtml parameter.

Examples

mailText          string(08000h)      ! 512K
mailHtml          string(010000h)     ! 1MB
  code
    mailText = MyOutlook.GetEmailBody (EntryID)       ! plain text
    mailHtml = MyOutlook.GetEmailBody (EntryID, true) ! html

    ! You can use Capesoft FileExplorer to display the HTML
    ! version of the email in your Clarion application

See Also

GetMailItemsQ, GetFolderQ, GetMailAttachmentsQ, SaveAttachment

GetMailAttachmentsQ (*oioAttachmentsQ pQueue, string pEntryID)

This method is used to read the list of email attachments from an email, by filling a Clarion queue (as in the example code below).

• See the Outlook_ReadEmailFolders procedure in the offdemo.app example application for more info.

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.

Parameters

*oioAttachmentsQ pQueue: A queue that contains the list of all attachments for a particular mail message. The oioAttachmentsQ queue type is provided for declaring this queue, and the fields are listed below under Data Type.

string pEntryID: The Outlook unique identifier for this item. Every item in Outlook has a unique identifier that is created by Outlook. This unique identifier is return by the Insert methods such as InsertTask, InsertAppointment and InsertContact, as well as when calling the methods to fill a queue with items of a particular type, such as GetMailItemsQ, which retrieve a list of all mail messages in a particular folder.

Return Value

Returns 1 for success and zero for failure.

Examples

! This example loops through a queue that would contain mail items
! which would be retrieved using the GetMailItemsQ method, and for
! each mail items shows two ways of saving attachments. Firstly how
! to save a single specific attachment, and secondly how to just save
! all attachments for an email.
AttachmentsQ    queue(oioAttachmentsQ)
                end
MailQ           queue(oioFolderItemsQType)
                end
i               long
a               long
  code
    loop i = 1 to Records(MailQ)
        Get(MailQ, i)

        ! Option 1: Save all attachments
        MyOutlook.SaveAttachment(MailQ.EntryID, 0, '.\Attachments', '')

        MyOutlook.GetMailAttachmentsQ(AttachmentsQ, MailQ.EntryID)

        ! Option 2: Save specific attachments (for example all .zip files)
        loop a = 1  to Records(AttachmentsQ)
            Get(AttachmentsQ, a)
            if Instring('.zip', Lower(AttachmentsQ.FileName), 1, 1)
                MyOutlook.SaveAttachment(MailQ.EntryID, AttachmentsQ._Index, |
                                         '.\Attachments', AttachmentsQ.FileName)
        end
        Free(AttachmentsQ)
    end

Data Types

oioAttachmentsQ Type
	Field Name Type Description _Index string The index of this entry, used for passing to the SaveAttachment function ParentFolderName string The name of the Folder that is the parent of this folder EntryID string The unique identifier assigned by Outlook to this item

 

See Also

GetMailFolderQ, GetMailItemsQ, SaveAttachments

GetMailFoldersQ (*oioFolderNamesQType pQueue, long allFolders = 0)

This method is used to read the names / structures of the email folders from Outlook, by filling a Clarion queue (as in the example code below).

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.

Parameters

oioFolderNamesQType pQueue: Stores the folder information, you should declare the queue using the provided Type to ensure changes to the types to not cause compiled errors in future versions (see below for an example of declaring a queue based on the provided type).

long AllFolders: Allows you to list all Outlook folders, include the root folder and non mail folders such as Contacts, Tasks, Journal etc. By default this is set to zero to only retrieve Mail folders, setting this to 1 will retrieve all folders in the Folders tree, including those that store appointments, contacts etc. You can then manually choose which entries you need from the queue and delete those that are not needed.

Return Values

Returns 1 if successful, zero if an error occurred.

Example

foldersQ       queue(oioFolderNamesQType)
               end
  code

    myOutlook.GetMailFoldersQ(foldersQ)
    Message('Found ' & Records(foldersQ) & ' mail folders')

See Also

GetMailItemsQ, GetTasksQ, GetAppointmentsQ, GetContactsQ, SaveAttachment
See the Outlook_ReadEmailFolders procedure in the offdemo.app example application for more info.

GetMailItemsQ (*oioFolderItemsQType pQueue, <string pFolderID>)

This method is used to read emails from Outlook, by filling a Clarion queue (as in the example code above). The queue type is described below in the Data Type section, along with the fields of the queue. Typically you would call GetMailFolderQ to retrieve a list of folders, and then call GetMailItemsQ to retrieve a list of all mail in a specific folder.

If the pFolderID parameter is omitted then the contents of the Inbox are fetched, otherwise if you pass the EntryID of the desired folder, the list of mail in that folder is retrieved.

Note: See the Outlook_ReadEmailFolders procedure in the offdemo.app example application for more info.

Parameters

*oioFolderItemsQType pQueue: A queue of the type oioFolderItemsQType (see the Data Types section below for the queue fields and description). This queue will be filled with the details of all mail message in the passed folder. Use the pFolderID parameter to specify which folder to enumerate.

<string pFolderID>: An optional parameter that specific which folder the mail list should be retrieved for. If this parameter is not passed then the queue is filled with the list of mail in the Inbox. If you pass an EntryID identifying a specific folder, then all mail in that folder is enumerated and the details placed in the passed queue. The EntryID for the folder is typically retrieved using the GetMailFoldersQ method to retrieve a list of all mail folders.

Return Value

Returns 1 for success and zero for failure.

Examples

FolderItemsQ       queue(FolderItemsQType)
                   end
  code
    MyOutlook.GetMailItemsQ(FolderItemsQ)                       ! Read the Inbox
    ! Do something with the contents of the queue here ...

    Free(FolderItemsQ)
    MyOutlook.GetMailItemsQ(FolderItemsQ, FolderQ.EntryID)      ! Read a specific folder
    ! Do something with the contents of the queue here ...

Data Types

See Also

GetMailFoldersQ, GetMailAttachmentsQ, GetEmailBody, SaveAttachment

GetTask (string pEntryID)

The GetTask method retrieves a Task entry using the EntryID that Outlook uses to uniquely identify each entry.

Parameters

string pEntryID: The unique Entry ID that Outlook uses to identify this entry. This is a string and is return by Outlook when using the "Get" methods to fetch entries (GetTask, GetAppointment and GetContact) as well as when using the Get Queue methods to fill a queue with all entries (GetTasksQ, GetAppointmentsQ and GetContactsQ). The EntryID is also return by each of the Insert methods (InsertContact, InsertTask and InsertAppointment). EntryIDs are created by Outlook and should be treated as read only.

Return Values

The method returns 1 for success and zero for failure.

Information

The GetTasksQ method can also be used to read all tasks from Outlook into a Clarion queue, rather than retrieving a single task. When you call this method the TaskProperties property is updated, as demonstrated above (this property is a group and contains the fields that store the Task values).

The information for the Task is stored in the oiOutlook.TaskProperties property of the Outlook class:

Example

! Fetch a Task, update some of its properties, and update the task:
MyOutlook.GetTask(TaskEntryID)
MyOutlook.TaskProperties.Subject = 'Important Bug Fix'
MyOutlook.TaskProperties.Priority = oio:ImportanceHigh
MyOutlook.UpdateTask(TaskEntryID)

See Also:

InsertTask, UpdateTask, DeleteTask, GetTasksQ

For further examples of usage see the Outlook_Tasks procedure in the offdemo.app or offdemo6.app example application.

GetTasksQ     ( *oioTasksQType1 pQueue, <string pEntryID> )

This method is used to read Tasks from Outlook, filling a Clarion queue with all the Outlook Tasks. Office Inside provides a queue type to store the tasks, and allows you to synchronise tasks between Outlook and your application. You can also retrieve a single specific task by calling GetTask.

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 GetTask method instead to read single entries.

Parameters

*oioTasksQType1 pQueue: A queue to be filled with the Outlook Tasks. The queue must be of the oioTasksQType1 type, or have exactly the same fields. We strongly recommend that you use the provided types rather than declaring the entire queue structure, as they may change between versions.

string pEntryID: Optionally allows a specific Task to be retrieved by passing the EntryID of the Task to be fetched. To retrieve a single Task a better approach is to use the GetTask method.

Return Values

Returns 1 for success and zero for failure (failure generally indicates an error when calling the COM interface).

Example

This example gets all the Tasks from Outlook and fills a queue. It then loops through the queue and adds all tasks that are marked as High importance to a queue called ImportantTasks. It then deletes entries that that are not High importance and have passed their Due date and time. These entries are placed in a DoneTasks queue before being deleted.

MyTasks        queue(oioTasksQType1) 
               end 
ImportantTasks queue(oioTasksQType1) 
               end 
DoneTasks      queue(oioTasksQType1) 
               end 
  code 
    !--- Fill a queue with all Tasks 
    MyOutlook.GetTasksQ(MyTasks) 
    loop i = 1 to Records(MyTasks) 
        Get(MyTasks, i)     ! The queue fields contain the information for this Tasks
        !--- Example: Add Important tasks to a new queue 
        if MyTasks.Importance = oio:ImportanceHigh 
            ImporantTasks = MyTasks 
            Add(importantTasks) 
        else                ! Example: Delete all tasks that are past the due date 
            if Today() > MyTasks.DueDate_Date and Clock() > MyTasks.DueDate_Time ! Delete the Task from Outlook             
                MyOutlook.DeleteAppointment(MyTasks.EntryID) 
                DoneTasks = MyTasks 
                Add(DoneTasks)    ! Add to the Done queue 
                Delete(MyTasks)   ! Delete from the Tasks queue 
            end 
       end
    end 

See Also

InsertTask, UpdateTask, GetTask, GetAppointmentsQ, GetContactsQ, GetMailItemsQ, GetMailFoldersQ

See the Outlook_Tasks procedure in the offdemo.app example application for more info.

Init (byte pStartVisible=0, byte pEnableEvents=0) ,byte,proc

This method initializes the oiOutlook object, and must be called before you call any other methods in this class. The pStartVisible parameter currently has no effect whatsoever, and should be passed as 0 (zero / false). The pVisible parameter can be used for other Office Inside classes, however for Outlook it is not used.

Note: Compatibility with other (non Office Inside) COM Objects:
If you are using other COM objects on the same thread then the COM interface must only get initialised once and destroyed once. The Office Inside template provides a "File Explorer Compatibility" option that allows File Explorer (or another COM object) to do this initialisation and destruction. This is done by setting the oiOffice.noComInit property to 1, so that Office Inside does not handle the COM interface. See Kill for more information.

Parameters

byte pStartVisible: Not used by Outlook. For other Office Inside object this parameter determines whether the application is visible or hidden when started by the COM object.

byte pEnableEvents: Set this to one to enable the event callbacks such as EventItemSend, EventNewMail, EventReminder, EventQuit etc.

Return Value

Returns 1 for success and zero for failure.

Examples

MyOutlook.Init(false, true)  ! Start Outlook with events turned on

MyOutlook.Init(false, false) ! Start Outlook with events turned off

See Also

Kill, EventItemSend, EventNewMail, EventReminder, EventQuit

InsertAppointment ( ) , string, proc

Inserts a new appointment into Outlook. Prime whatever values you want to use in the new appointment before calling this method, by setting the AppointmentProperties property (See below for an example as well as the fields in the AppointmentProperties group).

Note: See the Recurring Appointments section under GetAppointment for a full description of the Recurring fields, and which values need to be set for each type of recurring appointment.

Parameters

None

Return Value

Every item in Outlook has a unique ID (called an EntryID in Office Inside), this ID is returned as a string when you call this method.

Examples

subject             string(100)
startDate           long
startTime           long
endDate             long
endTime             long
body                string(1024)
importance          byte
allDayEvent         byte
busyStatus          byte
reminderOn          byte
reminderMins        long
entryID             long
  code
    ! The variables declared above typically would be displayed on
    ! a window for user input, below are simply example values:
    Subject      = 'PTA Meeting'
    StartDate    = Date(12, 10, 2007)
    StartTime    = (16*60 + 30)*6000   ! 16:03
    EndDate      = Date(12, 10, 2007)
    EndTime      = (19*60 + 30)*6000   ! 19:03
    Body         = 'PTA Meeting and Timmy''s school.'
    Importance   = oio:ImportanceHigh
    AllDayEvent  = false
    BusyStatus   = oio:OutOfOffice
    ReminderOn   = true              ! Turn on the Reminder
    ReminderMins = 120               ! Reminder 2 hours before the event (120 minutes)

    if subject and startDate and startTime and endDate and endTime
        MyOutlook1.AppointmentProperties.Subject    = subject
        MyOutlook1.AppointmentProperties.Start_Date = startDate
        MyOutlook1.AppointmentProperties.Start_Time = startTime
        MyOutlook1.AppointmentProperties.End_Date   = endDate
        MyOutlook1.AppointmentProperties.End_Time   = endTime
        MyOutlook1.AppointmentProperties.Body       = body
        MyOutlook1.AppointmentProperties.Importance = importance
        MyOutlook1.AppointmentProperties.AllDayEvent = allDayEvent
        MyOutlook1.AppointmentProperties.BusyStatus = busyStatus
        MyOutlook1.AppointmentProperties.ReminderSet = reminderOn
        MyOutlook1.AppointmentProperties.ReminderMinutesBeforeStart = reminderMins

        entryID = MyOutlook1.InsertAppointment()
    else
        Message('Please complete all required fields first.', 'Error')
    end

Objects Properties

See Also

GetAppointment, GetAppointmentsQ, DeleteAppointment, UpdateAppointment, InsertContact, InsertTask

InsertContact () , string, proc

Inserts a new Contact into the Outlook Address Book. Prime whatever values you want to use in the new contact before calling this method, by setting the ContactProperties property fields, as show in the example below. The ContactProperties group fields and a description of each field and its values is show below in the Object Properties section.

Note: Every item in Outlook has a unique ID, called an EntryID. This ID is returned when you call this method (as a string)

Parameters

None

Return Value

A string containing the EntryID for this contact. Every item in Outlook has a unique ID, called an EntryID in Office Inside. This is the ID that is returned when you call this method.

Examples

contactID       string(_oit:EntryIDSize)
  code
      MyOutlook1.ContactProperties.FirstName = 'Patrick'
      MyOutlook1.ContactProperties.LastName = 'O''Grady'
      MyOutlook1.ContactProperties.CompanyName = 'Three Leaves'
      MyOutlook1.ContactProperties.Email1Address = 'paddy@threeleaves.com'
      MyOutlook1.ContactProperties.BusinessAddress = |
                        '12 Throthworpe Lane, Blingshire, Farthington, 7922'
      
      ! Set any other properties here as desired
      ContactID = MyOutlook1.InsertContact()

Object Properties

The oiOutlook.ContactProperties group stores the details for a contact. You can use these fields to prime the values for inserting a new contact, get the details for the contact when calling GetContact, as well as updating the fields and then calling UpdateContact to update the contact. Fields that are read-only have been clearly labelled as such in the description section, these fields cannot be set when inserting a new contact, the values will be populated by Outlook.

oiOutlook.ContactProperties fields
	Field Name Type Description FirstName string The first name of the contact. LastName string The last name of the contact. CompanyName string The company name for the contact. Gender string Gender, one of: oio:Unspecified oio:Female oio:Male _Title string The title of this contact. Suffix string Suffix of this contact - a string that is added after the contact's name. For example: "Bruce Johnson Esq.", the Suffix would be "Esq.". JobTitle string Title of this contact's job. Profession string Profession of the contact. Department string Department that this contact is in. AssistantName string Name of the contact's assistant. ManagerName string Name of the contact's manager. Language string Language of the contact Spouse string Name of the contact's spouse Anniversary long Standard Clarion date for the contact's anniversary Birthday long Standard Clarion date for the contact's date of birth Children string String containing the names of any children Hobby string String for a hobby Initials string Contact's Initials MiddleName string Middle name of the contact NickName string Nickname for the contact FullName string Returns or sets a string specifying the whole, unparsed full name for the contact. Read/write. CompanyAndFullName string A string representing the concatenated company name and full name for the contact. Read-only. CompanyLastFirstNoSpace string A string representing the company name for the contact followed by the concatenated last name, first name, and middle name with no space between the last and first names. This property is parsed from the CompanyName , LastName , FirstName and MiddleName properties. Read-only. CompanyLastFirstSpaceOnly string A string representing the company name for the contact followed by the concatenated last name, first name, and middle name with spaces between the last, first, and middle names. This property is parsed from the CompanyName , LastName , FirstName and MiddleName properties. Read-only. PrimaryTelephoneNumber string Main telephone number. CompanyMainTelephoneNumber string Main company telephone number. BusinessTelephoneNumber string Business telephone number of the contact. Business2TelephoneNumber string Second business telephone number. MobileTelephoneNumber string Mobile number of the contact. HomeTelephoneNumber string Home telephone number. Home2TelephoneNumber string Home telephone number of the contact. CarTelephoneNumber string Car telephone number. CallbackTelephoneNumber string The callback number of the contact RadioTelephoneNumber string The radio telephone number. OtherTelephoneNumber string Any other telephone number for the contact. AssistantTelephoneNumber string Telephone number of the contact's assistance BusinessFaxNumber string Business fax number. HomeFaxNumber string Home fax number. PagerNumber string Page number. TelexNumber string Telex number. WebPage string We site address. BusinessHomePage string Home page of the contact's company web site. PersonalHomePage string Home page of the contact's personal web site. FTPSite string Address of the contact's FTP server. IMAddress string Instant Messaging address. Used for IM clients such as Skype, Google chat, MSN Messenger etc. SelectedMailingAddress byte Which one of the addresses is the selected one. One of the following values: oio:None oio:Home oio:Business oio:Other BusinessAddress string Returns or sets a string representing the whole, unparsed business address for the contact. BusinessAddressCity string Business address city. BusinessAddressCountry string Business address country. BusinessAddressPostalCode string Business address postal code. BusinessAddressPostOfficeBox string The post office box number portion of the business address for the contact. BusinessAddressState string Business address state. BusinessAddressStreet string Businessa address street. HomeAddress string Returns or sets a string representing the whole, unparsed home address for the contact. HomeAddressCity string Home address city. HomeAddressCountry string Home address country. HomeAddressPostalCode string Home address postal code. HomeAddressPostOfficeBox string Home address PO Box. HomeAddressState string Home address state. HomeAddressStreet string Home address street. MailingAddress string Returns or sets a string representing the whole, unparsed home address for the contact. MailingAddressCity string Mailing address city. MailingAddressCountry string Mailing address country. MailingAddressPostalCode string Mailing address postal code. MailingAddressPostOfficeBox string Mailing address PO Box. MailingAddressState string Mailing address state. MailingAddressStreet string Mailing address street. OtherAddress string Returns or sets a string representing the whole, unparsed address for the contact. OtherAddressCity string Address city. OtherAddressCountry string Address country. OtherAddressPostalCode string Address postal code. OtherAddressPostOfficeBox string Address PO Box. OtherAddressState string Address state. Email1Address string Email address for the contact. Email1AddressType string Returns or sets a String representing the address type (such as EX or SMTP) of the first e-mail entry for the contact. This is a free-form text field, but it must match the actual type of an existing e-mail transport. Email1DisplayName string Returns a String representing the display name of the first e-mail address for the contact. This property is set to the value of the FullName property by default. Read-only. Email2Address string A secondary email address for the contact. Email2AddressType string The type of address (see Email1AddressType above) Email2DisplayName string The display name of the second email address (see Email1DisplayName above) Email3Address string A tertiary email address for the contact. Email3AddressType string The type of address (see Email1AddressType above) Email3DisplayName string The display name of the third email address (see Email1DisplayName above) Categories string Returns or sets a String representing the categories assigned to the Microsoft Outlook item. CreationTime_Date long Returns a Date indicating the creation time for the Outlook item. Read-only. CreationTime_Time long Returns a Time indicating the creation time for the Outlook item. Read-only. LastModificationTime_Date long Returns a Date specifying the date that the Microsoft Outlook item was last modified. Read-only. LastModificationTime_Time long Returns a Time specifying the time that the Microsoft Outlook item was last modified. Read-only. EntryID string The unique Entry ID for this contact. Each object in Outlook has a unique EntryID that identifies it.

See Also

GetContact, GetContactsQ, DeleteContact, InsertAppointment, InsertTask

InsertTask ( ) ,string,proc

Inserts a new task into Outlook. Prime whatever values you want to use in the new task before calling this method, by setting the TaskProperties property See below for the TaskProperties fields).

oiOutlook.TaskProperties

To add a new task you should first populate the oiOutlook.TaskProperties group with the fields that you would like to add for the task.

Parameters

None

Return Value

Every item in Outlook has a unique ID (see the offdemo.app demo), this ID is returned when you call this method (as a string)

Examples

curTaskID     string(_oit:EntryIDSize) 
  code 
    myOutlook.TaskProperties.Subject = 'Soccer Ball Collection' 
    myOutlook.TaskProperties.Body = 'Collect new soccer balls from supplier'

    ! Importance: oio:ImportanceHigh or oio:ImportanceNormal or oio:ImportanceLow 
    myOutlook.TaskProperties.Importance = oio:ImportanceHigh 

    ! Set the time to 15h30, 3:30PM:
    myOutlook.TaskProperties.StartDate_Date = Date(12, 10, 2007) 
    myOutlook.TaskProperties.StartDate_Time = (15*60 + 30)*6000 
    myOutlook.TaskProperties.ReminderSet = true

    ! Set a Reminder an hour before the event at 2:30PM (14h30):
    myOutlook.TaskProperties.ReminderTime_Date = Date(12, 10, 2007)
    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()

    curTaskID = myOutlook.InsertTask()

See Also

UpdateTask, GetTask, GetTasksQ, InsertAppointment, InsertContact

Kill (byte pUnloadCOM=1) , byte, proc

Closes the Outlook object and cleans up.

Parameters

byte pUnloadCOM: parameter must always be passed as 1 (true), or simply omitted (in which case it will be passed as 1 anyway), as in the example code above.

Note on compatibility with other COM objects: The only exception is if you are using this object on the same window or thread as non Office Inside COM object (such as FileExplorer) that handles the COM initialisation and destruction. The template provides this options for FE compatability for you, so this is only applicable if you are calling Kill() yourself. If you do use this option for compatibility with FE (or any other COM object) then you must call Init after the other object has initialised the COM interface, and kill before the other object disposes of it. Also note that you will need to set the .noComInit property of the class to true before calling the Init method.

Return Values

Returns true (1) if no problems were experienced. Returns zero for failure.

Examples

MyOutlook.Kill()

See Also

Init

SaveAs (string entryID, string fileName, long fileType = oio:olMSGUnicode), long

Saves the Microsoft Outlook item to the specified path and in the format of the specified file type. If the file type is not specified, the MSG format (.msg) is used.

Parameters

string entryID: The Entry ID that identifies the Mail Item that you want to save (see the GetMailItemsQ method for more info).

string fileName: The file name and path to save the Mail item to.

long  fileType:The type of file to save the Mail Item as. The following values are supported:

Return Values

Returns 1 for success and zero for failure. In the event of a failure the ErrorTrap() method is called with the error information.

Examples

fileName     string(File:MaxFileName) !! The file name to save a mail as 
fileType     long                     ! The type to save the mail item as
  code
    if FileDialog('Save Mail Item As...', fileName, |
                  'Outlook message|*.msg|HTML|*.html|MIME HTML|.mht|Rich Text|' |
                  & '*.rtf|Plain Text|.txt|', |
                  File:Save + File:Keepdir + File:LongName + File:AddExtension)

    if Instring('.msg', fileName, 1, 1)
        if Message('Save this message as Unicode? Choose No to save it ' |
                   & 'as a standard message and Yes to save it as a Unicode message', |
                   'Save as Unicode?', Icon:Question, Button:Yes + BButton:No)
            fileType = oio:olMSGUnicode
        else
            fileType = oio:olMSG
        end
    elsif Instring('.html', fileName, 1, 1)
        fileType = oio:olHTML
    elsif Instring('.mht', fileName, 1, 1)
        fileType = oio:olMHTML
    elsif Instring('.rtf', fileName, 1, 1)
        fileType = oio:olRTF
    elsif Instring('.txt', fileName, 1, 1)
        fileType = oio:olTXT
    else
        fileType = oio:olMSG
    end

    if Exists(fileName)
        if Message('The file already exists, would you like to replace ' |
                   & Clip(fileName) & ' with this Mail Item?', |
                   'Replace Existing File?', Icon:Question, Button:Yes + Button:No)
            Remove(fileName)
        else
            ! cycle if in an event loop, exit for a routine, 
            ! return for a procedure etc.
            cycle   
        end
    end
    if not MyOutlook1.SaveAs(FolderItemsQ.EntryID, fileName, fileType)
        Message('Outlook could not save the selected Mail Item.')
    end
end

See Also

GetMailAttachmentsQ, GetMailFolderQ, GetMailItemsQ

SaveAttachment (string pEntryID, long pAttachmentID, string pPath, string pFileName) ,string

Use this method to save an attachment from an email message stored in Outlook. See the Outlook_ReadEmailFolders procedure in the offdemo.app example application for more info.

Parameters

string pEntryID: parameter identifies which email you want to work with (see the GetMailItemsQ method for more info).

long pAttachmentID: parameter identifies which attachment you want to save (as one email can have multiple attachments).  See the GetMailAttachmentsQ method for more info.  If you pass 0 for this parameter then all the attachments in the email identified by pEntryID will be saved.

string pPath: parameter specifies the path where you want to save the attachment(s).  If you do not pass a value it will default to the exe path.

string pFileName: parameter lets you specify the filename you want to save the attachment as.  If you do not pass a value in this parameter ('') then the attachment will be saved using it's original filename.

Return Values

If the method saves the attachment successfully, it will return the name of the newly saved file. If the method fails it returns a blank string.

Examples

! Example 1: Save first attachment to exe folder,
! using its original filename
MyOutlook.SaveAttachment(EmailID, 1, '', '')


! Example 2: Save first attachment to an 'Attachments' folder,
! inside the current folder, using its original filename
MyOutlook.SaveAttachment(EmailID, 1, '.\Attachments', '')


! Example 3: 
! This example loops through a queue that would contain mail items
! which would be retrieved using the GetMailItemsQ method, and for
! each mail items shows two ways of saving attachments. Firstly how
! to save a single specific attachment, and secondly how to just save
! all attachments for an email. Attachments are saved into an
! 'Attachments' folder in the current path.
AttachmentsQ    queue(oioAttachmentsQ)
                end
MailQ           queue(oioFolderItemsQType)
                end
i               long
a               long
  code
    loop i = 1  to Records(MailQ)
        Get(MailQ, i)

        ! Option 1: Save all attachments
        MyOutlook.SaveAttachment(MailQ.EntryID, 0, '.\Attachments', '')

        MyOutlook.GetMailAttachmentsQ(AttachmentsQ, MailQ.EntryID)

        ! Option 2: Save specific attachments (for example all .zip files)
        loop a = 1  to Records(AttachmentsQ)
            Get(AttachmentsQ, a)
            if Instring('.zip', Lower(AttachmentsQ.FileName), 1, 1)
                MyOutlook.SaveAttachment(MailQ.EntryID, AttachmentsQ._Index, |
                                         '.\Attachments', AttachmentsQ.FileName)
        end
        Free(AttachmentsQ)
    end

See Also

GetMailAttachmentsQ, GetMailFolderQ, GetMailItemsQ

SendEmail (string pToAddress, string pCCAddress, string pBCCAddress, string pSubject, string pAttachments, string pBody, byte pPlainText, byte pOpen=false) ,byte,proc

Sends an email from your app, using Outlook.  The email is add to the Outlook "Outbox" folder.

Parameters

string pToAddress: The address to send the email to. Can l take multiple email addresses, just separate each addresses with a semi-colon between each address. For example: 'bob@isp.com; "Phil Widget" <phil@domain.us>; "Spider Man" <spidey@web.net>'.

string pCCAddress: The list of email addresses to CC (Carbon). Can l take multiple email addresses, just separate each addresses with a semi-colon. A copy of the mail will be sent to each addres in the CC field.

string pBCCAddress: The list of address to BCC (Blind Carbon Copy). Can l take multiple email addresses, just separate each addresses with a semi-colon. When a mail is send with addresses in the BBC field the server receiving the mail creates a copy of the mail for each person in the BCC field. When the person receives the mail their address is in the TO field, and none of the BCC addresses are listed in the mail. This allows a message to be sent to multiple recipients, and each recipient receives an email addressed to them, and the mail does not contain any other addresses that it was sent to.

string pSubject: The subject of the email.

string pAttachments: A list of attachments to include in the email. Each attachment is simply the path and name of the file that should be attached. For multiple attachments separate each file name with with a semi colon. Example: 'c:\temp\instructions.doc; data.xls; c:\Documents and Settings\Bob\My Documents\RetirementPlan.ppt'

string pBody: The body of the message, if the pPlainText parameter is set to true (1) then this contains plain text, otherwise it contain HTML.

byte pPlainText: If this is set to true (1) then the mail is plain text only. If it it set to false (0) then the body contains HTML. You can use Capesoft File Explorer to provide a WSIWYG HTML editor in your Clarion application for allowing users to create an edit HTML emails.

byte pOpen: If this is set to true (1) then once the mail has been created then it is displayed by Outlook, and the user can modify it before pressing the Send button to send it. By default this is set to false (0) and the message is added to the Outbox without ever being displayed.

Return Values

Returns true (1) if no problems were experienced, and zero for failure.

Example

MyOutlook.SendEmail('me@myisp.com', '', '', 'Test', '', '
              Test Email', false)
MyOutlook.SendEmail('me@myisp.com', '
bob@isp.com; "Phil Widget" <phil@domain.us>', |
                    '', 'Test', '
                    c:\test.txt; c:\myfile.doc', '
                    This is a test',
                    false)
                    

See Also

oi_SendEmail, GetMailFoldersQ, GetMailItemsQ, GetEmailBody, GetAttachmentsQ, SaveAttachment

The UpdateAppointment method updates an appointment (calendar) entry in Outlook. There are two approaches provided for performing an update:

• The first approach uses the oiOutlook.AppointmentProperties group, which stores all the appointment fields. You populate the fields with the desired data (for example you could call GetAppointment or GetAppointmentsQ to first retrieve the appointment information) and call UpdateAppointments to write all the fields back to Outlook. In this case the method is called simply by passing the EntryID of the Appointment to update:
  
  MyOutlook.UpdateAppointment(string pEntryID)
  
• The second approach allows you to update individual fields by passing an equate for which field should be updated, and a value to update the field to. In this case the method is called as follows:
  
  MyOutlook.UpdateAppointment(string pEntryID, long pProperty, string pValue)

Note: See the Recurring Appointments section under GetAppointment for a full decription of the Recurring fields, and which values need to be set for each type of recurring appointment.

Parameters

string pEntryID: The unique ID of the entry that is to be updated. This value is returned by InsertAppointment and also retrieved by GetAppointment and GetAppointmentsQ.

long pProperty: This parameter is only used when updating a specific property of the Appointment rather than using the AppointmentProperties group. This contains an equate identifying which field is to be updated. If this field is passed then the pValue parameter must contain the value to set the selected Appointment property to. For a list of equates see the equates section below.

string pValue: The value to set the field to. This is only used in the second form of the method call, where an equate for which field is to be modified is passed, along with the value to set the field to

Return Values

Returns true (1) for success and false (0) for failure.

Examples

Example 1: Updating an appointment using the oiOutlook.AppointmentProperties group.
  code
    MyOutlook1.AppointmentProperties.Subject    = 'PTA Meeting'
    MyOutlook1.AppointmentProperties.Start_Date =  Date(12, 10, 2007)
    MyOutlook1.AppointmentProperties.Start_Time = (16*60 + 30)*6000   ! 16:03
    MyOutlook1.AppointmentProperties.End_Date   = Date(12, 10, 2007)
    MyOutlook1.AppointmentProperties.End_Time   = (19*60 + 30)*6000   ! 19:03
    MyOutlook1.AppointmentProperties.Body       = 'PTA Meeting and Timmy''s school.'
    MyOutlook1.AppointmentProperties.Importance = oio:ImportanceHigh
    MyOutlook1.AppointmentProperties.AllDayEvent = false
    MyOutlook1.AppointmentProperties.BusyStatus = oio:OutOfOffice
    ! Turn on the Reminder:
    MyOutlook1.AppointmentProperties.ReminderSet = true
    ! Reminder 2 hours before the event (120 minutes):
    MyOutlook1.AppointmentProperties.ReminderMinutesBeforeStart = 120
    MyOutlook1.UpdateAppointment(EntryID)


Example 2: Use the second approach to clear the Recurrence type, and then
           set it to a new value, along with the various fields needed
           for setting the recurrence properties
  code
    ! Remove any existing occurrence
  
    MyOutlook.UpdateAppointment(MyEntryID, oio:AppointmentIsRecurring, false)
    ! Set the new occurrence for every 2nd week on Mon and Wed, ending 31 July 2008
    MyOutlook.UpdateAppointment(MyEntryID, oio:AppointmentIsRecurring, true)
    MyOutlook.UpdateAppointment(MyEntryID, oio:AppointmentRecurrence_Type, oio:RecursWeekly)
    MyOutlook.UpdateAppointment(MyEntryID, oio:AppointmentRecurrence_DayOfWeekMask, |
                      oio:Monday + oio:Wednesday)                      ! Mon and Wed
    MyOutlook.UpdateAppointment(MyEntryID, oio:AppointmentRecurrence_Interval, 2) ! Every 2nd week
    MyOutlook.UpdateAppointment(MyEntryID, oio:AppointmentRecurrence_PatternStartDate, Today())
    MyOutlook.UpdateAppointment(MyEntryID, oio:AppointmentRecurrence_PatternEndDate, Date(7,31,2008)
  

Equates

These equates are used when calling the second form of the method, where individual properties are updated. The equates are passed using the pProperty parameter and are used to define which property is being updated. For a description of each field, the values that it takes, and its usage see the AppointmentProperties group below under Object Properties.

"Update Appointment" Equates

oio:AppointmentSubject
oio:AppointmentStart_Date
oio:AppointmentStart_Time
oio:AppointmentEnd_Date
oio:AppointmentEnd_Time
oio:AppointmentBody
oio:AppointmentImportance
oio:AppointmentAllDayEvent
oio:AppointmentBusyStatus
oio:AppointmentReminderSet
oio:AppointmentReminderMinutesBeforeStart
oio:AppointmentLocation
oio:AppointmentIsRecurring
oio:AppointmentRecurrence_Type
oio:AppointmentRecurrence_DayOfMonth
oio:AppointmentRecurrence_DayOfWeekMask
oio:AppointmentRecurrence_Duration
oio:AppointmentRecurrence_Instance
oio:AppointmentRecurrence_Interval
oio:AppointmentRecurrence_MonthOfYear
oio:AppointmentRecurrence_NoEndDate
oio:AppointmentRecurrence_Occurrences
oio:AppointmentRecurrence_PatternEndDate
oio:AppointmentRecurrence_PatternStartDate

Object Properties

The ouOutlook.Appointment properties group contains a field for each Appointment property that can be read from Outlook, most of these properties can also be updated. The table below describes each property, the values that it takes, and which ones are read-only (those that are set by Outlook and cannot be modified).

See Also

InsertAppointment, GetAppointment, GetAppointmentsQ, UpdateTask, UpdateContact

UpdateContact (string pEntryID, long pProperty, string pValue)

Updates the contact entry in Outlook (identified by the pEntryID parameter).

There are two ways you can use this method:

1. Set the fields in the Outlook.ContactProperties property (group), and then call this method (passing ONLY the pEntryID parameter). The method will then update multiple properties based on the values held in the Outlook.ContactProperties property (group). The method is called passing only the first parameter:
   UpdateContact(pEntryID)
   
2. Update a single property by passing the property id (see UpdateContact Equates) in the pProperty parameter, and pass the new value for that property in the pValue parameter. The method is called passing all three parameters:
   UpdateContact(pEntryID, pProperty, pValue)

Parameters

string pEntryID: A string containing the EntryID that identifies which contact to update. Every item in Outlok has a unique EntryID. This value is returned when inserting a new item (for example when calling InsertContact) and can also be retrieved by calling GetContactsQ to fill a queue with all Outlook contact entries.

long pProperty: Optional parameter only passed when using the second approach to update a specific field. This value is an equate that identifies which field should be updated. See the Equates section below for a list of equates that this value can be set to.

string pValue: Optional parameter only passed when using the second approach to update a specific field. This string contains the value to set the specific field to.

Return Value

Returns true (1) or sucess and zero (0) for failure.

Examples

Example 1: Using the ContactProperties group to update a contact
MyOutlook.ContactProperties.FirstName = 'Spider'
MyOutlook.ContactProperties.LastName = 'Man'
! Set other properties here using the fields in the ContactProperties group
MyOutlook.UpdateContact(MyEntryID)


Example 2: Using the second approach to update individual fields
MyOutlook.UpdateContact(MyEntryID,  oio:ContactFirstName, 'Spider')
MyOutlook.UpdateContact(MyEntryID,  oio:ContactLastName, 'Man')

Object Properties

The oiOutlook.ContactProperties group stores the details for each contact. You can use these fields to get the details for the contact, as well as updating the fields and then calling UpdateContact to update the contact itself. Fields that are read-only have been clearly labelled as such in the description section.

These equates are used to update specific fields using the second form of the method, where the pProperty and pValue parameters are passed to update a specific field, rather than populating the ContactProperties group and then updating the entire contact. Each equate relates to the properties of the same name as listed in the ContactProperties table below.

See Also

InsertContact, GetContact, GetContactsQ, DeleteContact, UpdateAppointment, UpdateTask

UpdateTask (string pEntryID, long pProperty, string pValue)

Updates the task entry in Outlook (identified by the pEntryID parameter).

• There are two ways you can use this method:
  1. First update the Outlook.TaskProperties property (group), and then call this method (passing ONLY the pEntryID parameter).  The method will then update multiple properties based on the values held in the Outlook.TaskProperties property (group).
     The syntax of the call is:
     Outlook.UpdateTask(TaskEntryID)
     
  2. Update a single property by passing the property id (see UpdateTask Equates) in the pProperty parameter, and pass the new value for that property in the pValue parameter.
     The syntax for calling the method using this approach is:
     Outlook.UpdateTask(TaskEntryID, pProperty, pValue)

Parameters

string pEntryID: The EntryID that identifies the Task to update. Every entry in Outlook has a unique EntryID that is assigned by Outlook. This EntryID is returned as a string when the Insert methods are called (InsertTask, InsertAppointment and InsertContact) and also retrieved when using GetTask, GetTaskQ etc.

long pProperty: Optional parameter, only used with the second approach described above. This parameter should be set to the equate identifying which field should be updated. The equates are listed below in the equates section. Each equate corrosponds to the property of the same name as described in the TaskProperties table below.

string pValue: Optional parameter, only used with the second approach described above. This string should be set to the value to update the Contact property to. The pProperty parameter determines which property of the Task must be updated, the pValue parameter determines the value that it is set to.

Return Values

Returns true (1) for success and false (zero) for failure.

Examples

Example 1: Updating the contact using the oiOutlook.ContactProperties group
MyOutlook.TaskProperties.Subject = 'Hello world'
! set other properties here...
MyOutlook.UpdateTask(MyEntryID)

! Example 2: Updating the contact using the second approach, by updating a
! specific field, specified by passing the pProperty parameter to specify the
! field and pValue to specify the new value
MyOutlook.UpdateTask(MyEntryID, oio:TaskSubject, 'Hello world')

Object Properties

Equates

The following equates are provided to allow specific fields to be updated using the second approach described above - passing pPropery and pValue. The equates match the fields described in the oiOutlook.TaskProperties table above.

oio:TaskSubject
oio:TaskBody
oio:TaskImportance
oio:TaskStartDate_Date
oio:TaskStartDate_Time
oio:TaskDueDate_Date
oio:TaskDueDate_Time
oio:TaskReminderSet
oio:TaskReminderTime_Date
oio:TaskReminderTime_Time
oio:TaskReminderPlaySound
oio:TaskReminderSoundFile

See Also

GetTask, GetTasksQ, InsertTask, DeleteTask, UpdateContact, UpdateAppointment

Office 2003 and Earlier

The only real way of doing this is using one of the utilities to either automatically click on the "yes" button to allow access to Outlook, or to use a plug-in that provides enhanced security controls. We recommend the later method using the free Advanced Security For Outlook plugin.

• Advanced Security for Outlook is a free plug-in for Outlook that provides proper security alerts and allows you to set which applications can access Outlook, so you only need to authorise an application once. Note that this is not a CapeSoft product and we do not provide support for it. Please visit the MapiLab website for more information: http://www.mapilab.com/outlook/security/.

Office 2007 and 2010

• "Warn me about suspicious activity when my antivirus software is inactive or out of date (recommended)".
  This is the recommended setting, and should not require any user interaction to send emails.
  
• "Always warn me about suspicious activity".
  This setting operates in the same manner as the security model in Outlook 2003, except that it introduces an even more onerous warning dialog box on mail sending. First the user is prompted to allow access to 1, 5 or 10 minutes, then when an email is sent a warning dialogue is displayed. The second dialog does not allow the user to continue immediately, but instead displays a progress bar for a few seconds before the button can be pressed. This means that utilities such as "ClickYes" can no longer be used.
  
• "Never warn me about suspicious activity".
  This setting allows all applications access, much like in Office 2000 and XP.