3.1.4.4.1 NetrDfsAddStdRoot (Opnum 12)

  • Article

The NetrDfsAddStdRoot (Opnum 12) method creates a new stand-alone DFS namespace.<118><119>

The NetrDfsAddStdRoot method uses the following MIDL syntax.

 NET_API_STATUS NetrDfsAddStdRoot(
   [in, string] WCHAR* ServerName,
   [in, string] WCHAR* RootShare,
   [in, string] WCHAR* Comment,
   [in] DWORD ApiFlags
 );

ServerName: The pointer to a null-terminated Unicode string. This is the host name of the new DFS root target.

RootShare: The pointer to a null-terminated Unicode string. This is the new DFS root target share name as well as the DFS namespace name. The share MUST already exist.

Comment: The pointer to a null-terminated Unicode string that contains a comment associated with the DFS namespace. Used for informational purposes, this string has no protocol-specified restrictions on length or content. The comment is meant for human consumption and does not affect server functionality. This parameter MAY be a NULL pointer.

ApiFlags: This parameter is reserved for future use and is ignored by the server.

Return Values: The method MUST return 0 on success and a nonzero error code on failure. The method can return 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

ERROR_SUCCESS

Successful completion.

0x00000005

ERROR_ACCESS_DENIED

Permission to perform the operation was denied.

0x00000050

ERROR_FILE_EXISTS

The DFS namespace that the ServerName and RootShare parameters specify already exists.<120>

0x000000B7

ERROR_ALREADY_EXISTS

The DFS namespace that the ServerName and RootShare parameters specify already exists.<121>

0x00000906

NERR_NetNameNotFound

The share that the RootShare parameter specifies does not already exist.

On receiving this method, the server MUST do the following:

  • If there is any entry in the NamespaceList with the NamespaceName matching RootShare, then the RPC method MUST fail with either ERROR_FILE_EXISTS (0x00000050) or ERROR_ALREADY_EXISTS (0x000000B7).

  • If the share that the RootShare parameter specifies does not already exist, the RPC method MUST fail with NERR_NetNameNotFound (0x00000906).

  • Create the Namespace object, and insert it into the NamespaceList. The Namespace object MUST be initialized as follows.

    • Namespace.NamespaceName is set to RootShare.

    • Namespace.NamespaceType is set to stand-alone.

    • Namespace.GenerationGUID is set with a GUID.

    • Create a NamespaceElement object and insert it into Namespace.NamespaceElementsList.

    • NamespaceElementsList.NamespaceElement is initialized as follows.

      • NamespaceElement.Properties is set to 0.

      • NamespaceElement.State is set to DFS_VOLUME_STATE_OK.

      • NamespaceElement.Comment is set to Comment.

      • NamespaceElement.ReferralTTL is set to 300 seconds.

      • NamespaceElement.SecurityDescriptor is set to none.

      • Create a Target object, insert it into NamespaceElement.TargetsList and update TargetsList.TargetCount to 1.

      • TargetsList.Target object is initialized as follows.

        • Target.PriorityRank is set to 0.

        • Target.PriorityClass is set to DfsSiteCostNormalPriorityClass.

        • Target.State is set to DFS_STORAGE_STATE_ONLINE.

        • Target.ServerName is set to ServerName.

        • Target.ShareName is set to RootShare.

  • The server MUST synchronously insert the Namespace object into the local information store.