3.3.5.59.4 Receiving an NT_TRANSACT_NOTIFY_CHANGE Request

  • Article

Upon receipt of an NT_TRANSACT_NOTIFY_CHANGE Request (section 2.2.7.4.1), the NT Trans subsystem MUST verify the TID and UID as described in section 3.3.5.2. The server MUST perform a lookup in the Server.Connection.FileOpenTable to verify that the FID, which is passed in the NT_Trans_Parameters block of the request, represents an opened directory within the TreeConnect given by TID.

If the client has not issued any NT_TRANSACT_NOTIFY_CHANGE Requests on this FID previously, the server SHOULD allocate an empty change notification buffer and associate it with the open directory. The size of the buffer SHOULD be at least equal to the MaxParameterCount field in the SMB_COM_NT_TRANSACT Request (section 2.2.4.62.1) used to transport the NT_TRANSACT_NOTIFY_CHANGE Request. If the client previously issued an NT_TRANSACT_NOTIFY_CHANGE Request on this FID, the server SHOULD already have a change notification buffer associated with the FID. The change notification buffer is used to collect directory change information in between NT_TRANSACT_NOTIFY_CHANGE (section 2.2.7.4) calls that reference the same FID.

The CompletionFilter indicates the set of change events for which the client requests notification. If WatchTree is TRUE, all of the subdirectories below the directory specified by FID are also watched. If there is a change notification buffer associated with the FID, the changes listed in the buffer are compared against the CompletionFilter. If there is a match, the NT_TRANSACT_NOTIFY_CHANGE Request is complete; otherwise, the request MUST wait asynchronously until a change event occurs to complete the request.

The NT_TRANSACT_NOTIFY_CHANGE Request is entered into the Server.Connection.PendingRequestTable, as is any other command that is processed asynchronously by the server. The request is completed when one of the following events occurs:

Once the request has completed, it is removed from the Server.Connection.PendingRequestTable, and an NT_TRANSACT_NOTIFY_CHANGE Response (section 2.2.7.4.2) is composed. The response MUST contain the names of the files that changed, as well as an indication of the type of change that occurred. All changed files within the directory or directories indicated by the FID are returned, not just those matching CompletionFilter. If the operation completed because the FID was closed, or due to an SMB_COM_NT_CANCEL (section 2.2.4.65), there might be no changes listed.

Any changes that occur within the directory or directories indicated by FID following the completion of the NT_TRANSACT_NOTIFY_CHANGE Request are recorded in the change notification buffer on the server. This is done on the assumption that the client will reissue the NT_TRANSACT_NOTIFY_CHANGE Request upon receipt of the response. In the event that the number of changes exceeds the size of the change notify buffer, or the maximum size of the NT_Trans_Parameter block in the response (as indicated by the MaxParameterCount field in the most recent request), the NT Trans subsystem MUST return an error response with a Status value of STATUS_NOTIFY_ENUM_DIR (ERRDOS/ERR_NOTIFY_ENUM_DIR). This indicates to the client that more changes have occurred on the server than the transaction has the capacity to report.

The server can also send an NT_TRANSACT_NOTIFY_CHANGE Response with a success Status and no changes listed (TotalParameterCount is zero) to cause the client to enumerate the directory and/or post a new NT_TRANSACT_NOTIFY_CHANGE Request.

If the server does not support the NT_TRANSACT_NOTIFY_CHANGE subcommand, it can return an error response with STATUS_NOT_IMPLEMENTED (ERRDOS/ERRbadfunc) in response to an NT_TRANSACT_NOTIFY_CHANGE Request. Alternatively, it can send STATUS_NOTIFY_ENUM_DIR (ERRDOS/ERR_NOTIFY_ENUM_DIR) to cause the client to enumerate the directory.<351>