3.3.5.47 Receiving an SMB_COM_SEARCH or SMB_COM_FIND Request

  • Article

The SMB_COM_SEARCH (section 2.2.4.58) and SMB_COM_FIND (section 2.2.4.59) commands are identical in format and behavior, with the exception that SMB_COM_FIND allows the use of SMB_COM_FIND_CLOSE (section 2.2.4.61) to close the search context.

Upon receiving either of these commands, the server MUST first determine whether the request is a continuation of a previous search, or a new search. If the ResumeKeyLength field is zero, then this is a new search. A new search proceeds as follows:

  • The server MUST perform a directory search using the FileName field as the pattern with which to search. If the FileName field is an empty string, the server SHOULD<310> return all the files that are present in the directory. The path indicated in the FileName field MUST exist within the specified TID.

  • The SMB_Parameters.Words.SearchAttributes field is used to further refine the search. See the tables in section 2.2.1.2.4 for a list of possible values.

    • If the SMB_FILE_ATTRIBUTE_VOLUME attribute is set, the volume label MUST be returned (the Volume Label attribute is exclusive).

    • If the value of this field is zero, only "normal" files are returned. Normal files include files with no attributes, the SMB_FILE_ATTRIBUTE_READONLY attribute, and/or the SMB_FILE_ATTRIBUTE_ARCHIVE attribute.

    • The "inclusive search attributes" are:

      • SMB_FILE_ATTRIBUTE_READONLY

      • SMB_FILE_ATTRIBUTE_HIDDEN

      • SMB_FILE_ATTRIBUTE_SYSTEM

      • SMB_FILE_ATTRIBUTE_DIRECTORY

      • SMB_FILE_ATTRIBUTE_ARCHIVE

        If any of these bits is included in the SearchAttributes field, files with matching attributes are also included in the results. (Specifying SMB_FILE_ATTRIBUTE_READONLY or SMB_FILE_ATTRIBUTE_ARCHIVE has no effect, because files with those attributes are included in "normal" searches by default.)

    • The "exclusive search attributes" are:

      • SMB_SEARCH_ATTRIBUTE_READONLY

      • SMB_SEARCH_ATTRIBUTE_HIDDEN

      • SMB_SEARCH_ATTRIBUTE_SYSTEM

      • SMB_SEARCH_ATTRIBUTE_DIRECTORY

      • SMB_SEARCH_ATTRIBUTE_ARCHIVE

        These attributes are used in search operations (SMB_COM_SEARCH, SMB_COM_FIND, SMB_COM_FIND_UNIQUE (section 2.2.4.60), and TRANS2_FIND_FIRST2 (section 2.2.6.2)) to select the specific set of attributes that a file needs to have in order to be included in the results of the search. A file MUST have all of the attributes that match (by name) in order to be listed in the search results. For example:

      • If SMB_SEARCH_ATTRIBUTE_HIDDEN is set in the SearchAttributes field, then files without the SMB_FILE_ATTRIBUTE_HIDDEN atttribute will be rejected.

      • If SMB_SEARCH_ATTRIBUTE_READONLY and SMB_SEARCH_ATTRIBUTE_ARCHIVE are set, files that do not have both the  SMB_FILE_ATTRIBUTE_READONLY and the SMB_FILE_ATTRIBUTE_ARCHIVE attributes set will be rejected.

        If no exclusive search attributes are set, then no files are rejected from being listed.

  • The response is formatted as specified in 2.2.4.58. The number of search result entries sent in the response is the minimum of:

    • The number of entries found.

    • The value of  the MaxCount field in the request.

    • The number of entries that can be fit into the response without exceeding the Server.Connection.ClientMaxBufferSize ADM element limit.

  • If, after composing the response, there are still additional entries available to be sent, the server MUST create a search context. If the number of entries in the Server.Connection.SearchOpenTable ADM element is greater than or equal to the Server.MaxSearches ADM element, the server MUST fail the request with STATUS_OS2_NO_MORE_SIDS. Otherwise, the server MUST allocate a SearchOpen object and insert it into the Server.Connection.SearchOpenTable ADM element. The following values MUST be set by the server:

    • Server.SearchOpen.MID: The value of the MID field from the SMB Header of the client request.

    • Server.SearchOpen.PID: The value of the PID from the SMB Header of the client request.

    • Server.SearchOpen.TID: The value of the TID field from the SMB Header of the client request.

    • Server.SearchOpen.UID: The value of the UID field from the SMB Header of the client request.

    • Server.SearchOpen.FindSID: A newly generated Search ID (SID) value, as specified in section 2.2.1.6.5.

    • Server.SearchOpen.PathName: The FileName field from the client request with its final component removed.

The response MUST be sent to the client as specified in section 3.3.4.1.

If this is the continuation of a previous search:

  • Using the UID, TID, PID, and MID, the Server.Connection.SearchOpenTable ADM element is scanned for a matching search context. If no matching search context is found, the server returns an error response with a Status value of STATUS_NO_MORE_FILES (ERRDOS/ERRnofiles). This indicates that the end of the search has been reached.

  • If the search context is found, then a new response is created containing the next set of entries to be sent to the client. The search is resumed based upon search location indicated by the ResumeKey field in the request. The response MUST be sent to the client as specified in section 3.3.4.1.

Unlike the SMB_COM_FIND command, the SMB_COM_SEARCH command has no matching Close operation to allow the client to explicitly close an incomplete search. Search contexts created by the SMB_COM_SEARCH command MUST be closed and removed from the Server.Connection.SearchOpenTable ADM element when the end of the search is reached (no more matching files are found), and whenever the PID that created the context is closed. A PID is closed with an SMB_COM_PROCESS_EXIT (section 2.2.4.18). If the TID in which the search is being performed is closed (with an SMB_COM_TREE_DISCONNECT (section 2.2.4.51) or a similar command), the search context MUST also be closed. The server SHOULD also periodically purge unused search contexts by using the Unused Open Search Timer (section 3.3.2.3), if implemented, or close the least recently used search context when a new search is received and the server is out of resources to process it.<311>

If a search continuation request arrives after the search context has been purged, the client receives an error response with a Status of STATUS_NO_MORE_FILES (ERRDOS/ERRnofiles), which is the same as the value returned if the end of search has been reached.<312>