NetAlertRaise, fonction (lmalert.h)

Article
08/24/2023

[Cette fonction n’est pas prise en charge à partir de Windows Vista, car le service d’alerte n’est pas pris en charge.]

La fonction NetAlertRaise avertit tous les clients inscrits lorsqu’un événement particulier se produit.

Pour simplifier l’envoi d’un message d’alerte, vous pouvez appeler la fonction étendue NetAlertRaiseEx à la place. NetAlertRaiseEx ne nécessite pas que vous spécifiiez une structure STD_ALERT .

Syntaxe

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

Paramètres

[in] AlertType

Pointeur vers une chaîne constante qui spécifie la classe d’alerte (type d’alerte) à déclencher. Ce paramètre peut être l’une des valeurs prédéfinies suivantes ou une classe d’alerte définie par l’utilisateur pour les applications réseau. Le nom d’événement d’une alerte peut être n’importe quelle chaîne de texte.

Nom	Signification
ALERT_ADMIN_EVENT	L’intervention d’un administrateur est requise.
ALERT_ERRORLOG_EVENT	Une entrée a été ajoutée au journal des erreurs.
ALERT_MESSAGE_EVENT	Un utilisateur ou une application a reçu un message de diffusion.
ALERT_PRINT_EVENT	Un travail d’impression est terminé ou une erreur d’impression s’est produite.
ALERT_USER_EVENT	Une application ou une ressource a été utilisée.

[in] Buffer

Pointeur vers les données à envoyer aux clients à l’écoute du message d’interruption. Les données doivent commencer par une structure de STD_ALERT de longueur fixe suivie de données de message supplémentaires dans une structure ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO ou USER_OTHER_INFO . Enfin, la mémoire tampon doit inclure toutes les informations de longueur variable requises. Pour plus d’informations, consultez l’exemple de code dans la section Remarques suivante.

L’application appelante doit allouer et libérer la mémoire pour toutes les structures et les données variables. Pour plus d’informations, consultez Mémoires tampons de fonction de gestion réseau.

[in] BufferSize

Taille, en octets, de la mémoire tampon de messages.

Valeur retournée

Si la fonction réussit, la valeur de retour est NERR_Success.

Si la fonction échoue, la valeur de retour est un code d’erreur système et peut être l’un des codes d’erreur suivants. Pour obtenir la liste de tous les codes d’erreur possibles, consultez Codes d’erreur système.

Code de retour	Description
ERROR_INVALID_PARAMETER	Un paramètre est incorrect. Cette erreur est retournée si le paramètre AlertEventName a la valeur NULL ou une chaîne vide, si le paramètre Buffer a la valeur NULL ou si le paramètre BufferSize est inférieur à la taille de la structure STD_ALERT plus la taille fixe de la structure de données de message supplémentaire.
ERROR_NOT_SUPPORTED	La demande n'est pas prise en charge. Cette erreur est retournée sur Windows Vista et versions ultérieures, car le service Alerter n’est pas pris en charge.

Remarques

Aucune appartenance à un groupe spécial n’est requise pour exécuter correctement la fonction NetAlertRaise .

Le service d’alerte doit s’exécuter sur l’ordinateur client lorsque vous appelez la fonction NetAlertRaise , sinon la fonction échoue avec ERROR_FILE_NOT_FOUND.

Exemples

L’exemple de code suivant montre comment déclencher une alerte administrative en appelant la fonction NetAlertRaise et en spécifiant STD_ALERT et ADMIN_OTHER_INFO structures. Tout d’abord, l’exemple calcule la taille de la mémoire tampon de messages. Ensuite, il alloue la mémoire tampon avec un appel à la fonction GlobalAlloc . Le code affecte des valeurs aux membres du STD_ALERT et aux parties ADMIN_OTHER_INFO de la mémoire tampon. L’exemple récupère un pointeur vers la structure ADMIN_OTHER_INFO en appelant la macro ALERT_OTHER_INFO . Il récupère également un pointeur vers la partie de données variables de la mémoire tampon en appelant la macro ALERT_VAR_DATA . Enfin, l’exemple de code libère la mémoire allouée à la mémoire tampon avec un appel à la fonction 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);
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	lmalert.h (include Lm.h)
Bibliothèque	Netapi32.lib
DLL	Netapi32.dll