NetAlertRaiseEx, fonction (lmalert.h)
[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 .
NET_API_STATUS NET_API_FUNCTION NetAlertRaiseEx(
[in] LPCWSTR AlertType,
[in] LPVOID VariableInfo,
[in] DWORD VariableInfoSize,
[in] LPCWSTR ServiceName
);
[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.)
[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.
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 |
---|---|
|
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 . |
|
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. |
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.
L’exemple de code suivant montre comment déclencher les types suivants de messages d’interruption (alertes) en appelant la fonction NetAlertRaiseEx :
- Une alerte administrative en spécifiant une structure de ADMIN_OTHER_INFO
- Une alerte d’impression en spécifiant une structure de PRINT_OTHER_INFO
- Une alerte utilisateur en spécifiant une structure de USER_OTHER_INFO
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);
}
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 |