Win32 API 日本語リファレンス
ホームNetworkManagement.NetManagement › NetApiBufferAllocate

NetApiBufferAllocate

関数
ネットワークAPI関数用のメモリバッファを割り当てる。
DLLNETAPI32.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

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

DWORD NetApiBufferAllocate(
    DWORD ByteCount,
    void** Buffer
);

パラメーター

名前方向説明
ByteCountDWORDin割り当てるバイト数。
Buffervoid**out割り当てられたバッファーへのポインターを受け取ります。

戻り値の型: DWORD

公式ドキュメント

NetApiBufferAllocate 関数は、ヒープからメモリを割り当てます。この関数は、NetApiBufferFree 関数との互換性が必要な場合にのみ使用してください。それ以外の場合は、メモリ管理関数を使用してください。

戻り値

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

関数が失敗した場合、戻り値はシステムエラーコードです。エラーコードの一覧については、 System Error Codes を参照してください。

解説(Remarks)

ApiBuffer 関数を正常に実行するために、特別なグループのメンバーシップは必要ありません。

詳細については、 Network Management Function Buffers および Network Management Function Buffer Lengths を参照してください。

次のコードサンプルは、ネットワーク管理の ApiBuffer 関数の使用方法を示しています。

このサンプルでは、まず NetApiBufferAllocate 関数を呼び出してメモリを割り当て、次に NetApiBufferSize 関数を呼び出して割り当てられたメモリのサイズを取得します。その後、サンプルは NetApiBufferReallocate を呼び出してメモリ割り当てのサイズを変更します。最後に、サンプルは NetApiBufferFree を呼び出してメモリを解放します。いずれの場合も、サンプルは成功または失敗を示すメッセージを出力します。

#ifndef UNICODE
#define UNICODE
#endif

#include <windows.h>
#include <lm.h>
#include <stdio.h>

#pragma comment(lib, "netapi32.lib")

void PrintError(LPSTR lpszApi, DWORD res);

int main()
{
   PUSER_INFO_10 p;
   DWORD res, dwSize;

   // NetApiBufferAllocate 関数を呼び出して
   //   メモリを割り当てます。成功した場合は
   //   メッセージを出力します。
   //
   res = NetApiBufferAllocate(1024, (LPVOID *) &p);
   if(res == NERR_Success)
   {
      printf("NetApiBufferAllocate:   Allocated 1024 bytes.\n");

      // NetApiBufferSize 関数を呼び出して
      //   割り当てられたバッファーのサイズを取得します。
      //   成功した場合はサイズを出力します。
      //
      res = NetApiBufferSize(p, &dwSize);
      if(res == NERR_Success)
      {
         printf("NetApiBufferSize:       Buffer has %u bytes.\n", dwSize);

         // NetApiBufferReallocate 関数を呼び出して
         //   割り当てられたメモリのサイズを変更します。
         //   成功した場合はバッファーの新しいサイズを出力します。
         //
         res = NetApiBufferReallocate(p, dwSize * 2, (LPVOID *) &p);   
         if(res == NERR_Success)
            printf("NetApiBufferReallocate: Re-Allocated %u bytes.\n", dwSize * 2);
         else
            PrintError("NetApiBufferReallocate", res);

         // NetApiBufferFree 関数を呼び出して
         //    割り当てられたメモリを解放します。
         //    成功した場合はメッセージを出力します。
         //
         res = NetApiBufferFree(p);
         if(res == NERR_Success)
            printf("Freed Buffer\n");

         else
            PrintError("NetApiBufferFree", res);
      }
      else
         PrintError("NetApiBufferSize", res);
   }         
   else
      PrintError("NetApiBufferAllocate", res);
   return 0;
}

void PrintError(LPSTR lpszApi, DWORD res)
{
   printf("%s: Error %u\n", lpszApi, res);
   return;
}
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

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

DWORD NetApiBufferAllocate(
    DWORD ByteCount,
    void** Buffer
);
[DllImport("NETAPI32.dll", ExactSpelling = true)]
static extern uint NetApiBufferAllocate(
    uint ByteCount,   // DWORD
    IntPtr Buffer   // void** out
);
<DllImport("NETAPI32.dll", ExactSpelling:=True)>
Public Shared Function NetApiBufferAllocate(
    ByteCount As UInteger,   ' DWORD
    Buffer As IntPtr   ' void** out
) As UInteger
End Function
' ByteCount : DWORD
' Buffer : void** out
Declare PtrSafe Function NetApiBufferAllocate Lib "netapi32" ( _
    ByVal ByteCount As Long, _
    ByVal Buffer As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

NetApiBufferAllocate = ctypes.windll.netapi32.NetApiBufferAllocate
NetApiBufferAllocate.restype = wintypes.DWORD
NetApiBufferAllocate.argtypes = [
    wintypes.DWORD,  # ByteCount : DWORD
    ctypes.c_void_p,  # Buffer : void** out
]
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('NETAPI32.dll')
NetApiBufferAllocate = Fiddle::Function.new(
  lib['NetApiBufferAllocate'],
  [
    -Fiddle::TYPE_INT,  # ByteCount : DWORD
    Fiddle::TYPE_VOIDP,  # Buffer : void** out
  ],
  -Fiddle::TYPE_INT)
#[link(name = "netapi32")]
extern "system" {
    fn NetApiBufferAllocate(
        ByteCount: u32,  // DWORD
        Buffer: *mut *mut ()  // void** out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[DllImport("NETAPI32.dll")]
public static extern uint NetApiBufferAllocate(uint ByteCount, IntPtr Buffer);
"@
$api = Add-Type -MemberDefinition $sig -Name 'NETAPI32_NetApiBufferAllocate' -Namespace Win32 -PassThru
# $api::NetApiBufferAllocate(ByteCount, Buffer)
#uselib "NETAPI32.dll"
#func global NetApiBufferAllocate "NetApiBufferAllocate" sptr, sptr
; NetApiBufferAllocate ByteCount, Buffer   ; 戻り値は stat
; ByteCount : DWORD -> "sptr"
; Buffer : void** out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
#uselib "NETAPI32.dll"
#cfunc global NetApiBufferAllocate "NetApiBufferAllocate" int, sptr
; res = NetApiBufferAllocate(ByteCount, Buffer)
; ByteCount : DWORD -> "int"
; Buffer : void** out -> "sptr"
; DWORD NetApiBufferAllocate(DWORD ByteCount, void** Buffer)
#uselib "NETAPI32.dll"
#cfunc global NetApiBufferAllocate "NetApiBufferAllocate" int, intptr
; res = NetApiBufferAllocate(ByteCount, Buffer)
; ByteCount : DWORD -> "int"
; Buffer : void** out -> "intptr"
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	netapi32 = windows.NewLazySystemDLL("NETAPI32.dll")
	procNetApiBufferAllocate = netapi32.NewProc("NetApiBufferAllocate")
)

// ByteCount (DWORD), Buffer (void** out)
r1, _, err := procNetApiBufferAllocate.Call(
	uintptr(ByteCount),
	uintptr(Buffer),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // DWORD
function NetApiBufferAllocate(
  ByteCount: DWORD;   // DWORD
  Buffer: Pointer   // void** out
): DWORD; stdcall;
  external 'NETAPI32.dll' name 'NetApiBufferAllocate';
result := DllCall("NETAPI32\NetApiBufferAllocate"
    , "UInt", ByteCount   ; DWORD
    , "Ptr", Buffer   ; void** out
    , "UInt")   ; return: DWORD
●NetApiBufferAllocate(ByteCount, Buffer) = DLL("NETAPI32.dll", "dword NetApiBufferAllocate(dword, void*)")
# 呼び出し: NetApiBufferAllocate(ByteCount, Buffer)
# ByteCount : DWORD -> "dword"
# Buffer : void** out -> "void*"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
const std = @import("std");

extern "netapi32" fn NetApiBufferAllocate(
    ByteCount: u32, // DWORD
    Buffer: ?*anyopaque // void** out
) callconv(std.os.windows.WINAPI) u32;
proc NetApiBufferAllocate(
    ByteCount: uint32,  # DWORD
    Buffer: pointer  # void** out
): uint32 {.importc: "NetApiBufferAllocate", stdcall, dynlib: "NETAPI32.dll".}
pragma(lib, "netapi32");
extern(Windows)
uint NetApiBufferAllocate(
    uint ByteCount,   // DWORD
    void** Buffer   // void** out
);
ccall((:NetApiBufferAllocate, "NETAPI32.dll"), stdcall, UInt32,
      (UInt32, Ptr{Cvoid}),
      ByteCount, Buffer)
# ByteCount : DWORD -> UInt32
# Buffer : void** out -> Ptr{Cvoid}
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
local ffi = require("ffi")
ffi.cdef[[
uint32_t NetApiBufferAllocate(
    uint32_t ByteCount,
    void** Buffer);
]]
local netapi32 = ffi.load("netapi32")
-- netapi32.NetApiBufferAllocate(ByteCount, Buffer)
-- ByteCount : DWORD
-- Buffer : void** out
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
const koffi = require('koffi');
const lib = koffi.load('NETAPI32.dll');
const NetApiBufferAllocate = lib.func('__stdcall', 'NetApiBufferAllocate', 'uint32_t', ['uint32_t', 'void *']);
// NetApiBufferAllocate(ByteCount, Buffer)
// ByteCount : DWORD -> 'uint32_t'
// Buffer : void** out -> 'void *'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("NETAPI32.dll", {
  NetApiBufferAllocate: { parameters: ["u32", "pointer"], result: "u32" },
});
// lib.symbols.NetApiBufferAllocate(ByteCount, Buffer)
// ByteCount : DWORD -> "u32"
// Buffer : void** out -> "pointer"
// 文字列引数は "buffer"(NUL 終端のバイト列を Uint8Array で渡す)。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
uint32_t NetApiBufferAllocate(
    uint32_t ByteCount,
    void** Buffer);
C, "NETAPI32.dll");
// $ffi->NetApiBufferAllocate(ByteCount, Buffer);
// ByteCount : DWORD
// Buffer : void** out
// 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
// WINAPI(stdcall): x64 では呼出規約が統一されるため問題なし。x86 では __stdcall 対応のラッパが必要な場合あり。
import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

public interface Netapi32 extends StdCallLibrary {
    Netapi32 INSTANCE = Native.load("netapi32", Netapi32.class);
    int NetApiBufferAllocate(
        int ByteCount,   // DWORD
        Pointer Buffer   // void** out
    );
}
@[Link("netapi32")]
lib LibNETAPI32
  fun NetApiBufferAllocate = NetApiBufferAllocate(
    ByteCount : UInt32,   # DWORD
    Buffer : Void**   # void** out
  ) : UInt32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef NetApiBufferAllocateNative = Uint32 Function(Uint32, Pointer<Void>);
typedef NetApiBufferAllocateDart = int Function(int, Pointer<Void>);
final NetApiBufferAllocate = DynamicLibrary.open('NETAPI32.dll')
    .lookupFunction<NetApiBufferAllocateNative, NetApiBufferAllocateDart>('NetApiBufferAllocate');
// ByteCount : DWORD -> Uint32
// Buffer : void** out -> Pointer<Void>
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function NetApiBufferAllocate(
  ByteCount: DWORD;   // DWORD
  Buffer: Pointer   // void** out
): DWORD; stdcall;
  external 'NETAPI32.dll' name 'NetApiBufferAllocate';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "NetApiBufferAllocate"
  c_NetApiBufferAllocate :: Word32 -> Ptr () -> IO Word32
-- ByteCount : DWORD -> Word32
-- Buffer : void** out -> Ptr ()
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let netapibufferallocate =
  foreign "NetApiBufferAllocate"
    (uint32_t @-> (ptr void) @-> returning uint32_t)
(* ByteCount : DWORD -> uint32_t *)
(* Buffer : void** out -> (ptr void) *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library netapi32 (t "NETAPI32.dll"))
(cffi:use-foreign-library netapi32)

(cffi:defcfun ("NetApiBufferAllocate" net-api-buffer-allocate :convention :stdcall) :uint32
  (byte-count :uint32)   ; DWORD
  (buffer :pointer))   ; void** out
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $NetApiBufferAllocate = Win32::API::More->new('NETAPI32',
    'DWORD NetApiBufferAllocate(DWORD ByteCount, LPVOID Buffer)');
# my $ret = $NetApiBufferAllocate->Call($ByteCount, $Buffer);
# ByteCount : DWORD -> DWORD
# Buffer : void** out -> LPVOID
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。

関連項目

公式の関連項目