Introduction to Microsoft Open Specifications
Summary: To many developers, the Microsoft Open Specifications may be a little-known offering among the set of Microsoft resources. However, they provide software developers with important information that enables them to integrate their products with Microsoft operating systems and applications.
Microsoft is helping developers open up new opportunities by making technical specifications for its products available to view and download from Microsoft MSDN at no charge (rights under Microsoft patents covering such specifications are available separately).
Published: December 2010
What Are Open Specifications?
Microsoft publishes the technical specifications to help software developers build products that interoperate with many of its products. In particular, the Open Specifications provide you with the information that you need to build applications that communicate with Windows client and server operating systems and certain Microsoft products. For example, they enable your programs to read, edit, and save files that Microsoft Office applications produce.
These technical specifications include:
It’s important to note that the applications you create do not have to run on a Microsoft operating system. Also, you do not have to use Microsoft tools to write or build your programs. If your organization creates programs that interoperate with Microsoft software, it is entirely possible that your customers do not need to install any Microsoft products to use your software.
Microsoft revises the technical specifications regularly and, particularly, in connection with the release of significant product updates and new versions.
These specifications may be accessed without charge and without restriction on this MSDN Library. Many of the technical specifications, however, include patented inventions. Some of those patents are available at no charge under the Open Specifications Promise. The remaining patents are available through various licensing programs. To learn more, please visit http://www.microsoft.com/openspecifications.
If you have questions about the documentation, please visit the Open Specifications Forums on MSDN.
What Can I Do with Open Specifications?
The information in the technical specifications can help you write applications that communicate with Windows operating systems and Microsoft applications. It can also help you create programs that search, analyze, or otherwise process information produced by specific Microsoft applications.
For example, one Microsoft Office protocol specification, [MS-DOC], provides a detailed description of the .doc file format used by certain versions of Microsoft Word. By using this information, you could write a program that searches for specific text in the headers of all documents in a large repository. If the search text is found, your program can then retrieve all bitmap images in those headers.
Such a program would be a useful tool for a law firm involved in a dispute over the ownership of a company logo. The law firm could use this tool rapidly to collect all of the logo bitmaps used by the litigants as evidence from a collection of millions of disclosure documents.
As another example, suppose you need to write a program for the Linux operating system that interoperates with the Exchange Unified Messaging system. One specification to reference is [MS-EUMSDP], which describes the extension to the Session Description Protocol (SDP) characteristics that are proprietary to Microsoft Exchange. This extension is necessary for programs that play or record voice messages from a phone and send them to an email account.
A Quick Tour of the Open Specifications
The library of Open Specifications documents covers methods of communications and data interchange used by Microsoft software. These documents are grouped into a few broad categories, each with a very specific focus.
Types of Specifications
In general, there are seven types of protocol documents.
What’s in a Microsoft Open Specifications Document?
Microsoft Open Specifications documents are divided into particular sections, some of which are common across multiple types of specifications, and some of which are particular only to one type of specification.
With the exception of implementer notes, all types of technical specifications contain an introduction. The introduction generally begins with a glossary of important terms used in the specification. The glossary is significant because the definition of a term can make a substantial difference in the implementation of software based on the specification.
There are three types of glossaries within protocol documents:
Next, the introduction provides two kinds of references: normative and informative. Normative references are documents, or sections of documents, that must be read to understand the Microsoft technical specification. The same is not true of informative references. Reading informative references can be helpful for understanding the specification, but is not essential.
Some protocol specifications describe the network interaction between the components of Microsoft software, or between Microsoft software components and other programs. These protocol specifications contain a section titled Messages. It is always section 2 of the document, immediately following the introduction.
The Messages section appears in protocol documents that provide packet-based protocols specifications, SOAP specifications, RPC specifications, and stored procedure specifications. It provides information about the syntax of the protocol, how messages are transported, and the syntax of those messages. If you want your application to exchange messages across a network with a Microsoft application or application component, this is important information for you.
Structures and Structure Examples
Technical specifications dealing with the layout of binary files produced and used by Microsoft products do not have a Messages section. Instead, Section 2 of these types of specifications is called Structures. It delineates all the enumerations used in the specification, provides details about the structure of every type of record that occurs in the file, and presents information about data streams contained within the file.
For example, the specification for the Microsoft Word .doc file format, [MS-DOC], contains a Structures section. The Structures section has an exact description of the format of the .doc file. This description covers everything in the file, including information about the various parts of a Word document such as the headers and footers, comments, and endnotes, and so forth. In addition, all the file’s data types are precisely described, as are the document’s properties.
Following the Structures section of BFF specifications is Structure Examples, which always appears as Section 3 of the document. It provides examples of data that can appear in the structures described in Section 2. These examples typically take the form of hexadecimal file dumps.
Protocol specifications for component interactions have a topic called Functional Architecture as Section 2 of the document. It begins with an overview of the high-level architectural elements that work together to achieve interoperability. This is then followed by a summary of the protocol, explanations of system dependencies and requirements, use cases, and information about versioning, error handling, and security requirements.
In general, the topics in the Functional Architecture section provide a conceptual description of the architecture of the system. This description includes the protocols, structures, and formats that the system uses to communicate both within the system itself and with external systems. Note that these topics don’t repeat any details provided in other specifications; instead, they provide references to those protocols, structures, and formats in their appropriate specifications.
Protocol Details and Protocol Examples
For protocol specifications that provide packet-based protocols specifications, SOAP specifications, RPC specifications, and stored procedure specifications, Section 3 is called Protocol Details. Among other things, the Protocol Details section describes the protocol’s abstract data model, provides timer and initialization information, and describes events related to the protocol.
Next, as Section 4, is the Protocol Examples topic. It briefly walks you through one or more protocol operations to illustrate the function of the protocol.
Section 5 of most types of protocol specifications describes security considerations not discussed elsewhere in the specification. It also provides an index of sections that present security parameters for the protocol.
Product-Specific Implementations and Behavior
Section 6 of many types of protocol specifications discusses how Microsoft products implement the standard that the specification describes. It is your discretion whether you use the same implementation of the protocol.
For example, the standard may present error codes that Microsoft products treat as serious. However, these error codes may not be significant at all for your application. If you determine that you can safely ignore certain error codes, you need not implement responses to them in your software to be compliant with the standard.
IDLs for Remote Procedure Calls
For protocols based on RPC, Section 6 is a detailed presentation of the IDLs that the protocols use. Any IDL samples presented in sections 2 or 3 are taken directly from the full and complete preprocessed IDL in Section 6. This section presents the IDLs in the form of complete copies of WSDL files. Because WSDL files are an industry standard, anyone familiar with WSDLs should be able to read the IDLs in Microsoft Open Specifications documents.
The final sections of Microsoft Open Specifications documents contain a document change-tracking table, provide an index, and so forth.
Now that you have an overview of what Microsoft Open Specifications documents are and what they contain, your next step is to dive into the documents themselves and increase your familiarity with the content so you can implement the protocols as appropriate. You’ll find them in the Open Specifications section in the MSDN library.