Hi, all. Today we’re happy to share some excerpts from the recently published Programming for Unified Communications with Microsoft Office Communications Server 2007 R2 (Microsoft Press, 2009; ISBN: 9780735626232; 416 pages), which comes directly from the Microsoft Office Communications Server product team. This post includes the book’s About the Authors, Contents at a Glance, Introduction, as well as a stretch of text from Chapter 2, “Microsoft Unified Communications APIs Foundation.” I’ll keep this intro text short because much follows.

About the Authors

Rui Maximo is a senior technical writer in the Office Communications Group. He has worked
on different aspects of the Microsoft Office Communications Server product suite (management,
migration, topology, VoIP, Communicator Web Access) and shipped Microsoft Live
Communications Server 2003, Live Communications Server 2005 (the original version and
the SP1), and Office Communications Server 2007 as a lead program manager and program
manager. With 13 years of experience at Microsoft, Rui has been fortunate to work in diverse
roles (program management, software engineering, and technical writer) and various products
(including Microsoft Windows, Windows Mobile, and Microsoft Office), primarily focusing
on security. Prior to Microsoft, Rui worked at IBM as a software tester and at Brigham Young
University as a UNIX administrator. Rui holds a master’s degree in mathematics, specializing
in abstract algebra and cryptography. You can reach him at ruim@ruimaximo.com. Please
send your comments!

Kurt De Ding is a senior programming writer in the Office Communications Group.
As the pioneering member of the SDK documentation team, he was instrumental in
the initial design, authoring, and delivery of the SDK documentation for the Microsoft
Unified Communications APIs, including Microsoft Office Communicator Automation API,
Unified Communications Client API, Unified Communications Managed API v 1.0, and Unified
Communications AJAX API, as well as Live Meeting Service API. Before joining the Office
Communications Group, Kurt had worked on various Microsoft technologies, including
Windows CE SDK, Windows Platform SDK, and Microsoft SQL Server SDK.

Vishwa Ranjan is a program manager in the Unified Communications Group. Most recently,
Vishwa has worked on the Unified Communications Platform API Workflow Activities, which
is available as part of Office Communications Server 2007 R2. Previously, he worked on
Microsoft Speech Server 2004 and Office Communications Server 2007 Speech Server. He
has more than 7 years of experience as a software design engineer in test, a technical lead,
and a program manager.

Chris Mayo is a technical evangelist in the Developer and Platform Evangelism group.
Chris focuses on the Unified Communications products (Office Communications Server
2007 R2, Office Communicator 2007 R2, and Microsoft Exchange Server 2007) and platform
software development kits (SDKs), working with the Office Communications Group
since the early betas of Office Communications Server 2007. Chris has been with Microsoft
for 8 years as an evangelist working with the developer and independent software vendor
communities. Chris has experience as both a writer for developer publications and a public
speaker at professional events, such as the Professional Developers Conference and TechEd.
Prior to joining Microsoft, Chris served as a developer and architect in the IT departments of
Fortune 500 companies in the retail and finance industries. Keep up with Chris at his Unified
Communications Development blog at http://blogs.msdn.com/cmayo/.

Oscar Newkerk is a Unified Communications Architect at Unify Square Inc. working in the
area of Unified Communications, with an emphasis on integrating and enhancing business
processes with collaboration technologies. With 14 years of experience at Microsoft, Oscar
worked in various roles and groups within the company. Most recently, he was a technical
evangelist in the Unified Communications Group, helping the developer community to plan,
design, develop, and deploy solutions that integrate with Office Communications Server.
Prior to Microsoft, Oscar worked for Digital Equipment Corporation as a software specialist
and in software engineering in the areas of systems and network management. Oscar holds a
bachelor of science degree in physics from Guilford College and holds patents in the areas of
systems management and speech recognition.

Albert Kooiman is a member of the Unified Communications Marketing team and has
been responsible for product management of the Unified Communications Developer
Platform since the group was created in 2006. He works on both Exchange Server and Office
Communications Server. With 14 years of experience in the telecommunications and speech
technology industry, Albert has been involved in a wide range of projects encompassing the
broad spectrum of Unified Communications solutions currently in the market. Albert holds
a master’s degree of the Medical Faculty of the University of Amsterdam, specializing in
medical informatics.

Mark Parker is a programming writer in the Office Communications Group. Most
recently, Mark was responsible for the Unified Communications Managed API 2.0 Core
SDK documentation and part of the Unified Communications Managed API 1.0 SDK
documentation. Before joining the Office Communications Group, Mark worked as a writer
on the Speech Server 2007 documentation team and was a lead programming writer on the
Windows Device Driver Kit documentation team. Prior to Microsoft, Mark taught mathematics
and a number of programming languages at Shoreline Community College. Mark holds a
master of science degree in mathematics.

Introduction

Why We Wrote This Book

Microsoft Office Communications Server is a relatively new product. Although it has its origins
in the Enterprise Instant Messaging products, such as Exchange Instant Messaging,
Live Communications Server 2003, and Live Communications Server 2005, it has evolved to
become a comprehensive platform for all real-time communications. The current release,
Office Communications Server 2007 R2, not only supports enterprise instant messaging (IM)
and rich presence, but also offers a powerful Voice over Internet Protocol (VOIP)–based telephony
system, multiparty audio conferencing, Web conferencing, and application sharing.

This server offers tangible benefits in direct cost savings (for example, by eliminating
costly audio conferencing services provided by telecom carriers) and improves productivity
by providing more efficient ways for people to contact each other. Office Communications
Server is one of the fastest-growing server products in Microsoft history, with tens of millions
of licenses sold.

Office Communications Server is a software-based solution that runs on standard computing
and networking hardware. This server offers a rich, open API platform, making it an open
and extensible part of the Microsoft Unified Communications (UC) platform. There are
many opportunities for developers to build new applications on this platform. We know
that developers are looking for resources to help them develop applications using the UC
APIs, and this book is the only one on the market today that addresses this need. Written by
experts from the product group, Programming for Unified Communications with Microsoft
Office Communications Server 2007 R2 offers an easy-to-read exploration of the APIs. We
hope it serves you well.

What This Book Is About

This book is organized into five parts.

Part I, “Understanding Unified Communications,” introduces the UC platform and provides
an overview of the APIs.

Part II, “Office Communicator Automation API,” explains the Office Communicator
Automation API in depth and provides a detailed walkthrough of an example.

Part III, “Unified Communications Managed API Workflow,” explains the UCMA Workflow API
in detail and walks through an example of a business process communication.

Part IV, “Unified Communications Managed API,” covers the Unified Communications
Managed API architecture and shows how to extend the Office Communications Server
Enhanced Presence model by using this API.

Part V, “Debugging, Tuning, and Deploying Unified Communications Applications,” explains
how to debug, tune, and deploy UC applications.

Who This Book Is For

This book is intended for developers who want to create enterprise applications that include
communications functionality built on the UC platform. Familiarity and experience with
Microsoft Windows COM, Microsoft .NET Framework, and Windows Workflow Foundation
development is recommended. This book is written on the assumption that the reader has
this knowledge. Code examples in this book are written in C# unless otherwise noted. For
clarity and to better illustrate how to use the APIs, the code samples are not written with
defensive coding practices in mind. Please apply defensive code practices when reusing the
samples in your own production applications.

For an in-depth resource on the internals of Office Communications Server 2007 R2, see the
Microsoft Office Communications Server 2007 R2 Resource Kit (Microsoft Press, 2009), which
you can purchase in a bookstore or order from http://www.microsoft.com/learning/en/us/
Books/13113.aspx. That book also covers the Office Communications Server Software
Development Kit (SDK), which is intended for administering and controlling compliance
of the conversations (for example, ethical walls and custom disclaimers) with Office
Communications Server, and therefore is outside the scope of this book.

We sincerely hope that you find the technical information within this book useful and
lucrative to your work.

Companion Content

This book features a companion Web site that makes available to you all of the code used in
the book. This code is organized by chapter, and you can download it from the companion
site at http://code.msdn.microsoft.com/programmingocs.

Hardware and Software Requirements

You need the following hardware and software to work with the companion content that is
included with this book:

Servers

Hardware  Use only a 64-bit computer that is running a 64-bit edition of Windows Server
(see more about the operating system below). Other technical specifications include the
following:

• CPU Dual-core 2.0-gigahertz (GHz) 4-way processor
• RAM 2 gigabytes (GB) of memory
• Hard drive 100-GB hard drive
• Network adapter 100 megabit-per-second (Mbps) network adapter

Operating System  Use only the 64-bit edition of Windows Server 2003 SP2, Windows
Server 2003 R2 SP2, or Windows Server 2008. Supported editions include Standard,
Enterprise, and Data Center versions of Windows Server 2003 and Windows Server 2008.

Client Computers

Hardware  Use any 32-bit or 64-bit computer that is running Windows Vista SP1. Other
technical specifications include the following:

• CPU A minimum 1.6-GHz Pentium III+ processor
• RAM 1 GB of memory
• Hard drive 50-GB hard drive
• Network adapter 100-Mbps network adapter
• Video A video monitor with 800 × 600 or higher resolution and at least 256 colors
• A CD-ROM or DVD-ROM drive
• A Microsoft mouse or compatible pointing device

Operating System  The 32-bit or 64-bit edition of Windows Vista SP1 or later. Windows
Vista Home Premium Edition, Windows Vista Business Edition, or Windows Vista
Ultimate Edition.

Database Requirements

Use the 32-bit version of Microsoft SQL Server 2005 Express Edition SP2, which is included
with Office Communications Server 2007 R2.

Office Communications Server 2007 R2

Deploy Office Communications Server 2007 R2 Standard Edition on a private network.

More Info  For more information about deployment for the UC test environment, see the
“Deploying Office Communications Server Standard Edition” section in Chapter 9, “Preparing the
UC Development Environment.”

Administrative Tools

Install the Office Communications Server Administrative Tools. The administrative tools can
be installed independent of the Office Communications Server deployment on a computer
that is running the 32-bit or 64-bit edition of Windows Server 2003 SP2, Windows Server
2003 R2 SP2, Windows Server 2008, Windows Vista Business, or Windows Vista Enterprise
with SP1.

Development Tools

The software development environment and tools required to build UC applications include
the following:

• Microsoft Visual Studio 2008 SP1
• Microsoft .NET Framework 3.5 SP1
• Microsoft Visual C++ 2008 Redistributable Package
• Office Communicator Automation API SDK
• Unified Communications Managed API (UCMA) Core 2.0 SDK

Visual Studio 2008 SP1–supported software includes Visual Studio 2008 Standard Edition,
Visual Studio 2008 Enterprise Edition, Visual C# 2008 Express Edition, and Microsoft Visual
Web Developer 2008 Express Edition.

More Info  For more information about configuring the UC software development environment,
see the “Configuring Application Development Components” section in Chapter 9.

Sample Test Topology

To build and test the samples included in this book, a typical test topology includes the
following clients and servers:

• A Windows Server 2008 domain controller, including the Domain Name System (DNS)
  and Certificate Authority (CA) roles
• Office Communications Server 2007 R2 Standard Edition deployment
• A Windows Server 2008 member server serving as the application server to run the
  sample applications
• Two Windows Vista clients running Office Communicator

Chapter 2
Microsoft Unified Communications APIs Foundation

This chapter will help you to:

• Understand the scenarios that you can build using the API.
• Understand the considerations to help you determine whether this API meets your
  requirements.
• Understand the API’s architecture.
• Understand the API’s design model.

This chapter provides a technical overview of the Microsoft Unified Communications (UC)
APIs so that you can understand them, how they relate to each other, and what purpose
they serve.

The intent of this chapter is to provide you with sufficient information to help you decide
which UC APIs best fulfill your needs. If you already know which APIs meet your needs, you
can look only at the sections that cover the APIs of interest to you, or skip this chapter altogether
if you wish.

Unified Communications Managed API 2.0

The Unified Communications Managed API (UCMA) is a code platform managed by
Microsoft .NET Framework, which provides access to presence, instant messaging (IM),
telephony, and audio/video (A/V). UCMA is a Session Initiation Protocol (SIP)–based platform.
SIP is a signaling protocol that is used for setting up and tearing down multimedia
communication sessions. This API abstracts the details of the communication protocols
used by Microsoft Office Communications Server.

Scenarios

UCMA is used to build scalable middle-tier applications that work with Office
Communications Server 2007 R2, provide large-scale message throughput, and represent
multiple endpoints. You can use this API to build the following types of applications:

• Highly scalable notification and alert systems that perform the following actions:
  o Send outbound alert messages.
  o Use the Enhanced Presence feature of the Office Communications Server 2007 R2
  platform to determine the appropriate channel and media to deliver alerts, such
  as instant messages, e-mail, or voice calls.
• Interactive automated agents (query/response bots) that perform the following actions:
  o Respond to user requests for information by means of IM or voice sessions.
  o Create custom call routing and interactive voice response systems.

More advanced applications include the following:

• Contact center or help desk applications that do the following:
  o Route incoming communications sessions to available agents.
  o Use the Enhanced Presence capabilities of the Office Communications Server
  2007 R2 platform to route to agents based on specific skill sets.
  o Provide “music on hold” functionality for voice sessions.
  o Create back-to-back user agents (B2BUAs) for help desk scenarios; for example,
  so that the specific identity of the help desk agent is not exposed to the
  customer.
• Conferencing portal applications that do the following:
  o Create custom conference bridging.
  o Record the contents of conference calls.
  o Schedule and manage instances of conferences.
  

Considerations

UCMA 2.0 is considered a middle-tier API written completely in C#. Therefore, it runs
only in environments where the .NET Framework is supported. It provides the following
characteristics:

• Scalability  UCMA 2.0 is able to support thousands of endpoints and concurrent
  communications and collaboration sessions. It is designed for building server applications
  (the recommended operating system is Microsoft Windows Server 2008
  on 64-bit hardware). UCMA 2.0 is multithreaded, and operations are performed asynchronously
  to maximize throughput.
• Availability  The deployment model supports running multiple instances of the
  UCMA 2.0 application for load balancing and failover across multiple computers with
  the use of hardware load balancers.
• Extensibility  New modalities can be added in the conversation framework. Extension
  headers and Uniform Resource Identifier (URI) parameters can be supplied and
  consumed through the APIs to support the creation of custom sessions.

UCMA 2.0 supports two types of SIP endpoints that are designed for distinct application
scenarios: the ApplicationEndpoint class and the UserEndpoint class. You use the
ApplicationEndpoint class in applications that represent automated applications, such as
bots that interact with users. You use the UserEndpoint class in applications that connect
to Office Communications Server on behalf of users and perform operations on behalf of
those users.

To configure Office Communications Server to trust connections from UCMA applications
that use the ApplicationEndpoint and UserEndpoint classes, the application provisioning
process must define a Globally Routable User Agent URI (GRUU). For more information
about GRUUs, see Chapter 9, “Preparing the UC Development Environment.” This is all that
is necessary if the application creates only UserEndpoints. After the application has authenticated
the user, it does not need to supply those credentials to Office Communications Server
for authentication. For applications that create ApplicationEndpoints, the provisioning process
also must create a Contact object that defines the application’s SIP URI. You also have the
option to create a display name and a TEL URI. The ApplicationEndpoint uses this Contact
object to register with Office Communications Server.

Examples of applications that use the ApplicationEndpoint class are Automatic Call
Distributor (ACD), interactive IM or voice bots, and conference bridges. For more information
about these applications, see the “UCMA 2.0 Workflow API” section later in this chapter.
These applications use a Contact object to identify the application in Active Directory
Domain Services. The Contact object specifies the application’s SIP URI and phone number.
Examples of applications that use the UserEndpoint class are those that publish additional
presence information. Examples of additional presence information include showing a Global
Positioning System (GPS) location on behalf of a user or acting as a proxy when the user is
not available and routing incoming IM messages through a Short Message Service (SMS)
gateway.

API Architecture

UCMA is composed of the following two interfaces:

• UCMA 2.0 Core API
• UCMA 2.0 Speech API

This architecture can be represented as shown in Figure 2-1.