3.2.4.1.5 Sending Any Transaction

The Transaction SMB Commands are generic operations. They provide transport for extended sets of subcommands which, in turn, allow the CIFS client to access advanced features on the server. CIFS supports three different transaction messages, which differ only slightly in their construction:

• SMB_COM_TRANSACTION (section 2.2.4.33)

• SMB_COM_TRANSACTION2 (section 2.2.4.46)

• SMB_COM_NT_TRANSACT (section 2.2.4.62)

Transactions messages MAY exceed the maximum size of a single SMB message (as determined by the value of the Client.Connection.ServerMaxBufferSize parameter). Transaction messages that do not fit within a single SMB message MUST be split across multiple transaction SMBs. Each SMB transaction request has an associated secondary request message for this purpose:

• SMB_COM_TRANSACTION_SECONDARY (section 2.2.4.34)

• SMB_COM_TRANSACTION2_SECONDARY (section 2.2.4.47)

• SMB_COM_NT_TRANSACT_SECONDARY (section 2.2.4.63)

There are no secondary response messages. The client MUST send as many secondary requests as are needed to complete the transfer of the transaction request. The server MUST respond to the transaction request as a whole. If the server's transaction response exceeds the maximum size of a single SMB message, then the server MUST send multiple SMB responses to the request.

Like SMB messages, transactions are a rudimentary form of remote procedure call. Transaction subcommands identify operations to be performed, the parameters to pass to the operation, and raw data upon which to operate. The response also includes parameters and data.

Transactions are made up of four SMB message types. The set of all messages sent and received in order to perform a particular operation is referred to as a transaction.

1. A "primary request" MUST be sent by the client to initiate the transaction. This message also includes the total size of the transaction, which might not fit into a single request. If the primary request is sent as part of a batched message, the size of the entire batch message including the primary request MUST NOT exceed the negotiated Client.Connection.ServerMaxBufferSize.

2. If all of the parameters and data for the transaction request do not fit within the primary request, a single "interim response" MUST be sent by the server.

3. If an interim response is sent, and no error is returned in the interim response, then a "secondary request" MUST be used to continue a transaction started with a primary request. This message is sent by the client only. The client sends as many secondary requests as are necessary to complete the transaction. The server MUST NOT process the transaction until the entire transaction request has been transferred.

4. A "final response" MUST be sent by the CIFS server when the transaction has been processed. If the results of the transaction (the transaction response) do not fit within a single SMB response message, multiple final response messages MUST be sent.

5. Transaction response messages MUST NOT be sent in response to transaction requests sent as class 2 mailslot messages. See [MS-MAIL] for more information on mailslot protocols.

In its simplest form, a transaction consists of a single primary request to the server followed by a single final response.

Figure 3: Simple Transaction

The client MUST set the TransactionState for the request (in Client.Connection.PIDMIDList) to "TransmittedAllRequests".

If a transaction request does not fit within a single SMB message, the following messages are exchanged:

1. The CIFS client MUST send a primary request that indicates that more messages are to follow. The client indicates that the transaction request is incomplete by setting the ParameterCount value less than the TotalParameterCount, or by setting the DataCount value less than the TotalDataCount, or both. After sending the primary request, the client MUST set the TransactionState for the request (in Client.Connection.PIDMIDList) to "TransmittedPrimaryRequest".<197>

2. Upon receiving a primary request containing an incomplete transaction, the server MUST check for any initial errors and MUST return a single interim response.

3. The response received from the server MUST be processed as described in section 3.2.5.1.4.

Figure 4: Transaction with secondary messages to complete the message transfer

Once it has received the entire request, the server MUST process the transaction and MUST finish with a transaction response. If the transaction response does not fit within a single SMB message, the following messages are exchanged:

1. The server MUST send a final response that indicates that additional response messages are to follow.

2. The server MUST send as many final response messages as are needed to complete the transfer of transaction parameters and data.

Figure 5: Transaction response with multiple SMB response messages

The number of SMB messages needed to transfer a transaction request is independent of the number of messages that can be returned. A single-part request can generate a single response or a multi-part response. Likewise, a multi-part request MAY generate one or more final response SMBs.

Secondary requests SHOULD NOT be used if the transaction request can fit within a single SMB message. Similarly, multiple final response messages SHOULD NOT be used if the transaction response can fit within a single SMB message.

Transaction parameters SHOULD take precedence over transaction data; all transaction parameters SHOULD be transferred before any transaction data.

All messages that are part of the same transaction MUST have the same UID, TID, PID, and MID values. If a connectionless transport is in use, the CID MUST also be the same for all transaction messages that are part of the same transaction. The client MUST NOT start a new transaction if it has not completed a previous transaction with the same PID and MID values. The client MAY start multiple concurrent transactions as long as at least one of the values of PID or MID differs from all other in-process transactions.