::OutlookTop, Main, Index

proc ::Outlook::AddAppointment {calId args} {

    # Create a new appointment in an Outlook calendar.
    #
    # calId - Identifier of the Outlook calendar.
    # args  - Options described below.
    #
    # -subject <string>            - Set the subject text of the appointment.
    #                                Default: No subject.
    # -startdate <string>          - Set the start date of the appointment in format `%Y-%m-%d %H:%M:%S`.
    #                                Default: Today.
    # -enddate <string>            - Set the end date of the appointment in format `%Y-%m-%d %H:%M:%S`.
    #                                Default: Today.
    # -category <string>           - Assign category to appointment.
    #                                If specified category does not yet exist, it is created.
    #                                Default: No category.
    # -location <string>           - Set the location of the appointment.
    #                                Default: No location.
    # -body <string>               - Set the body text of the appointment.
    #                                Default: No body text.
    # -alldayevent <bool>          - Specify, if appointment is an all day event.
    #                                Default: false.
    # -reminder <bool>             - Specify, if appointment has a reminder set.
    #                                Default: true.
    # -busystate <OlBusyStatus>    - Set the busy status of the appointment.
    #                                Possible values: `olBusy` `olFree` `olOutOfOffice` `olTentative` `olWorkingElsewhere`.
    #                                Default: `olBusy`.
    # -importance <OlImportance>   - Set the importance of the appointment.
    #                                Possible values: `olImportanceHigh` `olImportanceLow` `olImportanceNormal`.
    #                                Default: `olImportanceNormal`.
    # -sensitivity <OlSensitivity> - Set the sensitivity of the appointment.
    #                                Possible values: `olConfidential` `olNormal` `olPersonal` `olPrivate`.
    #                                Default: `olNormal`.
    # -isrecurring                  - Get the recurring flag of the appointment.
    #                                 Only available for procedure [GetAppointmentProperties].
    #
    # Returns the identifier of the new appointment object.
    #
    # See also: CreateMail AddCalendar AddHolidayAppointment GetAppointmentProperties GetNumAppointments

    set appointId [$calId -with { Items } Add $Outlook::olAppointmentItem]

    foreach { key value } $args {
        if { $value eq "" } {
            error "AddAppointment: No value specified for key \"$key\""
        }
        switch -exact -nocase -- $key {
            "-subject" {
                $appointId Subject $value
            }
            "-startdate" {
                $appointId Start [Cawt IsoDateToOfficeDate $value]
            }
            "-enddate" {
                $appointId End [Cawt IsoDateToOfficeDate $value]
            }
            "-category" {
                set appId [$calId Application]
                Outlook AddCategory $appId $value
                $appointId Categories $value
                Cawt Destroy $appId
            }
            "-location" {
                $appointId Location $value
            }
            "-body" {
                $appointId Body $value
            }
            "-alldayevent" {
                $appointId AllDayEvent [Cawt TclBool $value]
            }
            "-reminder" {
                $appointId ReminderSet [Cawt TclBool $value]
            }
            "-busystate" {
                $appointId BusyStatus [Outlook GetEnum $value]
            }
            "-importance" {
                $appointId Importance [Outlook GetEnum $value]
            }
            "-sensitivity" {
                $appointId Sensitivity [Outlook GetEnum $value]
            }
            default {
                error "AddAppointment: Unknown key \"$key\" specified"
            }
        }
    }
    $appointId Save
    return $appointId
}

proc ::Outlook::AddCalendar {appId calendarName} {

    # Add a new Outlook calendar.
    #
    # appId        - Identifier of the Outlook instance.
    # calendarName - Name of the new calendar.
    #
    # Returns the identifier of the new calendar.
    # If a calendar with given name is already existing, the identifier of that
    # calendar is returned.
    #
    # If the calendar could not be added an error is thrown.
    #
    # See also: AddAppointment DeleteCalendar GetNumCalendars HaveCalendar
    # GetCalendarNames GetCalendarId

    set nsObj [$appId GetNamespace "MAPI"]
    set calId [$nsObj GetDefaultFolder $Outlook::olFolderCalendar]
    set numFolders [$calId -with {Folders} Count]
    for { set i 1 } { $i <= $numFolders } { incr i } {
        set folderId [$calId -with {Folders} Item [expr {$i}]]
        if { [$folderId Name] eq $calendarName } {
            return $folderId
        }
        Cawt Destroy $folderId
    }
    set catchVal [catch {$calId -with { Folders } Add  $calendarName $Outlook::olFolderCalendar} newCalId]
    if { $catchVal != 0 } {
        error "AddCalendar: Could not add calendar \"$calendarName\"."
    }
    Cawt Destroy $calId
    Cawt Destroy $nsObj
    return $newCalId
}

proc ::Outlook::AddCategory {appId name {color {}}} {

    # Add a new category to the Outlook categories.
    #
    # appId - Identifier of the Outlook instance.
    # name  - Name of the new category.
    # color - Value of enumeration type [Enum::OlCategoryColor]
    #         or category color name.
    #         If set to the empty string, a color is choosen automatically by Outlook.
    #
    # Returns the identifier of the new category.
    # If a category with given name is already existing, the identifier of that
    # category is returned.
    #
    # See also: HaveCategory GetNumCategories GetCategoryNames
    # GetCategoryId DeleteCategory GetCategoryColor

    if { [Outlook HaveCategory $appId $name] } {
        return [Outlook::GetCategoryId $appId $name]
    }

    set nsObj [$appId GetNamespace "MAPI"]
    set categories [$nsObj Categories]
    if { $color eq "" } {
        set categoryId [$categories Add $name]
    } else {
        set colorEnum [Outlook::GetCategoryColorEnum $color]
        set categoryId [$categories Add $name $colorEnum]
    }
    Cawt Destroy $categories
    Cawt Destroy $nsObj
    return $categoryId
}

proc ::Outlook::AddContact {contactFolderId args} {

    # Create a new contact in an Outlook contact folder.
    #
    # contactFolderId - Identifier of the Outlook contact folder.
    # args            - Options described below.
    #
    # -category <string> - Assign category to contact.
    #                      If specified category does not yet exist, it is created.
    # -image <string>    - Add contact image.
    #                      Supported image formats:
    #                      `GIF` `JPEG` `BMP` `TIFF` `WMF` `EMF` `PNG`.
    # Key-value pairs    - Key is a read-write property name, value is the property value to be set.
    #
    # Create a new contact in an Outlook contact folder and set the
    # properties of the new contact.
    #
    # For details on contact properties see [SetContactProperties].
    #
    # See also: AddContactFolder SetContactProperties GetContactProperties
    # GetNumContacts GetContactReadWritePropertyNames GetContactReadOnlyPropertyNames

    set contactId [$contactFolderId -with { Items } Add $Outlook::olContactItem]

    Outlook::SetContactProperties $contactId {*}$args

    return $contactId
}

proc ::Outlook::AddContactFolder {appId contactFolderName args} {

    # Add a new Outlook contact folder.
    #
    # appId             - Identifier of the Outlook instance.
    # contactFolderName - Name of the new contact folder.
    # args              - Options described below.
    #
    # -addressbook <bool> - Add the contact folder to the addressbook.
    #                       Default: false.
    #
    # Returns the identifier of the new contact folder.
    #
    # If a contact folder with given name is already existing, the identifier
    # of that contact folder is returned.
    # If the contact folder could not be added, an error is thrown.
    #
    # See also: DeleteContactFolder GetNumContactFolders HaveContactFolder
    # GetContactFolderNames GetContactFolderId

    set addToAddressbook false
    foreach { key value } $args {
        if { $value eq "" } {
            error "AddContactFolder: No value specified for key \"$key\"."
        }
        switch -exact -nocase -- $key {
            "-addressbook" { set addToAddressbook $value }
            default        { error "AddContactFolder: Unknown key \"$key\" specified." }
        }
    }

    set nsObj [$appId GetNamespace "MAPI"]
    set contactFolderId [$nsObj GetDefaultFolder $Outlook::olFolderContacts]
    set numFolders [$contactFolderId -with {Folders} Count]
    for { set i 1 } { $i <= $numFolders } { incr i } {
        set folderId [$contactFolderId -with {Folders} Item [expr {$i}]]
        if { [$folderId Name] eq $contactFolderName } {
            return $folderId
        }
        Cawt Destroy $folderId
    }
    set catchVal [catch {$contactFolderId -with { Folders } Add  $contactFolderName $Outlook::olFolderContacts} folderId]
    if { $catchVal != 0 } {
        error "AddContactFolder: Could not add contact folder \"$contactFolderName\"."
    }
    $folderId ShowAsOutlookAB [Cawt TclBool $addToAddressbook]
    Cawt Destroy $contactFolderId
    Cawt Destroy $nsObj
    return $folderId
}

proc ::Outlook::AddHolidayAppointment {calId subject args} {

    # Create a new appointment in an Outlook calendar.
    #
    # calId   - Identifier of the Outlook calendar.
    # subject - Subject text.
    # args    - Options described below.
    #
    # -date <string>     - Set the date of the appointment in format `%Y-%m-%d`. Default: Today.
    # -category <string> - Assign category to appointment. Default: No category.
    # -location <string> - Set the location of the appointment. Default: No location.
    #
    # The appointment has the following properties automatically set:
    #   `All-Day event`, `No reminder`, `OutOfOffice status`.
    #
    # Returns the identifier of the new appointment object.
    #
    # See also: CreateMail AddAppointment ApplyHolidayFile GetNumAppointments

    set appointId [$calId -with { Items } Add $Outlook::olAppointmentItem]
    foreach { key value } $args {
        if { $value eq "" } {
            error "AddHolidayAppointment: No value specified for key \"$key\""
        }
        switch -exact -nocase -- $key {
            "-date"     {
                            set dateSec [clock scan $value -format "%Y-%m-%d"]
                            $appointId Start [Cawt SecondsToOfficeDate $dateSec]
                        }
            "-category" {
                            if { $value ne "" } {
                                set appId [$calId Application]
                                Outlook AddCategory $appId $value
                                $appointId Categories $value
                                Cawt Destroy $appId
                            }
                        }
            "-location" { $appointId Location $value }
            default     { error "AddHolidayAppointment: Unknown key \"$key\" specified" }
        }
    }

    $appointId Subject $subject
    $appointId AllDayEvent [Cawt TclBool true]
    $appointId ReminderSet [Cawt TclBool false]
    $appointId BusyStatus $Outlook::olOutOfOffice

    $appointId Save

    return $appointId
}

proc ::Outlook::ApplyHolidayFile {calId fileName {category {}}} {

    # Read an Outlook holiday file and insert appointments.
    #
    # calId    - Identifier of the Outlook calendar.
    # fileName - Name of the Outlook holiday file.
    # category - Assign category to appointment. Default: No category.
    #
    # Returns no value.
    # If the holiday file could not be read, an error is thrown.
    #
    # See also: ReadHolidayFile AddHolidayAppointment

    set holidayDict [Outlook::ReadHolidayFile $fileName]
    set sectionList [dict get $holidayDict SectionList]
    foreach section $sectionList {
        set subjectList [dict get $holidayDict "SubjectList_$section"]
        set dateList    [dict get $holidayDict "DateList_$section"]
        foreach subject $subjectList date $dateList {
            Outlook::AddHolidayAppointment $calId $subject  -date $date  -location $section  -category $category
        }
    }
}

proc ::Outlook::CreateHtmlMail {appId recipientList {subject {}} {body {}} {attachmentList {}}} {

    # Create a new Outlook HTML mail.
    #
    # appId          - Identifier of the Outlook instance.
    # recipientList  - List of mail addresses.
    # subject        - Subject text.
    # body           - Mail body text in HTML format.
    # attachmentList - List of files used as attachment.
    #
    # Returns the identifier of the new mail object.
    #
    # See also: CreateMail SendMail

    return [Outlook::_CreateMail $appId "html" $recipientList $subject $body $attachmentList]
}

proc ::Outlook::CreateMail {appId recipientList {subject {}} {body {}} {attachmentList {}}} {

    # Create a new Outlook text mail.
    #
    # appId          - Identifier of the Outlook instance.
    # recipientList  - List of mail addresses.
    # subject        - Subject text.
    # body           - Mail body text.
    # attachmentList - List of files used as attachment.
    #
    # Returns the identifier of the new mail object.
    #
    # See also: CreateHtmlMail SendMail

    return [Outlook::_CreateMail $appId "text" $recipientList $subject $body $attachmentList]
}

proc ::Outlook::DeleteAppointmentByIndex {calId index} {

    # Delete an appointment of an Outlook calendar by its index.
    #
    # calId - Identifier of the Outlook calendar.
    # index - Index of the appointment.
    #
    # Returns no value.
    #
    # The first appointment has index 1.
    # Instead of using the numeric index the special word `end` may
    # be used to specify the last appointment.
    # If the index is out of bounds an error is thrown.
    #
    # See also: AddCalendar AddAppointment GetNumAppointments GetAppointmentByIndex

    set count [Outlook::GetNumAppointments $calId]
    if { $index eq "end" } {
        set index $count
    } else {
        if { $index < 1 || $index > $count } {
            error "DeleteAppointmentByIndex: Invalid index $index given."
        }
    }
    $calId -with { Items } Remove [expr {$index}]
}

proc ::Outlook::DeleteCalendar {calId} {

    # Delete an Outlook calendar.
    #
    # calId - Identifier of the Outlook calendar.
    #
    # Returns no value.
    #
    # See also: AddCalendar GetNumCalendars HaveCalendar GetCalendarNames GetCalendarId

    $calId Delete
}

proc ::Outlook::DeleteCategory {appId indexOrName} {

    # Delete an Outlook category.
    #
    # indexOrName - Index or name of the Outlook category.
    #
    # Returns no value.
    #
    # See also: AddCategory HaveCategory GetNumCategories GetCategoryNames
    # GetCategoryId DeleteCategory

    set nsObj [$appId GetNamespace "MAPI"]
    set categories [$nsObj Categories]
    set count [$categories Count]

    if { [string is integer -strict $indexOrName] } {
        set index [expr int($indexOrName)]
        if { $index < 1 || $index > $count } {
            error "DeleteCategory: Invalid index $index given."
        }
    } else {
        set index 1
        set found false
        foreach name [Outlook::GetCategoryNames $appId] {
            if { $indexOrName eq $name } {
                set found true
                break
            }
            incr index
        }
        if { ! $found } {
            error "DeleteCategory: No category with name $indexOrName"
        }
    }
    $categories Remove $index

    Cawt Destroy $categories
    Cawt Destroy $nsObj
}

proc ::Outlook::DeleteContactByIndex {contactFolderId index} {

    # Delete a contact of an Outlook contact folder by its index.
    #
    # contactFolderId - Identifier of the Outlook contact folder.
    # index           - Index of the contact.
    #
    # Returns no value.
    #
    # The first contact has index 1.
    # Instead of using the numeric index the special word `end` may
    # be used to specify the last contact.
    #
    # If the index is out of bounds an error is thrown.
    #
    # See also: AddContactFolder AddContact GetNumContacts GetContactByIndex

    set count [Outlook::GetNumContacts $contactFolderId]
    if { $index eq "end" } {
        set index $count
    } else {
        if { $index < 1 || $index > $count } {
            error "DeleteContactByIndex: Invalid index $index given."
        }
    }
    $contactFolderId -with { Items } Remove [expr {$index}]
}

proc ::Outlook::DeleteContactFolder {contactFolderId} {

    # Delete an Outlook contact folder.
    #
    # contactFolderId - Identifier of the Outlook contact folder.
    #
    # Returns no value.
    #
    # See also: AddContactFolder GetNumContactFolders HaveContactFolder
    # GetContactFolderNames GetContactFolderId

    $contactFolderId Delete
}

proc ::Outlook::GetAppointmentByIndex {calId index} {

    # Get an appointment of an Outlook calendar by its index.
    #
    # calId - Identifier of the Outlook calendar.
    # index - Index of the appointment.
    #
    # Returns the identifier of the found appointment.
    #
    # The first appointment has index 1.
    # Instead of using the numeric index the special word `end` may
    # be used to specify the last appointment.
    # If the index is out of bounds an error is thrown.
    #
    # See also: AddCalendar AddAppointment GetNumAppointments DeleteAppointmentByIndex

    set count [Outlook::GetNumAppointments $calId]
    if { $index eq "end" } {
        set index $count
    } else {
        if { $index < 1 || $index > $count } {
            error "GetAppointmentByIndex: Invalid index $index given."
        }
    }

    set itemId [$calId -with { Items } Item [expr {$index}]]
    return $itemId
}

proc ::Outlook::GetAppointmentProperties {appointId args} {

    # Get properties of an Outlook appointment.
    #
    # appointId - Identifier of the Outlook appointment.
    # args      - List of keys specifying appointment configure options.
    #
    # See [AddAppointment] for a list of configure options.
    #
    # Returns the appointment properties as a list of values.
    # The list elements have the same order as the list of keys.
    #
    # See also: AddCalendar AddAppointment GetNumAppointments GetAppointmentByIndex

    set valueList [list]
    foreach key $args {
        switch -exact -nocase -- $key {
            "-subject" {
                lappend valueList [$appointId Subject]
            }
            "-startdate" {
                lappend valueList [Cawt OfficeDateToIsoDate [$appointId Start]]
            }
            "-enddate" {
                lappend valueList [Cawt OfficeDateToIsoDate [$appointId End]]
            }
            "-category" {
                lappend valueList [$appointId Categories]
            }
            "-location" {
                lappend valueList [$appointId Location]
            }
            "-body" {
                lappend valueList [$appointId Body]
            }
            "-alldayevent" {
                lappend valueList [$appointId AllDayEvent]
            }
            "-reminder" {
                lappend valueList [$appointId ReminderSet]
            }
            "-busystate" {
                lappend valueList [Outlook GetEnumName OlBusyStatus [$appointId BusyStatus]]
            }
            "-importance" {
                lappend valueList [Outlook GetEnumName OlImportance [$appointId Importance]]
            }
            "-sensitivity" {
                lappend valueList [Outlook GetEnumName OlSensitivity [$appointId Sensitivity]]
            }
            "-isrecurring" {
                lappend valueList [$appointId IsRecurring]
            }
            default {
                error "GetAppointmentProperties: Unknown key \"$key\" specified"
            }
        }
    }
    return $valueList
}

proc ::Outlook::GetCalendarId {appId {calendarName {}}} {

    # Get an Outlook calendar by its name.
    #
    # appId        - Identifier of the Outlook instance.
    # calendarName - Name of the calendar to find.
    #
    # Returns the identifier of the found calendar.
    # If $calendarName is not specified or the empty string, the identifier
    # of the default calendar is returned.
    #
    # If a calendar with given name does not exist, an empty string is returned.
    #
    # See also: AddCalendar DeleteCalendar GetNumCalendars HaveCalendar GetCalendarNames

    if { $calendarName eq "" } {
        set nsObj [$appId GetNamespace "MAPI"]
        set calId [$nsObj GetDefaultFolder $Outlook::olFolderCalendar]
        Cawt Destroy $nsObj
        return $calId
    }
    set foundId ""
    foreach { name calId } [Outlook::GetFoldersRecursive $appId $Outlook::olAppointmentItem] {
        if { $name eq $calendarName } {
            set foundId $calId
        } else {
            Cawt Destroy $calId
        }
    }
    return $foundId
}

proc ::Outlook::GetCalendarNames {appId} {

    # Get a list of Outlook calendar names.
    #
    # appId - Identifier of the Outlook instance.
    #
    # Returns a list of calendar names.
    #
    # See also: AddCalendar DeleteCalendar GetNumCalendars HaveCalendar GetCalendarId

    Cawt PushComObjects
    set calendarNameList [list]
    foreach { name calId } [Outlook::GetFoldersRecursive $appId $Outlook::olAppointmentItem] {
        lappend calendarNameList $name
    }
    Cawt PopComObjects
    return $calendarNameList
}

proc ::Outlook::GetCategoryColor {colorEnumOrName} {

    # Convert a category color enumeration or name
    # into a hexadecimal Tcl color string representation.
    #
    # colorEnumOrName - A category color enumeration or name.
    #
    # Outlook category colors can be specified in one of the following representations:
    #   Enum - A value of enumeration [Enum::OlCategoryColor].
    #   Name - Enumeration name without prefix `olCategoryColor`.
    #          Example: Name of `Outlook::olCategoryColorBlack` is `Black`.
    #
    # Returns the hexadecimal representation of the specified color, ex. `#00FFAA`.
    #
    # See also: ::Cawt::GetColor GetCategoryColorEnum GetCategoryColorName GetCategoryColorNames

    variable sCategoryColorList

    set enum [Outlook::GetCategoryColorEnum $colorEnumOrName]
    set rgb [lrange $sCategoryColorList($enum) 1 end]
    lassign $rgb r g b
    return [format "#%02X%02X%02X" $r $g $b]
}

proc ::Outlook::GetCategoryColorEnum {colorEnumOrName} {

    # Convert a category color enumeration or name into a color enumeration.
    #
    # colorEnumOrName - A category color enumeration or name.
    #
    # See [GetCategoryColor] for a description of color enumerations and names.
    #
    # Returns the category color enumeration.
    #
    # See also: ::Cawt::GetColor GetCategoryColor GetCategoryColorName GetCategoryColorNames

    variable sCategoryColorList

    if { [string is integer $colorEnumOrName] } {
        if { [info exists sCategoryColorList($colorEnumOrName)] } {
            return $colorEnumOrName
        }
    } else {
        foreach { key val } [array get sCategoryColorList] {
            if { [lindex $val 0] eq $colorEnumOrName } {
                return $key
            }
        }
    }
    error "GetCategoryColorEnum: Invalid color representation \"$colorEnumOrName\" specified."
}

proc ::Outlook::GetCategoryColorName {colorEnum} {

    # Convert a category color enumeration into a category color name.
    #
    # colorEnum - A category color enumeration.
    #
    # See [GetCategoryColor] for a description of color enumerations and names.
    #
    # Returns the category color name.
    #
    # See also: ::Cawt::GetColor GetCategoryColor GetCategoryColorEnum GetCategoryColorNames

    variable sCategoryColorList

    if { [info exists sCategoryColorList($colorEnum)] } {
        return [lindex $sCategoryColorList($colorEnum) 0]
    }
    error "GetCategoryColorName: Invalid color enumeration \"$colorEnum\" specified."
}

proc ::Outlook::GetCategoryColorNames {} {

    # Get all category color names.
    #
    # See [GetCategoryColor] for a description of color enumerations and names.
    #
    # Returns a list of all category color names.
    #
    # See also: ::Cawt::GetColor GetCategoryColor GetCategoryColorEnum GetCategoryColorName

    variable sCategoryColorList

    set colorNameList [list]
    foreach { key val } [array get sCategoryColorList] {
        lappend colorNameList [lindex $val 0]
    }
    return $colorNameList
}

proc ::Outlook::GetCategoryId {appId indexOrName} {

    # Get a category by its index or name.
    #
    # appId       - Identifier of the Outlook instance.
    # indexOrName - Index or name of the category.
    #
    # Returns the identifier of the found category.
    #
    # The first category has index 1.
    #
    # If the index is out of bounds or the category name does not
    # exist, an error is thrown.
    #
    # See also: HaveCategory GetNumCategories GetCategoryNames
    # AddCategory DeleteCategory

    set nsObj [$appId GetNamespace "MAPI"]
    set count [$nsObj -with { Categories } Count]
    if { [string is integer -strict $indexOrName] } {
        set index [expr int($indexOrName)]
        if { $index < 1 || $index > $count } {
            error "GetCategoryId: Invalid index $index given."
        }
    } else {
        set index 1
        set found false
        foreach name [Outlook GetCategoryNames $appId] {
            if { $indexOrName eq $name } {
                set found true
                break
            }
            incr index
        }
        if { ! $found } {
            error "GetCategoryId: No category with name $indexOrName"
        }
    }
    set categoryId [$nsObj -with { Categories } Item $index]
    Cawt Destroy $nsObj
    return $categoryId
}

proc ::Outlook::GetCategoryNames {appId} {

    # Get a list of category names.
    #
    # appId - Identifier of the Outlook instance.
    #
    # Returns a list of category names.
    #
    # See also: HaveCategory GetNumCategories GetCategoryId
    # AddCategory DeleteCategory

    set nsObj [$appId GetNamespace "MAPI"]
    set categories [$nsObj Categories]
    set count [$categories Count]

    set nameList [list]
    for { set i 1 } { $i <= $count } { incr i } {
        set categoryId [$categories Item [expr {$i}]]
        lappend nameList [$categoryId Name]
        Cawt Destroy $categoryId
    }
    Cawt Destroy $categories
    Cawt Destroy $nsObj
    return $nameList
}

proc ::Outlook::GetContactByIndex {contactFolderId index} {

    # Get a contact of an Outlook contact folder by its index.
    #
    # contactFolderId - Identifier of the Outlook contact folder.
    # index           - Index of the contact.
    #
    # Returns the identifier of the found contact.
    #
    # The first contact has index 1.
    # Instead of using the numeric index the special word `end` may
    # be used to specify the last contact.
    #
    # If the index is out of bounds an error is thrown.
    #
    # See also: AddContactFolder AddContact GetNumContacts DeleteContactByIndex

    set count [Outlook::GetNumContacts $contactFolderId]
    if { $index eq "end" } {
        set index $count
    } else {
        if { $index < 1 || $index > $count } {
            error "GetContactByIndex: Invalid index $index given."
        }
    }

    set itemId [$contactFolderId -with { Items } Item [expr {$index}]]
    return $itemId
}

proc ::Outlook::GetContactFolderId {appId {contactFolderName {}}} {

    # Get an Outlook contact folder by its name.
    #
    # appId             - Identifier of the Outlook instance.
    # contactFolderName - Name of the contact folder to find.
    #
    # Returns the identifier of the found contact folder.
    # If $contactFolderName is not specified or the empty string, the identifier
    # of the default contact folder is returned.
    #
    # If a contact folder with given name does not exist, an empty string is returned.
    #
    # See also: AddContactFolder DeleteContactFolder GetNumContactFolders
    # HaveContactFolder GetContactFolderNames

    if { $contactFolderName eq "" } {
        set nsObj [$appId GetNamespace "MAPI"]
        set folderId [$nsObj GetDefaultFolder $Outlook::olFolderContacts]
        Cawt Destroy $nsObj
        return $folderId
    }
    set foundId ""
    foreach { name folderId } [Outlook::GetFoldersRecursive $appId $Outlook::olContactItem] {
        if { $name eq $contactFolderName } {
            set foundId $folderId
        } else {
            Cawt Destroy $folderId
        }
    }
    return $foundId
}

proc ::Outlook::GetContactFolderNames {appId} {

    # Get a list of Outlook contact folder names.
    #
    # appId - Identifier of the Outlook instance.
    #
    # Returns a list of contact folder names.
    #
    # See also: AddContactFolder DeleteContactFolder GetNumContactFolders
    # HaveContactFolder GetContactFolderId

    Cawt PushComObjects
    set contactFolderNameList [list]
    foreach { name folderId } [Outlook::GetFoldersRecursive $appId $Outlook::olContactItem] {
        lappend contactFolderNameList $name
    }
    Cawt PopComObjects
    return $contactFolderNameList
}

proc ::Outlook::GetContactProperties {contactId args} {

    # Get property values of an Outlook contact.
    #
    # contactId - Identifier of the Outlook contact.
    # args  - Options described below.
    #
    # List of property names - If args is empty, all read-only and
    # read-write properties are returned.
    #
    # Returns the contact properties as a list of key-value pairs.
    #
    # If a property value could not be read, and error is thrown.
    #
    # See also: AddContactFolder AddContact GetNumContacts GetContactByIndex
    # SetContactProperties GetContactReadWritePropertyNames GetContactReadOnlyPropertyNames

    set keyValueList [list]
    if { [llength $args] == 0 } {
        set keyList [concat [GetContactReadWritePropertyNames] [GetContactReadOnlyPropertyNames]]
    } else {
        set keyList $args
    }
    foreach key $keyList {
        set catchVal [catch { $contactId $key } value]
        if { $catchVal != 0 } {
            error "GetContactProperties: Could not retrieve value of property \"$key\"."
        }
        switch -exact -nocase -- $key {
            "Anniversary" -
            "Birthday" -
            "CreationTime" -
            "LastModificationTime" -
            "TaskCompletedDate" -
            "TaskDueDate" -
            "TaskStartDate" -
            "ToDoTaskOrdinal" {
                set convertedValue  [Cawt OfficeDateToIsoDate $value]
            }
            "Gender" {
                set convertedValue [Outlook GetEnumName "OlGender" $value]
            }
            default {
                set convertedValue $value
            }
        }
        lappend keyValueList $key
        lappend keyValueList $convertedValue
    }
    return $keyValueList
}

proc ::Outlook::GetContactReadOnlyPropertyNames {} {

    # Get a list of Outlook contact read-only property names.
    #
    # The following contact properties are read-only:
    # **Name** - **Type**
    # `Categories` - String
    # `Companies` - String
    # `CompanyAndFullName` - String
    # `CompanyLastFirstNoSpace` - String
    # `CompanyLastFirstSpaceOnly` - String
    # `CreationTime` - Date in format `%Y-%m-%d %H:%M:%S`
    # `Email1EntryID` - String
    # `Email2EntryID` - String
    # `Email3EntryID` - String
    # `FullNameAndCompany` - String
    # `HasPicture` - Boolean
    # `LastFirstAndSuffix` - String
    # `LastFirstNoSpace` - String
    # `LastFirstNoSpaceAndSuffix` - String
    # `LastFirstNoSpaceCompany` - String
    # `LastFirstSpaceOnly` - String
    # `LastFirstSpaceOnlyCompany` - String
    # `LastModificationTime` - Date in format `%Y-%m-%d %H:%M:%S`
    # `LastNameAndFirstName` - String
    # `OutlookInternalVersion` - Integer
    # `OutlookVersion` - String
    #
    # Returns a list of contact property names, which are read-only.
    #
    # **Note 1:**
    # To get a list of all property names (read-only and read-write), use:
    #     [concat [GetContactReadWritePropertyNames] [GetContactReadOnlyPropertyNames]]
    #
    # **Note 2:**
    # Converting dates into needed format can be accomplished with [::Cawt::SecondsToIsoDate]:
    #     [Cawt SecondsToIsoDate [clock seconds]]
    #
    # See also: AddContactFolder AddContact GetContactReadWritePropertyNames
    # SetContactProperties GetContactProperties

    return [list  Categories  Companies  CompanyAndFullName  CompanyLastFirstNoSpace  CompanyLastFirstSpaceOnly  CreationTime  Email1EntryID  Email2EntryID  Email3EntryID  FullNameAndCompany  HasPicture  LastFirstAndSuffix  LastFirstNoSpace  LastFirstNoSpaceAndSuffix  LastFirstNoSpaceCompany  LastFirstSpaceOnly  LastFirstSpaceOnlyCompany  LastModificationTime  LastNameAndFirstName  OutlookInternalVersion  OutlookVersion  ]
}

proc ::Outlook::GetContactReadWritePropertyNames {} {

    # Get a list of Outlook contact read-write property names.
    #
    # The following contact properties are read-write:
    # **Name** - **Type**
    # `Account` - String
    # `Anniversary` - Date in format `%Y-%m-%d %H:%M:%S`
    # `AssistantName` - String
    # `AssistantTelephoneNumber - String
    # `BillingInformation` - String
    # `Birthday` - Date in format `%Y-%m-%d %H:%M:%S`
    # `Body` - String
    # `Business2TelephoneNumber` - String
    # `BusinessAddress` - String
    # `BusinessAddressCity` - String
    # `BusinessAddressCountry` - String
    # `BusinessAddressPostalCode` - String
    # `BusinessAddressPostOfficeBox` - String
    # `BusinessAddressState` - String
    # `BusinessAddressStreet` - String
    # `BusinessFaxNumber` - String
    # `BusinessHomePage` - String
    # `BusinessTelephoneNumber` - String
    # `CallbackTelephoneNumber` - String
    # `CarTelephoneNumber` - String
    # `CompanyMainTelephoneNumber` - String
    # `CompanyName` - String
    # `ComputerNetworkName` - String
    # `CustomerID` - String
    # `Department` - String
    # `Email1Address` - String
    # `Email1AddressType` - String
    # `Email1DisplayName` - String
    # `Email2Address` - String
    # `Email2AddressType` - String
    # `Email2DisplayName` - String
    # `Email3Address` - String
    # `Email3AddressType` - String
    # `Email3DisplayName` - String
    # `FileAs` - String
    # `FirstName` - String
    # `FTPSIte` - String
    # `FullName` - String
    # `Gender` - Enumeration of type [Enum::OlGender]
    # `GovernmentIDNumber` - String
    # `Hobby` - String
    # `Home2TelephoneNumber` - String
    # `HomeAddress` - String
    # `HomeAddressCity` - String
    # `HomeAddressCountry` - String
    # `HomeAddressPostalCode` - String
    # `HomeAddressPostOfficeBox` - String
    # `HomeAddressState` - String
    # `HomeAddressStreet` - String
    # `HomeFaxNumber` - String
    # `HomeTelephoneNumber` - String
    # `IMAddress` - String
    # `Initials` - String
    # `InternetFreeBusyAddress` - String
    # `ISDNNumber` - String
    # `JobTitle` - String
    # `Language` - String
    # `LastName` - String
    # `MailingAddress` - String
    # `MailingAddressCity` - String
    # `MailingAddressCountry` - String
    # `MailingAddressPostalCode` - String
    # `MailingAddressPostOfficeBox` - String
    # `MailingAddressState` - String
    # `MailingAddressStreet` - String
    # `ManagerName` - String
    # `MiddleName` - String
    # `Mileage` - String
    # `MobileTelephoneNumber` - String
    # `NetMeetingAlias` - String
    # `NetMeetingServer` - String
    # `NickName` - String
    # `OfficeLocation` - String
    # `OrganizationalIDNumber` - String
    # `OtherAddress` - String
    # `OtherAddressCity` - String
    # `OtherAddressCountry` - String
    # `OtherAddressPostalCode` - String
    # `OtherAddressPostOfficeBox` - String
    # `OtherAddressState` - String
    # `OtherAddressStreet` - String
    # `OtherFaxNumber` - String
    # `OtherTelephoneNumber` - String
    # `PagerNumber` - String
    # `PersonalHomePage` - String
    # `PrimaryTelephoneNumber` - String
    # `Profession` - String
    # `RadioTelephoneNumber` - String
    # `ReferredBy` - String
    # `Spouse` - String
    # `Subject` - String
    # `Suffix` - String
    # `TaskCompletedDate` - Date in format `%Y-%m-%d %H:%M:%S`
    # `TaskDueDate` - Date in format `%Y-%m-%d %H:%M:%S`
    # `TaskStartDate` - Date in format `%Y-%m-%d %H:%M:%S`
    # `TaskSubject` - String
    # `TelexNumber` - String
    # `Title` - String
    # `ToDoTaskOrdinal` - Date in format `%Y-%m-%d %H:%M:%S`
    # `TTYTDDTelephoneNumber` - String
    # `User1` - String
    # `User2` - String
    # `User3` - String
    # `User4` - String
    # `WebPage` - String
    # `YomiCompanyName` - String
    # `YomiFirstName` - String
    # `YomiLastName` - String
    #
    # Returns a list of contact property names, which can
    # be read and written.
    #
    # **Note 1:**
    # To get a list of all property names (read-only and read-write), use:
    #     [concat [GetContactReadWritePropertyNames] [GetContactReadOnlyPropertyNames]]
    #
    # **Note 2:**
    # Converting dates into needed format can be accomplished with [::Cawt::SecondsToIsoDate]:
    #     [Cawt SecondsToIsoDate [clock seconds]]
    #
    # See also: AddContactFolder AddContact GetContactReadOnlyPropertyNames
    # SetContactProperties GetContactProperties

    return [list  Account  Anniversary  AssistantName  AssistantTelephoneNumber  BillingInformation  Birthday  Body  Business2TelephoneNumber  BusinessAddress  BusinessAddressCity  BusinessAddressCountry  BusinessAddressPostalCode  BusinessAddressPostOfficeBox  BusinessAddressState  BusinessAddressStreet  BusinessFaxNumber  BusinessHomePage  BusinessTelephoneNumber  CallbackTelephoneNumber  CarTelephoneNumber  CompanyMainTelephoneNumber  CompanyName  ComputerNetworkName  CustomerID  Department  Email1Address  Email1AddressType  Email1DisplayName  Email2Address  Email2AddressType  Email2DisplayName  Email3Address  Email3AddressType  Email3DisplayName  FileAs  FirstName  FTPSIte  FullName  Gender  GovernmentIDNumber  Hobby  Home2TelephoneNumber  HomeAddress  HomeAddressCity  HomeAddressCountry  HomeAddressPostalCode  HomeAddressPostOfficeBox  HomeAddressState  HomeAddressStreet  HomeFaxNumber  HomeTelephoneNumber  IMAddress  Initials  InternetFreeBusyAddress  ISDNNumber  JobTitle  Language  LastName  MailingAddress  MailingAddressCity  MailingAddressCountry  MailingAddressPostalCode  MailingAddressPostOfficeBox  MailingAddressState  MailingAddressStreet  ManagerName  MiddleName  Mileage  MobileTelephoneNumber  NetMeetingAlias  NetMeetingServer  NickName  OfficeLocation  OrganizationalIDNumber  OtherAddress  OtherAddressCity  OtherAddressCountry  OtherAddressPostalCode  OtherAddressPostOfficeBox  OtherAddressState  OtherAddressStreet  OtherFaxNumber  OtherTelephoneNumber  PagerNumber  PersonalHomePage  PrimaryTelephoneNumber  Profession  RadioTelephoneNumber  ReferredBy  Spouse  Subject  Suffix  TaskCompletedDate  TaskDueDate  TaskStartDate  TaskSubject  TelexNumber  Title  ToDoTaskOrdinal  TTYTDDTelephoneNumber  User1  User2  User3  User4  WebPage  YomiCompanyName  YomiFirstName  YomiLastName  ]
}

proc ::Outlook::GetEnum {enumOrString} {

    # Get numeric value of an enumeration.
    #
    # enumOrString - Enumeration name
    #
    # Returns the numeric value of an enumeration.
    #
    # See also: GetEnumName GetEnumTypes GetEnumVal GetEnumNames

    set retVal [catch { expr int($enumOrString) } enumInt]
    if { $retVal == 0 } {
        return $enumInt
    } else {
        return [GetEnumVal $enumOrString]
    }
}

proc ::Outlook::GetEnumName {enumType enumVal} {

    # Get name of a given enumeration type and numeric value.
    #
    # enumType - Enumeration type
    # enumVal  - Enumeration numeric value.
    #
    # Returns the list of names of a given enumeration type.
    #
    # See also: GetEnumNames GetEnumTypes GetEnumVal GetEnum

    variable enums

    set enumName ""
    if { [info exists enums($enumType)] } {
        foreach { key val } $enums($enumType) {
            if { $val eq $enumVal } {
                set enumName $key
                break
            }
        }
    }
    return $enumName
}

proc ::Outlook::GetEnumNames {enumType} {

    # Get names of a given enumeration type.
    #
    # enumType - Enumeration type
    #
    # Returns the list of names of a given enumeration type.
    #
    # See also: GetEnumName GetEnumTypes GetEnumVal GetEnum

    variable enums

    if { [info exists enums($enumType)] } {
        foreach { key val } $enums($enumType) {
            lappend nameList $key
        }
        return $nameList
    } else {
        return [list]
    }
}

proc ::Outlook::GetEnumTypes {} {

    # Get available enumeration types.
    #
    # Returns the list of available enumeration types.
    #
    # See also: GetEnumName GetEnumNames GetEnumVal GetEnum

    variable enums

    return [lsort -dictionary [array names enums]]
}

proc ::Outlook::GetEnumVal {enumName} {

    # Get numeric value of an enumeration name.
    #
    # enumName - Enumeration name
    #
    # Returns the numeric value of an enumeration name.
    #
    # See also: GetEnumName GetEnumTypes GetEnumNames GetEnum

    variable enums

    foreach enumType [GetEnumTypes] {
        set ind [lsearch -exact $enums($enumType) $enumName]
        if { $ind >= 0 } {
            return [lindex $enums($enumType) [expr { $ind + 1 }]]
        }
    }
    return ""
}

proc ::Outlook::GetFoldersRecursive {appId type} {

    # Get all Outlook folders of a specific type.
    #
    # appId - Identifier of the Outlook instance.
    # type  - Value of enumeration type [Enum::OlItemType].
    #
    # Returns a key-value list containing the name of the folder
    # followed by the folder identifier.
    #
    # See also: GetMailSubjects GetContactFolderNames GetCalendarNames

    variable sFolderListValid
    variable sFolderListInvalid

    set nsObj [$appId GetNamespace "MAPI"]
    if { [info exists sFolderListValid] } {
        foreach name [array names sFolderListValid] {
            if { [Cawt IsComObject $sFolderListValid($name)] } {
                Cawt Destroy $sFolderListValid($name)
            }
        }
        unset sFolderListValid
    }
    if { [info exists sFolderListInvalid] } {
        foreach name [array names sFolderListInvalid] {
            if { [Cawt IsComObject $sFolderListInvalid($name)] } {
                Cawt Destroy $sFolderListInvalid($name)
            }
        }
        unset sFolderListInvalid
    }
    set folderList [list]
    set trashPath [[$nsObj GetDefaultFolder $Outlook::olFolderDeletedItems] FolderPath]
    Outlook::_ScanStoresRecursive $nsObj $type $trashPath

    foreach name [lsort -dictionary [array names sFolderListValid]] {
        lappend folderList $name $sFolderListValid($name)
    }
    foreach name [array names sFolderListInvalid] {
        if { [Cawt IsComObject $sFolderListInvalid($name)] } {
            Cawt Destroy $sFolderListInvalid($name)
        }
    }
    Cawt Destroy $nsObj
    return $folderList
}

proc ::Outlook::GetMailIds {appId} {

    # Get a list of mail identifiers.
    #
    # appId - Identifier of the Outlook instance.
    #
    # Returns a list of mail identifiers.
    #
    # See also: GetMailSubjects CreateMail SendMail

    set idList [list]
    foreach { name folderId } [Outlook::GetFoldersRecursive $appId $Outlook::olMailItem] {
        set numItems [$folderId -with { Items } Count]
        if { $numItems > 0 } {
            for { set i 1 } { $i <= $numItems } { incr i } {
                lappend idList [$folderId -with { Items } Item $i]
            }
        }
    }
    return $idList
}

proc ::Outlook::GetMailSubjects {appId} {

    # Get a list of mail subjects.
    #
    # appId - Identifier of the Outlook instance.
    #
    # Returns a list of mail subjects.
    #
    # See also: GetMailIds CreateMail SendMail

    set subjectList [list]
    foreach { name folderId } [Outlook::GetFoldersRecursive $appId $Outlook::olMailItem] {
        set numItems [$folderId -with { Items } Count]
        if { $numItems > 0 } {
            for { set i 1 } { $i <= $numItems } { incr i } {
                set mailId [$folderId -with { Items } Item $i]
                lappend subjectList [$mailId Subject]
                Cawt Destroy $mailId
            }
        }
    }
    return $subjectList
}

proc ::Outlook::GetNumAppointments {calId} {

    # Get the number of appointments in an Outlook calendar.
    #
    # calId - Identifier of the Outlook calendar.
    #
    # Returns the number of Outlook appointments.
    #
    # See also: AddCalendar AddAppointment GetAppointmentByIndex DeleteAppointmentByIndex

    set count [$calId -with { Items } Count]
    return $count
}

proc ::Outlook::GetNumCalendars {appId} {

    # Get the number of Outlook calendars.
    #
    # appId - Identifier of the Outlook instance.
    #
    # Returns the number of Outlook calendars.
    #
    # See also: AddCalendar DeleteCalendar HaveCalendar GetCalendarNames GetCalendarId

    return [llength [Outlook::GetCalendarNames $appId]]
}

proc ::Outlook::GetNumCategories {appId} {

    # Get the number of Outlook categories.
    #
    # appId - Identifier of the Outlook instance.
    #
    # Returns the number of Outlook categories.
    #
    # See also: HaveCategory GetCategoryNames GetCategoryId
    # AddCategory DeleteCategory

    set nsObj [$appId GetNamespace "MAPI"]
    set count [$nsObj -with { Categories } Count]
    Cawt Destroy $nsObj
    return $count
}

proc ::Outlook::GetNumContactFolders {appId} {

    # Get the number of Outlook contact folders.
    #
    # appId - Identifier of the Outlook instance.
    #
    # Returns the number of Outlook contact folders.
    #
    # See also: AddContactFolder DeleteContactFolder HaveContactFolder
    # GetContactFolderNames GetContactFolderId

    return [llength [Outlook::GetContactFolderNames $appId]]
}

proc ::Outlook::GetNumContacts {contactFolderId} {

    # Get the number of contacts in an Outlook contact folder.
    #
    # contactFolderId - Identifier of the Outlook contact folder.
    #
    # Returns the number of Outlook contacts.
    # If the contact folder is not accessible, -1 is returned.
    #
    # See also: AddContactFolder AddContact GetContactByIndex DeleteContactByIndex

    set catchVal [catch { $contactFolderId -with { Items } Count } numContacts]
    if { $catchVal != 0 } {
        set numContacts -1
    }
    return $numContacts
}

proc ::Outlook::GetVersion {objId {useString false}} {

    # Get the version of an Outlook application.
    #
    # objId     - Identifier of an Outlook object instance.
    # useString - If set to true, return the version name (ex. `Outlook 2000`).
    #             Otherwise return the version number (ex. `9.0`).
    #
    # Returns the version of an Outlook application.
    #
    # Both version name and version number are returned as strings.
    # Version number is in a format, so that it can be evaluated as a
    # floating point number.
    #
    # See also: Open

    array set map {
        "7.0"  "Outlook 95"
        "8.0"  "Outlook 97"
        "9.0"  "Outlook 2000"
        "10.0" "Outlook 2002"
        "11.0" "Outlook 2003"
        "12.0" "Outlook 2007"
        "14.0" "Outlook 2010"
        "15.0" "Outlook 2013"
        "16.0" "Outlook 2016/2019"
    }
    set versionString [Office GetApplicationVersion $objId]

    set members [split $versionString "."]
    set version "[lindex $members 0].[lindex $members 1]"
    if { $useString } {
        if { [info exists map($version)] } {
            return $map($version)
        } else {
            return "Unknown Outlook version $version"
        }
    } else {
        return $version
    }
}

proc ::Outlook::HaveCalendar {appId calendarName} {

    # Check, if an Outlook calendar exists.
    #
    # appId        - Identifier of the Outlook instance.
    # calendarName - Name of the calendar to check.
    #
    # Returns true, if the calendar exists, otherwise false.
    #
    # See also: AddCalendar DeleteCalendar GetNumCalendars GetCalendarNames GetCalendarId

    if { [lsearch -exact [Outlook::GetCalendarNames $appId] $calendarName] >= 0 } {
        return true
    } else {
        return false
    }
}

proc ::Outlook::HaveCategory {appId categoryName} {

    # Check, if a category already exists.
    #
    # appId        - Identifier of the Outlook instance.
    # categoryName - Name of the category to check.
    #
    # Returns true, if the category exists, otherwise false.
    #
    # See also: HaveCategory GetCategoryNames GetCategoryId
    # AddCategory DeleteCategory GetCategoryColor

    if { [lsearch -exact [Outlook::GetCategoryNames $appId] $categoryName] >= 0 } {
        return true
    } else {
        return false
    }
}

proc ::Outlook::HaveContactFolder {appId contactFolderName} {

    # Check, if an Outlook contact folder exists.
    #
    # appId             - Identifier of the Outlook instance.
    # contactFolderName - Name of the contact folder to check.
    #
    # Returns true, if the contact folder exists, otherwise false.
    #
    # See also: AddContactFolder DeleteContactFolder GetNumContactFolders
    # GetContactFolderNames GetContactFolderId

    if { [lsearch -exact [Outlook::GetContactFolderNames $appId] $contactFolderName] >= 0 } {
        return true
    } else {
        return false
    }
}

proc ::Outlook::Open {{explorerType olFolderInbox}} {

            # Open an Outlook instance.
            #
            # explorerType - Value of enumeration type [Enum::OlDefaultFolders].
            #                Typical values are: `olFolderCalendar`, `olFolderInbox`, `olFolderTasks`.
            #
            # Returns the identifier of the Outlook application instance.
            #
            # See also: Quit

            variable outlookAppName
    	variable outlookVersion

            set appId [Cawt GetOrCreateApp $outlookAppName true]
            set outlookVersion [Outlook GetVersion $appId]

            set explorers [$appId Explorers]
            if { $explorerType ne "" && ! [Cawt IsComObject [$appId ActiveExplorer]] } {
                set nsObj [$appId GetNamespace "MAPI"]
                set myFolder [$nsObj GetDefaultFolder [Outlook GetEnum $explorerType]]
                set myExplorer [$explorers Add $myFolder $Outlook::olFolderDisplayNormal]
                $myExplorer Display
                Cawt Destroy $myExplorer
                Cawt Destroy $myFolder
                Cawt Destroy $nsObj
            }
            Cawt Destroy $explorers
            return $appId
}

proc ::Outlook::OpenNew {{explorerType olFolderInbox}} {

    # Obsolete: Replaced with [Open] in version 2.4.1

    return [Outlook::Open $explorerType]
}

proc ::Outlook::Quit {appId} {

    # Quit an Outlook instance.
    #
    # appId - Identifier of the Outlook instance.
    #
    # Returns no value.
    #
    # See also: Open

    $appId Quit
}

proc ::Outlook::ReadHolidayFile {fileName} {

    # Read an Outlook holiday file.
    #
    # fileName - Name of the Outlook holiday file.
    #
    # The data of the holiday file is returned as a dict with the following keys:
    # `SectionList` - The list of sections in the holiday file.
    #
    # For each section the following keys are set:
    #  `SubjectList_$section` - The list of subjects of this section.
    #  `DateList_$section`    - The list of dates of this section.
    #
    # Returns the data of the holiday file as a dictionary.
    # If the holiday file could not be read, an error is thrown.
    #
    # See also: AddHolidayAppointment ApplyHolidayFile

    set isUnicodeFile [Cawt IsUnicodeFile $fileName]

    set catchVal [catch {open $fileName r} fp]
    if { $catchVal != 0 } {
        error "ReadHolidayFile: Could not open file \"$fileName\" for reading."
    }

    if { $isUnicodeFile } {
        # If Unicode, skip the 2 BOM bytes and set appropriate encoding.
        set bom [read $fp 2]
        fconfigure $fp -encoding unicode
    }

    set holidayDict [dict create]
    dict set emptyDict   SectionList [list]
    dict set holidayDict SectionList [list]

    while { [gets $fp line] >= 0 } {
        if { [string length $line] == 0 } {
            continue
        }
        if { [string index $line 0] eq "\[" } {
            set endRange [string first "\]" $line]
            if { $endRange < 0 } {
                return $emptyDict
            }
            set sectionName [string range $line 1 [expr {$endRange - 1}]]
            dict lappend holidayDict SectionList $sectionName
        } else {
            set nameDateList [split $line ","]
            if { [llength $nameDateList] == 2 } {
                lassign $nameDateList name date
                set isoDate [string map { "/" "-" } $date]
                dict lappend holidayDict "SubjectList_$sectionName" $name
                dict lappend holidayDict "DateList_$sectionName"    $isoDate
            } else {
                return $emptyDict
            }
        }
    }
    close $fp
    return $holidayDict
}

proc ::Outlook::SendMail {mailId} {

    # Send an Outlook mail.
    #
    # mailId - Identifier of the Outlook mail object.
    #
    # Returns no value.
    #
    # See also: CreateMail CreateHtmlMail

    $mailId Send
}

proc ::Outlook::SetContactProperties {contactId args} {

    # Set property values of an Outlook contact.
    #
    # contactId - Identifier of the Outlook contact.
    # args      - Options described below.
    #
    # -category <string> - Assign category to contact.
    #                      If specified category does not yet exist, it is created.
    # -image <string>    - Add contact image.
    #                      Supported image formats:
    #                      `GIF` `JPEG` `BMP` `TIFF` `WMF` `EMF` `PNG`.
    # Key-value pairs    - Key is a read-write property name, value is the property value to be set.
    #
    # Set the properties of an Outlook contact.
    #
    # For details on contact properties see the official [Microsoft documentation]
    # (https://docs.microsoft.com/office/vba/api/outlook.contactitem).
    #
    # **Note 1:**
    # Most properties are of type `String`. Some are of type `Date`, `Boolean` or enumerations.
    #
    # See [GetContactReadOnlyPropertyNames] and [GetContactReadWritePropertyNames]
    # for a list of properties and their corresponding types.
    #
    # **Note 2:**
    # Converting dates into needed format can be accomplished with [::Cawt::SecondsToIsoDate]:
    #     [Cawt SecondsToIsoDate [clock seconds]]
    #
    # **Note 3:**
    # `Anniversary` and `Birthday` set an appointment in the default calendar.
    #
    # Returns no value.
    #
    # See also: AddContact AddContactFolder GetContactProperties GetNumContacts
    # GetContactReadWritePropertyNames GetContactReadOnlyPropertyNames

    foreach { key value } $args {
        if { $key eq "" } {
            error "SetContactProperties: No valid contact property specified: \"$key\""
        }
        switch -exact -nocase -- $key {
            "-image" {
                set key "AddPicture"
                set convertedValue [file nativename [file normalize $value]]
            }
            "-category" {
                set appId [$contactId Application]
                Outlook AddCategory $appId $value
                $contactId Categories $value
                Cawt Destroy $appId
                continue
            }
            "Anniversary" -
            "Birthday" -
            "TaskCompletedDate" -
            "TaskDueDate" -
            "TaskStartDate" -
            "ToDoTaskOrdinal" {
                set convertedValue [Cawt IsoDateToOfficeDate $value]
            }
            "Gender" {
                set convertedValue [Outlook GetEnum $value]
            }
            default {
                set convertedValue $value
            }
        }
        set catchVal [catch { $contactId $key $convertedValue } errMsg]
        if { $catchVal != 0 } {
            error "SetContactProperties: Could not set property \"$key\" to value \"$convertedValue\"."
        }
    }
    $contactId Save
}