ホーム › NetworkManagement.NetManagement › NetLocalGroupEnum

NetLocalGroupEnum

関数

サーバー上のローカルグループを列挙する。

DLLNETAPI32.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

// NETAPI32.dll
#include <windows.h>

DWORD NetLocalGroupEnum(
    LPCWSTR servername,   // optional
    DWORD level,
    BYTE** bufptr,
    DWORD prefmaxlen,
    DWORD* entriesread,
    DWORD* totalentries,
    UINT_PTR* resumehandle   // optional
);

パラメーター

名前

型

方向

説明

servername

LPCWSTR

inoptional

関数を実行するリモートサーバーの DNS 名または NetBIOS 名を指定する定数文字列へのポインター。このパラメーターが NULL の場合、ローカルコンピューターが使用されます。

level

DWORD

データの情報レベルを指定します。このパラメーターには次のいずれかの値を指定できます。

Value	Meaning
0	ローカルグループ名を返します。bufptr パラメーターは LOCALGROUP_INFO_0 構造体の配列を指します。
1	ローカルグループ名と、各グループに関連付けられたコメントを返します。bufptr パラメーターは LOCALGROUP_INFO_1 構造体の配列を指します。

bufptr

BYTE**

out

情報構造体を受け取るバッファーのアドレスへのポインター。このデータの形式は level パラメーターの値によって異なります。このバッファーはシステムによって割り当てられ、 NetApiBufferFree 関数を使用して解放する必要があります。関数が ERROR_MORE_DATA で失敗した場合でも、バッファーを解放する必要があることに注意してください。

prefmaxlen

DWORD

返されるデータの推奨される最大長をバイト単位で指定します。MAX_PREFERRED_LENGTH を指定すると、関数はデータに必要なメモリ量を割り当てます。このパラメーターに別の値を指定すると、関数が返すバイト数を制限できます。バッファーサイズがすべてのエントリを保持するのに不十分な場合、関数は ERROR_MORE_DATA を返します。詳細については、 Network Management Function Buffers および Network Management Function Buffer Lengths を参照してください。

entriesread

DWORD*

out

実際に列挙された要素の数を受け取る値へのポインター。

totalentries

DWORD*

out

現在の再開位置から列挙できたであろうエントリの概算合計数を受け取る値へのポインター。エントリの合計数はあくまで目安です。正確なエントリ数の判定方法の詳細については、次の「Remarks」セクションを参照してください。

resumehandle

UINT_PTR*

inoutoptional

既存のローカルグループ検索を継続するために使用される再開ハンドルを格納する値へのポインター。このハンドルは最初の呼び出しではゼロにし、後続の呼び出しでは変更せずにそのままにする必要があります。このパラメーターが NULL の場合、再開ハンドルは格納されません。詳細については、次の「Remarks」セクションを参照してください。

戻り値の型: DWORD

公式ドキュメント

NetLocalGroupEnum 関数は、指定したサーバー上の各ローカルグループアカウントに関する情報を返します。

戻り値

関数が成功した場合、戻り値は NERR_Success です。

関数が失敗した場合、戻り値は次のいずれかのエラーコードになります。

Return code	Description
ERROR_ACCESS_DENIED	ユーザーは要求された情報へのアクセス権を持っていません。
ERROR_MORE_DATA	さらにエントリが存在します。すべてのエントリを受け取るのに十分な大きさのバッファーを指定してください。
NERR_InvalidComputer	コンピューター名が無効です。
NERR_BufTooSmall	戻りバッファーが小さすぎます。

解説(Remarks)

Active Directory を実行しているドメインコントローラー上でこの関数を呼び出す場合、アクセスは securable object のアクセス制御リスト (ACL) に基づいて許可または拒否されます。既定の ACL では、すべての認証済みユーザーおよび「Pre-Windows 2000 compatible access」グループのメンバーが情報を表示できます。メンバーサーバーまたはワークステーション上でこの関数を呼び出す場合、すべての認証済みユーザーが情報を表示できます。これらのプラットフォームにおける匿名アクセスおよび匿名アクセスの制限についての情報は、 Security Requirements for the Network Management Functions を参照してください。ACL、ACE、およびアクセストークンの詳細については、 Access Control Model を参照してください。

この関数は、呼び出し元が Read アクセス権を持つ情報のみを返します。呼び出し元は Domain オブジェクトに対する List Contents アクセス権、および System コンテナー内にある SAM Server オブジェクトに対する Enumerate Entire SAM Domain アクセス権を持っている必要があります。

ローカルグループの正確な合計数を判定するには、ツリー全体を列挙する必要があり、これはコストの高い操作になる場合があります。ツリー全体を列挙するには、resumehandle パラメーターを使用して連続する呼び出しで列挙を継続し、entriesread パラメーターを使用してローカルグループの合計数を累積します。アプリケーションがドメインコントローラーと通信している場合は、この種のデータをより効率的に取得するために ADSI LDAP Provider の使用を検討してください。ADSI LDAP Provider は、さまざまな ADSI インターフェイスをサポートする一連の ADSI オブジェクトを実装しています。詳細については、 ADSI Service Providers を参照してください。

ユーザーアカウント名は 20 文字までに制限され、グループ名は 256 文字までに制限されます。さらに、アカウント名はピリオドで終わることはできず、カンマや次の印字可能文字を含めることもできません: ", /, , [, ], :, |, <, >, +, =, ;, ?, *。また、名前には非印字文字である 1〜31 の範囲の文字を含めることもできません。

Active Directory 向けにプログラミングしている場合、特定の Active Directory Service Interface (ADSI) メソッドを呼び出すことで、ネットワーク管理ローカルグループ関数を呼び出す場合と同じ機能を実現できることがあります。詳細については、 IADsGroup を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// NETAPI32.dll
#include <windows.h>

DWORD NetLocalGroupEnum(
    LPCWSTR servername,   // optional
    DWORD level,
    BYTE** bufptr,
    DWORD prefmaxlen,
    DWORD* entriesread,
    DWORD* totalentries,
    UINT_PTR* resumehandle   // optional
);

[DllImport("NETAPI32.dll", ExactSpelling = true)]
static extern uint NetLocalGroupEnum(
    [MarshalAs(UnmanagedType.LPWStr)] string servername,   // LPCWSTR optional
    uint level,   // DWORD
    IntPtr bufptr,   // BYTE** out
    uint prefmaxlen,   // DWORD
    out uint entriesread,   // DWORD* out
    out uint totalentries,   // DWORD* out
    IntPtr resumehandle   // UINT_PTR* optional, in/out
);

<DllImport("NETAPI32.dll", ExactSpelling:=True)>
Public Shared Function NetLocalGroupEnum(
    <MarshalAs(UnmanagedType.LPWStr)> servername As String,   ' LPCWSTR optional
    level As UInteger,   ' DWORD
    bufptr As IntPtr,   ' BYTE** out
    prefmaxlen As UInteger,   ' DWORD
    <Out> ByRef entriesread As UInteger,   ' DWORD* out
    <Out> ByRef totalentries As UInteger,   ' DWORD* out
    resumehandle As IntPtr   ' UINT_PTR* optional, in/out
) As UInteger
End Function

' servername : LPCWSTR optional
' level : DWORD
' bufptr : BYTE** out
' prefmaxlen : DWORD
' entriesread : DWORD* out
' totalentries : DWORD* out
' resumehandle : UINT_PTR* optional, in/out
Declare PtrSafe Function NetLocalGroupEnum Lib "netapi32" ( _
    ByVal servername As LongPtr, _
    ByVal level As Long, _
    ByVal bufptr As LongPtr, _
    ByVal prefmaxlen As Long, _
    ByRef entriesread As Long, _
    ByRef totalentries As Long, _
    ByVal resumehandle As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

NetLocalGroupEnum = ctypes.windll.netapi32.NetLocalGroupEnum
NetLocalGroupEnum.restype = wintypes.DWORD
NetLocalGroupEnum.argtypes = [
    wintypes.LPCWSTR,  # servername : LPCWSTR optional
    wintypes.DWORD,  # level : DWORD
    ctypes.c_void_p,  # bufptr : BYTE** out
    wintypes.DWORD,  # prefmaxlen : DWORD
    ctypes.POINTER(wintypes.DWORD),  # entriesread : DWORD* out
    ctypes.POINTER(wintypes.DWORD),  # totalentries : DWORD* out
    ctypes.POINTER(ctypes.c_size_t),  # resumehandle : UINT_PTR* optional, in/out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('NETAPI32.dll')
NetLocalGroupEnum = Fiddle::Function.new(
  lib['NetLocalGroupEnum'],
  [
    Fiddle::TYPE_VOIDP,  # servername : LPCWSTR optional
    -Fiddle::TYPE_INT,  # level : DWORD
    Fiddle::TYPE_VOIDP,  # bufptr : BYTE** out
    -Fiddle::TYPE_INT,  # prefmaxlen : DWORD
    Fiddle::TYPE_VOIDP,  # entriesread : DWORD* out
    Fiddle::TYPE_VOIDP,  # totalentries : DWORD* out
    Fiddle::TYPE_VOIDP,  # resumehandle : UINT_PTR* optional, in/out
  ],
  -Fiddle::TYPE_INT)

#[link(name = "netapi32")]
extern "system" {
    fn NetLocalGroupEnum(
        servername: *const u16,  // LPCWSTR optional
        level: u32,  // DWORD
        bufptr: *mut *mut u8,  // BYTE** out
        prefmaxlen: u32,  // DWORD
        entriesread: *mut u32,  // DWORD* out
        totalentries: *mut u32,  // DWORD* out
        resumehandle: *mut usize  // UINT_PTR* optional, in/out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("NETAPI32.dll")]
public static extern uint NetLocalGroupEnum([MarshalAs(UnmanagedType.LPWStr)] string servername, uint level, IntPtr bufptr, uint prefmaxlen, out uint entriesread, out uint totalentries, IntPtr resumehandle);
"@
$api = Add-Type -MemberDefinition $sig -Name 'NETAPI32_NetLocalGroupEnum' -Namespace Win32 -PassThru
# $api::NetLocalGroupEnum(servername, level, bufptr, prefmaxlen, entriesread, totalentries, resumehandle)

#uselib "NETAPI32.dll"
#func global NetLocalGroupEnum "NetLocalGroupEnum" sptr, sptr, sptr, sptr, sptr, sptr, sptr
; NetLocalGroupEnum servername, level, varptr(bufptr), prefmaxlen, varptr(entriesread), varptr(totalentries), varptr(resumehandle)   ; 戻り値は stat
; servername : LPCWSTR optional -> "sptr"
; level : DWORD -> "sptr"
; bufptr : BYTE** out -> "sptr"
; prefmaxlen : DWORD -> "sptr"
; entriesread : DWORD* out -> "sptr"
; totalentries : DWORD* out -> "sptr"
; resumehandle : UINT_PTR* optional, in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "NETAPI32.dll"
#cfunc global NetLocalGroupEnum "NetLocalGroupEnum" wstr, int, var, int, var, var, var
; res = NetLocalGroupEnum(servername, level, bufptr, prefmaxlen, entriesread, totalentries, resumehandle)
; servername : LPCWSTR optional -> "wstr"
; level : DWORD -> "int"
; bufptr : BYTE** out -> "var"
; prefmaxlen : DWORD -> "int"
; entriesread : DWORD* out -> "var"
; totalentries : DWORD* out -> "var"
; resumehandle : UINT_PTR* optional, in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "NETAPI32.dll"
#cfunc global NetLocalGroupEnum "NetLocalGroupEnum" wstr, int, sptr, int, sptr, sptr, sptr
; res = NetLocalGroupEnum(servername, level, varptr(bufptr), prefmaxlen, varptr(entriesread), varptr(totalentries), varptr(resumehandle))
; servername : LPCWSTR optional -> "wstr"
; level : DWORD -> "int"
; bufptr : BYTE** out -> "sptr"
; prefmaxlen : DWORD -> "int"
; entriesread : DWORD* out -> "sptr"
; totalentries : DWORD* out -> "sptr"
; resumehandle : UINT_PTR* optional, in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。