Partager via

CAtlServiceModuleT, classe

  • Article

Cette classe implémente un service.

Important

Cette classe et ses membres ne peuvent pas être utilisés dans les applications qui s’exécutent dans Windows Runtime.

Syntaxe

template <class T, UINT nServiceNameID>
class ATL_NO_VTABLE CAtlServiceModuleT : public CAtlExeModuleT<T>

Paramètres

T
Votre classe dérivée de CAtlServiceModuleT.

nServiceNameID
Identificateur de ressource du service.

Membres

Constructeurs publics

Nom Description
CAtlServiceModuleT ::CAtlServiceModuleT Constructeur .

Méthodes publiques

Nom Description
CAtlServiceModuleT ::Handler Routine de gestionnaire pour le service.
CAtlServiceModuleT ::InitializeSecurity Fournit les paramètres de sécurité par défaut pour le service.
CAtlServiceModuleT ::Install Installe et crée le service.
CAtlServiceModuleT ::IsInstalled Confirme que le service a été installé.
CAtlServiceModuleT ::LogEvent Écrit dans le journal des événements.
CAtlServiceModuleT ::OnContinue Remplacez cette méthode pour continuer le service.
CAtlServiceModuleT ::OnInterrogate Remplacez cette méthode pour interroger le service.
CAtlServiceModuleT ::OnPause Remplacez cette méthode pour suspendre le service.
CAtlServiceModuleT ::OnShutdown Remplacer cette méthode pour arrêter le service
CAtlServiceModuleT ::OnStop Remplacer cette méthode pour arrêter le service
CAtlServiceModuleT ::OnUnknownRequest Remplacez cette méthode pour gérer les demandes inconnues adressées au service
CAtlServiceModuleT ::P arseCommandLine Analyse la ligne de commande et effectue l’inscription si nécessaire.
CAtlServiceModuleT ::P reMessageLoop Cette méthode est appelée immédiatement avant d’entrer la boucle de message.
CAtlServiceModuleT ::RegisterAppId Inscrit le service dans le Registre.
CAtlServiceModuleT ::Run Exécute le service.
CAtlServiceModuleT ::ServiceMain Méthode appelée par Service Control Manager.
CAtlServiceModuleT ::SetServiceStatus Met à jour l’état du service.
CAtlServiceModuleT ::Start Appelé par CAtlServiceModuleT::WinMain quand le service démarre.
CAtlServiceModuleT ::Uninstall Arrête et supprime le service.
CAtlServiceModuleT ::Unlock Décrémente le nombre de verrous du service.
CAtlServiceModuleT ::UnregisterAppId Supprime le service du Registre.
CAtlServiceModuleT ::WinMain Cette méthode implémente le code requis pour exécuter le service.

Membres de données publics

Nom Description
CAtlServiceModuleT ::m_bService Indicateur indiquant que le programme s’exécute en tant que service.
CAtlServiceModuleT ::m_dwThreadID Variable membre stockant l’identificateur de thread.
CAtlServiceModuleT ::m_hServiceStatus Variable membre stockant un handle dans la structure des informations d’état du service actuel.
CAtlServiceModuleT ::m_status Variable membre stockant la structure des informations d’état pour le service actuel.
CAtlServiceModuleT ::m_szServiceName Nom du service inscrit.

Notes

CAtlServiceModuleT, dérivé de CAtlExeModuleT, implémente un module de service ATL. CAtlServiceModuleT fournit des méthodes pour le traitement en ligne de commande, l’installation, l’inscription et la suppression. Si des fonctionnalités supplémentaires sont requises, ces méthodes et d’autres méthodes peuvent être remplacées.

Cette classe remplace la classe CComModule obsolète utilisée dans les versions antérieures d’ATL. Pour plus d’informations, consultez les classes de module ATL.

Hiérarchie d'héritage

_ATL_MODULE

CAtlModule

CAtlModuleT

CAtlExeModuleT

CAtlServiceModuleT

Spécifications

En-tête : atlbase.h

CAtlServiceModuleT ::CAtlServiceModuleT

Constructeur .

CAtlServiceModuleT() throw();

Notes

Initialise les membres de données et définit l’état du service initial.

CAtlServiceModuleT ::Handler

Routine de gestionnaire pour le service.

void Handler(DWORD dwOpcode) throw();

Paramètres

dwOpcode
Commutateur qui définit l’opération de gestionnaire. Pour plus d’informations, consultez les remarques.

Notes

Il s’agit du code que le Gestionnaire de contrôle de service (SCM) appelle pour récupérer l’état du service et émettre des instructions telles que l’arrêt ou la pause. Le SCM transmet un code d’opération, illustré ci-dessous, pour Handler indiquer ce que le service doit faire.

Code d’opération Signification
SERVICE_CONTROL_STOP arrête le service. Remplacez la méthode CAtlServiceModuleT ::OnStop dans atlbase.h pour modifier le comportement.
SERVICE_CONTROL_PAUSE Utilisateur implémenté. Remplacez la méthode vide CAtlServiceModuleT ::OnPause dans atlbase.h pour suspendre le service.
SERVICE_CONTROL_CONTINUE Utilisateur implémenté. Remplacez la méthode vide CAtlServiceModuleT ::OnContinue dans atlbase.h pour continuer le service.
SERVICE_CONTROL_INTERROGATE Utilisateur implémenté. Remplacez la méthode vide CAtlServiceModuleT ::OnInterrogate dans atlbase.h pour interroger le service.
SERVICE_CONTROL_SHUTDOWN Utilisateur implémenté. Remplacez la méthode vide CAtlServiceModuleT ::OnShutdown dans atlbase.h pour arrêter le service.

Si le code d’opération n’est pas reconnu, la méthode CAtlServiceModuleT ::OnUnknownRequest est appelée.

Un service généré par ATL par défaut gère uniquement l’instruction d’arrêt. Si le SCM transmet l’instruction d’arrêt, le service indique au SCM que le programme est sur le point d’arrêter. Le service appelle PostThreadMessage ensuite pour publier un message de quitter lui-même. Cela met fin à la boucle de message et le service se ferme en fin de compte.

CAtlServiceModuleT ::InitializeSecurity

Fournit les paramètres de sécurité par défaut pour le service.

HRESULT InitializeSecurity() throw();

Valeur de retour

Retourne S_OK sur la réussite ou une erreur HRESULT en cas d’échec.

Notes

Toute classe dérivée de CAtlServiceModuleT doit implémenter cette méthode dans la classe dérivée.

Utilisez l’authentification au niveau PKT, le niveau d’emprunt d’identité de RPC_C_IMP_LEVEL_IDENTIFY et un descripteur de sécurité non null approprié dans l’appel à CoInitializeSecurity.

Pour les projets de service non attribués générés par l’Assistant, ce serait dans

class CNonAttribServiceModule : public CAtlServiceModuleT< CNonAttribServiceModule, IDS_SERVICENAME >
{
public :
   DECLARE_LIBID(LIBID_NonAttribServiceLib)
   DECLARE_REGISTRY_APPID_RESOURCEID(IDR_NONATTRIBSERVICE, "{29160736-339F-4A1C-ABEF-C320CE103E12}")
   HRESULT InitializeSecurity() throw()
   {
      // TODO : Call CoInitializeSecurity and provide the appropriate security settings for 
      // your service
      // Suggested - PKT Level Authentication, 
      // Impersonation Level of RPC_C_IMP_LEVEL_IDENTIFY 
      // and an appropriate Non NULL Security Descriptor.

      return S_OK;
   }
};

Pour les projets de service attribués, ce serait dans

[ module(SERVICE, uuid = "{D3103322-7B70-4581-8E59-12769BD9A62B}", 
   name = "AttribService", 
   helpstring = "AttribService 1.0 Type Library", 
   resource_name="IDS_SERVICENAME") ]
class CAttribServiceModule
{
public:
   HRESULT InitializeSecurity() throw()
   {
      // TODO : Call CoInitializeSecurity and provide the appropriate security settings for 
      // your service
      // Suggested - PKT Level Authentication, 
      // Impersonation Level of RPC_C_IMP_LEVEL_IDENTIFY 
      // and an appropriate Non NULL Security Descriptor.

      return S_OK;
   }
};

CAtlServiceModuleT ::Install

Installe et crée le service.

BOOL Install() throw();

Valeur de retour

Retourne TRUE en cas de réussite, FALSE en cas d’échec.

Notes

Installe le service dans la base de données Service Control Manager (SCM), puis crée l’objet de service. Si le service n’a pas pu être créé, une boîte de message s’affiche et la méthode retourne FALSE.

CAtlServiceModuleT ::IsInstalled

Confirme que le service a été installé.

BOOL IsInstalled() throw();

Valeur de retour

Retourne TRUE si le service est installé, FALSE dans le cas contraire.

CAtlServiceModuleT ::LogEvent

Écrit dans le journal des événements.

void __cdecl LogEvent(LPCTSTR pszFormat, ...) throw();

Paramètres

pszFormat
Chaîne à écrire dans le journal des événements.

...
Chaînes supplémentaires facultatives à écrire dans le journal des événements.

Notes

Cette méthode écrit des détails dans un journal des événements à l’aide de la fonction ReportEvent. Si aucun service n’est en cours d’exécution, la chaîne est envoyée à la console.

CAtlServiceModuleT ::m_bService

Indicateur indiquant que le programme s’exécute en tant que service.

BOOL m_bService;

Notes

Permet de distinguer un EXE de service d’un EXE d’application.

CAtlServiceModuleT ::m_dwThreadID

Variable membre stockant l’identificateur de thread du service.

DWORD m_dwThreadID;

Notes

Cette variable stocke l’identificateur de thread du thread actuel.

CAtlServiceModuleT ::m_hServiceStatus

Variable membre stockant un handle dans la structure des informations d’état du service actuel.

SERVICE_STATUS_HANDLE m_hServiceStatus;

Notes

La structure SERVICE_STATUS contient des informations sur un service.

CAtlServiceModuleT ::m_status

Variable membre stockant la structure des informations d’état pour le service actuel.

SERVICE_STATUS m_status;

Notes

La structure SERVICE_STATUS contient des informations sur un service.

CAtlServiceModuleT ::m_szServiceName

Nom du service inscrit.

TCHAR [256] m_szServiceName;

Notes

Chaîne terminée par null qui stocke le nom du service.

CAtlServiceModuleT ::OnContinue

Remplacez cette méthode pour continuer le service.

void OnContinue() throw();

CAtlServiceModuleT ::OnInterrogate

Remplacez cette méthode pour interroger le service.

void OnInterrogate() throw();

CAtlServiceModuleT ::OnPause

Remplacez cette méthode pour suspendre le service.

void OnPause() throw();

CAtlServiceModuleT ::OnShutdown

Remplacez cette méthode pour arrêter le service.

void OnShutdown() throw();

CAtlServiceModuleT ::OnStop

Remplacez cette méthode pour arrêter le service.

void OnStop() throw();

CAtlServiceModuleT ::OnUnknownRequest

Remplacez cette méthode pour gérer les demandes inconnues adressées au service.

void OnUnknownRequest(DWORD /* dwOpcode*/) throw();

Paramètres

dwOpcode
Réservé.

CAtlServiceModuleT ::P arseCommandLine

Analyse la ligne de commande et effectue l’inscription si nécessaire.

bool ParseCommandLine(LPCTSTR lpCmdLine, HRESULT* pnRetCode) throw();

Paramètres

lpCmdLine
Ligne de commande.

pnRetCode
HRESULT correspondant à l’inscription (si elle a eu lieu).

Valeur de retour

Retourne true en cas de réussite ou false si le fichier RGS fourni dans la ligne de commande n’a pas pu être inscrit.

Notes

Analyse la ligne de commande et inscrit ou annule l’inscription du fichier RGS fourni si nécessaire. Cette méthode appelle CAtlExeModuleT ::P arseCommandLine pour rechercher /RegServer et /UnregServer. L’ajout de l’argument -/Service inscrit le service.

CAtlServiceModuleT ::P reMessageLoop

Cette méthode est appelée immédiatement avant d’entrer la boucle de message.

HRESULT PreMessageLoop(int nShowCmd) throw();

Paramètres

nShowCmd
Ce paramètre est passé à CAtlExeModuleT ::P reMessageLoop.

Valeur de retour

Retourne S_OK sur la réussite ou une erreur HRESULT en cas d’échec.

Notes

Remplacez cette méthode pour ajouter du code d’initialisation personnalisé pour le service.

CAtlServiceModuleT ::RegisterAppId

Inscrit le service dans le Registre.

inline HRESULT RegisterAppId(bool bService = false) throw();

Paramètres

bService
Doit être vrai pour s’inscrire en tant que service.

Valeur de retour

Retourne S_OK sur la réussite ou une erreur HRESULT en cas d’échec.

CAtlServiceModuleT ::Run

Exécute le service.

HRESULT Run(int nShowCmd = SW_HIDE) throw();

Paramètres

nShowCmd
Spécifie la façon dont la fenêtre doit être affichée. Ce paramètre peut être l’une des valeurs décrites dans la section WinMain . La valeur par défaut est SW_HIDE.

Valeur de retour

Retourne S_OK sur la réussite ou une erreur HRESULT en cas d’échec.

Notes

Après avoir été appelé, Run appelle CAtlServiceModuleT ::P reMessageLoop, CAtlExeModuleT ::RunMessageLoop et CAtlExeModuleT ::P ostMessageLoop.

CAtlServiceModuleT ::ServiceMain

Cette méthode est appelée par service Control Manager.

void ServiceMain(DWORD dwArgc, LPTSTR* lpszArgv) throw();

Paramètres

dwArgc
Argument argc.

lpszArgv
Argument argv.

Notes

Le Gestionnaire de contrôle de service (SCM) appelle ServiceMain lorsque vous ouvrez l’application Services dans le Panneau de configuration, sélectionnez le service, puis cliquez sur Démarrer.

Après l’appel ServiceMainde SCM, un service doit attribuer à la SCM une fonction de gestionnaire. Cette fonction permet au SCM d’obtenir l’état du service et de transmettre des instructions spécifiques (telles que la suspension ou l’arrêt). Par la suite, CAtlServiceModuleT ::Run est appelé pour effectuer le travail principal du service. Run continue à s’exécuter jusqu’à ce que le service soit arrêté.

CAtlServiceModuleT ::SetServiceStatus

Cette méthode met à jour l’état du service.

void SetServiceStatus(DWORD dwState) throw();

Paramètres

dwState
Le nouveau statut. Consultez SetServiceStatus pour connaître les valeurs possibles.

Notes

Met à jour les informations d’état du Gestionnaire de contrôle de service pour le service. Elle est appelée par CAtlServiceModuleT ::Run, CAtlServiceModuleT ::ServiceMain et d’autres méthodes de gestionnaire. L’état est également stocké dans la variable membre CAtlServiceModuleT ::m_status.

CAtlServiceModuleT ::Start

Appelé par CAtlServiceModuleT::WinMain quand le service démarre.

HRESULT Start(int nShowCmd) throw();

Paramètres

nShowCmd
Spécifie la façon dont la fenêtre doit être affichée. Ce paramètre peut être l’une des valeurs décrites dans la section WinMain .

Valeur de retour

Retourne S_OK sur la réussite ou une erreur HRESULT en cas d’échec.

Notes

La méthode CAtlServiceModuleT ::WinMain gère à la fois l’inscription et l’installation, ainsi que les tâches impliquées dans la suppression des entrées de Registre et la désinstallation du module. Quand le service est exécuté, WinMain appelle Start.

CAtlServiceModuleT ::Uninstall

Arrête et supprime le service.

BOOL Uninstall() throw();

Valeur de retour

Retourne TRUE en cas de réussite, FALSE en cas d’échec.

Notes

Arrête l’exécution du service et la supprime de la base de données Service Control Manager.

CAtlServiceModuleT ::Unlock

Décrémente le nombre de verrous du service.

LONG Unlock() throw();

Valeur de retour

Retourne le nombre de verrous, qui peut être utile pour les diagnostics et le débogage.

CAtlServiceModuleT ::UnregisterAppId

Supprime le service du Registre.

HRESULT UnregisterAppId() throw();

Valeur de retour

Retourne S_OK sur la réussite ou une erreur HRESULT en cas d’échec.

CAtlServiceModuleT ::WinMain

Cette méthode implémente le code requis pour démarrer le service.

int WinMain(int nShowCmd) throw();

Paramètres

nShowCmd
Spécifie la façon dont la fenêtre doit être affichée. Ce paramètre peut être l’une des valeurs décrites dans la section WinMain .

Valeur de retour

Retourne la valeur de retour du service.

Notes

Cette méthode traite la ligne de commande (avec CAtlServiceModuleT ::P arseCommandLine), puis démarre le service (à l’aide de CAtlServiceModuleT ::Start).

Voir aussi

CAtlExeModuleT, classe
Vue d’ensemble de la classe