OutlookTools
The OutlookTools UDF offers some often needed extended functionality to control and manipulate Microsoft Outlook. It is built on top of the OutlookEX UDF.
General
Limitations/Requirements
- The functions do not support encoded text (e.g. =D6 for O Umlaut)
- The functions do not support multiline text (e.g. lines ending with =0D=0A)
- The functions do not support nested objects (e.g. nest a meeting.ics and person.vcf)
- Only supports local or UTC date/time. Time zones are not supported
Callback function
Most of the functions provide a callback function. It gets called before an Outlook item is created.
You decide how the item is being handled by setting @extended. You HAVE to return one of the following values:
| Flag | Action |
|---|---|
| $iOLT_FlagProcessRecord (1) | Process the current record, then continue with the next record |
| $iOLT_FlagCancelRecord (2) | Do not process the current record, then continue with the next record |
| $iOLT_FlagCancelAll (4) | Do not process the current record, cancel processing all remaining records and exit the _OLT_* function |
| $iOLT_FlagReturnData (8) | The data passed to the callback function has been modified. Pass the data back to the calling _OLT_* function |
The function is called with a parameter describing the data being used to create the Outlook item. The full description of this data can be found in the corresponding function you find below.
This parameter is read only by default. If you want to modify this data and return it to the calling function you need to:
- set @extended to $iOLT_FlagReturnData
- set the return value to the modified variable or array
Example: Return the modified array to the calling function:
Func CallBack($aData)
$aData[0] = "A"
Return SetError(0, $iOLT_FlagReturnData, $aData)
EndFunc
Example: Do not return data to the calling function. Just process the record:
Func CallBack($aData)
Return SetError(0, $iOLT_FlagProcessRecord)
EndFunc
Debugging
You can pass debugging flags to the OutlookTools functions. Possible values (can be a combination of one or more of the following values):
| Flag | Action |
|---|---|
| $iOLT_DebugOff (0) | No debugging (default) |
| $iOLT_DebugConsole (1) | Writes debugging messages to the console |
| $iOLT_DebugFile (2) | Writes debugging messages to a file specified by parameter $sDebugFile |
| $iOLT_DebugProperties (4) | Writes the properties used to create the Outlook item to the debugging destination |
| $iOLT_DebugCreateOff (8) | Do not create the Outlook item. Allows to test the function without modifying Outlook |
Functions
_OLT_iCal_VEvent_Import
Import iCal events from an ICS file to an Outlook calendar.
The function processes the following properties (in whole or in part) according to RFC 5545 (properties not listed will be ignored):
| COMPONENT:PROPERTY | SECTION IN RFC 5545 | OUTLOOK PROPERTY | COMMENT |
|---|---|---|---|
| VEVENT:CATEGORIES | Section 3.8.1.2 | Categories | |
| VEVENT:CLASS | Section 3.8.1.3 | Sensitivity | olNormal, olPrivate or olConfidentional. olPersonal does not get set |
| VEVENT:DESCRIPTION | Section 3.8.1.5 | Body | |
| VEVENT:LOCATION | Section 3.8.1.7 | Location | |
| VEVENT:PRIORITY | Section 3.8.1.9 | Importance | |
| VEVENT:SUMMARY | Section 3.8.1.12 | Subject | |
| VEVENT:DTEND | Section 3.8.2.2 | End | specifies the non-inclusive end of the event |
| VEVENT:DTSTART | Section 3.8.2.4 | Start | Example |
| VEVENT:DURATION | Section 3.8.2.5 | End | used to calculate the end property |
| VEVENT:TRANSP | Section 3.8.2.7 | BusyStatus | |
| VALARM:TRIGGER | Section 3.8.6.3 | ReminderMinutesBeforeStart | Only the minutes section of the duration is processed |
Limitations/Requirements
Input for the function has been taken from the following standards:
This means that the function does not fully follow this standards. It just scans throught he input file and extracts as much information as possible. Means: What you get from the function is just an educated guess :-)
Example script
_OLT_iCal_VEvent_Import.au3
- creates a test.ics file in the current directory
- this test file holds two events starting today with a duration of 1 and 2 days
- debugging is done to the console
- it uses a callback function to suppress all events with SUBJECT=Party
- an array holding Start, End and Subject of the created items is displayed
Callback function parameter
A one dimensional array holding the Outlook properties to create the item.
Format: Outlook-property-name=Outlook-property-value
_OLT_vCard_Import
Import vCard contacts to an Outlook contacts folder.
The function processes the following properties (in whole or in part) according to RFC 6350 (properties not listed will be ignored):
| COMPONENT:PROPERTY | SECTION IN RFC 6350 | OUTLOOK PROPERTY | COMMENT |
|---|---|---|---|
| VCARD:FN | Section 6.2.1 | fullname | |
| VCARD:N | Section 6.2.2 | lastname, firstname, middlename, title | Family Names, Given Names, Additional Names, Honorific Prefixes, and Honorific Suffixes |
| VCARD:ADR TYPE=HOME | Section 6.3.1 | HomeAddressPostOfficeBox, HomeAddress, HomeAddressStreet, HomeAddressCity, HomeAddressState, HomeAddressPostalCode, HomeAddressCountry | |
| VCARD:ADR TYPE=WORK | Section 6.3.1 | BusinessAddressPostOfficeBox, BusinessAddress, BusinessAddressStreet, BusinessAddressCity, BusinessAddressState, BusinessAddressPostalCode, BusinessAddressCountry | |
| VCARD:TEL TYPE=HOME | Section 6.4.1 | PersonalHomePage | |
| VCARD:TEL TYPE=WORK | Section 6.4.1 | BusinessHomePage | |
| VCARD:EMAIL | Section 6.4.2 | Email1Address | |
| VCARD:ORG | Section 6.6.4 | CompanyName | |
| VCARD:TITLE | Section 6.6.1 | JobTitle | |
| VCARD:CATEGORIES | Section 6.7.1 | Categories | |
| VCARD:URL TYPE=HOME | Section 6.7.8 | PersonalHomePage | |
| VCARD:URL TYPE=WORK | Section 6.7.8 | BusinessHomePage |
Limitations/Requirements
Input for the function has been taken from the following standards:
- vCard 2.1: vCard 2.1 specification, 1996-09-18 (https://web.archive.org/web/20120501162958/http://www.imc.org/pdi/vcard-21.doc)
- vCard 3.0: RFC 2426, 1998-09
- vCard 4.0: RFC 6350, 2011-08
This means that the function does not fully follow this standards. It just scans throught he input file and extracts as much information as possible. Means: What you get from the function is just an educated guess :-)
Example script
vCard_Import.au3
- creates a test.vcf file in the current directory
- this test file holds a single contact
- debugging is done to the console
- it uses a callback function to not import contacts that already exist
- an array holding all created items is displayed
Callback function parameter
A one dimensional array holding the Outlook properties to create the item.
Format: Outlook-property-name=Outlook-property-value
_OLT_CSV_Import
Imports data from a CSV file and creates Outlook items in a specified folder.
Limitations/Requirements
- has only been tested for contact items
- this function does not read the input file (as other functions of the OutlookTools UDF do). You have to use _FileReadToArray (or a similar function) and pass the resulting array to _OLT_CSV_Import. With this approach you can process different types of CSV files (delimiters etc.) and files that do not comply to RFC 4180
- you have to pass a second array describing the structure of the data array. The structure is described by using the corresponding Outlook item properties
- this function allows to alter data used to create the Outlook item (all other functions don't for the time being). This is possible because the data is held in a global variable which is filled before _OLT_CSV_Import gets called
Example script
CSVImport.au3
- creates the data array ($aData) without reading a file (you should use _FileReadToArray to read the CSV file and fill the array)
- the structure array ($aStruct) describes the columns in $aData using the Outlook contact properties Firstname, LastName and UnRead
- debugging is done to the console
- it uses a callback function to set Outlook property UnRead to True for contacts with FirstName=Jane
Callback function parameter
The zero based index of the currently processed row in $aData.
As the data to process is being held in $aData in the main script the callback function can directly alter this data. So there is no need to return $aData to _OLT_CSVImport and hence _OLT_CSVImport will ignore returned data.
_OLT_Export
Export Outlook items (contacts, appointments ...) to files in different formats (VCF, ICS, CSV ...).
Limitations/Requirements
- currently just available for contacts and appointments (VCF and ICS files)
Example script
_OLT_Export.au3
- creates the data array ($aData) without reading a file (you should use _FileReadToArray to read the CSV file and fill the array)
- the structure array ($aStruct) describes the columns in $aData using the Outlook contact properties Firstname, LastName and UnRead
- debugging is done to the console
- it uses a callback function to set Outlook property UnRead to True for contacts with FirstName=Jane
Callback function parameter
The zero based index of the currently processed row in $aData.
As the data to process is being held in $aData in the main script the callback function can directly alter this data. So there is no need to return $aData to _OLT_CSVImport and hence _OLT_CSVImport will ignore returned data.