Função NetAlertRaise (lmalert.h)

Artigo
08/24/2023

[Não há suporte para essa função a partir do Windows Vista porque não há suporte para o serviço de alerta.]

A função NetAlertRaise notifica todos os clientes registrados quando ocorre um evento específico.

Para simplificar o envio de uma mensagem de alerta, você pode chamar a função estendida NetAlertRaiseEx . NetAlertRaiseEx não exige que você especifique uma estrutura STD_ALERT .

Sintaxe

NET_API_STATUS NET_API_FUNCTION NetAlertRaise(
  [in] LPCWSTR AlertType,
  [in] LPVOID  Buffer,
  [in] DWORD   BufferSize
);

Parâmetros

[in] AlertType

Um ponteiro para uma cadeia de caracteres constante que especifica a classe de alerta (tipo de alerta) a ser gerada. Esse parâmetro pode ser um dos seguintes valores predefinidos ou uma classe de alerta definida pelo usuário para aplicativos de rede. O nome do evento de um alerta pode ser qualquer cadeia de texto.

Nome	Significado
ALERT_ADMIN_EVENT	A intervenção de um administrador é necessária.
ALERT_ERRORLOG_EVENT	Uma entrada foi adicionada ao log de erros.
ALERT_MESSAGE_EVENT	Um usuário ou aplicativo recebeu uma mensagem de difusão.
ALERT_PRINT_EVENT	Um trabalho de impressão foi concluído ou ocorreu um erro de impressão.
ALERT_USER_EVENT	Um aplicativo ou recurso foi usado.

[in] Buffer

Um ponteiro para os dados a serem enviados aos clientes que escutam a mensagem de interrupção. Os dados devem começar com uma estrutura de STD_ALERT de comprimento fixo seguida por dados de mensagem adicionais em uma estrutura de ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO ou USER_OTHER_INFO . Por fim, o buffer deve incluir todas as informações de comprimento variável necessárias. Para obter mais informações, consulte o exemplo de código na seção Comentários a seguir.

O aplicativo de chamada deve alocar e liberar a memória para todas as estruturas e dados variáveis. Para obter mais informações, consulte Buffers de função de gerenciamento de rede.

[in] BufferSize

O tamanho, em bytes, do buffer de mensagens.

Retornar valor

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 e um poderá ser um dos códigos de erro a seguir. Para obter uma lista de todos os códigos de erro possíveis, consulte Códigos de erro do sistema.

Código de retorno	Descrição
ERROR_INVALID_PARAMETER	Um parâmetro está incorreto. Esse erro será retornado se o parâmetro AlertEventName for NULL ou uma cadeia de caracteres vazia, o parâmetro Buffer for NULL ou o parâmetro BufferSize for menor que o tamanho da estrutura STD_ALERT mais o tamanho fixo para a estrutura de dados de mensagem adicional.
ERROR_NOT_SUPPORTED	A solicitação não terá suporte. Esse erro é retornado no Windows Vista e posteriormente, pois não há suporte para o serviço Alerter.

Comentários

Nenhuma associação de grupo especial é necessária para executar com êxito a função NetAlertRaise .

O serviço de alerta deve estar em execução no computador cliente quando você chama a função NetAlertRaise ou a função falha com ERROR_FILE_NOT_FOUND.

Exemplos

O exemplo de código a seguir demonstra como gerar um alerta administrativo chamando a função NetAlertRaise e especificando estruturas STD_ALERT e ADMIN_OTHER_INFO . Primeiro, o exemplo calcula o tamanho do buffer de mensagens. Em seguida, ele aloca o buffer com uma chamada para a função GlobalAlloc . O código atribui valores aos membros do STD_ALERT e às partes ADMIN_OTHER_INFO do buffer. O exemplo recupera um ponteiro para a estrutura ADMIN_OTHER_INFO chamando a macro ALERT_OTHER_INFO . Ele também recupera um ponteiro para a parte de dados variáveis do buffer chamando a macro ALERT_VAR_DATA . Por fim, o exemplo de código libera a memória alocada para o buffer com uma chamada para a função GlobalFree .

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")

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

const int ALERT_VAR_DATA_SIZE = 216;

int wmain(int argc, wchar_t *argv[])
{
   int nBufferSize;
   LPVOID pAlertOtherInfo;
   PSTD_ALERT pStdAlert;              // STD_ALERT structure
   PADMIN_OTHER_INFO pAdminOtherInfo; // ADMIN_OTHER_INFO structure
   LPVOID pVarData; 
   time_t now;
   DWORD dwResult;
   //
   // Check command line arguments.
   //
   if (argc != 2)
   {
      fwprintf(stderr, L"Usage: %s LogFileName\n", argv[0]);
      exit(1);
   }
   // Calculate the buffer size;
   //  then allocate the memory for the buffer.
   //
   nBufferSize  = sizeof(STD_ALERT) + ALERT_VAR_DATA_SIZE;
   pAlertOtherInfo = (LPVOID) GlobalAlloc(GPTR, nBufferSize);

   if (pAlertOtherInfo == NULL)
   {
       fwprintf(stderr, L"Unable to allocate memory\n");
       exit(1);
   }

   //
   // Assign values to the STD_ALERT portion of the buffer.
   //   (This is required when you call NetAlertRaise.)
   //
   pStdAlert = (PSTD_ALERT)pAlertOtherInfo;
   time( &now );
   pStdAlert->alrt_timestamp = (DWORD)now;
   wcscpy_s(pStdAlert->alrt_eventname, EVLEN + 1, ALERT_ADMIN_EVENT);
   wcscpy_s(pStdAlert->alrt_servicename, SNLEN + 1, argv[0]);
   //
   // Retrieve the pointer to the ADMIN_OTHER_INFO structure 
   //  that follows the STD_ALERT portion of the buffer.
   //   Do this by calling the ALERT_OTHER_INFO macro.
   //
   pAdminOtherInfo = (PADMIN_OTHER_INFO)ALERT_OTHER_INFO(pAlertOtherInfo);
   //
   // Assign values to the ADMIN_OTHER_INFO structure.
   //
   pAdminOtherInfo->alrtad_numstrings = 1;
   //
   // Error 2377, NERR_LogOverflow, indicates
   //  a log file is full.
   //
   pAdminOtherInfo->alrtad_errcode = 2377;
   //
   // Retrieve the pointer to the variable data portion
   //  of the buffer by calling the ALERT_VAR_DATA macro.
   //
   pVarData = (LPTSTR)ALERT_VAR_DATA(pAdminOtherInfo);
   //
   // Supply the log file name for error 2377.
   //
   wcsncpy_s((wchar_t*) pVarData, ALERT_VAR_DATA_SIZE/2, 
           argv[1],
           ALERT_VAR_DATA_SIZE/2 );
   //
   // Send an administrative alert by calling the
   //  NetAlertRaise function.
   //
   dwResult = NetAlertRaise(ALERT_ADMIN_EVENT,
                            pAlertOtherInfo,
                            nBufferSize);
   //
   // Display the results of the function call.
   //
   if (dwResult != NERR_Success)
      wprintf(L"NetAlertRaise failed: %d\n", dwResult);
   else
      wprintf(L"Administrative alert raised successfully.\n");
   //
   // Free the allocated memory.
   //
   GlobalFree(pAlertOtherInfo);

   return (dwResult);
}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	lmalert.h (inclua Lm.h)
Biblioteca	Netapi32.lib
DLL	Netapi32.dll