DOCUMENT:Q159498 11-JAN-2001 [vbwin] TITLE :HOWTO: Call LanMan Services from 32-bit Visual Basic Apps PRODUCT :Microsoft Visual Basic for Windows PROD/VER:WINDOWS:4.0 OPER/SYS: KEYWORDS:kbnetwork kbAPI kbSDKPlatform kbVBp400 kbNetAPI kbGrpDSVBDB kbGrpDSNet kb32bitOnly ====================================================================== ------------------------------------------------------------------------------- The information in this article applies to: - Microsoft Visual Basic Standard Edition, 32-bit, for Windows, version 4.0 - Microsoft Visual Basic Professional Edition, 32-bit, for Windows, version 4.0 - Microsoft Visual Basic Enterprise Edition, 32-bit, for Windows, version 4.0 ------------------------------------------------------------------------------- SUMMARY ======= This article demonstrates how to call various LanMan services from 32-bit Visual Basic 4.0 applications. The sample code also applies to applications which use the 32-bit VBA engine. An example of such an application is Microsoft Excel 97. MORE INFORMATION ================ Windows NT and Windows 2000 exposes LanMan 32-bit Application Programming Interfaces (APIs) to provide network services. These APIs are called only from 32-bit programs running on a Windows NT or Windows 2000 and are used to control both the local and remote Windows NT (or Windows 2000) machines that you have permission to access. Note: While Windows 2000 supports LanMan APIs for backwards compatibility, it is recommended that ADSI be used instead for most of the functions below. For more information about ADSI, search for Active Directory Services Interface or ADSI in the Microsoft Knowledge Base or MSDN. This article contains code examples of using the following LanMan APIs: NetGetDCName NetUserDel NetGroupAddUser NetGroupDelUser NetUserAdd (using Level 1 structure) NetUserEnum (using Level 0 structure) NetGroupEnumUsers (using Level 0 structure) NetGroupEnum (using Level 0 structure) NetUserGetGroups (using Level 0 structure) NetAPIBufferFree NetAPIBufferAllocate Although, Visual Basic stores strings internally as UNICODE, it converts them to ANSI when it calls APIs. Normally this isn't a problem because most 32-bit APIs have both an ANSI and a UNICODE version. However, LanMan APIs only support UNICODE. The code snippet below demonstrates how to use Byte arrays to pass UNICODE parameters. Instead of using strings, for example: "X = My_ANSI_API("Some String")" use Byte arrays, such the one below, because they aren't converted to ANSI: Dim Temp() As Byte, Message As String Message = "Some String" Temp = Message & vbNullChar ' MyUnicodeAPI Temp(0) Message = Temp ' modified me Declarations and Sample Code ---------------------------- WARNING: ANY USE BY YOU OF THE CODE PROVIDED IN THIS ARTICLE IS AT YOUR OWN RISK. Microsoft provides this macro code "as is" without warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability and/or fitness for a particular purpose. Microsoft provides examples of Visual Basic procedures for illustration only, without warranty either expressed or implied, including, but not limited to the implied warranties of merchantability and/or fitness for a particular purpose. The Visual Basic procedures in this article are provided 'as is' and Microsoft does not guarantee that they can be used in all situations. While Microsoft Support professionals can help explain the functionality of a particular procedure, they will not modify these examples to provide added functionality, nor will they help you construct procedures to meet your specific needs. If you have limited programming experience, you may want to consult one of the Microsoft Solution Providers. Solution Providers offer a wide range of fee-based services, including creating custom procedures. For more information about Microsoft Solution Providers, call Microsoft Customer Information Service at (800) 426-9400. Option Explicit Option Base 0 ' Important assumption for this code Type MungeLong X As Long Dummy As Integer End Type Type MungeInt XLo As Integer XHi As Integer Dummy As Integer End Type Type TUser0 ' Level 0 ptrName As Long End Type Type TUser1 ' Level 1 ptrName As Long ptrPassword As Long dwPasswordAge As Long dwPriv As Long ptrHomeDir As Long ptrComment As Long dwFlags As Long ptrScriptPath As Long End Type ' ' for dwPriv ' Const USER_PRIV_MASK = &H3 Const USER_PRIV_GUEST = &H0 Const USER_PRIV_USER = &H1 Const USER_PRIV_ADMIN = &H2 ' ' for dwFlags ' Const UF_SCRIPT = &H1 Const UF_ACCOUNTDISABLE = &H2 Const UF_HOMEDIR_REQUIRED = &H8 Const UF_LOCKOUT = &H10 Const UF_PASSWD_NOTREQD = &H20 Const UF_PASSWD_CANT_CHANGE = &H40 Const UF_NORMAL_ACCOUNT = &H200 ' Needs to be ORed with the ' other flags ' ' for lFilter ' Const FILTER_NORMAL_ACCOUNT = &H2 Declare Function NetGetDCName Lib "NETAPI32.DLL" (ServerName As Byte, _ DomainName As Byte, DCNPtr As Long) As Long Declare Function NetUserDel Lib "NETAPI32.DLL" (ServerName As Byte, _ UserName As Byte) As Long Declare Function NetGroupAddUser Lib "NETAPI32.DLL" (ServerName As _ Byte, GroupName As Byte, UserName As Byte) As Long Declare Function NetGroupDelUser Lib "NETAPI32.DLL" (ServerName As _ Byte, GroupName As Byte, UserName As Byte) As Long ' Add using Level 1 user structure Declare Function NetUserAdd1 Lib "NETAPI32.DLL" Alias "NetUserAdd" _ (ServerName As Byte, ByVal Level As Long, Buffer As TUser1, ParmError _ As Long) As Long ' Enumerate using Level 0 user structure Declare Function NetUserEnum0 Lib "NETAPI32.DLL" Alias "NetUserEnum" _ (ServerName As Byte, ByVal Level As Long, ByVal lFilter As Long, _ Buffer As Long, ByVal PrefMaxLen As Long, EntriesRead As Long, _ TotalEntries As Long, ResumeHandle As Long) As Long Declare Function NetGroupEnumUsers0 Lib "NETAPI32.DLL" Alias _ "NetGroupGetUsers" (ServerName As Byte, GroupName As Byte, _ ByVal Level As Long, Buffer As Long, ByVal PrefMaxLen As Long, _ EntriesRead As Long, TotalEntries As Long, ResumeHandle As Long) As Long Declare Function NetGroupEnum0 Lib "NETAPI32.DLL" Alias "NetGroupEnum" _ (ServerName As Byte, ByVal Level As Long, Buffer As Long, ByVal _ PrefMaxLen As Long, EntriesRead As Long, TotalEntries As Long, _ ResumeHandle As Long) As Long Declare Function NetUserGetGroups0 Lib "NETAPI32.DLL" Alias _ "NetUserGetGroups" (ServerName As Byte, UserName As Byte, _ ByVal Level As Long, Buffer As Long, ByVal PrefMaxLen As Long, _ EntriesRead As Long, TotalEntries As Long) As Long Declare Function NetAPIBufferFree Lib "NETAPI32.DLL" Alias _ "NetApiBufferFree" (ByVal Ptr As Long) As Long Declare Function NetAPIBufferAllocate Lib "NETAPI32.DLL" Alias _ "NetApiBufferAllocate" (ByVal ByteCount As Long, Ptr As Long) As Long Declare Function PtrToStr Lib "Kernel32" Alias "lstrcpyW" _ (RetVal As Byte, ByVal Ptr As Long) As Long Declare Function StrToPtr Lib "Kernel32" Alias "lstrcpyW" _ (ByVal Ptr As Long, Source As Byte) As Long Declare Function PtrToInt Lib "Kernel32" Alias "lstrcpynW" _ (RetVal As Any, ByVal Ptr As Long, ByVal nCharCount As Long) As Long Declare Function StrLen Lib "Kernel32" Alias "lstrlenW" _ (ByVal Ptr As Long) As Long Function AddUserToGroup(ByVal SName As String, _ ByVal GName As String, ByVal UName As String) As Long ' ' This only adds users to global groups - not to local groups ' Dim SNArray() As Byte, GNArray() As Byte, UNArray() As Byte, _ Result As Long SNArray = SName & vbNullChar GNArray = GName & vbNullChar UNArray = UName & vbNullChar Result = NetGroupAddUser(SNArray(0), GNArray(0), UNArray(0)) If Result = 2220 Then Debug.Print _ "There is no **GLOBAL** group '" & GName & "'" AddUserToGroup = Result End Function Function DelUser(ByVal SName As String, ByVal UName As String) As Long Dim UNArray() As Byte, SNArray() As Byte UNArray = UName & vbNullChar SNArray = SName & vbNullChar DelUser = NetUserDel(SNArray(0), UNArray(0)) End Function Function DelUserFromGroup(ByVal SName As String, _ ByVal GName As String, ByVal UName As String) As Long ' ' This only deletes users from global groups - not local groups ' Dim SNArray() As Byte, GNArray() As Byte, UNArray() As Byte, _ Result As Long SNArray = SName & vbNullChar GNArray = GName & vbNullChar UNArray = UName & vbNullChar Result = NetGroupDelUser(SNArray(0), GNArray(0), UNArray(0)) If Result = 2220 Then Debug.Print _ "There is no **GLOBAL** group '" & GName & "'" DelUserFromGroup = Result End Function Function EnumerateGroups(ByVal SName As String, _ ByVal UName As String) As Long ' ' Enumerates global groups only - not local groups ' ' The buffer is filled from the left with pointers to user names that ' are filled from the right side. For example: ' ' ptr1|ptr2|...|ptrn||strn|...|str2|str1 ' ^-------------- BufPtr buffer ----------------^ ' ' On NT, TotalEntries is the number of entries left to be read including ' the currently read entries. ' ' On LanMan and OS/2, it is the total number of entries, period. Code ' would have to be changed to reflect this if the Domain controller ' wasn't an NT machine. ' ' BufPtr gets the address of the buffer (or ptr1 - add 4 to BufPtr for ' each additional pointer) ' Dim Result As Long, BufPtr As Long, EntriesRead As Long, _ TotalEntries As Long, ResumeHandle As Long, BufLen As Long, _ SNArray() As Byte, GNArray(99) As Byte, UNArray() As Byte, _ GName As String, I As Integer, UNPtr As Long, _ TempPtr As MungeLong, TempStr As MungeInt SNArray = SName & vbNullChar ' Move to byte array UNArray = UName & vbNullChar ' Move to Byte array BufLen = 255 ' Buffer size ResumeHandle = 0 ' Start with the first entry Do If UName = "" Then Result = NetGroupEnum0(SNArray(0), 0, BufPtr, BufLen, _ EntriesRead, TotalEntries, ResumeHandle) Else Result = NetUserGetGroups0(SNArray(0), UNArray(0), 0, BufPtr, _ BufLen, EntriesRead, TotalEntries) End If EnumerateGroups = Result If Result <> 0 And Result <> 234 Then ' 234 means multiple reads ' required Debug.Print "Error " & Result & " enumerating group " & _ EntriesRead & " of " & TotalEntries Exit Function End If For I = 1 To EntriesRead ' Get pointer to string from beginning of buffer ' Copy 4 byte block of memory in 2 steps Result = PtrToInt(TempStr.XLo, BufPtr + (I - 1) * 4, 2) Result = PtrToInt(TempStr.XHi, BufPtr + (I - 1) * 4 + 2, 2) LSet TempPtr = TempStr ' munge 2 Integers to a Long ' Copy string to array and convert to a string Result = PtrToStr(GNArray(0), TempPtr.X) GName = Left(GNArray, StrLen(TempPtr.X)) Debug.Print "Group: " & GName Next I Loop Until EntriesRead = TotalEntries ' The above condition only valid for reading accounts on NT ' but not OK for OS/2 or LanMan Result = NetAPIBufferFree(BufPtr) ' Don't leak memory End Function Function EnumerateUsers(ByVal SName As String, ByVal GName As String) _ As Long ' ' If a group name is specified, it must be a global group ' and not a local group. ' ' The buffer is filled from the left with pointers to user names that ' are filled from the right side. For example: ' ' ptr1|ptr2|...|ptrn||strn|...|str2|str1 ' ^-------------- BufPtr buffer ----------------^ ' ' On Windows NT, TotalEntries is the number of entries left to be read, ' including the currently read entries. ' On LanMan and OS/2, it is the total number of entries, period. Code ' would have to be changed to reflect this if the Domain controller ' wasn't an NT machine. ' ' BufPtr gets the address of the buffer (or ptr1 - add 4 to BufPtr for ' each additional pointer) ' ' SName should be "\\servername" ' Dim Result As Long, BufPtr As Long, EntriesRead As Long, _ TotalEntries As Long, ResumeHandle As Long, BufLen As Long, _ SNArray() As Byte, GNArray() As Byte, UNArray(99) As Byte, _ UName As String, I As Integer, UNPtr As Long, TempPtr As MungeLong, _ TempStr As MungeInt SNArray = SName & vbNullChar ' Move to byte array GNArray = GName & vbNullChar ' Move to Byte array BufLen = 255 ' Buffer size ResumeHandle = 0 ' Start with the first entry Do If GName = "" Then Result = NetUserEnum0(SNArray(0), 0, FILTER_NORMAL_ACCOUNT, _ BufPtr, BufLen, EntriesRead, TotalEntries, ResumeHandle) Else Result = NetGroupEnumUsers0(SNArray(0), GNArray(0), 0, BufPtr, _ BufLen, EntriesRead, TotalEntries, ResumeHandle) End If EnumerateUsers = Result If Result <> 0 And Result <> 234 Then ' 234 means multiple reads ' required Debug.Print "Error " & Result & " enumerating user " _ & EntriesRead & " of " & TotalEntries If Result = 2220 Then Debug.Print _ "There is no **GLOBAL** group '" & GName & "'" Exit Function End If For I = 1 To EntriesRead ' Get pointer to string from beginning of buffer ' Copy 4-byte block of memory in 2 steps Result = PtrToInt(TempStr.XLo, BufPtr + (I - 1) * 4, 2) Result = PtrToInt(TempStr.XHi, BufPtr + (I - 1) * 4 + 2, 2) LSet TempPtr = TempStr ' munge 2 integers into a Long ' Copy string to array Result = PtrToStr(UNArray(0), TempPtr.X) UName = Left(UNArray, StrLen(TempPtr.X)) Debug.Print "User: " & UName Next I Loop Until EntriesRead = TotalEntries ' The above condition is only valid for reading accounts on Windows NT, ' but is not OK for OS/2 or LanMan Result = NetAPIBufferFree(BufPtr) ' Don't leak memory End Function Function GetPrimaryDCName(ByVal MName As String, _ ByVal DName As String) As String Dim Result As Long, DCName As String, DCNPtr As Long Dim DNArray() As Byte, MNArray() As Byte, DCNArray(100) As Byte MNArray = MName & vbNullChar DNArray = DName & vbNullChar Result = NetGetDCName(MNArray(0), DNArray(0), DCNPtr) If Result <> 0 Then Debug.Print "Error: " & Result Exit Function End If Result = PtrToStr(DCNArray(0), DCNPtr) Result = NetAPIBufferFree(DCNPtr) DCName = DCNArray() GetPrimaryDCName = DCName End Function Function AddUser(ByVal SName As String, ByVal UName As String, _ ByVal PWD As String) As Long Dim Result As Long, UNPtr As Long, PWDPtr As Long, ParmError As Long Dim SNArray() As Byte, UNArray() As Byte, PWDArray() As Byte Dim UserStruct As TUser1 ' ' Move to byte arrays ' SNArray = SName & vbNullChar UNArray = UName & vbNullChar PWDArray = PWD & vbNullChar ' ' Allocate buffer space ' Result = NetAPIBufferAllocate(UBound(UNArray) + 1, UNPtr) Result = NetAPIBufferAllocate(UBound(PWDArray) + 1, PWDPtr) ' ' Copy arrays to the buffer ' Result = StrToPtr(UNPtr, UNArray(0)) Result = StrToPtr(PWDPtr, PWDArray(0)) ' ' Fill the structure ' With UserStruct .ptrName = UNPtr .ptrPassword = PWDPtr .dwPasswordAge = 3 .dwPriv = USER_PRIV_USER .ptrHomeDir = 0 .ptrComment = 0 .dwFlags = UF_NORMAL_ACCOUNT Or UF_SCRIPT .ptrScriptPath = 0 End With ' ' Add the user ' Result = NetUserAdd1(SNArray(0), 1, UserStruct, ParmError) AddUser = Result If Result <> 0 Then Debug.Print "Error " & Result & " in parameter " & ParmError _ & " when adding user " & UName End If ' ' Release buffers from memory ' Result = NetAPIBufferFree(UNPtr) Result = NetAPIBufferFree(PWDPtr) End Function Additional query words: ====================================================================== Keywords : kbnetwork kbAPI kbSDKPlatform kbVBp400 kbNetAPI kbGrpDSVBDB kbGrpDSNet kb32bitOnly Technology : kbVBSearch kbAudDeveloper kbVB400Search kbVB400 Version : WINDOWS:4.0 Issue type : kbhowto ============================================================================= THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY. Copyright Microsoft Corporation 2001.