Função NetAlertRaiseEx (lmalert.h)
[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 NetAlertRaiseEx notifica todos os clientes registrados quando ocorre um evento específico. Você pode chamar essa função estendida para simplificar o envio de uma mensagem de alerta porque NetAlertRaiseEx não exige que você especifique uma estrutura STD_ALERT .
Sintaxe
NET_API_STATUS NET_API_FUNCTION NetAlertRaiseEx(
[in] LPCWSTR AlertType,
[in] LPVOID VariableInfo,
[in] DWORD VariableInfoSize,
[in] LPCWSTR ServiceName
);
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.)
[in] VariableInfo
Um ponteiro para os dados a serem enviados aos clientes que escutam a mensagem de interrupção. Os dados devem consistir em uma estrutura ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO ou USER_OTHER_INFO seguida por qualquer informação de comprimento variável necessária. 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] VariableInfoSize
O número de bytes de informações de variáveis no buffer apontado pelo parâmetro VariableInfo .
[in] ServiceName
Um ponteiro para uma cadeia de caracteres constante que especifica o nome do serviço que gera a mensagem de interrupção.
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 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 |
|---|---|
|
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 ServiceName for NULL ou uma cadeia de caracteres vazia, o parâmetro VariableInfo for NULL ou o parâmetro VariableInfoSize for maior que 512 menos o tamanho da estrutura STD_ALERT . |
|
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 NetAlertRaiseEx .
O serviço de alerta deve estar em execução no computador cliente quando você chama a função NetAlertRaiseEx ou a função falha com ERROR_FILE_NOT_FOUND.
Exemplos
O exemplo de código a seguir demonstra como gerar os seguintes tipos de mensagens de interrupção (alertas) chamando a função NetAlertRaiseEx :
- Um alerta administrativo especificando uma estrutura ADMIN_OTHER_INFO
- Um alerta de impressão especificando uma estrutura de PRINT_OTHER_INFO
- Um alerta do usuário especificando uma estrutura de USER_OTHER_INFO
Observe que o aplicativo de chamada deve alocar e liberar a memória para todas as estruturas e dados de comprimento variável em um buffer de mensagens de alerta.
Para passar uma estrutura definida pelo usuário e cadeias de caracteres válidas em um alerta de usuário, você deve criar um arquivo de mensagem de evento e vinculá-lo ao seu aplicativo. Você também deve registrar o aplicativo na subchave EventMessageFile na seção EventLog do registro. Se você não registrar o aplicativo, o alerta do usuário conterá as informações passadas nas cadeias de caracteres de comprimento variável que seguem a estrutura USER_OTHER_INFO . Para obter mais informações sobre EventMessageFile, consulte Log de Eventos.
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")
#include <windows.h>
#include <lm.h>
#include <stdio.h>
#include <time.h>
//
// Define default strings.
//
#define PROGRAM_NAME TEXT("NETALRT")
#define szComputerName TEXT("\\\\TESTCOMPUTER")
#define szUserName TEXT("TEST")
#define szQueueName TEXT("PQUEUE")
#define szDestName TEXT("MYPRINTER")
#define szStatus TEXT("OK")
//
// Define structure sizes.
//
#define VAREDSIZE 312 // maximum size of the variable length message
char buff[VAREDSIZE];
//
int main()
{
time_t now;
PADMIN_OTHER_INFO pAdminInfo; // ADMIN_OTHER_INFO structure
PPRINT_OTHER_INFO pPrintInfo; // PRINT_OTHER_INFO structure
PUSER_OTHER_INFO pUserInfo; // USER_OTHER_INFO structure
TCHAR *p;
DWORD dwResult;
time( &now ); // Retrieve the current time to print it later.
//
// Sending an administrative alert
//
// Assign values to the members of the ADMIN_OTHER_INFO structure.
//
pAdminInfo = (PADMIN_OTHER_INFO) buff;
ZeroMemory(pAdminInfo, VAREDSIZE);
//
// Error 2377, NERR_LogOverflow, indicates
// a log file is full.
//
pAdminInfo->alrtad_errcode = 2377;
pAdminInfo->alrtad_numstrings = 1;
//
// Retrieve a pointer to the variable data portion at the
// end of the buffer by calling the ALERT_VAR_DATA macro.
//
p = (LPTSTR) ALERT_VAR_DATA(pAdminInfo);
//
// Fill in the variable-length, concatenated strings
// that follow the ADMIN_OTHER_INFO structure. These strings
// will be written to the message log.
//
wcscpy_s(p,VAREDSIZE/2, TEXT("'C:\\MYLOG.TXT'"));
//
// Call the NetAlertRaiseEx function to raise the
// administrative alert.
//
dwResult = NetAlertRaiseEx(ALERT_ADMIN_EVENT, pAdminInfo, 255 , TEXT("MYSERVICE"));
//
// Display the results of the function call.
//
if (dwResult != NERR_Success)
{
wprintf(L"NetAlertRaiseEx failed: %d\n", dwResult);
return -1;
}
else
wprintf(L"Administrative alert raised successfully.\n");
//
// Sending a print alert
//
// Assign values to the members of the PRINT_OTHER_INFO structure.
//
pPrintInfo = (PPRINT_OTHER_INFO) buff;
ZeroMemory(pPrintInfo, VAREDSIZE);
pPrintInfo->alrtpr_jobid = 5457;
pPrintInfo->alrtpr_status = 0;
pPrintInfo->alrtpr_submitted = (DWORD) now;
pPrintInfo->alrtpr_size = 1000;
//
// Retrieve a pointer to the variable data portion at the
// end of the buffer by calling the ALERT_VAR_DATA macro.
//
p = (LPTSTR) ALERT_VAR_DATA(pPrintInfo);
//
// Fill in the variable-length, concatenated strings
// that follow the PRINT_OTHER_INFO structure.
//
wcscpy_s(p, VAREDSIZE/2, szComputerName); // computername
p += lstrlen(p) + 1;
wcscpy_s(p, (VAREDSIZE/2)-wcslen(szComputerName)-1, szUserName); // user name
p += lstrlen(p) + 1;
wcscpy_s(p, (VAREDSIZE/2)-wcslen(szComputerName)-wcslen(szUserName)-2,
szQueueName); // printer queuename
p += lstrlen(p) + 1;
wcscpy_s(p, (VAREDSIZE/2)-wcslen(szComputerName)-wcslen(szUserName)-wcslen(szQueueName)-3,
szDestName); // destination or printer name (optional)
p += lstrlen(p) + 1;
wcscpy_s(p, (VAREDSIZE/2)-wcslen(szComputerName)-wcslen(szUserName)-wcslen(szQueueName)
- wcslen(szDestName)-4, szStatus); // status of the print job (optional)
//
// Call the NetAlertRaiseEx function to raise the
// print alert.
//
dwResult = NetAlertRaiseEx(ALERT_PRINT_EVENT, pPrintInfo, VAREDSIZE, TEXT("MYSERVICE"));
//
// Display the results of the function call.
//
if (dwResult != NERR_Success)
{
wprintf(L"NetAlertRaiseEx failed: %d\n", dwResult);
return -1;
}
else
wprintf(L"Print alert raised successfully.\n");
//
// Sending a user alert
//
// Assign values to the members of the USER_OTHER_INFO structure.
//
pUserInfo = (PUSER_OTHER_INFO) buff;
ZeroMemory(pUserInfo, VAREDSIZE);
pUserInfo->alrtus_errcode = 0xffff;
pUserInfo->alrtus_numstrings = 1;
//
// Retrieve a pointer to the variable data portion at the
// end of the buffer by calling the ALERT_VAR_DATA macro.
//
p = (LPTSTR) ALERT_VAR_DATA(pUserInfo);
//
// Fill in the variable-length, concatenated strings
// that follow the USER_OTHER_INFO structure.
//
wcscpy_s(p,(VAREDSIZE/2), TEXT("C:\\USERLOG.TXT"));
p += lstrlen(p) + 1;
wcscpy_s(p, (VAREDSIZE/2) - wcslen(TEXT("C:\\USERLOG.TXT"))-1, szUserName);
//
// Call the NetAlertRaiseEx function to raise the
// user alert.
//
dwResult = NetAlertRaiseEx(ALERT_USER_EVENT, pUserInfo, VAREDSIZE, TEXT("MYSERVICE"));
//
// Display the results of the function call.
//
if (dwResult != NERR_Success)
{
wprintf(L"NetAlertRaiseEx failed: %d\n", dwResult);
return -1;
}
else
wprintf(L"User alert raised successfully.\n");
return(dwResult);
}
Requisitos
| 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 |
Confira também
Funções de gerenciamento de rede
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de