Search
Module:
Directory

   Desktop Functions:

   Smart Device Functions:


Show Recent Changes
Subscribe (RSS)
Misc. Pages
Comments
FAQ
Helpful Tools
Playground
Suggested Reading
Website TODO List
Download Visual Studio Add-In

NetLocalGroupEnum (netapi32)
 
.
Summary
Returns information about each local group account on the specified server.

C# Signature:

[DllImport("Netapi32.dll")]
internal extern static int NetLocalGroupEnum([MarshalAs(UnmanagedType.LPWStr)]
       string servername,
       int level,
       out IntPtr bufptr,
       int prefmaxlen,
       out int entriesread,
       out int totalentries,
       ref int resume_handle);

VB Signature:

Declare Function NetLocalGroupEnum Lib "netapi32.dll" (TODO) As TODO

User-Defined Types:

Managed version of the LOCALGROUP_INFO_0 and LOCALGROUP_INFO_1 structures:

    [StructLayout(LayoutKind.Sequential, CharSet=CharSet.Unicode)]
    internal struct LOCALGROUP_USERS_INFO_0
    {
        [MarshalAs(UnmanagedType.LPWStr)]internal string name;
    }

    [StructLayout(LayoutKind.Sequential)]
    internal struct LOCALGROUP_USERS_INFO_1
    {
        [MarshalAs(UnmanagedType.LPWStr)] public string name;
        [MarshalAs(UnmanagedType.LPWStr)] public string comment;
    }

Notes:

None.

Tips & Tricks:

The largest challenge is marshaling the pointer to the array of structures which the output is placed in.

In this example, I use a do/while which doubles the size of the buffer until it is large enough to contain all of the groups that are on the server. The API call is designed so that you can read sequentially (ERROR_MORE_DATA), but I didn't want to deal with marshaling returned data stored in more than one of the pointers to the array of structures which the output is placed in!

Sample Code:

        private string [] GetAllLocalGroups(string ServerName) {
            int size=1024;    //Start with 1k
            IntPtr bufptr=new IntPtr(size);
            int level=0;
            int prefmaxlen=1023;
            int entriesread=0;
            int totalentries=0;
            int resume_handle=0;
            int err=0;
            do
            {
                err= NativeMethods.NetLocalGroupEnum(
                    ServerName,
                    level,
                    out bufptr,
                    prefmaxlen,
                    out entriesread,
                    out totalentries,
                    ref resume_handle
                );
                switch(err)
                {
                    //If there is more data, double the size of the buffer...
                    case 2123:        //NERR_BufTooSmall
                    case 234:        //ERROR_MORE_DATA
                        size*=2;
                        bufptr=new IntPtr(size);
                        prefmaxlen=size-1;    //Increase the size you want read as well
                        resume_handle=0;    //And reset the resume_handle or you'll just pick up where you left off.

                        break;
                    case 2351:    //NERR_InvalidComputer
                    case 0:        //NERR_Success
                    default:
                        break;
                }
            }
            while(err==234);    // and start over

            LOCALGROUP_USERS_INFO_0 group=new LOCALGROUP_USERS_INFO_0(); //See user type above
            string [] ret = new string[totalentries];
            IntPtr iter = bufptr;

            for(int i=0; i < totalentries; i++)
            {
                group = (LOCALGROUP_USERS_INFO_0)Marshal.PtrToStructure(iter, typeof(LOCALGROUP_USERS_INFO_0));
                ret[i] = group.name;
                iter = (IntPtr)((int)iter + Marshal.SizeOf(typeof(LOCALGROUP_USERS_INFO_0)));
            }

            return ret;
        }

Please be careful with the above code:

1. if you want all the entries you can just pass MAX_PREFERRED_LENGTH to prefmaxlen

2. the loop should be over read entries and not total entries (see msdn)

3. the code is missing the deallocation of the data using NetApiBufferFree.

Here it is the revised code.

Alternative Managed API:

Do you know one? Please contribute it!

        [DllImport("Netapi32.dll")]
        internal extern static int NetLocalGroupEnum(
            [MarshalAs(UnmanagedType.LPWStr)] string servername,
               int level,
               out IntPtr bufptr,
               int prefmaxlen,
               out int entriesread,
               out int totalentries,
               ref int resume_handle);

        [DllImport("Netapi32.dll")]
        internal extern static int NetApiBufferFree(IntPtr buffer);

        private static readonly int NERR_Success = 0;

        private static readonly int ERROR_ACCESS_DENIED = 5;
        private static readonly int ERROR_MORE_DATA = 234;
        private static readonly int NERR_Base = 2100;
        private static readonly int NERR_InvalidComputer = NERR_Base + 251;
        private static readonly int NERR_BufTooSmall = NERR_Base + 23;

        public static LOCALGROUP_USERS_INFO_1[] GetAllLocalGroups()
        {
            return GetAllLocalGroups(null);
        }

        public static LOCALGROUP_USERS_INFO_1[] GetAllLocalGroups(string serverName)
        {
            int res = 0;
            int level = 1;
            IntPtr buffer = IntPtr.Zero;
            int MAX_PREFERRED_LENGTH = -1;
            int read, total;
            int handle = 0;

            var groups = new List<LOCALGROUP_USERS_INFO_1>();
            try
            {
                res = NetLocalGroupEnum(serverName, level, out buffer, MAX_PREFERRED_LENGTH,
                    out read, out total, ref handle);

                if (res != NERR_Success)
                {
                    DumpError(res);
                    return groups.ToArray();
                }

                IntPtr ptr = buffer;
                for (int i = 0; i < read; i++)
                {
                    var group = (LOCALGROUP_USERS_INFO_1)Marshal.PtrToStructure(ptr, typeof(LOCALGROUP_USERS_INFO_1));
                    groups.Add(group);
                    ptr = (IntPtr)((int)ptr + Marshal.SizeOf(typeof(LOCALGROUP_USERS_INFO_1)));
                }
            }
            finally
            {
                NetApiBufferFree(buffer);
            }

            return groups.ToArray();
        }

        private static void DumpError(int res)
        {
            if(res == ERROR_ACCESS_DENIED)
                Trace.WriteLine("ERROR_ACCESS_DENIED");
            else if(res == ERROR_MORE_DATA)
                    Trace.WriteLine("ERROR_MORE_DATA");
            else if(res == NERR_InvalidComputer)
                    Trace.WriteLine("NERR_InvalidComputer");
            else if(res == NERR_BufTooSmall)
                    Trace.WriteLine("NERR_BufTooSmall");
            else
                Trace.WriteLine("Error 0x" + res.ToString("x"));
        }

Alternative Managed API:

Do you know one? Please contribute it!

Documentation

Please edit this page!

Do you have...

  • helpful tips or sample code to share for using this API in managed code?
  • corrections to the existing content?
  • variations of the signature you want to share?
  • additional languages you want to include?

Select "Edit This Page" on the right hand toolbar and edit it! Or add new pages containing supporting types needed for this API (structures, delegates, and more).

 
Access PInvoke.net directly from VS:
Terms of Use
Edit This Page
Find References
Show Printable Version
Revisions