Partager via

NetAlertRaiseEx, fonction (lmalert.h)

  • Article

[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 NetAlertRaiseEx avertit tous les clients inscrits lorsqu’un événement particulier se produit. Vous pouvez appeler cette fonction étendue pour simplifier l’envoi d’un message d’alerte, car NetAlertRaiseEx ne nécessite pas que vous spécifiiez une structure STD_ALERT .

Syntaxe

NET_API_STATUS NET_API_FUNCTION NetAlertRaiseEx(
  [in] LPCWSTR AlertType,
  [in] LPVOID  VariableInfo,
  [in] DWORD   VariableInfoSize,
  [in] LPCWSTR ServiceName
);

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 de l’é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] VariableInfo

Pointeur vers les données à envoyer aux clients à l’écoute du message d’interruption. Les données doivent se composer d’une structure ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO ou USER_OTHER_INFO suivie de 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] VariableInfoSize

Nombre d’octets d’informations de variable dans la mémoire tampon vers laquelle pointe le paramètre VariableInfo .

[in] ServiceName

Pointeur vers une chaîne constante qui spécifie le nom du service qui déclenche le message d’interruption.

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 ServiceName a la valeur NULL ou une chaîne vide, si le paramètre VariableInfo a la valeur NULL ou si le paramètre VariableInfoSize est supérieur à 512 moins la taille de la structure STD_ALERT .
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.

Notes

Aucune appartenance de groupe spéciale n’est requise pour exécuter correctement la fonction NetAlertRaiseEx .

Le service d’alerte doit être en cours d’exécution sur l’ordinateur client lorsque vous appelez la fonction NetAlertRaiseEx , sinon la fonction échoue avec ERROR_FILE_NOT_FOUND.

Exemples

L’exemple de code suivant montre comment déclencher les types suivants de messages d’interruption (alertes) en appelant la fonction NetAlertRaiseEx :

Dans chaque instance le code affecte des valeurs aux membres de la structure d’informations d’alerte appropriée. Après cela, l’exemple récupère un pointeur vers la partie de la mémoire tampon de messages qui suit la structure en appelant la macro ALERT_VAR_DATA . Le code remplit également les chaînes de longueur variable dans cette partie de la mémoire tampon. Enfin, l’exemple appelle NetAlertRaiseEx pour envoyer l’alerte.

Notez que l’application appelante doit allouer et libérer la mémoire pour toutes les structures et les données de longueur variable dans une mémoire tampon de messages d’alerte.

Pour passer une structure définie par l’utilisateur et des chaînes valides dans une alerte utilisateur, vous devez créer un fichier de message d’événement et le lier à votre application. Vous devez également inscrire l’application dans la sous-clé EventMessageFile de la section EventLog du Registre. Si vous n’inscrivez pas l’application, l’alerte utilisateur contient les informations que vous transmettez dans les chaînes de longueur variable qui suivent la structure USER_OTHER_INFO . Pour plus d’informations sur EventMessageFile, consultez Journalisation des événements.

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

Configuration requise

   
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

Voir aussi

ADMIN_OTHER_INFO

ALERT_VAR_DATA

Fonctions d’alerte

ERRLOG_OTHER_INFO

NetAlertRaise

Fonctions de gestion réseau

Vue d’ensemble de la gestion du réseau

PRINT_OTHER_INFO

USER_OTHER_INFO