Platform SDK: Network Management

NetJoinDomain

The NetJoinDomain function joins a computer to a workgroup or domain.

Security Requirements

Joining (and unjoining) a computer to a domain or workgroup can be performed only by a member of the Administrators local group on the target computer. Note that the domain administrator can set additional requirements for joining the domain using delegation and assignment of privileges.

If you call the NetJoinDomain function remotely, you must supply credentials because you cannot delegate credentials under these circumstances.

NET_API_STATUS NetJoinDomain(
  LPCWSTR lpServer,
  LPCWSTR lpDomain,
  LPCWSTR lpAccountOU,
  LPCWSTR lpAccount,
  LPCWSTR lpPassword,
  DWORD fJoinOptions
);

Parameters

lpServer

[in] Pointer to a constant null-terminated character string that specifies the name of the computer on which to call the function. The string must begin with \\. If this parameter is NULL, the local computer is used.

lpDomain

[in] Pointer to a constant null-terminated character string that specifies the name of the domain or workgroup to join.

Optionally, you can specify the preferred domain controller to perform the join operation. In this instance, the string must be of the form DomainName\MachineName, where DomainName is the name of the domain to join, and MachineName is the name of the domain controller to perform the join.

lpAccountOU

[in] Optionally specifies the pointer to a constant null-terminated character string that contains the RFC 1779 format name of the organizational unit (OU) for the computer account. If you specify this parameter, the string must contain a full path, for example, OU=testOU,DC=domain,DC=Domain,DC=com. Otherwise, this parameter must be NULL.

lpAccount

[in] Pointer to a constant null-terminated character string that specifies the account name to use when connecting to the domain controller. The string must specify either a domain NetBIOS name and user account (for example, "REDMOND\user") or the user principal name (UPN) of the user in the form of an Internet-style login name (for example, "someone@microsoft.com"). If this parameter is NULL, the caller's context is used.

lpPassword

[in] If the lpAccount parameter specifies an account name, this parameter must point to the password to use when connecting to the domain controller. Otherwise, this parameter must be NULL.

fJoinOptions

[in] Specifies a DWORD value that contains a set of bit flags defining the join options. This parameter can be one or more of the following values.

Value	Meaning
NETSETUP_JOIN_DOMAIN	Joins the computer to a domain. If this value is not specified, joins the computer to a workgroup.
NETSETUP_ACCT_CREATE	Creates the account on the domain.
NETSETUP_WIN9X_UPGRADE	The join operation is occurring as part of an upgrade of Windows 95/98 to Windows NT/Windows 2000.
NETSETUP_DOMAIN_JOIN_IF_JOINED	Allows a join to a new domain even if the computer is already joined to a domain.
NETSETUP_JOIN_UNSECURE	Performs an unsecured join.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes or one of the Win32 error codes.

Value	Meaning
ERROR_INVALID_PARAMETER	A parameter is incorrect.
ERROR_NO_SUCH_DOMAIN	The specified domain did not exist.
NERR_SetupAlreadyJoined	The computer is already joined to a domain.
NERR_InvalidWorkgroupName	The specified workgroup name is not valid.

Remarks

Different processes, or different threads of the same process, should not call the NetJoinDomain function at the same time. This situation can leave the computer in an inconsistent state.

If you encounter a problem during a join operation, you should not delete a computer account and immediately follow the deletion with another join attempt. This can lead to replication-related problems that are difficult to investigate. When you delete a computer account, wait until the change has replicated to all domain controllers before attempting another join operation.

Requirements