3.1.4.36 NetrDfsCreateLocalPartition (Opnum 44)

  • Article

The NetrDfsCreateLocalPartition method marks a share as being a DFS share. In addition, if the RelationInfo parameter is non-NULL, it creates DFS links, as specified in [MS-DFSC], for each of the entries in the RelationInfo parameter. An implementation MAY<132> choose to support this method.

 NET_API_STATUS NetrDfsCreateLocalPartition(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in, string] WCHAR* ShareName,
   [in] GUID* EntryUid,
   [in, string] WCHAR* EntryPrefix,
   [in, string] WCHAR* ShortName,
   [in] LPNET_DFS_ENTRY_ID_CONTAINER RelationInfo,
   [in] int Force
 );

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.

ShareName: A pointer to a null-terminated UTF-16 string that specifies the name of a local disk share on the server to add to DFS.

EntryUid: A pointer to a GUID type that specifies the GUID for this DFS share. The GUID for this share MUST NOT match a GUID for an existing local partition.<133>

EntryPrefix: A pointer to a null-terminated UTF-16 string that specifies the path of the DFS share.

ShortName: A pointer to a null-terminated UTF-16 string that specifies the short-name version (8.3 format) of the EntryPrefix parameter.

RelationInfo: A pointer to a NET_DFS_ENTRY_ID_CONTAINER structure. Specifies the DFS child links that are under the DFS share that is specified by the EntryPrefix parameter.

Force: The Force parameter is ignored and MUST be set to zero.

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.

In response to a NetrDfsCreateLocalPartition message, the server SHOULD<134> choose to perform no processing and return an implementation-specific error code when this method is called. If the server supports DFS, the server MAY mark an existing SMB file share as a DFS share that enables it to be accessed by using DFS, as specified in [MS-DFSC].

The ShareName parameter MUST specify the name of an existing SMB file share of type STYPE_DISKTREE (for more information, see Share Types (section 2.2.2.4)), or the server MUST fail the call with an ERROR_BAD_NET_NAME error code if the share is not present. If the share is present, but not of type STYPE_DISKTREE, it MUST fail with an ERROR_BAD_DEV_TYPE error code.

The EntryUid parameter specifies the GUID that the server MUST assign to the new DFS share.

This parameter MUST NOT be NULL, or the server MUST fail the call with an ERROR_INVALID_PARAMETER error code. If the EntryUid parameter matches a GUID for an existing local partition, the server MUST fail the call with an ERROR_INVALID_PARAMETER error code.

The EntryPrefix parameter specifies the path of the DFS share. This string MUST be in one of the following two forms:

  • The first form is \Dfsname\sharename, where Dfsname is the name of the storage server that hosts the root of a standalone DFS implementation; and sharename is the name of a shared folder that is published on the DFS host server.

  • The second form is \DomainName\DomDfsname, where DomainName is the name of the domain that hosts the DFS root; and DomDfsname is the name of the root of a domain-based DFS implementation that is published in the directory service of the domain.

The RelationInfo parameter specifies the DFS child links to create under the share that is specified by EntryPrefix. It has a member count that specifies the number of child links and a Buffer member that is an array of the Count structure of type NET_DFS_ENTRY_ID. A DFS child link MUST be created for each entry in the Buffer. The RelationInfo parameter MUST not be NULL, or the server MUST fail the call with an ERROR_INVALID_PARAMETER error code.

The ShortName parameter specifies a share name (in the 8.3 format) that is specified by EntryPrefix and MUST be interpreted by the server in an implementation-specific manner.<135>

The Force parameter is ignored and MUST be zero.

The server MAY<136> enforce security measures to verify that the caller has the required permissions to execute this call. If the server enforces these security measures and the caller does not have the required credentials, the server SHOULD<137> fail the call.