NetApiBufferFree function

The NetApiBufferFree function frees the memory that the NetApiBufferAllocate function allocates. Applications should also call NetApiBufferFree to free the memory that other network management functions use internally to return information.

Syntax


NET_API_STATUS NetApiBufferFree(
  _In_ LPVOID Buffer
);

Parameters

Buffer [in]

A pointer to a buffer returned previously by another network management function or memory allocated by calling the NetApiBufferAllocate function.

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

The NetApiBufferFree function is used to free memory used by network management functions. This function is used in two cases:

  • To free memory explicitly allocated by calls in an application to the NetApiBufferAllocate function when the memory is no longer needed.
  • To free memory allocated internally by calls in an application to remotable network management functions that return information to the caller. The RPC run-time library internally allocates the buffer containing the return information.

Many network management functions retrieve information and return this information as a buffer that may contain a complex structure, an array of structures, or an array of nested structures. These functions use the RPC run-time library to internally allocate the buffer containing the return information, whether the call is to a local computer or a remote server. For example, the NetServerEnum function retrieves a lists of servers and returns this information as an array of structures pointed to by the bufptr parameter. When the function is successful, memory is allocated internally by the NetServerEnum function to store the array of structures returned in the bufptr parameter to the application. When this array of structures is no longer needed, the NetApiBufferFree function should be called by the application with the Buffer parameter set to the bufptr parameter returned by NetServerEnum to free this internal memory used. In these cases, the NetApiBufferFree function frees all of the internal memory allocated for the buffer including memory for nested structures, pointers to strings, and other data.

No special group membership is required to successfully execute the NetApiBufferFree function or any of the other ApiBuffer functions.

For a code sample that demonstrates how to use of the NetApiBufferFree function to free memory explicitly allocated by an application, see the NetApiBufferAllocate function.

For a code sample that demonstrates how to use of the NetApiBufferFree function to free memory internally allocated by a network management function to return information, see the NetServerEnum function.

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 Function Buffers
Network Management Function Buffer Lengths
Network Management Overview
Network Management Functions
Api Buffer Functions
NetApiBufferAllocate
NetApiBufferReallocate
NetApiBufferSize

 

 

Show: