Export (0) Print
Expand All
Expand Minimize

NetApiBufferAllocate function

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 NetApiBufferAllocate(
  _In_   DWORD ByteCount,
  _Out_  LPVOID *Buffer
);

Parameters

ByteCount [in]

Number of bytes to be allocated.

Buffer [out]

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

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Lmapibuf.h (include Lm.h)

Library

Netapi32.lib

DLL

Netapi32.dll

See also

Network Management Overview
Network Management Functions
Api Buffer Functions
NetApiBufferFree
NetApiBufferReallocate

 

 

Community Additions

ADD
Show:
© 2014 Microsoft