NetApiBufferAllocate function (lmapibuf.h)

Article
02/22/2024

The NetApiBufferAllocate function allocates memory from the heap. Use this function only when compatibility with the NetApiBufferFree function is required. Otherwise, use the memory management functions.

Syntax

NET_API_STATUS NET_API_FUNCTION NetApiBufferAllocate(
  [in]  DWORD  ByteCount,
  [out] LPVOID *Buffer
);

Parameters

[in] ByteCount

Number of bytes to be allocated.

[out] Buffer

Receives a pointer to the allocated buffer.

Return value

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a system error code. For a list of error codes, see System Error Codes.

Remarks

No special group membership is required to successfully execute the ApiBuffer functions.

For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.

Examples

The following code sample demonstrates how to use the network management ApiBuffer functions.

The sample first calls the NetApiBufferAllocate function to allocate memory and then the NetApiBufferSize function to retrieve the size of the allocated memory. Following this, the sample calls NetApiBufferReallocate to change the size of the memory allocation. Finally, the sample calls NetApiBufferFree to free the memory. In each case, the sample prints a message indicating success or failure.

#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;

   // Call the NetApiBufferAllocate function 
   //   to allocate the memory. If successful,
   //   print a message.
   //
   res = NetApiBufferAllocate(1024, (LPVOID *) &p);
   if(res == NERR_Success)
   {
      printf("NetApiBufferAllocate:   Allocated 1024 bytes.\n");

      // Call the NetApiBufferSize function 
      //   to retrieve the size of the allocated buffer.
      //   If successful, print the size.
      //
      res = NetApiBufferSize(p, &dwSize);
      if(res == NERR_Success)
      {
         printf("NetApiBufferSize:       Buffer has %u bytes.\n", dwSize);

         // Call the NetApiBufferReallocate function
         //   to change the size of the allocated memory.
         //   If successful, print the new size of the buffer.
         //
         res = NetApiBufferReallocate(p, dwSize * 2, (LPVOID *) &p);   
         if(res == NERR_Success)
            printf("NetApiBufferReallocate: Re-Allocated %u bytes.\n", dwSize * 2);
         else
            PrintError("NetApiBufferReallocate", res);

         // Call the NetApiBufferFree function
         //    to free the allocated memory.
         //    If successful, print a message.
         //
         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;
}

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	lmapibuf.h (include Lm.h)
Library	Netapi32.lib
DLL	Netapi32.dll