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.

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.

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.

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)

Requirements

See Also

Win32_ComputerSystem

Send comments about this topic to Microsoft

Build date: 6/15/2009