Article
06/14/2014

Exchange Web Services Windows Vista Gadget

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Topic Last Modified: 2008-05-15

By Kim Brandl, Programming Writer

In addition to simplifying and improving Microsoft® Exchange Server 2007 application development, Exchange Web Services also allows for some very cool development scenarios. In this article, we'll explore the Exchange Web Services Windows Vista Gadget Sample Application and see firsthand how easy it is to harness the power of Exchange Web Services.

Overview of the Exchange Web Services Windows Vista Gadget Sample Application

The Exchange Web Services Windows Vista Gadget sample application uses Exchange Web Services to retrieve Inbox, Calendar, and Task information from a user's Exchange 2007 mailbox. It doesn't get much cooler than this — a Windows Vista Sidebar Gadget that brings Exchange mailbox data right to your desktop!

The gadget enables you to do the following:

View your latest e-mail messages, upcoming appointments, and tasks.
Page through your Inbox.
Open items in a fly-out window.
Open items in Outlook Web Access.
Mark messages as read or unread.
Delete messages.

Prerequisites

The following prerequisites are required before you can use the Exchange Web Services Windows Vista Gadget sample application:

Access to a computer that is running Exchange 2007 or Exchange 2007 Service Pack 1 (SP1) that has the Client Access and Mailbox server roles installed. The Exchange Web Services Windows Vista Gadget sample application will retrieve mailbox data from Exchange 2007 or Exchange 2007 SP1.

Note

The integration of the Windows Vista gadget with Office Outlook Web Access is only fully operational when the gadget is run against Exchange 2007 SP1. When it is run against Exchange 2007, items that are displayed by the gadget cannot be opened in their dedicated Outlook Web Access forms.

A mail-enabled account that is located in the mailbox database on the Mailbox server. This account will be used to demonstrate the Exchange Web Services Windows Vista Gadget sample application. For more information about how to create this account, see How to Create a New Mail-Enabled User.
Access to a computer that is running Windows Vista to install the Exchange Web Services Windows Vista Gadget sample application on.

Installing the Exchange Web Services Windows Vista Gadget Sample Application

Installing the Exchange Web Services Windows Vista Gadget sample application is quick and painless. Just download the sample from the Microsoft Download Center to a Windows Vista computer, and then double-click the ExchangeWebServices.gadget file. Because the ExchangeWebServices.gadget file is unsigned, you will see a Security Warning prompt that asks you to confirm installation. To install the gadget into the Windows Vista Sidebar, confirm installation by clicking Install.

A Look Inside

Now that you know what the Exchange Web Services Windows Vista Gadget sample application does, let's take a look at how it's built.

Directory Structure

When you install the Exchange Web Services Windows Vista Gadget sample application, the folder C:\Users\username\AppData\Local\Microsoft\Windows Sidebar\Gadgets\ExchangeWebServices.gadget\ is created. This folder contains all application folders and files.

The sample application directory structure consists of one top-level folder and three subfolders, as described in the following table.

Sample application directory structure

Folder	Description
ExchangeWebServices.gadget\	Contains the main gadget configuration file and the HTML files that define the presentation of the gadget.
ExchangeWebServices.gadget\help\	Contains the Help.html file (which contains information about gadget settings and functionality) and its supporting files.
ExchangeWebServices.gadget\images\	Contains the image files that are used by the sample application.
ExchangeWebServices.gadget\include\	Contains the files that define the functionality of the gadget.

Now that you are familiar with the directory structure of the application, let's take a closer look at the files that live inside each of these folders.

ExchangeWebServices.gadget\

The ExchangeWebServices.gadget folder contains the files that define the presentation of the gadget, as described in the following table.

ExchangeWebServices.gadget\ files

File	Description
gadget.xml	Specifies how the gadget is displayed in the Windows Vista gadget gallery (gadget icon, gadget properties) and which HTML file is used to display the gadget.
ExchangeWebServices.html	Displays the main gadget view, showing the Inbox, Calendar, or Task items that are retrieved from Exchange 2007.
Flyout.html	Displays the fly-out window of the gadget (shown when a user clicks an Inbox, Calendar, or Task item that is displayed in the gadget).
Settings.html	Displays the Settings page that is used to configure the gadget.

ExchangeWebServices.gadget\help

The help folder contains the very informative Help.html file, which provides information about gadget functionality and configuration settings. Reading through this file is a great way to become familiar with the gadget.

ExchangeWebServices.gadget\images

As you might expect, the images folder contains the images that are used in the rendering of the gadget.

ExchangeWebServices.gadget\include

The include folder contains by far the most interesting files in the sample application — the ones that use Exchange Web Services to retrieve mailbox data from Exchange 2007 and then to display that data in the gadget. Let's take inventory of the files in this folder.

Include folder files

File	Description
Autodiscover.js	Contains functions that call the Autodiscover service and read the response to an Autodiscover request.
ExchangeWebServices.css	The style sheet that is used for the presentation of the main gadget view and the fly-out window.
ExchangeWebServices.js	Provides key functions that are used throughout the application to interact with Exchange Web Services and update gadget contents. Contains functions to do the following: Manage gadget state (initialize, reset). Manage timer and update gadget contents at set intervals. Form the Exchange Web Services URL and Outlook Web Access URL. Execute an Exchange Web Services request. Get and set gadget connection property values. Switch gadget view between folders (Inbox, Calendar, Tasks). Open current folder in Outlook Web Access. Manage gadget size and appearance in a docked or undocked state. Manage visibility of the fly-out window. Refresh gadget contents when the Settings page is closed. Perform data conversion, mapping, and formatting.
Flyout.js	Provides the functionality in the fly-out window of the gadget. Contains functions to do the following: Retrieve the specified item from the Exchange server. Display the item in the fly-out window. Update the item to mark it as read or unread. Delete the specified item. Open the specified item in Outlook Web Access.
Settings.css	The style sheet that is used for the presentation of the gadget Settings page.
Settings.js	Provides all the functionality in the Settings page of the gadget. Contains functions to do the following: Open the Help.html file. Display current gadget settings when the Settings page is opened. Save gadget settings when the Settings page is closed.
Tiles.js	Works closely with ExchangeWebServices.js to provide functionality in the main gadget view. Contains functions to do the following: Form the FindItem request. Read the response to the FindItem request and update gadget contents accordingly. Determine the CSS styles that are used for display based on whether the gadget is docked or undocked. Move between item pages. Generate HTML to display items, paging controls, and calendar summary zone. Determine the unread mail count by using a GetFolder request.

Key Functions

Now that you have examined the sample application folder structure and are familiar with the files and what they do, let's conclude by taking a closer look at some key functions that retrieve messages, tasks, and calendar items from Exchange 2007 by using Exchange Web Services. The following table lists and describes each function.

Functions that retrieve and display mailbox data

Function	File	Description
refreshTiles	ExchangeWebServices.js	Regenerates the items that are shown in the main gadget view. Based on the type of items displayed, this function calls the appropriate "get" function (getMessages, getTasks, getCalendarItems) to retrieve information from the Exchange server.
getMessages	Tiles.js	Called by the refreshTiles function to retrieve messages from the Inbox folder. It calls formatFindItemRequest to generate the FindItem SOAP request, and calls executeEwsRequest to send the request to Exchange Web Services. Then it calls readMessages to process the response from Exchange Web Services and update gadget contents accordingly.
getTasks	Tiles.js	Called by the refreshTiles function to retrieve tasks from the Tasks folder. It calls formatFindItemRequest to generate the FindItem SOAP request, and calls executeEwsRequest to send the request to Exchange Web Services. Then it calls readTasks to process the response from Exchange Web Services and update gadget contents accordingly.
getCalendarItems	Tiles.js	Called by the refreshTiles function to retrieve upcoming appointments and meetings from the Calendar folder. It calls formatFindItemRequest to generate the FindItem SOAP request, and calls executeEwsRequest to send the request to Exchange Web Services. Then it calls readCalendarItems to process the response from Exchange Web Services and update gadget contents accordingly.
formatFindItemRequest	Tiles.js	Called by each "get" function (getMessages, getTasks, getCalendarItems) to generate the FindItem SOAP request.
executeEwsRequest	ExchangeWebServices.js	Called by each "get" function (getMessages, getTasks, getCalendarItems) to execute the Exchange Web Services request.
readMessages	Tiles.js	Called asynchronously after the response to the FindItem request (sent by the getMessages function) is received from the server.
readTasks	Tiles.js	Called asynchronously after the response to the FindItem request (sent by the getTasks function) is received from the server.
readCalendarItems	Tiles.js	Called asynchronously after the response to the FindItem request (sent by the getCalendarItems function) is received from the server.
readItems	Tiles.js	Called by both readMessages and readTasks to process the FindItem response that is received from Exchange Web Services. It reads the response and uses the renderItems and renderPagingControls functions to update gadget contents.

Supportability

We strongly recommend that you perform thorough code and security reviews and testing before you deploy applications that are based on this sample in any production environment.

Additional Resources

For more information about how to create Windows Vista gadgets and about Exchange Web Services, see the following resources: