Share via

3.1.4.10 NetrShareGetInfo (Opnum 16)

  • Article

The NetrShareGetInfo method retrieves information about a particular shared resource on the server from the ShareList.

 NET_API_STATUS NetrShareGetInfo(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in, string] WCHAR* NetName,
   [in] DWORD Level,
   [out, switch_is(Level)] LPSHARE_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 ([C706] sections 4.3.5 and 5.1.5.2). If this parameter is NULL, the local computer is used.

NetName: A pointer to a null-terminated UTF-16 string that specifies the name of the share to return information for.

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

Value

Meaning

0

LPSHARE_INFO_0

1

LPSHARE_INFO_1

2

LPSHARE_INFO_2

501

LPSHARE_INFO_501

502

LPSHARE_INFO_502_I

503

LPSHARE_INFO_503_I

1005

LPSHARE_INFO_1005

InfoStruct: This parameter is of type LPSHARE_INFO union, as specified in section 2.2.3.6. Its contents are determined by the value of the Level parameter, as shown in the preceding 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.

0x0000007C

ERROR_INVALID_LEVEL

The system call level is not correct.

0x00000057

ERROR_INVALID_PARAMETER

The client request failed because the specified parameter is invalid.

0x00000008

ERROR_NOT_ENOUGH_MEMORY

Not enough storage is available to process this command.

0x0000084B

NERR_BufTooSmall

The supplied buffer is too small.

0x00000906

NERR_NetNameNotFound

The share name does not exist.

If ServerName does not match any Transport.ServerName in TransportList with the SVTI2_SCOPED_NAME bit set in Transport.Flags, the server MUST reset ServerName as "*".

The server MUST remove any preceding "\\" from the parameter ServerName and normalize the ServerName parameter as specified in section 3.1.6.8, passing in the updated ServerName parameter as the ServerName, and an empty string as the ShareName.

The NetName parameter specifies the name of the share for which to return information. This MUST be a nonempty null-terminated UTF-16 string; otherwise, the server MUST fail the call with an ERROR_INVALID_PARAMETER error code.

The value of the Level parameter can be 0, 1, 2, 501, 502, 503, or 1005. If the value of the Level parameter is anything else, the server MUST fail the call with an ERROR_INVALID_LEVEL error code. The value of the Level parameter determines the format of the InfoStruct parameter.

The server MUST locate a Share from ShareList, where NetName matches Share.ShareName and the normalized ServerName matches Share.ServerName. If no share is found, the server MUST fail the call with NERR_NetNameNotFound error code. If a matching Share is found, the server MUST query share properties by invoking the underlying server events as specified in [MS-CIFS] section 3.3.4.12 or [MS-SMB] section 3.3.4.7, and [MS-SMB2] section 3.3.4.16, providing the tuple <normalized server name, NetName> as the input parameter. When the server receives STATUS_SUCCESS for a share, it MUST consider the received SHARE_INFO_503_I and SHARE_INFO_1005 structures as valid. The server MUST return information about the shared resource on the server.

The server MUST use the share in valid SHARE_INFO_503_I and SHARE_INFO_1005 structures from either CIFS or SMB2 servers and fill the return structures as follows. The server MUST discard the structures received from other file server except the value of share.shi503_current_uses.

If the value of the Level parameter is 0, the server MUST return information about the share by filling the SHARE_INFO_0 structure in the ShareInfo0 member of the InfoStruct parameter.

  • shi0_netname MUST be set to share.shi503_netname.

If the value of the Level parameter is 1, the server MUST return information about the share by filling the SHARE_INFO_1 structure in the ShareInfo1 member of the InfoStruct parameter.

  • shi1_netname MUST be set to share.shi503_netname.

  • shi1_type MUST be set to share.shi503_type.

  • shi1_remark MUST be set to share.shi503_remark.

If the value of the Level parameter is 2, the server MUST return information about the share by filling the SHARE_INFO_2 structure in the ShareInfo2 member of the InfoStruct parameter.

  • shi2_netname MUST be set to share.shi503_netname.

  • shi2_type MUST be set to share.shi503_type.

  • shi2_remark MUST be set to share.shi503_remark.

  • shi2_permissions MUST be set to share.shi503_permissions.

  • shi2_max_uses MUST be set to share.shi503_max_uses.

  • shi2_current_uses MUST be set to the sum of share.shi503_current_uses values retrieved from both CIFS and SMB2 servers.

  • shi2_path MUST be set to share.shi503_path.

  • shi2_passwd MUST be set to share.shi503_passwd.

If the value of the Level parameter is 501, the server MUST return information about the share by filling the SHARE_INFO_501 structure in the ShareInfo501 member of the InfoStruct parameter.

  • shi501_netname MUST be set to share.shi503_netname.

  • shi501_type MUST be set to share.shi503_type.

  • shi501_remark MUST be set to share.shi503_remark.

  • shi501_flags MUST be set to share.ShareFlags.

If the value of the Level parameter is 502, the server MUST return information about the share by filling the SHARE_INFO_502_I structure in the ShareInfo502 member of the InfoStruct parameter.

  • shi502_netname MUST be set to share.shi503_netname.

  • shi502_type MUST be set to share.shi503_type.

  • shi502_remark MUST be set to share.shi503_remark.

  • shi502_permissions MUST be set to share.shi503_permissions.

  • shi502_max_uses MUST be set to share.shi503_max_uses.

  • shi502_current_uses MUST be set to the sum of share.shi503_current_uses values retrieved from both CIFS and SMB2 servers.

  • shi502_path MUST be set to share.shi503_path.

  • shi502_passwd MUST be set to share.shi503_passwd.

  • shi502_security_descriptor MUST be set to share.shi503_security_descriptor.

If the value of the Level parameter is 503, the server MUST return information about the share in the SHARE_INFO_503_I structure by filling the SHARE_INFO_503_I structure in the ShareInfo503 member of the InfoStruct parameter, except that shi503_current_uses MUST be set to the sum of share.shi503_current_uses values retrieved from both CIFS and SMB2 servers.

The server MUST set the STYPE_CLUSTER_FS, STYPE_CLUSTER_SOFS, and STYPE_CLUSTER_DFS bits of the shi*_type field to zero; the client MUST ignore them on receipt.

If the value of the Level parameter is 1005, the server MUST return information about the share in the SHARE_INFO_1005 structure directly by filling the SHARE_INFO_1005 structure in the ShareInfo1005 member of the InfoStruct parameter.

If both the SMB server and the SMB2 server return an error, the server MUST fail the call with NERR_NetNameNotFound error code.

The server SHOULD<61> 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<62> fail the call.