Syntax

uint32 JoinDomainOrWorkgroup(
  [in]            string Name,
  [in]            string Password,
  [in]            string UserName,
  [in, optional]  string AccountOU,
  [in]            uint32 FJoinOptions = 1
);

Parameters

Name [in]

Specifies the domain or workgroup to join. Cannot be NULL.

Password [in]

If the UserName parameter specifies an account name, the Password parameter must point to the password to use when connecting to the domain controller. Otherwise, this parameter must be NULL.

UserName [in]

Pointer to a constant null-terminated character string that specifies the account name to use when connecting to the domain controller. Must specify a domain NetBIOS name and user account, for example, Domain\user. If this parameter is NULL, the caller information is used.

You can also use the user principal name (UPPED) in the form user@domain.

Windows 2000, Windows NT 4.0, and Windows Me/98/95:  You cannot specify UserName in UPPED format.

AccountOU [in, optional]

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, otherwise Accent must be NULL.

Example: "OU=testOU, DC=domain, DC=Domain, DC=com"

FJoinOptions [in]

Set of bit flags that define the join options.

Value	Meaning
1 0x1	Default. Joins a computer to a domain. If this value is not specified, the join is a computer to a workgroup.
2 0x2	Creates an account on a domain.
4 0x4	Deletes an account when a domain exists.
16 0x10	The join operation is part of an upgrade from Windows 98 or Windows 95 to Windows 2000 or Windows NT.
32 0x20	Allows a join to a new domain, even if the computer is already joined to a domain.
64 0x40	Performs an unsecured join.
128 0x80	The machine, not the user, password passed. This option is only valid for unsecure joins.
256 0x100	Writing SPN and DnsHostName attributes on the computer object should be deferred until the rename that follows the join.
262144 0x40000	The APIs were invoked during install.

Return Value

Returns one of the following numeric values.

Examples

For script code examples, see WMI Tasks for Scripts and Applications and the TechNet ScriptCenter Script Repository.

For C++ code examples, see WMI C++ Application Examples.

Examples - VBScript

The following VBScript code example joins a computer to a domain and creates the computer's account in Active Directory.

Const JOIN_DOMAIN             = 1
Const ACCT_CREATE             = 2
Const ACCT_DELETE             = 4
Const WIN9X_UPGRADE           = 16
Const DOMAIN_JOIN_IF_JOINED   = 32
Const JOIN_UNSECURE           = 64
Const MACHINE_PASSWORD_PASSED = 128
Const DEFERRED_SPN_SET        = 256
Const INSTALL_INVOCATION      = 262144
strDomain   = "FABRIKAM"
strPassword = "ls4k5ywA"
strUser     = "shenalan"
Set objNetwork = CreateObject("WScript.Network")
strComputer = objNetwork.ComputerName
Set objComputer = _
    GetObject("winmgmts:{impersonationLevel=Impersonate}!\\" & _
    strComputer & "\root\cimv2:Win32_ComputerSystem.Name='" _
    & strComputer & "'")
ReturnValue = objComputer.JoinDomainOrWorkGroup(strDomain, _
    strPassword, _
    strDomain & "\" & strUser, _
    NULL, _
    JOIN_DOMAIN + ACCT_CREATE)

Remarks

When moving a computer from a domain to a workgroup, you must remove the computer from the domain before calling this method to join a workgroup. After calling this method, restart the affected computer to apply the changes.

UserName and Password can be left null. However, the authentication of the connection to WMI must be 6 in script or WbemAuthenticationLevelPktPrivacy in Visual Basic and other languages that can use the wbemdisp.dll library. For more information, see Setting the Default Process Security Level Using VBScript.

In C++, set the authentication at RPC_C_AUTHN_LEVEL_PKT_PRIVACY either in CoInitializeSecurity, for the entire process, or in CoSetProxyBlanket, for a connection to the IWbemServices proxy. For more information, see Setting Authentication Using C++ and Setting the Security on IWbemServices and Other Proxies.

Requirements

See Also

Win32_ComputerSystem

Send comments about this topic to Microsoft

Build date: 9/29/2008