3.2.4.27 Application Requests a Directory Enumeration

  • Article

The application provides the following:

  • A Client.TreeConnect indicating the share within which the directory resides.

  • The pathname of the directory to query, relative to Client.TreeConnect.ShareName.

  • A valid Client.Session.

  • A wildcard qualifier to select the file names to return.

  • A set of attribute flags that further qualify the list of file names to return.

  • An Information Level that defines the format of the data to return.

  • The number of results to return.

  • A set of flags used to request that the server manage the transaction state based on how the client attempts to traverse results.

  • A MASK specifying whether the search is for directories or for files.

  • If the Information Level provided is SMB_INFO_QUERY_EAS_FROM_LIST, the application provides a list of extended attributes.

The client can use any of the following commands to enumerate the directory entries matching the application's criteria:

  • SMB_COM_SEARCH (deprecated) (section 2.2.4.58)

    The client MUST construct the SMB_COM_SEARCH request message as defined in section 2.2.4.58.1. The FileName field is the full directory path (relative to the TID) of the file(s) being sought. The final component of the path MAY contain wildcards. This string MAY be the empty string. The SearchAttributes field is an attribute mask used to specify the standard attributes that a file MUST have to match the search. If the value of this field is 0x0000, only normal files are returned. If the Volume Label attribute is set, then the volume label MUST be the only name returned (the Volume Label attribute is exclusive). If the Directory, System, or Hidden attributes are specified, those entries are requested in addition to the normal files.

    There is no Close operation associated with the SMB_COM_SEARCH. The client provides the server with no direct indication that the search is complete unless the client continues the search until the last matching entry has been returned.

    An SMB_COM_PROCESS_EXIT request from the client closes an incomplete search. Disconnecting the Client.TreeConnect within which the search is active also closes the search.

  • SMB_COM_FIND (deprecated)

    The client MUST construct the SMB_COM_FIND request message as defined in section 2.2.4.59.1. The format and operation of SMB_COM_FIND is identical to that of SMB_COM_SEARCH, except that the search MAY be closed using the SMB_COM_FIND_CLOSE command, which provides a specific indication to the server that the search has been completed.

  • SMB_COM_FIND_UNIQUE (deprecated)

    The client MUST construct the SMB_COM_FIND_UNIQUE request message as defined in section 2.2.4.60.1. The format and operation of SMB_COM_FIND_UNIQUE is identical to that of SMB_COM_FIND. The former performs an implicit close on the search operation so that no SMB_COM_FIND_CLOSE is needed. The SMB_COM_FIND_UNIQUE returns only the results that can fit within a single response.

  • TRANS2_FIND_FIRST2

    The client MUST construct the TRANS2_FIND_FIRST2 request message as defined in section 2.2.6.2.1. If the search is incomplete following the first response from the server, the client MAY continue the search using a TRANS2_FIND_NEXT2 request as defined in section 2.2.6.3.1. These requests MUST be transported to the server using the Transaction2 subprotocol. If the search finds no names that match the client request, or if the continuation of the search finds no more names that match the client request:

    • The server returns STATUS_NO_MORE_FILES as a 32-bit error code if the client set SMB_FLAGS2_NT_STATUS in the Flags2 field of the client request.

    • The server returns ERRDOS/ERRnofiles as an SMBSTATUS if SMB_FLAGS2_NT_STATUS is NOT set in the Flags2 field of the client request.

      Note that these return codes are not considered errors in this case.

The request MUST be sent to the server as described in section 3.2.4.1.