[MS-CMP]:
MSDTC Connection Manager: OleTx Multiplexing Protocol
Intellectual Property Rights Notice for Open Specifications Documentation
Technical Documentation. Microsoft publishes Open Specifications documentation (“this documentation”) for protocols, file formats, data portability, computer languages, and standards support. Additionally, overview documents cover inter-protocol relationships and interactions.
Copyrights. This documentation is covered by Microsoft copyrights. Regardless of any other terms that are contained in the terms of use for the Microsoft website that hosts this documentation, you can make copies of it in order to develop implementations of the technologies that are described in this documentation and can distribute portions of it in your implementations that use these technologies or in your documentation as necessary to properly document the implementation. You can also distribute in your implementation, with or without modification, any schemas, IDLs, or code samples that are included in the documentation. This permission also applies to any documents that are referenced in the Open Specifications documentation.
No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation.
Patents. Microsoft has patents that might cover your implementations of the technologies described in the Open Specifications documentation. Neither this notice nor Microsoft's delivery of this documentation grants any licenses under those patents or any other Microsoft patents. However, a given Open Specifications document might be covered by the Microsoft Open Specifications Promise or the Microsoft Community Promise. If you would prefer a written license, or if the technologies described in this documentation are not covered by the Open Specifications Promise or Community Promise, as applicable, patent licenses are available by contacting .
License Programs. To see all of the protocols in scope under a specific license program and the associated patents, visit the Patent Map.
Trademarks. The names of companies and products contained in this documentation might be covered by trademarks or similar intellectual property rights. This notice does not grant any licenses under those rights. For a list of Microsoft trademarks, visit
Fictitious Names. The example companies, organizations, products, domain names, email addresses, logos, people, places, and events that are depicted in this documentation are fictitious. No association with any real company, organization, product, domain name, email address, logo, person, place, or event is intended or should be inferred.
Reservation of Rights. All other rights are reserved, and this notice does not grant any rights other than as specifically described above, whether by implication, estoppel, or otherwise.
Tools. The Open Specifications documentation does not require the use of Microsoft programming tools or programming environments in order for you to develop an implementation. If you have access to Microsoft programming tools and environments, you are free to take advantage of them. Certain Open Specifications documents are intended for use in conjunction with publicly available standards specifications and network programming art and, as such, assume that the reader either is familiar with the aforementioned material or has immediate access to it.
Support. For questions and support, please contact .
Revision Summary
Date / Revision History / Revision Class / Comments4/3/2007 / 1.0 / New / Version 1.0 release
7/3/2007 / 2.0 / Major / MLonghorn+90
7/20/2007 / 3.0 / Major / Updated and revised the technical content.
8/10/2007 / 3.0.1 / Editorial / Changed language and formatting in the technical content.
9/28/2007 / 4.0 / Major / Made a change to the IDL.
10/23/2007 / 5.0 / Major / Updated and revised the technical content.
11/30/2007 / 5.0.1 / Editorial / Changed language and formatting in the technical content.
1/25/2008 / 5.0.2 / Editorial / Changed language and formatting in the technical content.
3/14/2008 / 5.1 / Minor / Clarified the meaning of the technical content.
5/16/2008 / 5.1.1 / Editorial / Changed language and formatting in the technical content.
6/20/2008 / 6.0 / Major / Updated and revised the technical content.
7/25/2008 / 6.1 / Minor / Clarified the meaning of the technical content.
8/29/2008 / 7.0 / Major / Updated and revised the technical content.
10/24/2008 / 7.0.1 / Editorial / Changed language and formatting in the technical content.
12/5/2008 / 7.0.2 / Editorial / Editorial Update.
1/16/2009 / 8.0 / Major / Updated and revised the technical content.
2/27/2009 / 9.0 / Major / Updated and revised the technical content.
4/10/2009 / 10.0 / Major / Updated and revised the technical content.
5/22/2009 / 10.1 / Minor / Clarified the meaning of the technical content.
7/2/2009 / 10.1.1 / Editorial / Changed language and formatting in the technical content.
8/14/2009 / 10.1.2 / Editorial / Changed language and formatting in the technical content.
9/25/2009 / 11.0 / Major / Updated and revised the technical content.
11/6/2009 / 12.0 / Major / Updated and revised the technical content.
12/18/2009 / 13.0 / Major / Updated and revised the technical content.
1/29/2010 / 13.1 / Minor / Clarified the meaning of the technical content.
3/12/2010 / 14.0 / Major / Updated and revised the technical content.
4/23/2010 / 14.0.1 / Editorial / Changed language and formatting in the technical content.
6/4/2010 / 15.0 / Major / Updated and revised the technical content.
7/16/2010 / 15.0 / None / No changes to the meaning, language, or formatting of the technical content.
8/27/2010 / 15.0 / None / No changes to the meaning, language, or formatting of the technical content.
10/8/2010 / 15.0 / None / No changes to the meaning, language, or formatting of the technical content.
11/19/2010 / 15.0 / None / No changes to the meaning, language, or formatting of the technical content.
1/7/2011 / 16.0 / Major / Updated and revised the technical content.
2/11/2011 / 17.0 / Major / Updated and revised the technical content.
3/25/2011 / 18.0 / Major / Updated and revised the technical content.
5/6/2011 / 18.0 / None / No changes to the meaning, language, or formatting of the technical content.
6/17/2011 / 18.1 / Minor / Clarified the meaning of the technical content.
9/23/2011 / 18.1 / None / No changes to the meaning, language, or formatting of the technical content.
12/16/2011 / 19.0 / Major / Updated and revised the technical content.
3/30/2012 / 19.0 / None / No changes to the meaning, language, or formatting of the technical content.
7/12/2012 / 19.0 / None / No changes to the meaning, language, or formatting of the technical content.
10/25/2012 / 19.0 / None / No changes to the meaning, language, or formatting of the technical content.
1/31/2013 / 19.0 / None / No changes to the meaning, language, or formatting of the technical content.
8/8/2013 / 19.1 / Minor / Clarified the meaning of the technical content.
11/14/2013 / 19.1 / None / No changes to the meaning, language, or formatting of the technical content.
2/13/2014 / 19.1 / None / No changes to the meaning, language, or formatting of the technical content.
5/15/2014 / 19.1 / None / No changes to the meaning, language, or formatting of the technical content.
6/30/2015 / 20.0 / Major / Significantly changed the technical content.
10/16/2015 / 20.0 / None / No changes to the meaning, language, or formatting of the technical content.
7/14/2016 / 20.0 / None / No changes to the meaning, language, or formatting of the technical content.
6/1/2017 / 20.0 / None / No changes to the meaning, language, or formatting of the technical content.
Table of Contents
1Introduction
1.1Glossary
1.2References
1.2.1Normative References
1.2.2Informative References
1.3Overview
1.4Relationship to Other Protocols
1.5Prerequisites/Preconditions
1.6Applicability Statement
1.7Versioning and Capability Negotiation
1.8Vendor-Extensible Fields
1.9Standards Assignments
2Messages
2.1Transport
2.1.1Transmitting Messages and Boxcars
2.1.1.1Boxcar Format
2.1.1.2Boxcar Size Limitations
2.1.1.3Transmitting Boxcars
2.1.2Security
2.2Message Syntax
2.2.1BOX_CAR_HEADER
2.2.2MESSAGE_PACKET
2.2.3MTAG_DISCONNECT
2.2.4MTAG_DISCONNECTED
2.2.5MTAG_CONNECTION_REQ_DENIED
2.2.6MTAG_PING
2.2.7MTAG_CONNECTION_REQ
2.2.8MTAG_USER_MESSAGE
3Protocol Details
3.1Common Details
3.1.1Abstract Data Model
3.1.1.1Connection Object
3.1.1.2Boxcar Object
3.1.2Timers
3.1.2.1Idle Timer
3.1.3Initialization
3.1.3.1Initialization by a Higher-Layer Protocol
3.1.3.2Initialization by the Protocol
3.1.4Higher-Layer Triggered Events
3.1.4.1Send Message
3.1.4.2Create Connection
3.1.4.3Disconnect Connection
3.1.5Message Processing Events and Sequencing Rules
3.1.5.1MTAG_DISCONNECT (MsgTag 0x00000001)
3.1.5.2MTAG_DISCONNECTED (MsgTag 0x00000002)
3.1.5.3MTAG_CONNECTION_REQ_DENIED (MsgTag 0x00000003)
3.1.5.4MTAG_PING (MsgTag 0x00000004)
3.1.5.5MTAG_CONNECTION_REQ (MsgTag 0x00000005)
3.1.5.6MTAG_USER_MESSAGE (MsgTag 0x00000FFF)
3.1.6Timer Events
3.1.6.1Idle Timer
3.1.7Other Local Events
3.1.7.1Enqueuing a Message
3.1.7.2Session Down
3.1.7.3Allocate Incoming Connection Objects
3.1.7.4Notify Higher-Layer of Incoming Message Events
3.1.7.4.1Receiving a Message
3.1.7.4.2Connection Disconnected
3.1.7.4.3Connection Request Denied
4Protocol Examples
4.1Sending Messages
4.1.1Creating the MESSAGE_PACKETs
4.1.2Creating a Boxcar
4.1.3Sending the Boxcar Using the Underlying MSDTC Connection Manager: OleTx Transports Protocol Session
4.2A Simple Connection Scenario
4.2.1Initiating a Connection
4.2.1.1Connection Denied
4.2.1.2Connection Accepted
4.2.2Disconnecting a Connection
5Security
5.1Security Considerations for Implementers
5.2Index of Security Parameters
6Appendix A: Product Behavior
7Change Tracking
8Index
1Introduction
This document specifies the MSDTC Connection Manager: OleTx Multiplexing Protocol.
Sections 1.5, 1.8, 1.9, 2, and 3 of this specification are normative. All other sections and examples in this specification are informative.
1.1Glossary
This document uses the following terms:
acceptor: A participant that receives a session or connection request. This role is also known as the "subordinate".
boxcar: A set of messages transmitted together by way of an underlying MSDTC Connection Manager: OleTx Transports Protocol session.
connection: In OleTx, an ordered set of logically related messages. The relationship between the messages is defined by the higher-layer protocol, but they are guaranteed to be delivered exactly one time and in order relative to other messages in the connection.
connection type: A specific set of interactions between participants in an OleTx protocol that accomplishes a specific set of state changes. A connection type consists of a bidirectional sequence of messages that are conveyed by using the MSDTC Connection Manager: OleTx Transports Protocol and the MSDTC Connection Manager: OleTx Multiplexing Protocol transport protocol, as described in [MS-CMPO] and [MS-CMP]. A specified transaction typically involves many different connection types during its lifetime.
initiator: A participant that originates a session or connection request.
little-endian: Multiple-byte values that are byte-ordered with the least significant byte stored in the memory location with the lowest address.
Name Object: An object that contains endpoint contact information (as specified in [MS-CMPO] section 3.2.1.4).
session: In OleTx, a transport-level connection between a Transaction Manager and another Distributed Transaction participant over which multiplexed logical connections and messages flow. A session remains active so long as there are logical connections using it.
MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as defined in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or SHOULD NOT.
1.2References
Links to a document in the Microsoft Open Specifications library point to the correct section in the most recently published version of the referenced document. However, because individual documents in the library are not updated at the same time, the section numbers in the documents may not match. You can confirm the correct section numbering by checking the Errata.
1.2.1Normative References
We conduct frequent surveys of the normative references to assure their continued availability. If you have any issue with finding a normative reference, please contact . We will assist you in finding the relevant information.
[MS-CMPO] Microsoft Corporation, "MSDTC Connection Manager: OleTx Transports Protocol".
[MS-CMP] Microsoft Corporation, "MSDTC Connection Manager: OleTx Multiplexing Protocol".
[MS-DTCM] Microsoft Corporation, "MSDTC Connection Manager: OleTx Transaction Internet Protocol".
[MS-DTCO] Microsoft Corporation, "MSDTC Connection Manager: OleTx Transaction Protocol".
[MS-ERREF] Microsoft Corporation, "Windows Error Codes".
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997,
1.2.2Informative References
None.
1.3Overview
This protocol allows partners to multiplex any number of two-way connections over the transport session between them, as specified in [MS-CMPO]. To do this, this protocol defines a small number of messages to manage connections and uses the transport protocol resource requests to allocate connection-related resources. To facilitate higher-level protocols, this protocol defines a single user message and allows associating a connection type with a connection.
To illustrate these concepts, the following figure depicts typical messages of this protocol to initiate, use, and terminate two connections between partners labeled A and B.
Figure 1: Messages used to manage two connections between partners
As the first message of the preceding figure depicts, to initiate a connection, either partner sends a Connect message (MTAG_CONNECTION_REQ) to the other partner over their session.
A Connect message includes an identifier for the new connection (abbreviated ID in the figure). To simplify connection management, connections are identified by two pieces of information: the partner that initiated the connection, and an identifier assigned by that partner. This scheme allows each partner to assign identifiers without the risk of collision with the other partner. In effect, each partner maintains two tables of connections: those initiated by itself (so-called "outgoing" connections) and those initiated by the other partner (so-called "incoming" connections). Despite the names "outgoing" and "incoming", either partner has the option to send messages to the other by using any open connection. To correlate a message with its connection, the message includes a flag (fIsMaster) indicating which table the connection belongs to, in addition to the initiator-assigned identifier (dwConnectionId) for the connection.
Though not depicted in the figure, a Connect message also includes a type to identify the higher-level protocol for the connection's messages. Specifically, this connection type typically implies which types of User messages are expected over the connection.
As depicted in the preceding figure, a Connect message is assumed to succeed. If the receiving partner does not want to accept the connection, it sends a not-acknowledged message (MTAG_CONNECTION_REQ_DENIED).
After a connection is open, either partner has the option to send any number of User messages (MTAG_USER_MESSAGE) to the other partner by using that connection. User messages include their connection, a message type handled by a higher-level protocol, and the message payload. As the receiving partner never sends positive acknowledgment to a Connect message, the sending partner is free to send User messages to the connection along with the Connect message. If the receiving partner does not accept the connection, it will ignore these extraneous User messages.
A partner receives messages in the order in which they were sent over the connection.
To close a connection, the partner that initiated the connection sends a Disconnect message (MTAG_DISCONNECT) to the other partner; either partner has the option to initiate a connection, but only the partner that initiated a connection is allowed to close it. Unlike the Connect message, the Disconnect message is assumed to fail. As the preceding figure depicts, if the receiving partner has the option to close the connection, it does so and sends a Disconnect acknowledgment message (MTAG_DISCONNECTED). Finally, on receipt of the Disconnected message, the initiating partner closes the connection on its side. This asymmetric design allows the receiving partner to send any outstanding messages to the initiating partner before acknowledging the Disconnect message.
For efficiency, the MSDTC Connection Manager: OleTx Multiplexing Protocol batches messages by using Boxcar objects that contain one or more messages for one or more connections. A Boxcar includes the number of messages it encloses, their total size, and the messages themselves. Typically, the fact that messages are enclosed in a Boxcar is transparent to connection management and User messages in the MSDTC Connection Manager: OleTx Multiplexing Protocol. One exception occurs when a partner receives an unrecognized message type and discards the rest of the messages in the Boxcar.
1.4Relationship to Other Protocols
This protocol is explicitly layered upon the transport protocol that is specified in [MS-CMPO], and its design is greatly influenced by that protocol. It relies on the transport protocol to provide sessions and peer-to-peer message exchange. This protocol, in turn, provides message batching and connection multiplexing services to a protocol layered above it. For example, the transaction protocol that is specified in [MS-DTCM] is a set of connections with different connection types layered above this protocol, and it is used for coordinating distributed atomic transactions.
Figure 2: Relationship of MS-CMP to other protocols
1.5Prerequisites/Preconditions
This protocol relies on the transports protocol specified in [MS-CMPO] for carrying communication; there is no handshake between MSDTC Connection Manager: OleTx Multiplexing Protocol instances. The initialization of the transports protocol instance occurs during the initialization of the instance of this protocol, and is as described in section 3.1.3.
1.6Applicability Statement
This protocol is suitable for use as a connection multiplexing protocol over the transports protocol specified in [MS-CMPO], and it is applicable in all of the same situations.
1.7Versioning and Capability Negotiation
There are no optional capabilities exposed by the MSDTC Connection Manager: OleTx Multiplexing Protocol, and there are no extensibility points within the MSDTC Connection Manager: OleTx Multiplexing Protocol. There are therefore no version negotiation capabilities in this protocol.
1.8Vendor-Extensible Fields
There are no Vendor-Extensible Fields used by the MSDTC Connection Manager: OleTx Multiplexing Protocol.
1.9Standards Assignments
The MSDTC Connection Manager: OleTx Multiplexing Protocol does not use any standard assignments.
2Messages
This section specifies how the MSDTC Connection Manager: OleTx Multiplexing Protocol messages are encapsulated on the wire and common data types.
2.1Transport
Messages in this protocol MUST be transported over an instance of the transports protocol specified in [MS-CMPO]session; therefore, each instance of this protocol MUST have an underlying transports protocol instance. The initialization of the transports protocol instance occurs during the initialization of the instance of this protocol, and is specified in section 3.
2.1.1Transmitting Messages and Boxcars
Every message in MSDTC Connection Manager: OleTx Multiplexing Protocol is an extension of the message packet structure specified in section 2.2.2. When any event causes an implementation of this protocol to send a message, an implementation of this protocol MUST place this message in a boxcar. Boxcars are represented conceptually as Boxcar objects in the abstract data model; adding a message to a boxcar is represented conceptually as adding a message to the end of the Message List in a Boxcar object. For more information about Boxcar objects in the abstract data model, see section 3.1.1.2. For more information about processing boxcars, see section 3.1.5.
2.1.1.1Boxcar Format
A boxcar is formatted as an array of bytes that begins with a BOX_CAR_HEADER(section2.2.1) structure and continues with one or more MESSAGE_PACKET structures, each of which is appended with its associated variable length data (if any). Each MESSAGE_PACKET structure in a boxcar MUST be aligned on an 8-byte boundary. Because the size of each MESSAGE_PACKET structure is a multiple of 4 bytes (as defined in section 2.2.2), padding bytes MUST be added as necessary between the structures in order to have each structure aligned on a 8-byte boundary. Any necessary padding bytes can be set to any value, and MUST be ignored on receipt. The dwcMessages field of the BOX_CAR_HEADER structure MUST be equal to the number of messages in the boxcar, and the dwcbTotal field of the BOX_CAR_HEADER structure MUST be equal to the total number of bytes in the boxcar.