2.2.3.2 CHANGE_ORDER_COMMAND

  • Article

The CHANGE_ORDER_COMMAND is referenced below in sections 2.2.3.6.20, 2.2.3.6.21, 2.2.3.6.22, and 2.2.3.10. It MUST be formatted as follows.

 typedef struct _CHANGE_ORDER_COMMAND {
   ULONG SequenceNumber;
   ULONG Flags;
   ULONG IFlags;
   ULONG State;
   ULONG ContentCmd;
   ULONG LocationCmd;
   ULONG FileAttributes;
   ULONG FileVersionNumber;
   ULONG PartnerAckSeqNumber;
   ULONG Notused;
   ULONGLONG FileSize;
   ULONGLONG FileOffset;
   ULONGLONG FrsVsn;
   ULONGLONG FileUsn;
   ULONGLONG JrnlUsn;
   ULONGLONG JrnlFirstUsn;
   ULONG OriginalReplicaNum;
   ULONG NewReplicaNum;
   GUID ChangeOrderGuid;
   GUID OriginatorGuid;
   GUID FileGuid;
   GUID OldParentGuid;
   GUID NewParentGuid;
   GUID CxtionGuid;
   ULONGLONG AckVersion;
   ULONGLONG Spare2Ul1;
   GUID Spare1Guid;
   GUID Spare2Guid;
   PWCHAR Spare1Wcs;
   PWCHAR Spare2Wcs;
   ULONG Extension;
   PVOID Spare2Bin;
   LARGE_INTEGER EventTime;
   USHORT FileNameLength;
   WCHAR FileName[MAX_PATH+1];
   UCHAR Padding[4];
 } CHANGE_ORDER_COMMAND,
  *PCHANGE_ORDER_COMMAND;

SequenceNumber: A 32-bit, unsigned integer that specifies the sequence number in the change order command. It MUST be initialized to 0. The sequence number MUST be incremented with each change order that goes into the outbound log. The sequence number MUST be unique per replica set per machine.

Flags: A 32-bit, unsigned integer that MUST contain one or more change order flags, represented as the bitwise OR of zero or more of the following values (see section 3.3.4.4).

Value

Meaning

CO_FLAG_ABORT_CO

0x00000001

The change order is being aborted.

CO_FLAG_VV_ACTIVATED

0x00000002

A version vector activate request has been made (see section 3.3.4.4.6.2).

CO_FLAG_CONTENT_CMD

0x00000004

A valid content command.

CO_FLAG_LOCATION_CMD

0x00000008

A valid location command.

CO_FLAG_ONLIST

0x00000010

This change order is on a change order process list.

CO_FLAG_LOCALCO

0x00000020

This change order is locally generated.

CO_FLAG_RETRY

0x00000040

This change order MUST be retried (see section 3.1.1.10.2).

CO_FLAG_INSTALL_INCOMPLETE

0x00000080

The installation of the change order on the downstream partner is incomplete.

CO_FLAG_OUT_OF_ORDER

0x00000200

Do not check/update version vector.

CO_FLAG_NEW_FILE

0x00000400

The file or folder inside the change order is new. An IDTable record MUST be created for this file or folder. If the change order fails, then delete the IDTable record just created.

CO_FLAG_CONTROL

0x00001000

This is a control change order sent by a remote partner when an inbound connection starts up, so that the inbound log is scanned and any pending change orders for this connection are queued again.

CO_FLAG_DIRECTED_CO

0x00002000

This change order is directed to a single connection.

CO_FLAG_VVJOIN_TO_ORIG

0x00040000

This change order is from a replica member identified by the originator GUID.

CO_FLAG_SKIP_ORIG_REC_CHK

0x00100000

Skip the originator reconcile check.

CO_FLAG_MOVEIN_GEN

0x00200000

This change order was generated as part of a subfolder MOVEIN.

CO_FLAG_MORPH_GEN_LEADER

0x00400000

This is a MORPH_GEN leader, and it needs to refabricate the MORPH_GEN follower if it is retried.

CO_FLAG_JUST_OID_RESET

0x00800000

Reset object ID (OID) back to its FRS-defined value.

CO_FLAG_COMPRESSED_STAGE

0x01000000

The staging file for this change order is compressed.

CO_FLAG_SKIP_VV_UPDATE

0x02000000

This change order can not update the version vector.

IFlags: A 32-bit, unsigned integer that contains additional flag values for the change order. The value of this field MUST be a bitwise OR of one or more of the values defined in the following table.

Value

Meaning

CO_IFLAG_NONE

0x00000000

This value is sent by the downstream replication partner if the change order is dampened.

CO_IFLAG_VVRETIRE_EXEC

0x00000001

Indicates that an FRS operation, such as a file rename or copy, is complete. This IFlag value is sent by a downstream replication partner if the change order is not dampened.

CO_IFLAG_CO_ABORT

0x00000002

This value is sent by the downstream replication partner if change order processing needs to be aborted.

CO_IFLAG_DIR_ENUM_PENDING

0x00000004

This value is sent by the downstream replication partner if change order needs to enumerate its children as part of a sub-directory MoveIn.

State: A 32-bit, unsigned integer that indicates the change order process state.

Value

Meaning

0x00000000

This change order is entered in the log.

0x00000001

Allocating staging file space for a local change order.

0x00000002

This local change order staging file copy has started.

0x00000003

This local change order staging file is complete.

0x00000004

Waiting to retry local change order staging file generation.

0x00000005

Allocated staging file space for a remote change order.

0x00000006

This remote change order staging file fetch has started.

0x00000007

This remote change order staging file fetch is complete.

0x00000008

Waiting to retry the fetch of the staging file for the remote change order.

0x00000009

File install requested.

0x0000000A

File install has started.

0x0000000B

File install is complete.

0x0000000C

File install is waiting to try again.

0x0000000D

File install is retrying.

0x0000000E

File install rename is retrying.

0x0000000F

File install delete is retrying.

0x00000013

This change order is being recycled to perform a folder enumeration.

0x00000014

Request outbound propagation.

0x00000015

Request was accepted and is now in the outbound log.

0x00000016

Database state update has started.

0x00000017

Database state update has completed, and FRS is now freeing the change order.

0x00000018

This change order is being aborted.

ContentCmd: A 32-bit, unsigned integer that indicates the reasons for the change. The value of this field MUST be a bitwise OR of zero or more of the values defined in the following table.

Value

Meaning

REASON_DATA_OVERWRITE

0x00000001

Overwrite a file.

REASON_DATA_EXTEND

0x00000002

Extend a file.

REASON_DATA_TRUNCATION

0x00000004

Truncate the data.

REASON_NAMED_DATA_OVERWRITE

0x00000010

Overwrite named data.

REASON_NAMED_DATA_EXTEND

0x00000020

Extend named data.

REASON_NAMED_DATA_TRUNCATION

0x00000040

Truncate named data.

REASON_FILE_CREATE

0x00000100

Create a file.

REASON_FILE_DELETE

0x00000200

Delete a file.

REASON_EA_CHANGE

0x00000400

Change the extended attribute.

REASON_SECURITY_CHANGE

0x00000800

Change the security type.

REASON_RENAME_OLD_NAME

0x00001000

The old name for rename operation.

REASON_RENAME_NEW_NAME

0x00002000

The new name for rename operation.

REASON_BASIC_INFO_CHANGE

0x00008000

Change the basic information.

REASON_COMPRESSION_CHANGE

0x00020000

Change the compression.

REASON_ENCRYPTION_CHANGE

0x00040000

Change the encryption.

REASON_OBJECT_ID_CHANGE

0x00080000

Change the object identifier.

REASON_REPARSE_POINT_CHANGE

0x00100000

Change the file reparse point.

REASON_STREAM_CHANGE

0x00200000

Change the file stream.

LocationCmd: File or folder location command. The location command specifies the movement of a file or folder in the replica tree. The location command also specifies whether the change order describes a change for a file or a folder. The location command MUST have the following structure.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

D

C

C

C

C

F

F

F

F

F

F

F

F

F

F

F

F

F

F

F

F

F

F

F

F

F

F

F

F

F

F

F

D = DirOrFile (1 bit)

C = File Location Command (4 bits)

F = Filler bits, not used (27 bits). MUST be 0. MUST be ignored on receipt.

DirOrFile: Bit that indicates whether the change is for a folder or for a file. The value MUST be one of the following:

 Value

 Meaning

0

The change is for a file.

1

The change is for a folder.

Command:  File location command MUST be one of the following values:

 Value

 Meaning

CO_LOCATION_CREATE

0x0

Create a file or folder.

CO_LOCATION_DELETE

0x1

Delete a file or folder.

CO_LOCATION_MOVEIN

0x2

Rename a file or folder from a path outside the replica tree to a path inside the replica tree on the same volume.

CO_LOCATION_MOVEIN2

0x3

Rename a file or folder into the replica set after a CO_LOCATION_MOVEOUT.

CO_LOCATION_MOVEOUT

0x4

Rename a file or folder from a path inside the replica tree to a path outside the replica tree on the same volume.

CO_LOCATION_MOVERS

0x5

Rename a file or folder from one replica tree to another replica tree on the same volume.

CO_LOCATION_MOVEDIR

0x6

Rename a file or folder from one folder to another folder in the same replica tree.

CO_LOCATION_NO_CMD

0x7

No command.

Filler: These bits are not used and MUST be set to 0 and ignored by the receiver.

FileAttributes: A 32-bit, unsigned integer that indicates file attributes, as specified in [MS-FSCC] section 2.6.

FileVersionNumber: A 32-bit, unsigned integer that indicates the file version number.

PartnerAckSeqNumber: A 32-bit, unsigned integer that indicates the replication partner acknowledgment sequence number.

Notused: Four padding bytes to align the following field in memory. Not used. MUST be 0. MUST be ignored on receipt.

FileSize: A 64-bit, unsigned integer that indicates the file size in bytes. This is the original file size before staging and compression. It is used as a hint about how much staging space will be used on the downstream partner. The actual compressed staging file size is passed from upstream partner to downstream partner in the COMM_FILE_SIZE field in a COMM_PACKET packet whose COMM_COMMAND value is set to CMD_RECEIVING_STAGE (see section 3.3.4.4.7 and 3.3.4.4.8).

FileOffset: A 64-bit, unsigned integer that MUST be 0. Not used. MUST be ignored on receipt. (COMM_FILE_OFFSET inside COMM_PACKET indicates the file offset in downloading the staging file. See section 2.2.3.6.16. This FileOffset field inside CHANGE_ORDER_COMMAND is not used.)

FrsVsn: A 64-bit, unsigned integer that indicates the originating server's volume sequence number.

FileUsn: A 64-bit, unsigned integer that indicates internal implementation-specific data on the current replica member. This value is meaningful only on the current replica member and has no meaning on any other replica member. Once the change order is sent to another replica member, the receiving partner MUST ignore this field.<5>

JrnlUsn: A 64-bit, unsigned integer that indicates internal implementation-specific data on the current replica member. This value is meaningful only on the current replica member and has no meaning on any other replica member. Once the change order is sent to another replica member, the receiving partner MUST ignore this field.<6>

JrnlFirstUsn: A 64-bit, unsigned integer that indicates internal implementation-specific data on the current replica member. This value is meaningful only on the current replica member and has no meaning on any other replica member. Once the change order is sent to another replica member, the receiving partner MUST ignore this field.<7>

OriginalReplicaNum: A 32-bit, unsigned integer that indicates internal implementation specific data on the current replica member. This value is meaningful only on the current replica member and has no meaning on any other replica member. Once the change order is sent to another replica member, the receiving partner MUST ignore this field.<8>

NewReplicaNum: A 32-bit, unsigned integer that indicates internal implementation specific data on the current replica member. This value is meaningful only on the current replica member and has no meaning on any other replica member. Once the change order is sent to another replica member, the receiving partner MUST ignore this field.<9>

ChangeOrderGuid: The identifying GUID of the change order.

OriginatorGuid: The GUID of the originating server.

FileGuid: The identifying GUID of the file.

OldParentGuid: The identifying GUID of the file's original parent folder.

NewParentGuid: The identifying GUID of the file's current parent folder.

CxtionGuid: The identifying GUID of the remote change order connection.

AckVersion: A 64-bit, unsigned integer that indicates the partner's acknowledgment version number. The downstream partner MUST preserve this value when receiving a change order from the upstream partner. The vendor can set it to any value based on the vendor's implementation or set it to 0 and ignore it.

Spare2Ul1: An 8-byte field that is not used and MUST be set to 8 bytes of 0x00 and MUST be ignored by the receiver.

Spare1Guid: A 16-byte field that is not used and MUST be set to 16 bytes of 0x00 and MUST be ignored by the receiver.

Spare2Guid: A 16-byte field that is not used and MUST be set to 16 bytes of 0x00 and MUST be ignored by the receiver.

Spare1Wcs: A 4-byte field that is not used and MUST be set to 4 bytes of 0x00 and MUST be ignored by the receiver.

Spare2Wcs: A 4-byte field that is not used and MUST be set to 4 bytes of 0x00 and MUST be ignored by the receiver.

Extension: A 4-byte field that MUST be ignored.

Spare2Bin: A 4-byte field that is not used and MUST be set to 4 bytes of 0x00 and MUST be ignored by the receiver.

EventTime: USN journal event time that MUST be in the format of FILETIME, as specified in [MS-DTYP].

FileNameLength: A 16-bit, unsigned integer that indicates the length in bytes of FileName field. FileNameLength does not include the terminating 0 inside FileName.

FileName: MUST be a Unicode string that contains the NULL-terminated file name. It is not a whole path or a relative path, only the file name.

Padding: A 4-byte field (beyond the 522nd byte of FileName) that is not used and MUST be set to 4 bytes of 0x00 and MUST be ignored by the receiver.