3.1.4.2 NetrFileEnum (Opnum 9)

  • Article

The NetrFileEnum method MUST return information about some or all open files on a server, depending on the parameters specified, or return an error code.

 NET_API_STATUS NetrFileEnum(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in, string, unique] WCHAR* BasePath,
   [in, string, unique] WCHAR* UserName,
   [in, out] PFILE_ENUM_STRUCT InfoStruct,
   [in] DWORD PreferedMaximumLength,
   [out] DWORD* TotalEntries,
   [in, out, unique] DWORD* ResumeHandle
 );

ServerName: An SRVSVC_HANDLE (section 2.2.1.1) pointer that identifies the server. The client MUST map this structure to an RPC binding handle (see [C706] sections 4.3.5 and 5.1.5.2). The server MUST ignore this parameter.

BasePath: A pointer to a null-terminated UTF-16 string that specifies a path component.

UserName: A pointer to a null-terminated UTF-16 string that specifies the name of a user.

InfoStruct: A pointer to a structure, in the format of a FILE_ENUM_STRUCT. The FILE_ENUM_STRUCT structure has a Level field that specifies the type of structure to return. The Level member MUST be one of the values specified in section 2.2.4.10.

PreferedMaximumLength: Specifies the preferred maximum length, in bytes, of returned data. If the value that is specified is MAX_PREFERRED_LENGTH, the method MUST attempt to return all entries.

TotalEntries: The total number of entries that could have been enumerated if the buffer had been big enough to hold all the entries.

ResumeHandle: A pointer to a value that contains a handle that is used to continue an Open connection search. The handle MUST be zero on the first call and left unchanged for subsequent calls. If ResumeHandle is NULL, a resume handle MUST NOT be stored. If this parameter is not NULL and the method returns ERROR_MORE_DATA, this parameter receives an implementation-specific nonzero value that can be passed in subsequent calls to this method to continue with the enumeration.

If this parameter is NULL or points to 0x00000000, the enumeration starts from the beginning of the list of the currently active connections.

Return Values: The method returns 0x00000000 (NERR_Success) to indicate success; otherwise, it returns a nonzero error code. The method can take any specific error code value, as specified in [MS-ERREF] section 2.2. The most common error codes are listed in the following table.

Return value/code

Description

0x00000000

NERR_Success

The client request succeeded.

0x00000005

ERROR_ACCESS_DENIED

Access is denied.

0x0000007C

ERROR_INVALID_LEVEL

The system call level is not correct.

0x000000EA

ERROR_MORE_DATA

The client request succeeded. More entries are available. Not all entries could be returned in the buffer size that is specified by PreferedMaximumLength.

0x00000008

ERROR_NOT_ENOUGH_MEMORY

Not enough storage is available to process this command.

0x0000084B

NERR_BufTooSmall

The client request succeeded. More entries are available. The buffer size that is specified by PreferedMaximumLength was too small to fit even a single entry.

In response to a NetrFileEnum message, the server MUST enumerate Open entries in FileList based on the value of the ResumeHandle parameter. For each entry, the server MUST query open properties by invoking the underlying server events as specified in [MS-CIFS] section 3.3.4.16 and [MS-SMB2] section 3.3.4.20, providing Open.GlobalFileId as the input parameter. When the server receives STATUS_SUCCESS for an Open.GlobalFileId from either a CIFS or SMB2 server, the server MUST consider the received FILE_INFO_3 structure as valid, and the server MUST continue to query all other open entries on the server. The server MUST then return the information about some or all valid open entries on a server, depending on the qualifier parameters that are specified.

The BasePath parameter specifies a qualifier for the returned information. If this parameter is not NULL, the server MUST return only those FILE_INFO_3 structures received from CIFS and SMB2 servers, where the field fi3_path_name contains BasePath as the prefix. (A prefix is the path component up to a backslash.) If the BasePath parameter is not NULL and if the length of the BasePath string, including the terminating null character, is greater than 1,024, the server MUST fail the call with ERROR_INVALID_PARAMETER.

The UserName parameter MUST specify the name of a user. If this parameter is specified, the server MUST return only those FILE_INFO_3 structures received from CIFS and SMB2 servers where the field fi3_username  matches UserName. If the UserName parameter is not NULL and if the length of the UserName string, including the terminating null character, is greater than 1,024, the server MUST fail the call with ERROR_INVALID_PARAMETER.

The BasePath and UserName parameters have no role in determining the value of ResumeHandle. The server uses the ResumeHandle parameter to start the enumeration (as described in the rules that follow for processing the ResumeHandle parameter), and then applies these qualifier parameters, if specified, to restrict the returned results to only those items that pass the qualifier test (as described previously in this topic for BasePath and UserName) for returned information.

The InfoStruct parameter has a Level member. The valid values of Level are 2 and 3. If the Level member is not equal to one of the valid values, the server MUST fail the call with ERROR_INVALID_LEVEL.

The server MUST fill the return structures as follows.

If the Level member is 2, the server MUST return the information about Opens by filling the FILE_INFO_2_CONTAINER structure in the FileInfo field of the InfoStruct parameter as follows. The FILE_INFO_2_CONTAINER structure contains an array of FILE_INFO_2 structures.

  • fi2_id MUST be set to open.fi3_id.

If the Level member is 3, the server MUST return Opens directly by filling the FILE_INFO_3_CONTAINER structure in the FileInfo field of the InfoStruct parameter. The FILE_INFO_3_CONTAINER structure contains an array of FILE_INFO_3 structures.

The PreferedMaximumLength parameter specifies the maximum number of bytes that the server can return for the FileInfo buffer.

If PreferedMaximumLength is insufficient to hold all the entries, the server MUST return the maximum number of entries that will fit in the FileInfo buffer and return ERROR_MORE_DATA. If this parameter is equal to MAX_PREFERRED_LENGTH, the server MUST return all the requested data.

If the server returns NERR_Success or ERROR_MORE_DATA, it MUST set the TotalEntries parameter equal to the total number of entries passing the qualifier filter (BasePath or UserName) that could have been enumerated from the current resume position.

If the PreferedMaximumLength is insufficient to hold all the entries and if the client has specified a ResumeHandle, the server MUST set ResumeHandle to some implementation-specific value that allows the server to continue with this enumeration on a subsequent call to this method with the same value for ResumeHandle.

The following rules specify processing of the ResumeHandle parameter:

  • If the ResumeHandle parameter is either NULL or points to 0x00000000, the enumeration MUST start from the beginning of the FileList.

  • If the ResumeHandle parameter points to a nonzero value, the server MUST validate the  ResumeHandle.

    • If the value of ResumeHandle is less than the size of the FileList, the server MUST continue enumeration based on the value of ResumeHandle. The value of ResumeHandle specifies the index into the FileList after which enumeration is to begin.

    • If the value of ResumeHandle is greater than or equal to the size of the FileList, the server MUST return NERR_Success and zero entries.

  • If the client specified a ResumeHandle and if the server returns ERROR_MORE_DATA (0x000000EA), the server MUST set the ResumeHandle to the index of the last enumerated file open in the FileList.

Because the ResumeHandle specifies the index into the FileList, and the FileList can be modified between multiple requests, the results of a query spanning multiple requests using the ResumeHandle can be unreliable, offering either duplicate or missed open files.

The server SHOULD<46> enforce security measures to verify that the caller has the required permissions to execute this routine. If the caller does not have the required credentials, the server SHOULD<47> fail the call.