Função NetApiBufferAllocate (lmapibuf.h)

A função NetApiBufferAllocate aloca memória do heap. Use essa função somente quando a compatibilidade com a função NetApiBufferFree for necessária. Caso contrário, use as funções de gerenciamento de memória.

Sintaxe

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

Parâmetros

[in] ByteCount

Número de bytes a serem alocados.

[out] Buffer

Recebe um ponteiro para o buffer alocado.

Valor retornado

Se a função for bem-sucedida, o valor retornado será NERR_Success.

Se a função falhar, o valor retornado será um código de erro do sistema. Para obter uma lista de códigos de erro, consulte Códigos de erro do sistema.

Comentários

Nenhuma associação de grupo especial é necessária para executar com êxito as funções do ApiBuffer.

Para obter mais informações, consulte Buffers de função de gerenciamento de rede e Comprimentos de buffer de função de gerenciamento de rede.

Exemplos

O exemplo de código a seguir demonstra como usar as funções ApiBuffer de gerenciamento de rede.

O exemplo primeiro chama a função NetApiBufferAllocate para alocar memória e, em seguida, a função NetApiBufferSize para recuperar o tamanho da memória alocada. A seguir, o exemplo chama NetApiBufferReallocate para alterar o tamanho da alocação de memória. Por fim, o exemplo chama NetApiBufferFree para liberar a memória. Em cada caso, o exemplo imprime uma mensagem indicando êxito ou falha.

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

Requisitos

Confira também

Funções de buffer de API

NetApiBufferFree

NetApiBufferReallocate

Funções de gerenciamento de rede

Visão geral do gerenciamento de rede