Share via

3.2.4.5 NtFrsApi_Rpc_WriterCommand (Opnum 9)

  • Article

The NtFrsApi_Rpc_WriterCommand method MUST deactivate or reactivate the replication of the specified Replica Set.

 unsigned long NtFrsApi_Rpc_WriterCommand(
   [in] handle_t Handle,
   [in] unsigned long Command
 );

Handle: RPC binding handle obtained when the partner authenticates with the file replication service (FRS), as specified in [MS-RPCE]. For RPC binding handle transport, see section 2.1.

Command: A 32-bit unsigned integer that indicates if the FRS can install new files. It MUST be one of the following.

Value

Meaning

NTFRSAPI_WRITER_COMMAND_FREEZE

0x00000001

Prevent the FRS from installing new files. FRS MUST continue sending/receiving/processing updates. However, the updates received will not be installed to the file system unless NTFRSAPI_WRITER_COMMAND_THAW is received.

NTFRSAPI_WRITER_COMMAND_THAW

0x00000002

Allow the FRS to install new files.

Return Values: The method MUST return 0 on success or a nonzero error code on failure. All nonzero values MUST be treated as equivalent failures unless otherwise specified.

Return value/code

Description

0x00000000

ERROR_SUCCESS

The method completed successfully.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].

Validating the NtFrsApi_Rpc WriterCommand request: The server must validate the NtFrsApi_Rpc WriterCommand request by performing the following checks.

  • If IsWriterCommandCheckEnabled is set to "None", the server MUST fail the call with an implementation specific value.

  • If IsWriterCommandCheckEnabled is set to "Disabled", the server MUST process the request without performing an access check.

  • If IsWriterCommandCheckEnabled is set to "Enabled", the server MUST check whether the calling client is authorized to perform that function. If the calling client is not authorized to perform that function, the server MUST return ERROR_NOT_AUTHENTICATED.

    • If WriterCommandAccessRequired is set to "None", the server MUST fail the call with an implementation-specific value.

    • If WriterCommandAccessRequired is set to "Read", the server MUST check whether the caller has read access. If the caller does not have read access, the server MUST return FRS_ERR_INSUFFICIENT_PRIV.

    • If WriterCommandAccessRequired is set to "Write", the server MUST check whether the caller has write access. If the caller does not have write access, the server MUST return FRS_ERR_INSUFFICIENT_PRIV.

  • If the server is not able to verify the passed-in parameters, then it MUST ignore the failure and succeed the call.

Actions Triggered: If the command is NTFRSAPI_WRITER_COMMAND_FREEZE, FRS MUST stop installing new files for all replica sets. If the command is NTFRSAPI_WRITER_COMMAND_THAW, FRS MUST resume installing new files. When FRS is frozen, the Partner continues to participate in replication, change orders are passed between partners, and staging files are transmitted to and from the partner. The staging files MUST remain in the staged state as long as FRS is frozen. Staging files can only be installed into the replica tree when FRS is in the thawed state.