3.1.4.7 NetrShareAdd (Opnum 14)

  • Articolo

The NetrShareAdd method shares a server resource.

 NET_API_STATUS NetrShareAdd(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in] DWORD Level,
   [in, switch_is(Level)] LPSHARE_INFO InfoStruct,
   [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 (see [C706] sections 4.3.5 and 5.1.5.2). The server MUST ignore this parameter.

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

Value

Meaning

2

The buffer is of type SHARE_INFO_2.

502

The buffer is of type SHARE_INFO_502_I.

503

The buffer is of type SHARE_INFO_503_I.

InfoStruct: A pointer to the SHARE_INFO union. The contents of the InfoStruct parameter depend on the value of the Level parameter. 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 an ERROR_INVALID_PARAMETER error code, 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.

0x0000007C

ERROR_INVALID_LEVEL

The system call level is not correct.

0x0000007B

ERROR_INVALID_NAME

The file name, directory name, or volume label syntax is incorrect.

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.

0x00000846

NERR_DuplicateShare

The share name is already in use on this server.

0x00000844

NERR_UnknownDevDir

The device or directory does not exist.

In response to a NetrShareAdd message, the server MUST share a server resource or return an error code. A shared resource is a local resource on a server (for example, a disk directory, print device, or named pipe) that can be accessed by users and applications on the network.

The Level parameter determines the type of structure that the client has used to specify information about the new share. The value of the Level parameter MUST be 2, 502, or 503. If the Level parameter is not one of the valid values, the server MUST fail the call with an ERROR_INVALID_LEVEL error code.

If the Level parameter is 2, InfoStruct contains a SHARE_INFO_2 structure.

If the Level parameter is 502, InfoStruct contains a SHARE_INFO_502_I structure.

If the Level parameter is 503, InfoStruct contains a SHARE_INFO_503_I structure.

The name of the share to be added is specified in the shi*_netname member of the SHARE_INFO structure. If the specified share name is an empty string, or is a nonempty string of length greater than 80 characters, the server MUST fail the call with an ERROR_INVALID_PARAMETER error code. If the specified share name is "pipe" or "mailslot", the server MUST fail the call with an ERROR_ACCESS_DENIED error code.

If Level is 2 or 502, the server MUST look up the Share in ShareList, where Share.ShareName matches shi*_netname and Share.ServerName matches "*".

If Level is 503, the server MUST look up the Share in ShareList, where Share.ShareName matches shi503_netname and Share.ServerName matches shi503_servername.

If a matching Share is found, the server MUST fail the call with NERR_DuplicateShare.

The server MUST validate all information that is provided in the SHARE_INFO (section 2.2.3.6) structure, and if any SHARE_INFO structure member is found to be invalid, the server MUST fail the call with an ERROR_INVALID_PARAMETER error code.

The server performs the following validation on the structure:

  • shi*_netname must not be a NULL (zero-length) string, and its length must not be greater than 80 characters.

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

  • If shi*_netname specifies an IPC$ or the ADMIN$ share, shi*_path must be NULL; otherwise, shi*_path must be a nonempty string that specifies a valid share path (must not have "." and ".." appear as directory names).

  • If shi*_netname specifies an NT path (begins with "\\?\"), shi*_type must not have a STYPE_DISKTREE flag.

  • If shi*_remark is specified, its length must not be greater than 48.

  • If shi*_ type specifies a STYPE_DISKTREE flag and shi*_netname is not an ADMIN$ share, shi*_path must specify an absolute directory path. If the server does not support shared net drivers (determined by the SERVER_INFO field sv*_enablesharednetdrives), the path must not be on a network drive.

  • If a disk share is being added, the directory to be shared must exist and the caller must have access to it.

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 an ERROR_INVALID_PARAMETER (0x00000057) error code. The mapping between the values to set and the corresponding member is listed in section 2.2.2.11.

If the ParmErr parameter is NERR_Success, the server MUST create a Share and insert it into ShareList with the following fields set:

  • If the STYPE_TEMPORARY field is set in shi*_type, Share.IsPersistent MUST be set to FALSE. Otherwise, Share.IsPersistent MUST be set to TRUE.

  • Share.IsMarkedForDeletion MUST be set to FALSE.

  • Share.IsPrinterShare MUST be set to TRUE if shi*_ type specifies STYPE_PRINTQ flag.

  • Share.ShareName MUST be set to shi*_netname.

  • Share.ServerName MUST be set to shi503_servername if it is specified and if Level is equal to 503; otherwise it MUST be set to "*".

  • Share.LocalPath MUST be set to shi*_path.

  • Share.FileSecurity MUST be set to shi*_security_descriptor if it is specified and if Level is equal to 502 or 503; otherwise it MUST be set to NULL.

  • Share.CscFlags MUST be set to 0.

  • Share.IsDfs MUST be set to FALSE.

  • Share.DoAccessBasedDirectoryEnumeration MUST be set to FALSE.

  • Share.AllowNamespaceCaching MUST be set to FALSE.

  • Share.ForceSharedDelete MUST be set to FALSE.

  • Share.RestrictExclusiveOpens MUST be set to FALSE.

  • Share.Type MUST be set to shi*_type.

  • Share.Remark MUST be set to shi*_remark.

  • Share.MaxUses MUST be set to 0xFFFF if shi*_max_uses is not specified; otherwise it MUST be set to shi*_max_uses.

  • Share.CurrentUses MUST be set to 0.

  • Share.ForceLevel2Oplock MUST be set to FALSE.

If shi*_ type specifies STYPE_PRINTQ flag, PrinterShareCount MUST be increased by 1, and the server MUST invoke the events as specified in section 3.1.6.9, providing SV_TYPE_PRINTQ_SERVER as the input parameter.

The server MUST construct a share in SHARE_INFO_503_I structure as the input parameter to register the share by invoking underlying server event as specified in [MS-CIFS] section 3.3.4.9 and [MS-SMB2] section 3.3.4.13, providing share as the input parameter. The fields in share MUST be set as follows:

  • share.shi503_netname MUST be set to Share.ShareName.

  • share.shi503_type MUST be set to Share.Type.

  • share.shi503_remark MUST be set to Share.Remark.

  • share.shi503_permissions MUST be set to 0.

  • share.shi503_max_uses MUST be set to Share.MaxUses.

  • share.shi503_current_uses MUST be set to 0.

  • share.shi503_path MUST be set to Share.LocalPath.

  • share.shi503_passwd MUST be set to NULL.

  • share.shi503_security_descriptor MUST be set to Share.FileSecurity.

  • share.shi503_servername MUST be set to Share.ServerName.

If either the CIFS or the SMB2 server returns an error:

  • The server MUST remove the Share from ShareList and free the share object.

  • The server MUST invoke the underlying server events as specified in [MS-CIFS] section 3.3.4.11 and [MS-SMB2] section 3.3.4.15, providing tuple <Share.ServerName, Share.ShareName> as input parameters.

  • If the error returned by the CIFS or the SMB2 server is STATUS_INVALID_PARAMETER, then the server MUST fail the call with ERROR_INVALID_DATA (0x0000000D). Otherwise, the server MUST fail the call with NERR_DuplicateShare.

If Share.IsPersistent is TRUE, the server MUST persist the Share to a persistent configuration store. If a share with the same ShareName already exists in the store, the preexisting entry MUST be overwritten with this entry.

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