OutlookEX UDF - General

2012-12-19T15:33:57Z

Tjalve: /* Wrapper functions */

{{WIP}}

The OutlookEX UDF offers functions to control and manipulate Microsoft Outlook. This page describes the OutlookEX UDF in general.
== Concept ==
The OutlokEX UDF is based upon this concept:

* Every item in Outlook is uniquely identified by EntryID and StoreID. The default StoreID is your inbox
* Every item has properties to describe the item (subject, startdate ..) and methods to act upon the item (move, delete …)
* It does not matter where an item is stored. You can access any folder and get/create/modify items there
* The search and action functions are now separated. As an example the user first searches for the items to be deleted and then calls the delete function
* The UDF was designed to be as modular as possible. E.g. there is a single function to create an item, be it a mail item, contact item or whatever
* The number of properties you can pass to most functions is not limited by the number of parameters defined for the function. Properties can be passed as parameters (up to 10) or in an unlimited array as parameter 1
* The UDF allows to access all kind of folders (see the following listing). Folders can be passed to a function by name or as an object

The UDF contains two sets of functions:
* One to control and manipulate the items in an Exchange Store or PST archive
* One to control and manipulate the Outlook GUI

== Folders ==
It does not matter where an item is stored. You can access any folder and get/create/modify items there.

Folders you can access:

{| style="border: 1px solid darkgray" cellspacing=0 cellpadding=5px
|-
! style="border: 1px solid darkgray" | Syntax
! style="border: 1px solid darkgray" | Folder you access
|-
| style="border: 1px solid darkgray" | "rootfolder\subfolder\...\subfolder"
| style="border: 1px solid darkgray" | any public folder or any folder of the current user (replace rootfolder with * to access the root folder of your mailbox)
|-
| style="border: 1px solid darkgray" | "\\firstname name"
| style="border: 1px solid darkgray" | default folder of another user (class specified by $iOL_FolderType) (replace "firstname name" with "*" to access your mailbox)
|-
| style="border: 1px solid darkgray" | "\\firstname name\\subfolder\...\subfolder"
| style="border: 1px solid darkgray" | subfolder of the default folder of another user (class specified by $iOL_FolderType)
|-
| style="border: 1px solid darkgray" | "\\firstname name\subfolder\..\subfolder"
| style="border: 1px solid darkgray" | subfolder of another user
|-
| style="border: 1px solid darkgray" | ""
| style="border: 1px solid darkgray" | default folder of the current user (class specified by $iOL_FolderType)
|-
| style="border: 1px solid darkgray" | "\subfolder"
| style="border: 1px solid darkgray" | subfolder of the default folder of the current user (class specified by $iOL_FolderType)
|}

== Supported Version ==
The OutlookEX UDF has been tested with Outlook 2002 on Windows XP SP3 and Outlook 2010 on Windows 7 SP1.
== Naming pattern ==
If a method can be used for more than one item type (e.g. mail, calendar and notes) the function is called _OL_ItemXXX else the function is called _OL_CalendarXXX

== Outlook security ==
[[File:outlook_security_warning_1.gif|frame|alt=Outlook Security Warning|Outlook Security Warning]]
Some Outlook objects (address book, mail items ...) including their properties and methods are protected by security settings.
Accessing such objects makes the Outlook Object Model Guard present a popup warning like "a program is trying to access your Address book or Contacts" or "a program is trying to access e-mail addresses you have stored in Outlook...".

A small function (''_OL_Warnings.au3''), which has to be compiled and run separately, clicks away all Outlook Security Warnings. Setting parameter ''$fOL_WarningClick'' to ''True'' when you call function ''_OL_Open()'' runs the ''_OL_Warnings.exe''.
The ''_OL_Warnings.exe'' stays active and clicks away all warnings until the calling script is ended.

It's written for an english language environment but can easily be adopted to other languages.
== Wrapper functions ==
To make transition from the original Outlook UDF to the new OutlookEX UDF a bit smoother, ''wrapper'' functions that mimic functions of the original UDF have been implemented in the new UDF.
Number and position of the parameters have been left untouched as far as possible. E.G. ''_OutlookSendMail'' of the original UDF has become ''_OL_Wrapper_SendMail''.

The ''wrapper'' function names are prefixed with ''_OL_Wrapper_''.

However, the message does not apper if a valid Anti-Virus is installed.

== Call a function ==
Some functions need to accept a lot of parameters when a user needs to set many properties of an item. Let's say you want to create a mail item and pass subject, bodyformat, body and importance to the _OL_ItemCreate function.
Most functions accept up to 10 properties as parameters or an unlimited number of properties as a zero based one-dimensional array.

This two examples are equivalent:
<syntaxhighlight lang="autoit">
$oItem = _OL_ItemCreate($oOutlook, $olMailItem, "*\Outlook-UDF-Test\TargetFolder\Mail", "", "Subject=TestMail", "Importance=" & $olImportanceHigh, "BodyFormat=" & $olFormatHTML, _
"HTMLBody=Bodytext in bold<img src='cid:The_Outlook.jpg'>Embedded image.")
</syntaxhighlight>
or
<syntaxhighlight lang="autoit">
Global $aProperties[100] = ["Subject=TestMail", "Importance=" & $olImportanceHigh, "BodyFormat=" & $olFormatHTML, "HTMLBody=Bodytext in bold<img src='cid:The_Outlook.jpg'>Embedded image."]
$oItem = _OL_ItemCreate($oOutlook, $olMailItem, "*\Outlook-UDF-Test\TargetFolder\Mail", "", $aProperties)
</syntaxhighlight>
Empty properties in the passed array are ignored.

== Example Scripts ==
=== For single functions ===
Every function of the UDF comes with an example script (except internal functions). The example script is named like the function.
==== Test Environment ====
Every example script calls function _OL_TestEnvironment.au3. This function creates a test environment to make sure each function delivers a predictable result independant of the system it is running on and to make sure the Outlook environment of the user is left untouched. 
The test environment is created as folder "Outlook-UDF-Test" plus subfolders and multiple items in your mailbox. This folders and items are manipulated by the example scripts. 
_OL_TestEnvironment.au3 can directly be called by the user. It then displays a GUI where the user can save some settings for the example scripts or create and delete the test environment manually. The test environment is created by every example script but is not deleted after the script has ended. To remove the test environment run _OL_TestEnvironment.au3 and delete the test environment manually.

=== Extended Examples ===
Example scripts which describe more than a single function of the UDF are prefixed with ''_OL_Example_''.

== Function specific pages ==
The following pages contain information for the functions that can be used for may different item types.
=== Find an Item ===
Further information on how to find items: [[OutlookEX UDF - Find Items]]
=== Forward an Item ===
Further information on how to forward items: [[OutlookEX UDF - Forward Items]]

== Item specific pages ==
The following pages contain information for each of the Outlook item types supported by the OutlookEX UDF.
=== Appointment Item ===
Further information about wrapper functions plus tips & tricks for appointment items: [[OutlookEX UDF - Appointment Item]]
=== Mail Item ===
Further information about wrapper functions plus tips & tricks for mail items: [[OutlookEX UDF - Mail Item]]
=== Meeting Item ===
Further information about wrapper functions plus tips & tricks for meeting items: [[OutlookEX UDF - Meeting Item]]

AutoIt Wiki - User contributions [en]

OutlookEX UDF - General