 |
Microsoft Outlook Functionality |
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:
- Send mail and have it end in the Users Outbox
- Get the mail folders and messages from Outlook, create new folders and messages
- Create new contacts, and import existing contacts
- Synchronize Tasks between your application and Outlook
- Add, edit and delete Calendar entries.
- And much more!
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:
- Mail
- Address Book (Contacts)
- Calendar (Appointments, events etc.)
- Tasks
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:
- Add the global extension
- Add an Office Inside object using the local extension
- 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
- Create a queue using the Folder type provided (oioFolderNamesQType)
- Call
.GetMailFoldersQ() to get the folder list
- Call .GetMailItemsQ()
to get the folder contents
Fetching a Message
- Call .GetEmailBody() for the HTML and Text parts of each
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
MyOutlook.GetMailFoldersQ(MailFolders)
messageText &= new string(32000)
messageHtml &= new string(64000)
loop curFolder = 1 to
Records(MailFolders)
Get(MailFolders, curFolder)
MyOutlook.GetMailItemsQ(MailMessages, MailFolders.EntryID)
loop
curMail = 1 to Records(MailMessages)
Get(MailMessages, curMail)
retVal = MyOutlook.GetEmailBody(MailMessages.EntryID, messageText,
false)
if
retVal = -1
elsif
retVal > 0
Dispose(messageText)
messageText&= new string(retVal)
retVal = GetEmailBody(MailMessages.EntryID, messageText,
false)
if retVal <> 0
end
end
retVal = MyOutlook.GetEmailBody(MailMessages.EntryID, messageHtml,
true)
myOutlook.GetMailAttachmetsQ(AttachmentsQ, MailMessages.EntryID)
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\'
MyOutlook.SaveAtttachment(MailMessages.EntryID, 0, savePath, AttachmentsQ.FileName)
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:
- 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.
- 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:
- Fetching an entry: GetTask, GetAppointment, GetContact
- Fetching all entries: GetTasksQ, GetAppointmentsQ , GetContactsQ
- Updating an entry: UpdateContact, UpdateAppointmen, UpdateTask
- Deleting an entry: DeleteContact, DeleteAppointment, DeleteTask
- Inserting an
entry: InsertTask, InsertAppointment, InsertContact
As you can see above, for
fetching entries there are two approachs:
- 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.
- 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
myOutlook.GetTask(TaskEntryID)
! Get a specific task by EntryID
! 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:
- Fetching an entry: GetTask, GetAppointment, GetContact
- Fetching all entries: GetTasksQ, GetAppointmentsQ , GetContactsQ
- Updating an entry: UpdateContact, UpdateAppointmen, UpdateTask
- Deleting an entry: DeleteContact, DeleteAppointment, DeleteTask
- Inserting an entry: InsertTask, InsertAppointment, InsertContact
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.
| |
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? |
- Select the procedure which you want to add this template to.
- Select "Properties..." from the "Edit" menu
- Click the "Extensions" button
- Click on the "Insert" button to add a new extension template
- Select "Add_MSOutlook_Object" ( found under the "Class
OfficeInside" group )
- 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.
|
|
|
| |
|
|
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 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 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.
The table below list the same class methods as above, but in alphabetical order.
| |
| 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. |
|
|
| |
|
|
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:
- First, this ErrorTrap method is called, where
you can act on the error message as shown in the example code above.
- 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()
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)
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!')
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()
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.
| |
| 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:
| |
| 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.
| |
| 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.
| |
| 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 |
| |
Examples
Templates
Classes
The
oiOutlook Class - Introduction
Contacts