SUPPLEMENTARY NOTE

This supplementary note provides information for functions and structures used in program examples of Module M and Module N. The information compiled for NT 5 (Windows 2000 and above).

Index

Functions

NetUserAdd()

NetUserEnum()

NetUserSetInfo()

NetUserChangePassword()

NetLocalGroupAdd()

NetLocalGroupAddMembers()

NetGetDCName()

DsGetDcName()

NetApiBufferFree()

NetApiBufferReallocate()

NetApiBufferSize()

NetApiBufferAllocate()

SetLastError()

GetProcessHeap()

lstrlen()/lstrlenW()

Structures

USER_INFO_1

USER_INFO_1008

LOCALGROUP_INFO_1

LOCALGROUP_MEMBERS_INFO_3

Functions

NetUserAdd()

Item	Description
Function	NetUserAdd().
Use	To add a user account and assigns a password and privilege level.
Prototype	NET_API_STATUS NetUserAdd( LMSTR servername, DWORD level, LPBYTE buf, LPDWORD parm_err);
Parameters	servername [in] Pointer to a constant string that specifies the DNS or NetBIOS name of the remote server on which the function is to execute. If this parameter is NULL, the local computer is used. This string is Unicode if _WIN32_WINNT or FORCE_UNICODE are defined. For Windows NT: This string must begin with \\. level [in] Specifies the information level of the data. This parameter can be one of the following values. 1 - Specifies information about the user account. The buf parameter points to a USER_INFO_1 structure. When you specify this level, the call initializes certain attributes to their default values. 2 - Specifies level one information and additional attributes about the user account. The buf parameter points to a USER_INFO_2 structure. 3 - Specifies level two information and additional attributes about the user account. This level is valid only on servers. The buf parameter points to a USER_INFO_3 structure. Note that it is recommended that you use USER_INFO_4 instead. 4 - Specifies level two information and additional attributes about the user account. This level is valid only on servers. The buf parameter points to a USER_INFO_4 structure. For Windows 2000/NT: This level is not supported. buf [in] Pointer to the buffer that specifies the data. The format of this data depends on the value of the level parameter. parm_err [out] Pointer to a value that receives the index of the first member of the user information structure that causes ERROR_INVALID_PARAMETER. If this parameter is NULL, the index is not returned on error.
Return value	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: ERROR_ACCESS_DENIED - The user does not have access to the requested information. NERR_InvalidComputer - The computer name is invalid. NERR_NotPrimary - The operation is allowed only on the primary domain controller of the domain. NERR_GroupExists - The group already exists. NERR_UserExists - The user account already exists. NERR_PasswordTooShort - The password is shorter than required. (The password could also be too long, be too recent in its change history, not have enough unique characters, or not meet another password policy requirement.)
Include file	<lm.h>
Remark
Table 1

If you call this function on a domain controller that is running Active Directory, access is allowed or denied based on the ACL for the securable object. The default ACL permits only Domain Admins and Account Operators to call this function. On a member server or workstation, only Administrators and Power Users can call this function. For Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetUserAdd() function. Only members of the Administrators local group can add an Administrators privilege account.

The security descriptor of the user container is used to perform the access check for this function. The caller must be able to create child objects of the user class.

Server users must use a system in which the server creates a WINDOWS NT system account for the new user. The creation of this account is controlled by several parameters in the server's lanman.ini file.

If the newly added user already exists as a system user, the usri1_home_dir member of the USER_INFO_1 structure is ignored.

When you call the NetUserAdd() function and specify information level 1, the call initializes the additional members in the USER_INFO_2, USER_INFO_3, and USER_INFO_4 structures to their default values. You can change the default values by making subsequent calls to the NetUserSetInfo() function. The default values supplied are listed in the following Table. The prefix usriX indicates that the member can begin with multiple prefixes, for example, usri2_ or usri4_.

Member	Default Value
usriX_auth_flags	None (0).
usriX_full_name	None (null string).
usriX_usr_comment	None (null string).
usriX_parms	None (null string).
usriX_workstations	All (null string).
usriX_acct_expires	Never (TIMEQ_FOREVER).
usriX_max_storage	Unlimited (USER_MAXSTORAGE_UNLIMITED).
usriX_logon_hours	Logon allowed at any time (each element 0xFF; all bits set to 1).
usriX_logon_server	Any domain controller (\\*).
usriX_country_code	0
usriX_code_page	0
Table 2.

User account names are limited to 20 characters and group names are limited to 256 characters. In addition, account names cannot be terminated by a period and they cannot include commas or any of the following printable characters: ", /, \, [, ], :, |, <, >, +, =, ;, ?, *. Names also cannot include characters in the range 1-31, which are nonprintable. For Windows NT 4.0: Calls to this function fail if an account name does not meet the criteria outlined previously.

NetUserEnum()

Item	Description
Function	NetUserEnum().
Use	To provide information about all user accounts on a server. To quickly enumerate user, computer, or global group account information, call the NetQueryDisplayInformation() function.
Prototype	NET_API_STATUS NetUserEnum( LPCWSTR servername, DWORD level, DWORD filter, LPBYTE* bufptr, DWORD prefmaxlen, LPDWORD entriesread, LPDWORD totalentries, LPDWORD resume_handle);
Parameters	servername [in] Pointer to a constant string that specifies the DNS or NetBIOS name of the remote server on which the function is to execute. If this parameter is NULL, the local computer is used. Windows NT: This string must begin with \\. level [in] Specifies the information level of the data. This parameter can be one of the following values. 0 - Return user account names. The bufptr parameter points to an array of USER_INFO_0 structures. 1 - Return detailed information about user accounts. The bufptr parameter points to an array of USER_INFO_1 structures. 2 - Return detailed information about user accounts, including authorization levels and logon information. The bufptr parameter points to an array of USER_INFO_2 structures. 3 - Return detailed information about user accounts, including authorization levels, logon information, RIDs for the user and the primary group, and profile information. The bufptr parameter points to an array of USER_INFO_3 structures. 10 - Return user and account names and comments. The bufptr parameter points to an array of USER_INFO_10 structures. 11 - Return detailed information about user accounts. The bufptr parameter points to an array of USER_INFO_11 structures. 20 - Return the user's name and identifier and various account attributes. The bufptr parameter points to an array of USER_INFO_20 structures. Note that on Windows XP and later, it is recommended that you use USER_INFO_23 instead. 23 - Return the user's name and identifier and various account attributes. The bufptr parameter points to an array of USER_INFO_23 structures. Windows 2000/NT: This level is not supported. filter [in] Specifies a value that filters the account types for enumeration. A value of zero indicates all account types. This parameter can be one of the following values: FILTER_TEMP_DUPLICATE_ACCOUNT - Enumerates local user account data on a domain controller. FILTER_NORMAL_ACCOUNT - Enumerates global user account data on a computer. FILTER_INTERDOMAIN_TRUST_ACCOUNT - Enumerates domain trust account data on a domain controller. The data is associated with the accounts of domains trusting the specified domain. FILTER_WORKSTATION_TRUST_ACCOUNT - Enumerates workstation or member server account data on a domain controller. FILTER_SERVER_TRUST_ACCOUNT - Enumerates domain controller account data on a domain controller. bufptr [out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree() function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA. prefmaxlen [in] Specifies the preferred maximum length, in 8-bit bytes of returned data. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. entriesread [out] Pointer to a value that receives the count of elements actually enumerated. totalentries [out] Pointer to a value that receives the total number of entries that could have been enumerated from the current resume position. Note that applications should consider this value only as a hint. If your application is communicating with a Windows 2000 or later domain controller, you should consider using the ADSI LDAP Provider to retrieve this type of data more efficiently. The ADSI LDAP Provider implements a set of ADSI objects that support various ADSI interfaces. LAN Manager: If the call is to a computer that is running LAN Manager 2.x, the totalentries parameter will always reflect the total number of entries in the database no matter where it is in the resume sequence. resume_handle [in, out] Pointer to a value that contains a resume handle which is used to continue an existing user search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.
Return value	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: ERROR_ACCESS_DENIED - The user does not have access to the requested information. NERR_InvalidComputer - The computer name is invalid. ERROR_MORE_DATA - More entries are available. Specify a large enough buffer to receive all entries.
Include file	<lm.h>
Remark	-
Table 3.

If you call this function on a domain controller that is running Active Directory, access is allowed or denied based on the access control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. If you call this function on a member server or workstation, all authenticated users can view the information. For Windows NT: No special group membership is required to successfully execute the NetUserEnum() function.

The function only returns information to which the caller has Read access. The caller must have List Contents access to the Domain object, and Enumerate Entire SAM Domain access on the SAM Server object located in the System container.

To retrieve the names and SIDs of domains trusted by a Local Security Authority (LSA) policy object, call the LsaEnumerateTrustedDomains() function.

The NetUserEnum() function does not return all system users. It returns only those users who have been added with a call to the NetUserAdd() function. There is no guarantee that the list of users will be returned in sorted order. If you call NetUserEnum() and specify information level 1, 2, 3, or 4, the password member of each structure is set to NULL to maintain password security.

NetUserSetInfo()

Item	Description
Function	NetUserSetInfo().
Use	To set the parameters of a user account.
Prototype	NET_API_STATUS NetUserSetInfo( LPCWSTR servername, LPCWSTR username, DWORD level, LPBYTE buf, LPDWORD parm_err);
Parameters	servername [in] Pointer to a constant string that specifies the DNS or NetBIOS name of the remote server on which the function is to execute. If this parameter is NULL, the local computer is used. For Windows NT: This string must begin with \\. username [in] Pointer to a constant string that specifies the name of the user account for which to set information. level [in] Specifies the information level of the data. This parameter can be one of the following values: 0 - Specifies the user account name. The buf parameter points to a USER_INFO_0 structure. Use this structure to specify a new group name. 1 - Specifies detailed information about the user account. The buf parameter points to a USER_INFO_1 structure. 2 - Specifies level one information and additional attributes about the user account. The buf parameter points to a USER_INFO_2 structure. 3 - Specifies level two information and additional attributes about the user account. This level is valid only on servers. The buf parameter points to a USER_INFO_3 structure. Note that it is recommended that you use USER_INFO_4 instead. 4 - Specifies level two information and additional attributes about the user account. This level is valid only on servers. The buf parameter points to a USER_INFO_4 structure. For Windows 2000/NT: This level is not supported. 21 - Specifies a one-way encrypted LAN Manager 2.x-compatible password. The buf parameter points to a USER_INFO_21 structure. 22 - Specifies detailed information about the user account. The buf parameter points to a USER_INFO_22 structure. 1003 - Specifies a user password. The buf parameter points to a USER_INFO_1003 structure. 1005 - Specifies a user privilege level. The buf parameter points to a USER_INFO_1005 structure. 1006 - Specifies the path of the home directory for the user. The buf parameter points to a USER_INFO_1006 structure. 1007 - Specifies a comment to associate with the user account. The buf parameter points to a USER_INFO_1007 structure. 1008 - Specifies user account attributes. The buf parameter points to a USER_INFO_1008 structure. 1009 - Specifies the path for the user's logon script file. The buf parameter points to a USER_INFO_1009 structure. 1010 - Specifies the user's operator privileges. The buf parameter points to a USER_INFO_1010 structure. 1011 - Specifies the full name of the user. The buf parameter points to a USER_INFO_1011 structure. 1012 - Specifies a comment to associate with the user. The buf parameter points to a USER_INFO_1012 structure. 1014 - Specifies the names of workstations from which the user can log on. The buf parameter points to a USER_INFO_1014 structure. 1017 - Specifies when the user account expires. The buf parameter points to a USER_INFO_1017 structure. 1020 - Specifies the times during which the user can log on. The buf parameter points to a USER_INFO_1020 structure. 1024 - Specifies the user's country/region code. The buf parameter points to a USER_INFO_1024 structure. 1051 - Specifies the relative identifier of a global group that represents the enrolled user. The buf parameter points to a USER_INFO_1051 structure. 1052 - Specifies the path to a network user's profile. The buf parameter points to a USER_INFO_1052 structure. 1053 - Specifies the drive letter assigned to the user's home directory. The buf parameter points to a USER_INFO_1053 structure. buf [in] Pointer to the buffer that specifies the data. The format of this data depends on the value of the level parameter. parm_err [out] Pointer to a value that receives the index of the first member of the user information structure that causes ERROR_INVALID_PARAMETER. If this parameter is NULL, the index is not returned on error.
Return value	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: ERROR_ACCESS_DENIED - The user does not have access to the requested information. ERROR_INVALID_PARAMETER - One of the function parameters is invalid. For more information, see the following Remarks section. NERR_InvalidComputer - The computer name is invalid. NERR_NotPrimary - The operation is allowed only on the primary domain controller of the domain. NERR_SpeGroupOp - The operation is not allowed on specified special groups, which are user groups, admin groups, local groups, or guest groups. NERR_LastAdmin - The operation is not allowed on the last administrative account. NERR_BadPassword - The share name or password is invalid. NERR_PasswordTooShort - The password is shorter than required. The password could also be too long, be too recent in its change history, not have enough unique characters, or not meet another password policy requirement. NERR_UserNotFound - The user name could not be found.
Include file	<lm.h>
Remark
Table 4.

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetUserSetInfo() function on a remote server or on a computer that has local security enabled. A user can call NetUserSetInfo() to set certain information on his or her own account. The security descriptor of the User object is used to perform the access check for this function.

Only users or applications having administrative privileges can call the NetUserSetInfo() function to change a user's password. When an administrator calls NetUserSetInfo(), the only restriction applied is that the new password length must be consistent with system modals. A user or application that knows a user's current password can call the NetUserChangePassword() function to change the password.

Members of the Administrators local group can set any modifiable user account elements. All users can set the usri2_country_code member of the USER_INFO_2 structure (and the usri1024_country_code member of the USER_INFO_1024 structure) for their own accounts.

A member of the Account Operator's local group cannot set details for an Administrators class account, give an existing account Administrator privilege, or change the operator privilege of any account. If you attempt to change the privilege level or disable the last account with Administrator privilege in the security database, (the security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory), the NetUserSetInfo() function fails and returns NERR_LastAdmin.

To set the following user account control flags, the following privileges and control access rights are required.

Account control flag	Privilege or right required
UF_TRUSTED_TO_AUTHENTICATE_FOR_DELEGATION	SeEnableDelegationPrivilege privilege, which is granted to Administrators by default.
UF_TRUSTED_FOR_DELEGATION	SeEnableDelegationPrivilege.
UF_PASSWD_NOTREQD	"Update password not required" control access right on the Domain object, which is granted to authenticated users by default.
UF_DONT_EXPIRE_PASSWD	"Unexpire password" control access right on the Domain object, which is granted to authenticated users by default.
UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED	"Enable per user reversibly encrypted password" control access right on the Domain object, which is granted to authenticated users by default.
UF_SERVER_TRUST_ACCOUNT	"Add/remove replica in domain" control access right on the Domain object, which is granted to Administrators by default.
Table 5.

The correct way to specify the new name for an account is to call NetUserSetInfo() with USER_INFO_0 and to specify the new value using the usri0_name member. If you call NetUserSetInfo() with other information levels and specify a value using a usriX_name member, the value is ignored.

Note that calls to NetUserSetInfo() can change the home directory only for user accounts that the network server creates. If the NetUserSetInfo() function returns ERROR_INVALID_PARAMETER, you can use the parm_err parameter to indicate the first member of the user information structure that is invalid. A user information structure begins with USER_INFO_ and its format is specified by the level parameter. The following table lists the values that can be returned in the parm_err parameter and the corresponding structure member that is in error. The prefix usri*_ indicates that the member can begin with multiple prefixes, for example, usri10_ or usri1003_.

Value	Member
USER_NAME_PARMNUM	usri*_name
USER_PASSWORD_PARMNUM	usri*_password
USER_PASSWORD_AGE_PARMNUM	usri*_password_age
USER_PRIV_PARMNUM	usri*_priv
USER_HOME_DIR_PARMNUM	usri*_home_dir
USER_COMMENT_PARMNUM	usri*_comment
USER_FLAGS_PARMNUM	usri*_flags
USER_SCRIPT_PATH_PARMNUM	usri*_script_path
USER_AUTH_FLAGS_PARMNUM	usri*_auth_flags
USER_FULL_NAME_PARMNUM	usri*_full_name
USER_USR_COMMENT_PARMNUM	usri*_usr_comment
USER_PARMS_PARMNUM	usri*_parms
USER_WORKSTATIONS_PARMNUM	usri*_workstations
USER_LAST_LOGON_PARMNUM	usri*_last_logon
USER_LAST_LOGOFF_PARMNUM	usri*_last_logoff
USER_ACCT_EXPIRES_PARMNUM	usri*_acct_expires
USER_MAX_STORAGE_PARMNUM	usri*_max_storage
USER_UNITS_PER_WEEK_PARMNUM	usri*_units_per_week
USER_LOGON_HOURS_PARMNUM	usri*_logon_hours
USER_PAD_PW_COUNT_PARMNUM	usri*_bad_pw_count
USER_NUM_LOGONS_PARMNUM	usri*_num_logons
USER_LOGON_SERVER_PARMNUM	usri*_logon_server
USER_COUNTRY_CODE_PARMNUM	usri*_country_code
USER_CODE_PAGE_PARMNUM	usri*_code_page
USER_PRIMARY_GROUP_PARMNUM	usri*_primary_group_id
USER_PROFILE_PARMNUM	usri*_profile
USER_HOME_DIR_DRIVE_PARMNUM	usri*_home_dir_drive
Table 6.

NetUserChangePassword()

Item	Description
Function	NetUserChangePassword().
Use	To change a user's password for a specified network server or domain.
Prototype	NET_API_STATUS NetUserChangePassword( LPCWSTR domainname, LPCWSTR username, LPCWSTR oldpassword, LPCWSTR newpassword);
Parameters	domainname [in] Pointer to a constant string that specifies the DNS or NetBIOS name of a remote server or domain on which the function is to execute. If this parameter is NULL, the logon domain of the caller is used. For Windows NT: This string must begin with \\. username [in] Pointer to a constant string that specifies a user name. The NetUserChangePassword() function changes the password for the specified user. If this parameter is NULL, the logon name of the caller is used. oldpassword [in] Pointer to a constant string that specifies the user's old password. newpassword [in] Pointer to a constant string that specifies the user's new password.
Return value	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: ERROR_ACCESS_DENIED - The user does not have access to the requested information. ERROR_INVALID_PASSWORD - The user has entered an invalid password. NERR_InvalidComputer - The computer name is invalid. NERR_NotPrimary - The operation is allowed only on the primary domain controller of the domain. NERR_UserNotFound - The user name could not be found. NERR_PasswordTooShort - The password is shorter than required. The password could also be too long, be too recent in its change history, not have enough unique characters, or not meet another password policy requirement.
Include file	<lm.h>
Remark
Table 7.

Windows NT: A server or domain can be configured to require a user to log on before changing the password on a user account. In that case, only members of the Administrators or Account Operators local group or the user can change the password for a user account. If logon is not required, a user can change the password for any user account, as long as the user knows the current password.

The security descriptor of the User object is used to perform the access check for this function. In addition, the caller must have the "Change password" control access right on the User object. This right is granted to Anonymous Logon and Everyone by default.

Note that for the function to succeed, the oldpassword parameter must match the password as it currently exists.

In some cases, the process that calls the NetUserChangePassword() function must also have the SE_CHANGE_NOTIFY_NAME privilege enabled; otherwise, NetUserChangePassword() fails and GetLastError() returns ERROR_ACCESS_DENIED. This privilege is not required for the LocalSystem account or for accounts that are members of the administrators group. By default, SE_CHANGE_NOTIFY_NAME is enabled for all users, but some administrators may disable the privilege for everyone.

NetLocalGroupAdd()

Item	Description
Function	NetLocalGroupAdd().
Use	To create a local group in the security database, which is the security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory.
Prototype	NET_API_STATUS NetLocalGroupAdd( LPCWSTR servername, DWORD level, LPBYTE buf, LPDWORD parm_err);
Parameters	servername [in] Pointer to a constant string that specifies the DNS or NetBIOS name of the remote server on which the function is to execute. If this parameter is NULL, the local computer is used. Windows NT: This string must begin with \\. level [in] Specifies the information level of the data. This parameter can be one of the following values: 0 - Specifies a local group name. The buf parameter points to a LOCALGROUP_INFO_0 structure. 1 - Specifies a local group name and a comment to associate with the group. The buf parameter points to a LOCALGROUP_INFO_1 structure. buf [in] Pointer to a buffer that contains the local group information structure. The format of this data depends on the value of the level parameter. parm_err [out] Pointer to a value that receives the index of the first member of the local group information structure to cause the ERROR_INVALID_PARAMETER error. If this parameter is NULL, the index is not returned on error.
Return value	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: ERROR_ACCESS_DENIED - The user does not have access to the requested information. NERR_InvalidComputer - The computer name is invalid. NERR_NotPrimary - The operation is allowed only on the primary domain controller of the domain. NERR_GroupExists - The local group already exists. ERROR_ALIAS_EXISTS - The local group already exists.
Include file	<lm.h>
Remark
Table 8.

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetLocalGroupAdd() function.

The security descriptor of the user container is used to perform the access check for this function. The caller must be able to create child objects of the group class.

NetLocalGroupAddMembers()

Item	Description
Function	NetLocalGroupAddMembers().
Use	To add membership of one or more existing user accounts or global group accounts to an existing local group. The function does not change the membership status of users or global groups that are currently members of the local group.
Prototype	NET_API_STATUS NetLocalGroupAddMembers( LPCWSTR servername, LPCWSTR groupname, DWORD level, LPBYTE buf, DWORD totalentries);
Parameters	servername [in] Pointer to a constant string that specifies the DNS or NetBIOS name of the remote server on which the function is to execute. If this parameter is NULL, the local computer is used. Windows NT: This string must begin with \\. groupname [in] Pointer to a constant string that specifies the name of the local group to which the specified users or global groups will be added. level [in] Specifies the information level of the data. This parameter can be one of the following values: 0 - Specifies the security identifier (SID) of the new local group member. The buf parameter points to an array of LOCALGROUP_MEMBERS_INFO_0 structures. 3 - Specifies the domain and name of the new local group member. The buf parameter points to an array of LOCALGROUP_MEMBERS_INFO_3 structures. buf [in] Pointer to a buffer that contains the data for the new local group members. The format of this data depends on the value of the level parameter. totalentries [in] Specifies the number of entries in the buffer pointed to by the buf parameter.
Return value	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. NERR_GroupNotFound - The local group specified by the groupname parameter does not exist. ERROR_ACCESS_DENIED - The user does not have access to the requested information. ERROR_NO_SUCH_MEMBER - One or more of the members specified do not exist. Therefore, no new members were added. ERROR_MEMBER_IN_ALIAS - One or more of the members specified were already members of the local group. No new members were added. ERROR_INVALID_MEMBER - One or more of the members cannot be added because their account type is invalid. No new members were added.
Include file	<lm.h>
Remark	-
Table 9.

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetLocalGroupAddMembers function on a remote server.

The security descriptor of the LocalGroup object is used to perform the access check for this function.

NetGetDCName()

Item	Description
Function	NetGetDCName().
Use	To return the name of the primary domain controller (PDC). It does not return the name of the backup domain controller (BDC) for the specified domain. Also, you cannot remote this function to a non-PDC server. Applications that support DNS-style names should call the DsGetDcName() function. Domain controllers in this type of environment have a multi-master directory replication relationship. Therefore, it may be advantageous for your application to use a DC that is not the PDC. You can call the DsGetDcName() function to locate any DC in the domain; NetGetDCName() returns only the name of the PDC.
Prototype	NET_API_STATUS NetGetDCName( LPCWSTR servername, LPCWSTR domainname, LPBYTE* bufptr);
Parameters	servername [in] Pointer to a constant string that specifies the DNS or NetBIOS name of the remote server on which the function is to execute. If this parameter is NULL, the local computer is used. For Windows NT: This string must begin with \\. domainname [in] Pointer to a constant string that specifies the name of the domain. The domain name must be a NetBIOS domain name (for example, microsoft). NetGetDCName() does not support DNS-style names (for example, microsoft.com). If this parameter is NULL, the function returns the name of the domain controller for the primary domain. bufptr [out] Pointer to an allocated buffer that receives a string that specifies the server name of the PDC of the domain. The server name is prefixed by \\. This buffer is allocated by the system and must be freed using the NetApiBufferFree() function.
Return value	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. NERR_DCNotFound - Could not find the domain controller for the domain. ERROR_INVALID_NAME - The name could not be found.
Include file	<lm.h>
Remark	No special group membership is required to successfully execute the NetGetDCName() function.
Table 10.

DsGetDcName()

Some provocation :o). For Domain based object you can use directory service functions (the function name prefixed with dc… DsGetDcName() function provided here just for informational. In MSDN documentation it is in Active Directory category.

Item	Description
Function	DsGetDcName().
Use	To return the name of a domain controller in a specified domain. This function accepts additional domain controller selection criteria to indicate preference for a domain controller with particular characteristics.
Prototype	DWORD DsGetDcName( LPCTSTR ComputerName, LPCTSTR DomainName, GUID* DomainGuid, LPCTSTR SiteName, ULONG Flags, PDOMAIN_CONTROLLER_INFO* DomainControllerInfo);
Parameters	See below.
Return value	If the function returns domain controller data, the return value is ERROR_SUCCESS. If the function fails, the return value can be one of the following error codes: ERROR_INVALID_DOMAINNAME - The format of the specified DomainName is invalid. ERROR_INVALID_FLAGS - The Flags parameter contains conflicting or superfluous flags. ERROR_NOT_ENOUGH_MEMORY - A memory allocation failure occurred. ERROR_NO_SUCH_DOMAIN - No domain controller is available for the specified domain or the domain does not exist.
Include file	<dsgetdc.h>
Remark