3.1.4.11 NetrShareSetInfo (Opnum 17)

  • Article

The NetrShareSetInfo method sets the parameters of a shared resource in a ShareList.

 NET_API_STATUS NetrShareSetInfo(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in, string] WCHAR* NetName,
   [in] DWORD Level,
   [in, switch_is(Level)] LPSHARE_INFO ShareInfo,
   [in, out, unique] DWORD* ParmErr
 );

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 set information for.

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

Value

Meaning

1

LPSHARE_INFO_1

2

LPSHARE_INFO_2

502

SHARE_INFO_502_I

503

SHARE_INFO_503_I

1004

LPSHARE_INFO_1004

1005

LPSHARE_INFO_1005

1006

LPSHARE_INFO_1006

1501

LPSHARE_INFO_1501_I

ShareInfo: 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. This parameter MUST NOT contain a null value. If the Level parameter is equal to 1, 2, 502, or 503, the client MUST set the STYPE_CLUSTER_FS, STYPE_CLUSTER_SOFS, and STYPE_CLUSTER_DFS bits in the shi*_type field of the SHARE_INFO union to zero; the server MUST ignore them on receipt.

ParmErr: A pointer to a value that receives the index of the first member of the share information structure that caused the ERROR_INVALID_PARAMETER error, if it occurs.

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.

0x00000057

ERROR_INVALID_PARAMETER

The client request failed because the specified parameter is invalid. For details, see the description that follows for the ParmErr parameter.

0x00000008

ERROR_NOT_ENOUGH_MEMORY

Not enough storage is available to process this command.

0x00000906

NERR_NetNameNotFound

The share name does not exist.

0x00000032

ERROR_NOT_SUPPORTED

The server does not support branch cache. <63>

0x00000424

ERROR_SERVICE_DOES_NOT_EXIST

The branch cache component does not exist as an installed service. <64>

0x0000007C

ERROR_INVALID_LEVEL

The system call level is not correct.

In response to a NetrShareSetInfo message, the server MUST set the parameters of a shared resource or return an error code.

The NetName parameter specifies the name of the share for which to set information in ShareList. The NetName 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 1, 2, 502, 503, 1004, 1005, 1006, or 1501. 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.

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 ServerName parameter 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 server MUST validate all information that is provided in the SHARE_INFO structure. If a member of the SHARE_INFO structure is found to be invalid, the server MUST fail the call with an ERROR_INVALID_PARAMETER error code. The server does the following validation on the SHARE_INFO structure:

  • If shi*_type has the flag STYPE_SPECIAL, a security descriptor MUST NOT be specified in shi502_security_descriptor (Level = 502).

  • If shi*_remark is specified, its length MUST NOT be greater than 48.

  • If Level=502 and a security descriptor is provided, it MUST be a valid security descriptor.

If the ParmErr parameter is not NULL and the server finds a member of the SHARE_INFO structure to be invalid, the server MUST set ParmErr to a value that denotes the index of the member that was found to have an invalid value and fail the call with ERROR_INVALID_PARAMETER (0x00000057). The mapping between the values to set and the corresponding member MUST be as specified in section 2.2.2.11.

The server MUST locate a Share from ShareList, where NetName matches Share.ShareName and ServerName matches Share.ServerName. If no share is found, the server MUST fail the call with a NERR_NetNameNotFound error code.

If a matching share is found, the server MUST construct a SHARE_INFO_503_I structure and a SHARE_INFO_1005 structure from the share, as specified in section 3.1.3.

The server MUST update the members of SHARE_INFO_503_I and SHARE_INFO_1005 structures based on the Level parameter, as follows:

If the Level parameter is equal to 1, all the settings that are defined by the SHARE_INFO_1 structure as settable (that is, they are not defined as ignored on receipt or ignored for the NetrShareSetInfo method) MUST be updated. The share properties MUST be updated as follows:

  • SHARE_INFO_503_I.shi503_remark MUST be set to shi1_remark.

If the Level parameter is equal to 2, all the settings that are defined by the SHARE_INFO_2 structure as settable (that is, they are not defined as ignored on receipt or ignored for the NetrShareSetInfo method) MUST be updated. The share properties MUST be updated as follows:

  • SHARE_INFO_503_I.shi503_remark MUST be set to shi2_remark.

  • SHARE_INFO_503_I.shi503_max_uses MUST be set to shi2_max_uses.

If the Level parameter is equal to 502, all the settings that are defined by the SHARE_INFO_502_I structure as settable (that is, they are not defined as ignored on receipt or ignored for the NetrShareSetInfo method) MUST be updated. The share properties MUST be updated as follows:

  • SHARE_INFO_503_I.shi503_remark MUST be set to shi502_remark.

  • SHARE_INFO_503_I.shi503_max_uses MUST be set to shi502_max_uses.

  • SHARE_INFO_503_I.shi503_security_descriptor MUST be set to shi502_security_descriptor.

If the Level parameter is equal to 503, all the settings that are defined by the SHARE_INFO_503_I structure as settable (that is, they are not defined as ignored on receipt or ignored for the NetrShareSetInfo method) MUST be updated. The share properties MUST be updated as follows:

  • SHARE_INFO_503_I.shi503_remark MUST be set to shi503_remark.

  • SHARE_INFO_503_I.shi503_max_uses MUST be set to shi503_max_uses.

  • SHARE_INFO_503_I.shi503_security_descriptor MUST be set to shi503_security_descriptor.

If the Level parameter is equal to 1004, all the settings that are defined by the SHARE_INFO_1004 structure as settable (that is, they are not defined as ignored on receipt or ignored for the NetrShareSetInfo method) MUST be updated.

  • SHARE_INFO_503_I.shi503_remark MUST be set to shi1004_remark.

If the Level parameter is equal to 1005, all the settings that are defined by the SHARE_INFO_1005 structure as settable (that is, they are not defined as ignored on receipt or ignored for the NetrShareSetInfo method) MUST be updated. Only disk shares can be affected by this Level. The share MUST be updated as follows:<65>

  • SHARE_INFO_1005.shi1005_flags MUST be set to shi1005_flags.

If the Level parameter is equal to 1006, all the settings that are defined by the SHARE_INFO_1006 structure as settable (that is, they are not defined as ignored on receipt or ignored for the NetrShareSetInfo method) MUST be updated. The share properties are updated as follows:

  • SHARE_INFO_503_I.shi503_max_uses MUST be set to shi1006_max_uses.

If the Level parameter is equal to 1501, all the settings that are defined by the SHARE_INFO_1501_I structure as settable (that is, they are not defined as ignored on receipt or ignored for the NetrShareSetInfo method) MUST be updated. The share properties MUST be updated as follows:

  • SHARE_INFO_503_I.shi503_security_descriptor MUST be set to shi1501_security_descriptor.

The server MUST invoke the underlying server events as specified in [MS-CIFS] section 3.3.4.10 or [MS-SMB] section 3.3.4.6 and [MS-SMB2] section 3.3.4.14, providing the updated SHARE_INFO_503_I structure and the updated SHARE_INFO_1005 structure as input parameters.

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

If only one of the SMB and SMB2 servers returns STATUS_SUCCESS:

  • The server MUST construct a new SHARE_INFO_503_I structure and a new SHARE_INFO_1005 structure from the Share, as specified in section 3.1.3.

  • The server MUST revert the updates made to the share on the server that returned STATUS_SUCCESS by invoking the underlying server event (as specified in [MS-CIFS] section 3.3.4.10, [MS-SMB] section 3.3.4.6, or [MS-SMB2] section 3.3.4.14), providing the SHARE_INFO_503_I structure and the SHARE_INFO_1005 structure as input parameters.

  • The server MUST return ERROR_INVALID_DATA to the caller.

If both the SMB and the SMB2 servers return STATUS_SUCCESS, the server MUST update the Share as follows and return NERR_Success to the caller:

  • If the Level parameter is equal to 1, 2, 502, 503, or 1004, Share.Remark MUST be set to shi*_remark.

  • If the Level parameter is equal to 2, 502, 503, or 1006, Share.MaxUses MUST be set to shi*_max_uses.

  • If the Level parameter is equal to 502, 503, or 1501, Share.FileSecurity MUST be set to shi*_security_descriptor if Level is equal to 502 or 503; otherwise, it MUST be set to NULL.

  • If the Level parameter is equal to 1005:

    • Share.CscFlags MUST be set to the value of shi1005_flags masked by CSC_MASK as specified in section 2.2.4.29.

    • Share.IsDfs MUST be set to TRUE if shi1005_flags contains SHI1005_FLAGS_DFS or SHI1005_FLAGS_DFS_ROOT as specified in section 2.2.4.29; otherwise, it MUST be set to FALSE.

    • Share.DoAccessBasedDirectoryEnumeration MUST be set to TRUE if shi1005_flags contains SHI1005_FLAGS_ACCESS_BASED_DIRECTORY_ENUM bit as specified in section 2.2.4.29; otherwise it MUST be set to FALSE.

    • Share.AllowNamespaceCaching MUST be set to True if shi1005_flags contains SHI1005_FLAGS_ALLOW_NAMESPACE_CACHING bit as specified in section 2.2.4.29; otherwise, it MUST be set to FALSE.

    • Share.ForceSharedDelete MUST be set to TRUE if shi1005_flags contains SHI1005_FLAGS_FORCE_SHARED_DELETE bit as specified in section 2.2.4.29; otherwise, it MUST be set to FALSE.

    • Share.RestrictExclusiveOpens MUST be set to TRUE if shi1005_flags contains SHI1005_FLAGS_RESTRICT_EXCLUSIVE_OPENS bit as specified in section 2.2.4.29; otherwise, it MUST be set to FALSE.

    • Share.HashEnabled MUST be set to TRUE if shi1005_flags contains SHI1005_FLAGS_ENABLE_HASH bit as specified in section 2.2.4.29; otherwise it MUST be set to FALSE.

    • Share.ForceLevel2Oplock MUST be set to TRUE if shi1005_flags contains SHI1005_FLAGS_FORCE_LEVELII_OPLOCK bit as specified in section 2.2.4.29; otherwise, it MUST be set to FALSE.

The server SHOULD<66> 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<67> fail the call.