2.2.3.5 COMM_PACKET and PCOMM_PACKET

Article
04/06/2021

The COMM_PACKET is the primary message used to accomplish file replication through FRS. It MUST be transmitted as the payload of the FrsRpcSendCommPkt method. By successively invoking FrsRpcSendCommPkt, a computer participates in a synchronous request/response-based conversation with another computer that results in replication of data files. On receiving an FrsRpcSendCommPkt call from another computer, FRS responds based on the nature of the request inside the COMM_PACKET data received (see section 3.3.4.4).

A PCOMM_PACKET is a pointer to a COMM_PACKET.

The COMM_PACKET contains information about the partner, the replication command, and data specific to that replication command, plus hash fields to verify the data's integrity. This information is contained in a series of elements within each COMM_PACKET. There MUST be no padding between each element unless it is called out in the specification.

Twelve types of COMM_PACKETS, each representing a different replication command, are sent over the wire. The replication command for the packet is indicated by the data field in the COMM_COMMAND element.

Every packet, regardless of replication command type, MUST begin with the following eight elements. There MUST be no padding between each element unless it is called out in the specification.

COMM_BOP: Beginning-of-packet marker, as specified in section 2.2.3.6.1.

COMM_COMMAND: The replication command, as specified in section 2.2.3.6.2.

COMM_TO: GUID and name of the member to receive this packet, as specified in section 2.2.3.6.3.

COMM_FROM: GUID and name of the member that sent this packet, as specified in section 2.2.3.6.4.

COMM_REPLICA: GUID and name that identifies the replica set to which this packet applies, as specified in section 2.2.3.6.5.

COMM_CXTION: GUID and name of the connection over which this packet is transmitted, as specified in section 2.2.3.6.6.

COMM_JOIN_GUID: GUID that identifies the last successful Join over the connection identified in the COMM_CXTION element, as specified in section 2.2.3.6.7.

COMM_LAST_JOIN_TIME: Time that the Join identified by the COMM_JOIN_GUID element completed, as specified in section 2.2.3.6.8.

In addition, every packet MUST end with the following element, which MUST appear in the packet immediately after the preceding element, with no padding between it and the preceding element.

COMM_EOP: End-of-Packet (EOP) marker, as specified in section 2.2.3.6.23.

FRS MUST respond to zero or more replication command-specific elements that appear between the last element in the beginning sequence and the ending element. There MUST be no padding bytes before or after any elements in the packet, so the following text gives the bit-level layout of the fields. All of the COMM_PACKET elements are defined in the following section.

The types of replication command packets are listed in the following table along with a brief description and the list of elements that are contained in the packet. Only the mandatory elements and the elements listed for that COMM_COMMAND value in the following table MUST be present for a packet with a particular COMM_COMMAND value. The mandatory elements are omitted from this table, but MUST be present in every replication command packet. FRS MUST respond to these requests, as specified in section 3.3.4.4.

COMM_COMMAND value	Extra sequence of elements in packet (no padding between elements)	Meaning
CMD_REMOTE_CO (0x218)	COMM_REMOTE_CO COMM_CO_EXTENSION_2	To send a remote change order to a downstream partner.
CMD_RECEIVING_STAGE (0x238)	COMM_BLOCK COMM_BLOCK_SIZE COMM_FILE_SIZE COMM_FILE_OFFSET COMM_CO_GUID COMM_CO_SEQUENCE_NUMBER	To transmit staging file to a downstream partner.
CMD_REMOTE_CO_DONE (0x250)	COMM_BLOCK_SIZE COMM_FILE_SIZE COMM_FILE_OFFSET COMM_GVSN COMM_CO_GUID COMM_CO_SEQUENCE_NUMBER COMM_REMOTE_CO COMM_CO_EXTENSION_2	To inform the upstream partner that processing the remote change order is complete. This packet also MUST include the change order command that has completed.
CMD_ABORT_FETCH (0x246)	COMM_BLOCK_SIZE COMM_FILE_SIZE COMM_FILE_OFFSET COMM_CO_GUID COMM_CO_SEQUENCE_NUMBER	To inform the downstream partner that the staged file data cannot be sent. This command tells the partner to abort the fetch operation on the staging file.
CMD_RETRY_FETCH (0x244)	COMM_BLOCK_SIZE COMM_FILE_OFFSET COMM_CO_GUID COMM_CO_SEQUENCE_NUMBER	To inform the downstream partner that the request for the staging file data cannot be fulfilled at this time and that the request SHOULD be retried at a later time.
CMD_NEED_JOIN (0x121)		To inform the upstream partner that a Join operation is needed.
CMD_START_JOIN (0x122)		To inform the downstream partner that a Join operation is starting.
CMD_JOINING (0x130)	COMM_VVECTOR COMM_JOIN_TIME COMM_REPLICA_VERSION_GUID COMM_COMPRESSION_GUID	To send a version vector to an upstream partner.
CMD_JOINED (0x128)		To inform the downstream partner that Join is successful.
CMD_UNJOIN_REMOTE (0x148)		On completion of a VVJ on a connection, this command causes the upstream partner to disconnect the connection so that it can be torn down.
CMD_VVJOIN_DONE (0x136)		To inform the downstream partner that all change orders are sent out during Initial Sync.
CMD_SEND_STAGE (0x228)	COMM_BLOCK_SIZE COMM_FILE_SIZE COMM_FILE_OFFSET COMM_CO_GUID COMM_CO_SEQUENCE_NUMBER COMM_REMOTE_CO COMM_CO_EXTENSION_2	To request staging data from an upstream partner.

The structure of the COMM_PACKET MUST be as follows:

 typedef struct {
   unsigned long Major;
   unsigned long Minor;
   unsigned long CsId;
   unsigned long MemLen;
   [range(0,262144)] unsigned long PktLen;
   unsigned long UpkLen;
   [size_is(PktLen)] unsigned char* Pkt;
   [ignore] void* DataName;
   [ignore] void* DataHandle;
 } COMM_PACKET,
  *PCOMM_PACKET;

Major: A 32-bit, unsigned integer indicating the major version number of the FRS. This field MUST be zero (0).

Minor: A 32-bit unsigned integer that specifies the minor version number of FRS. The minor version number of FRS MUST be one of the following.

Value	Meaning
NTFRS_COMM_MINOR_0 0x00000000	This is the first version.
NTFRS_COMM_MINOR_1 0x00000001	Supports MD5.
NTFRS_COMM_MINOR_2 0x00000002	Supports trigger schedule (see section 3.3.2.1.1).
NTFRS_COMM_MINOR_3 0x00000003	Supports change order record extension (see section 2.2.3.6.21).
NTFRS_COMM_MINOR_4 0x00000004	Forces the replica number fields in a change order to be an unsigned long instead of an unsigned long PTR for 32–64 bit interoperation. Supports the use of the COMM_COMPRESSION_GUID. Supports COMM_CO_EXTENSION_2.
NTFRS_COMM_MINOR_5 0x00000005	Supports change order extension COMM_CO_EXTENSION_2 when replication partner is running FRS minor version 4 or later.
NTFRS_COMM_MINOR_6 0x00000006	No new capabilities.
NTFRS_COMM_MINOR_7 0x00000007	No new capabilities.
NTFRS_COMM_MINOR_8 0x00000008	No new capabilities.
NTFRS_COMM_MINOR_9 0x00000009	No new capabilities.

Version 0.7 or earlier is deprecated and SHOULD be used only for backward compatibility.

Subsequent versions MUST subsume all capabilities of lower versions.

CsId: A 32-bit, unsigned integer that MUST be set to 1.

MemLen: A 32-bit, unsigned integer containing the size, in bytes, of Pkt. Used to determine the packet length.

PktLen: A 32-bit, unsigned integer containing the length, in bytes, of the packet's valid data portion. Not all bytes inside Pkt hold valid data. The valid data inside Pkt is from offset 0 to PktLen.

UpkLen: MUST be 0.

Pkt: A pointer to a buffer that MUST consist of a sequence of COMM_PACKET element structures placed back to back in contiguous memory. These elements MUST be in a particular order; however, some elements can be omitted depending on the command that is being transmitted. The table earlier in this section specifies the elements that MUST exist in the Pkt buffer, for each supported COMM_COMMAND value.

The following table shows the order of the elements in the Pkt buffer. The first column shows when the element is included in the table: A – Always; V – included when a version vector is transmitted; S – included when staging data is transmitted; C – included when a change order Command is transmitted. See the first table in section 2.2.3.5 to see what element types MUST appear for each communication packet. For more information on version vectors see section 3.1.1.11.

See sections 2.2.3.6 through 2.2.3.6.23 for the definitions of the packet structures associated with each element type.

Usage	Element type and value	Element contents
A	COMM_BOP 0x0001	Beginning of the packet. This element MUST be the first element in the packet.
A	COMM_COMMAND 0x0002	Type of command sent in this packet. See the "Type of communication packets" table in section 2.2.3.5.
A	COMM_TO 0x0003	GUID and name of the member to receive this packet. This MUST refer to either local machine or partner.
A	COMM_FROM 0x0004	GUID and name of member that sent this packet. This MUST refer to either local machine or partner.
A	COMM_REPLICA 0x0005	GUID and name that identifies the replica set to which this packet applies.
A	COMM_CXTION 0x0008	GUID and name of the connection over which this packet is transmitted.
A	COMM_JOIN_GUID 0x0006	GUID that identifies the last successful Join over the connection identified in the COMM_CXTION element.
A	COMM_LAST_JOIN_TIME 0x0012	Time (see section 2.2.3.6.8) that the Join identified by the COMM_JOIN_GUID element completed. Packet element contains the time of the last Join by this connection.
V	COMM_VVECTOR 0x0007	A COMM_VVECTOR element MUST be inserted into Pkt for each GVSN structure in the version vector. There MUST be one COMM_VVECTOR element for each partner.
V	COMM_JOIN_TIME 0x0011	This element MUST be initialized to the FILETIME (as specified in [MS-DTYP]) when the connection is joined.
V	COMM_REPLICA_VERSION_GUID 0x0014	GUID of the machine that generated the version vector.
V	COMM_COMPRESSION_ GUID 0x0018	A COMM_COMPRESSION_GUID element MUST be inserted for each compression algorithm that the sending member supports (see section 2.2.3.6.12. There can be more than one COMM_COMPRESSION_GUID element. There are no other GUID values used by FRS.
S	COMM_BLOCK 0x0009	Block of data from the staging file that is being transmitted.
S	COMM_BLOCK_SIZE 0x000A	Size in bytes of the block of data in the COMM_BLOCK element.
S	COMM_FILE_SIZE 0x000B	Size in bytes of the staging file being transmitted.
S	COMM_FILE_OFFSET 0x000C	Offset from the beginning of the staging file to the beginning of the block in the COMM_BLOCK element.
S	COMM_GVSN 0x000E	GVSN structure for the file being transmitted.
S	COMM_CO_GUID 0x000F	GUID that identifies the change order that caused the file to be transmitted.
S	COMM_CO_SEQUENCE_ NUMBER 0x0010	Sequence number starting at 1 to record the order of change order commands. It MUST be used for acknowledgment.
C	COMM_REMOTE_CO 0x000D	Includes a remote change order command.
C	COMM_CO_EXT_WIN2K 0x0016 COMM_CO_EXTENSION_2 0x0017	COMM_CO_EXT_WIN2K or a COMM_CO_EXTENSION_2 element will be in Pkt. If either partner is NTFRS_COMM_MINOR_3 or lower, the COMM_CO_EXT_WIN2K element will be used. Otherwise, the COMM_CO_EXTENSION_2 element will be used. It contains change order extensions.
A	COMM_EOP (0x13)	End-of-packet (EOP) element.

DataName: MUST be 0.

DataHandle: MUST be 0.

2.2.3.5 COMM_PACKET and PCOMM_PACKET

Additional resources