I have created a Tcl package for access to Microsoft Exchange Outlook Web Access servers. The package is dependent on Jean-Claude Wippler's webdav package and on TclXML. Thanks are due to Jean-Claude both for his package and for his help.
The owa package is available as a tcl file or as part of the owaSync starkit. This package is now mainly used to support my OWA Synchronisation application. The IMAP to OWA proxy is now obsolete and no longer maintained as the Mail folder synchronisation code in owaSync provides a much more robust solution.
Copyright (C) 2005, 2006 Graham R. Cobb
OWA For TCL is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
OWA For TCL is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
There are two parts of the owa package:
This is just a wrapper for the ::webdav::connect routine. One day it may be enhanced to return an OWA-specific object but for now it just returns a webdav object. Typical usage:
::owa::connect http://owa.server.org/exchange/user/ -username userid -password mypassword
Note: if you need to use https: you will need to enable TLS before calling ::owa::connect
as follows:
package require tls
http::register https 443 ::tls::socket
This fetches the text of an OWA object (mail message, notes, etc.).
dav is a webdav connection name (returned by ::webdav::open)
or a webdav connection object (returned by ::webdav::connect or ::owa::connect).
path is the specification of an OWA object, relative to the root specified when
the connection was created. For example Inbox/Test%20Message.EML.
This fetches the body of an OWA object (mail message, etc.) without mail headers. The effects are undefined if the object is not a mail message!
dav is a webdav connection name (returned by ::webdav::open)
or a webdav connection object (returned by ::webdav::connect or ::owa::connect).
path is the specification of an OWA object, relative to the root specified when
the connection was created. For example Inbox/Test%20Message.EML.
This fetches the OWA object properties in XML (using a Webdav PROPFIND operation). It is up to the caller to parse the XML. Note that the properties do not necessarily include the actual object contents (for example text of Notes is not returned).
dav is a webdav connection name (returned by ::webdav::open)
or a webdav connection object (returned by ::webdav::connect or ::owa::connect).
path is the specification of an OWA object, relative to the root specified when
the connection was created. For example Inbox/Test%20Message.EML.
This returns a list of the names of the objects contained within the directory.
Note: it is possible to use ::webdav::search directly to perform more complicated lookups, but this requires creating an XML query and analysing the XML response, and is slower.
dav is a webdav connection name (returned by ::webdav::open)
or a webdav connection object (returned by ::webdav::connect or ::owa::connect).
path is the specification of an OWA folder, relative to the root specified when
the connection was created. For example Inbox.
All these routines reside within the ::owa::sync namespace.
OWA replication involves working with the concept of an "OWAsync collection".
A collection is an OWA folder, possibly with an SQL WHERE clause restricting the
objects which form the collection. Neither the folder name nor the WHERE clause can be
changed during the life of the collection.
OWA tracks the state of the collection and returns, on request, the list of changes that have been made to the collection.
Note: the current version of the owa package handles receiving collection updates from OWA but does not handle making updates to OWA. Thus it can be used to keep another copy in sync with the OWA version but does not handle propagating updates to the OWA version.
Users are advised to check out the Microsoft Exchange SDK, particularly the Webdav Replication section, for more information.
This creates a new OWAsync collection object.
dav is a webdav connection name (returned by ::webdav::open)
or a webdav connection object (returned by ::webdav::connect or ::owa::connect).
Note that the same webdav connection can be used for many different OWAsync collections.
path is the path, from the root of the webdav connection, to the folder to be watched.
For example Notes.
where is the value to be used in an SQL WHERE clause in the SELECT
statement in a webdav SEARCH.
If this is left out, all the elements in the folder are selected.
Note: quoting rules for this parameter can be quite complicated and it should always be specified in braces.
An example of this parameter is {"http://schemas.microsoft.com/exchange/outlookmessageclass" = 'IPM.StickyNote'}
collblob is for internal use by the ::owa::sync::recreate procedure and should not be
specified when calling ::owa::sync::create.
Note that the create call does not actually contact the server to validate the parameters. If there is an error, it will not be noticed until the manifest procedure is called.
Note that this can also be called as ::owa::sync::kill coll.
This deletes the specified OWAsync collection object.
coll is the OWAsync object
Note that this can also be called as ::owa::sync::reset coll.
This resets the collection to forget the previous state. The next call to manifest will return all the current members of the collection but no information on updates.
coll is the OWAsync object
Note that this can also be called as ::owa::sync::serial coll.
This serialises the internal state of the OWAsync object so that it may, for example,
be stored in a file and restored at a later date.
The returned value is a list of even length consisting of pairs in the form of a keyword and a value
(similar to the format returned by array get).
The list should not be modified, except that additional keyword and value pairs can be added if the caller wishes (for example if they want to store additional information of their own). Unrecognised keywords will be ignored when restoring.
Note the data does not include any information about the webdav connection. The caller is responsible for re-establishing a webdav collection before restoring the state.
coll is the OWAsync object
This restores the internal state of a OWAsync object from the data returned from a previous serial command.
This is useful if state needs to be stored in a file and restored at a later date.
The return value is a new OWAsync collection object.
dav is an existing webdav connection name (returned by ::webdav::open)
or webdav connection object (returned by ::webdav::connect or ::owa::connect).
Note that the same webdav connection can be used for many different OWAsync collections.
data is the return value of a previous serial comamand.
This is a list of even length consisting of pairs in the form of a keyword and a value
(similar to the format returned by array get).
The list should not have been modified, except that additional keyword and value pairs can be added
if the caller wishes (for example if they want to store additional information of their own).
Unrecognised keywords will be ignored.
Note that this can also be called as ::owa::sync::manifest coll.
This procedure returns all the changes to the collection since the last call to manifest.
coll is the OWAsync object
The return value is a list of five element lists.
Each quintuplet represents a changed element in the collection.
The quintuplets are {path resourceid change repl-uid displayname} where:
path is the path to the element from the root of the webdav connection.
This can be provided to ::owa::fetch to retrieve the content of the element.
resourceid is the OWA resource id of the element.
See the description in the
Microsft Exchange SDK for usage of the resource id.
change indicates the type of change and is "new", "change" or "delete"
repl-uid should be used to determine which element this replaces.
Note that the other attributes of an element can change and should not be used to uniquely identify the element.
displayname is the webdav display name of the element, which can be useful for displaying to users.
However note that this will end in ".EML".
The path and displayname will be empty if the change is "delete".
Initial release.
Changes to support IMAP2OWA.
Add fetch-no-headers.
Changes to support owaSync.
Add fetch-xml.
Change keywords used when saving and restoring collection state. Previous keywords will be supported for one release.
Handle folder names with spaces
Reset parser after use (issue for Windows support)
See the owaSync package as an example of using this.
Please contact me by email on owa-tcl AT cobb.uk.net.
If you use this, please let me know of your experience. In return I will let you know of any updates.
