OutlookEX UDF - General: Difference between revisions

From AutoIt Wiki
Jump to navigation Jump to search
(14 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Category:UDF]]
[[Category:UDF]]
The OutlookEX UDF offers functions to control and manipulate Microsoft Outlook. This page describes the OutlookEX UDF in general.
The OutlookEX UDF offers basic functions to control and manipulate Microsoft Outlook. This page describes the OutlookEX UDF in general.
== Concept ==
 
The OutlokEX UDF is based upon this concept:
On top of the OutlookEX UDF I have built the [[OutlookTools|OutlookTools UDF]] with some often needed functionality.
== Concepts ==
=== UDF ===
The OutlookEX 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 in Outlook is uniquely identified by EntryID and StoreID. The default StoreID is your inbox
Line 12: Line 15:
* 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 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:
The code has been split into the following files:
* One to control and manipulate the items in an Exchange Store or PST archive
* '''OutlookEX_Base.au3''': Functions used by both of the following UDF files. OutlookEX_Base.au3 comes with the OutlookEX.zip and the OutlookEX_GUI.zip
* One to control and manipulate the Outlook GUI
* '''OutlookEX.au3''': Functions to control and manipulate the items in a Store (Exchange, PST, Cloud ...)
* '''OutlookEX_GUI''': Functions to control and manipulate the Outlook GUI
 
=== Outlook ===
==== Events, Appointments and Meeting Requests ====
* An '''event''' is an activity that lasts 24 hours or longer.
* An '''appointment''' is an activity that does not involve reserving resources or inviting other people.
* A '''meeting''' is an appointment for which you reserve a period of time, invite people to, or reserve resources.
A more detailed description can be found [http://www.knowledgewave.com/blog/msoffice/outlook/whats-the-dif-events-appointments-and-meeting-requests-in-microsoft-outlook-2013.html here].


== Folders ==
== Folders ==
Line 27: Line 38:
|-
|-
| style="border: 1px solid darkgray" | "rootfolder\subfolder\...\subfolder"
| 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" | 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" | "\\rootfolder"
| style="border: 1px solid darkgray" | "\\rootfolder"
| style="border: 1px solid darkgray" | default folder of another user (class specified by $iOL_FolderType) (replace "rootfolder" with "*" to access your mailbox)
| style="border: 1px solid darkgray" | default folder of '''another user''' (class specified by $iOL_FolderType) (replace "rootfolder" with "*" to access your mailbox)
|-
|-
| style="border: 1px solid darkgray" | "\\rootfolder\\subfolder\...\subfolder"
| style="border: 1px solid darkgray" | "\\rootfolder\\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" | subfolder of the default folder of '''another user''' (class specified by $iOL_FolderType)
|-
|-
| style="border: 1px solid darkgray" | "\\rootfolder\subfolder\..\subfolder"
| style="border: 1px solid darkgray" | "\\rootfolder\subfolder\..\subfolder"
| style="border: 1px solid darkgray" | subfolder of another user
| style="border: 1px solid darkgray" | subfolder of '''another user'''
|-
|-
| style="border: 1px solid darkgray" | ""
| 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" | default folder of the '''current user''' (class specified by $iOL_FolderType)
|-
|-
| style="border: 1px solid darkgray" | "\subfolder"
| 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)
| style="border: 1px solid darkgray" | subfolder of the default folder of the '''current user''' (class specified by $iOL_FolderType)
|}
|}
'''Note:''' You need to use different formats to access '''public folders''' and the mailbox of '''other users'''!


"rootfolder" is one of the following:
"rootfolder" is one of the following:
Line 52: Line 65:


=== Search folders ===
=== Search folders ===
The UDF does not support Search Folders. You need to access a search folder as described below before you can process it the same way as any other folder:
As of January 2018 the UDF supports Search Folders as well. Please have a look at functions _OL_SearchFolder*.
<syntaxhighlight lang="autoit">
#include <OutlookEX.au3>
Global $oOL = _OL_Open()
Global $oNamespace = $oOL.GetNamespace("MAPI")
Global $oDefaultStore = $oNamespace.DefaultStore
Global $oSearchFolders = $oDefaultStore.GetSearchFolders
Global $oSearchFolder = $oSearchFolders("Mail to Read")


;-------------------------------------
== Supported Version ==
; Get all mails from the search folder
The OutlookEX UDF has been tested with Outlook 2002 on Windows XP SP3, Outlook 2010 and Outlook 2016 on Windows 7 SP1.
;-------------------------------------
Global $aItems = _OL_ItemFind($oOL, $oSearchFolder, $olMail, "", "", "", "Subject,Body")
_ArrayDisplay($aItems, "Unread mails")
</syntaxhighlight>


== Supported Version ==
The OutlookEX UDF has been tested with Outlook 2002 on Windows XP SP3 and Outlook 2010 on Windows 7 SP1.
== Naming pattern ==
== 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 named like the item type e.g. _OL_CalendarXXX
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 named like the item type e.g. _OL_CalendarXXX
Line 96: Line 96:
Most functions accept up to 10 properties as parameters or an unlimited number of properties as a zero based one-dimensional array.
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:
The following two examples are equivalent:
<syntaxhighlight lang="autoit">
<syntaxhighlight lang="autoit">
$oItem = _OL_ItemCreate($oOutlook, $olMailItem, "*\Outlook-UDF-Test\TargetFolder\Mail", "", "Subject=TestMail", "Importance=" & $olImportanceHigh, "BodyFormat=" & $olFormatHTML, _
$oItem = _OL_ItemCreate($oOutlook, $olMailItem, "*\Outlook-UDF-Test\TargetFolder\Mail", "", "Subject=TestMail", "Importance=" & $olImportanceHigh, "BodyFormat=" & $olFormatHTML, _
Line 136: Line 136:
=== Meeting Item ===
=== Meeting Item ===
Further information about wrapper functions plus tips & tricks for meeting items: [[OutlookEX UDF - Meeting Item]]
Further information about wrapper functions plus tips & tricks for meeting items: [[OutlookEX UDF - Meeting Item]]
== Known issues ==
Some features of Microsoft's Office products are proprietary and cannot readily be manipulated.<br>
Sometimes workarounds are required. [[Known issues with Microsoft Office automation.|This page]] is dedicated to identifying those issues, provide explanations and list solutions or workarounds.
=== Attachment in GMail ===
"When I attach a PDF with the Outlook UDF the attachment gets renamed to 'noname' with no extension".<br />
When you search the web for "gmail attachment noname" you get a lot of hits. Seems it is a problem with GMail.
=== HTML body shown as WINMAIL.DAT ===
"I have successfully inserted an HTML body and a PDF attachment. However, Thunderbird and SquirrelMail clients do not show the HTML and only show a WINMAIL.DAT attachment."<br />
This has been discussed [https://www.autoitscript.com/forum/topic/158418-outlookex-udf-help-support-iii/?page=35#comment-1345813 here].<br>
Another good explanation including Transport Neutral Encapsulation Format (TNEF) can be found [https://support.microsoft.com/en-us/help/290809/how-e-mail-message-formats-affect-internet-e-mail-messages-in-outlook here].
=== Mail in RTF format ===
I think RTF is not supported by Outlook and was introduced by "accident". Described in this - quite old - [http://www.vbforums.com/showthread.php?229250-RESOLVED-Write-RTF-to-outlook-mailitem&p=1352438&viewfull=1#post1352438 thread].


== Debugging ==
== Debugging ==
Line 146: Line 162:
   Number = -2147221021
   Number = -2147221021
   WinDesciption = Operation Unavailable
   WinDesciption = Operation Unavailable
=== Office trial version ===
=== Office trial version ===
The trial version of Office comes without COM components. You get @error = 1 from _OL_Open.
The trial version of Office comes without COM components. You get @error = 1 from _OL_Open.


Installing the full Office product over a trial doesn't seem to help. You need to uninstall the trial and then re-install the full product.
Installing the full Office product over a trial doesn't seem to help. You need to uninstall the trial and then re-install the full product.
=== COM error 0x80040004 - action cancelled ===
Group Policy settings might deny all "unsafe" actions. Please see this [https://www.autoitscript.com/forum/topic/190964-outlookex-udf-help-support-iv/?do=findComment&comment=1437641 post].
=== All kind of strange return codes ===
=== All kind of strange return codes ===
You get COM errors like  
You get COM errors like  

Revision as of 08:08, 17 June 2020

The OutlookEX UDF offers basic functions to control and manipulate Microsoft Outlook. This page describes the OutlookEX UDF in general.

On top of the OutlookEX UDF I have built the OutlookTools UDF with some often needed functionality.

Concepts

UDF

The OutlookEX 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 code has been split into the following files:

  • OutlookEX_Base.au3: Functions used by both of the following UDF files. OutlookEX_Base.au3 comes with the OutlookEX.zip and the OutlookEX_GUI.zip
  • OutlookEX.au3: Functions to control and manipulate the items in a Store (Exchange, PST, Cloud ...)
  • OutlookEX_GUI: Functions to control and manipulate the Outlook GUI

Outlook

Events, Appointments and Meeting Requests

  • An event is an activity that lasts 24 hours or longer.
  • An appointment is an activity that does not involve reserving resources or inviting other people.
  • A meeting is an appointment for which you reserve a period of time, invite people to, or reserve resources.

A more detailed description can be found here.

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:

Syntax Folder you access
"rootfolder\subfolder\...\subfolder" any public folder or any folder of the current user (replace rootfolder with * to access the root folder of your mailbox)
"\\rootfolder" default folder of another user (class specified by $iOL_FolderType) (replace "rootfolder" with "*" to access your mailbox)
"\\rootfolder\\subfolder\...\subfolder" subfolder of the default folder of another user (class specified by $iOL_FolderType)
"\\rootfolder\subfolder\..\subfolder" subfolder of another user
"" default folder of the current user (class specified by $iOL_FolderType)
"\subfolder" subfolder of the default folder of the current user (class specified by $iOL_FolderType)

Note: You need to use different formats to access public folders and the mailbox of other users!

"rootfolder" is one of the following:

  • Mailbox name, e.g. "John.Doe@company.com"
  • Display name, e.g. "John Doe"

For details please see the item specific section below.

Search folders

As of January 2018 the UDF supports Search Folders as well. Please have a look at functions _OL_SearchFolder*.

Supported Version

The OutlookEX UDF has been tested with Outlook 2002 on Windows XP SP3, Outlook 2010 and Outlook 2016 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 named like the item type e.g. _OL_CalendarXXX

Outlook security

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

However, the Outlook Security Warning message does not appear if a valid Anti-Virus is installed.


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

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.

The following two examples are equivalent:

$oItem = _OL_ItemCreate($oOutlook, $olMailItem, "*\Outlook-UDF-Test\TargetFolder\Mail", "", "Subject=TestMail", "Importance=" & $olImportanceHigh, "BodyFormat=" & $olFormatHTML, _
         "HTMLBody=Bodytext in &lt;b>bold&lt;/b><img src='cid:The_Outlook.jpg'>Embedded image.")

or

Global $aProperties[100] = ["Subject=TestMail", "Importance=" & $olImportanceHigh, "BodyFormat=" & $olFormatHTML, "HTMLBody=Bodytext in &lt;b>bold&lt;/b><img src='cid:The_Outlook.jpg'>Embedded image."]
$oItem = _OL_ItemCreate($oOutlook, $olMailItem, "*\Outlook-UDF-Test\TargetFolder\Mail", "", $aProperties)

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 many 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

Folder Item

Further information about how to access and manipulate folders: OutlookEX UDF - Folder 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

Known issues

Some features of Microsoft's Office products are proprietary and cannot readily be manipulated.
Sometimes workarounds are required. This page is dedicated to identifying those issues, provide explanations and list solutions or workarounds.

Attachment in GMail

"When I attach a PDF with the Outlook UDF the attachment gets renamed to 'noname' with no extension".
When you search the web for "gmail attachment noname" you get a lot of hits. Seems it is a problem with GMail.

HTML body shown as WINMAIL.DAT

"I have successfully inserted an HTML body and a PDF attachment. However, Thunderbird and SquirrelMail clients do not show the HTML and only show a WINMAIL.DAT attachment."
This has been discussed here.
Another good explanation including Transport Neutral Encapsulation Format (TNEF) can be found here.

Mail in RTF format

I think RTF is not supported by Outlook and was introduced by "accident". Described in this - quite old - thread.

Debugging

Running script as Administrator

It seems that the process that starts or hooks into Outlook needs to be run with the same permissions as Outlook.

You get the following error when setting _OL_ErrorNotify(2):

 NumberHex = 800401E3
 Number = -2147221021
 WinDesciption = Operation Unavailable

Office trial version

The trial version of Office comes without COM components. You get @error = 1 from _OL_Open.

Installing the full Office product over a trial doesn't seem to help. You need to uninstall the trial and then re-install the full product.

COM error 0x80040004 - action cancelled

Group Policy settings might deny all "unsafe" actions. Please see this post.

All kind of strange return codes

You get COM errors like

  • 0x800706BA - The RPC server is unavailable
  • 0x800706BE - The remote procedure call failed
  • or strange return values from all kind of _OL_* functions.

Outlook (starting with Outlook 2007 SP2) shuts itself down if there is no open window (which is always true when Outlook was not running when _OL_Open is being called) and there is no open reference to an Outlook item (mail, appointment ...).

This is described in the following MSDN article: "Application Shutdown Changes in Outlook 2007 SP2"

So a bug in the UDF or your code can cause Outlook to shut down prematurely.