3.1.4.3 NetrFileGetInfo (Opnum 10)

  • Article

The NetrFileGetInfo method MUST retrieve information about a particular open server resource or return an error code.

 NET_API_STATUS NetrFileGetInfo(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in] DWORD FileId,
   [in] DWORD Level,
   [out, switch_is(Level)] LPFILE_INFO InfoStruct
 );

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.

FileId: Specifies the file identifier of the open resource to return information for. The value of this parameter MUST have been returned in a previous NetrFileEnum method call.

NOTE: The FileId parameter returned in a previous NetrFileEnum call is not guaranteed to be valid. Therefore, the NetrFileGetInfo method is not guaranteed to succeed based on the validity of the FileId parameter.

Level: Specifies the information level of the data. This parameter MUST have one of the following values.

Value

Meaning

2

FILE_INFO_2

3

FILE_INFO_3

InfoStruct: This parameter is of type LPFILE_INFO, which is defined in section 2.2.3.3. Its contents are determined by the value of the Level member, as shown in the previous parameter table.

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.

0x00000002

ERROR_FILE_NOT_FOUND

The system cannot find the file specified.

0x0000007C

ERROR_INVALID_LEVEL

The system call level is not correct.

0x00000008

ERROR_NOT_ENOUGH_MEMORY

Not enough storage is available to process this command.

0x0000084B

NERR_BufTooSmall

The supplied buffer is too small.

In response to a NetrFileGetInfo message, the server MUST query open properties by invoking underlying server events as specified in [MS-CIFS] section 3.3.4.16 and [MS-SMB2] section 3.3.4.20, providing FileId as the input parameter. When the server receives a non-NULL FILE_INFO_3 structure from either a CIFS or SMB2 server, the server MUST return information about a particular opening of a server resource (file, device, or named pipe). Otherwise, the server MUST fail the call with an ERROR_FILE_NOT_FOUND error code.

The FileId parameter specifies the file identifier of the open resource in FileList to return information for. The value of this parameter MUST have been returned in a previous NetrFileEnum message response by the server.

The Level parameter can be either 2 or 3. If the value of the Level parameter is anything else, the server MUST fail the call with ERROR_INVALID_LEVEL. The value of the Level parameter determines the format of the InfoStruct parameter.

The server MUST retrieve the open in FILE_INFO_3 structure from CIFS and SMB2 servers and fill the return structures as follows.

If the value of the Level parameter is 2, the server MUST return information about the open whose file identifier is FileId by filling the FILE_INFO_2 structure in the FileInfo2 field of the InfoStruct parameter as follows:

  • fi2_id MUST be set to open.fi3_id.

If the value of the Level parameter is 3, the server MUST return the open directly whose fi3_id is equal to FileId.

The server SHOULD<48> 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<49> fail the call.