3.1.4.42 NetrDfsFixLocalVolume (Opnum 51)

  • Article

The NetrDfsFixLocalVolume method provides knowledge of a new DFS share on the server. An implementation MAY<159> choose to support this method.

 NET_API_STATUS NetrDfsFixLocalVolume(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in, string] WCHAR* VolumeName,
   [in] unsigned long EntryType,
   [in] unsigned long ServiceType,
   [in, string] WCHAR* StgId,
   [in] GUID* EntryUid,
   [in, string] WCHAR* EntryPrefix,
   [in] LPNET_DFS_ENTRY_ID_CONTAINER RelationInfo,
   [in] unsigned long CreateDisposition
 );

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.

VolumeName: A pointer to a null-terminated UTF-16 string that specifies the target for the DFS root share. This target MUST be local to the server; for example, \??\C:\DfsShare.<160> This target SHOULD NOT contain a directory that is in DFS, and it SHOULD NOT be a child of a DFS share. If the specified volume name is not valid, the server SHOULD fail the call by using an implementation-specific error code.

EntryType: This parameter MUST be one of the values listed in section 2.2.2.13. If the specified entry type is not valid, the server SHOULD fail the call with an implementation-specific error code.

ServiceType: This parameter MUST be a combination of one or more of the following values. If the specified service type is not valid, the server SHOULD fail the call with an implementation-specific error code.

Value

Meaning

DFS_SERVICE_TYPE_MASTER

0x00000001

Master service

DFS_SERVICE_TYPE_READONLY

0x00000002

Read-only service

DFS_SERVICE_TYPE_LOCAL

0x00000004

Local service

DFS_SERVICE_TYPE_REFERRAL

0x00000008

Referral service

DFS_SERVICE_TYPE_ACTIVE

0x000000010

Active service

DFS_SERVICE_TYPE_DOWN_LEVEL

0x000000020

Down-level service

DFS_SERVICE_TYPE_COSTLIER

0x000000040

Costlier service than previous

DFS_SERVICE_TYPE_OFFLINE

0x000000080

Service is offline

StgId: A pointer to a variable that specifies an ID for the local storage. The server MUST ignore the value that is passed in for the StgId parameter.

EntryUid: Specifies the GUID that corresponds to the DFS share. This GUID MUST be obtained by using the NetrDfsGetInfo (Opnum 4) method, which is specified in [MS-DFSNM] section 3.1.4.1.6.

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

RelationInfo: A pointer to a NET_DFS_ENTRY_ID_CONTAINER structure as specified in section 2.2.4.108. Specifies the DFS child links under the DFS share as specified by the EntryPrefix parameter.

CreateDisposition: Specifies what to do, depending on whether the share already exists. This field MUST be set to one of the following values.

Value

Meaning

FILE_SUPERSEDE

0x00000000

If the share already exists, replace it with the specified share. If it does not exist, create the specified share.

FILE_OPEN

0x00000001

If the share already exists, fail the request and do not create or open the specified share. If it does not exist, create the specified share.

FILE_CREATE

0x00000002

If the file already exists, open it instead of creating a new share. If it does not exist, fail the request and do not create a new share.

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 NetrDfsFixLocalVolume message, the server SHOULD<161> 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 add the link name that corresponds to a specified Uid. This message typically is sent by a domain controller when it discovers that the server is completely unaware of a new DFS volume.

The VolumeName parameter specifies the target for the DFS root share. This target MUST be local to the server and is in the form of a Windows NT operating system path name, for example, \??\C:\DfsShare.<162> This target SHOULD NOT contain a directory that is in DFS, and it SHOULD NOT be a child of a DFS share.

The EntryType parameter specifies the type of the link and MUST be one of the values listed in section 2.2.2.13.

The ServiceType parameter specifies the service type of the client.

The StgId parameter specifies an implementation-specific ID for the local storage.

The EntryUid parameter specifies the GUID for the new link.

The Prefix parameter specifies the path of the updated DFS link. The string MUST be in one of two forms:

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

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

The RelationInfo parameter specifies the DFS child links under the DFS share that is specified by EntryPrefix. If this parameter is NULL or if its Count member is nonzero and its Buffer member is NULL, the server fails the call by using an ERROR_INVALID_PARAMETER error code.

The CreateDisposition parameter specifies what MUST happen if a share with the path EntryPrefix already exists.

The server MAY<163> 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<164> fail the call.