Classe CAtlServiceModuleT

Questa classe implementa un servizio.

Importante

Questa classe e i relativi membri non possono essere usati nelle applicazioni eseguite in Windows Runtime.

Sintassi

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

Parametri

T
Classe derivata da CAtlServiceModuleT.

nServiceNameID
Identificatore della risorsa del servizio.

Membri

Costruttori pubblici

Nome	Descrizione
CAtlServiceModuleT::CAtlServiceModuleT	Costruttore.

Metodi pubblici

Nome	Descrizione
CAtlServiceModuleT::Handler	Routine del gestore per il servizio.
CAtlServiceModuleT::InitializeSecurity	Fornisce le impostazioni di sicurezza predefinite per il servizio.
CAtlServiceModuleT::Install	Installa e crea il servizio.
CAtlServiceModuleT::IsInstalled	Conferma che il servizio è stato installato.
CAtlServiceModuleT::LogEvent	Scrive nel registro eventi.
CAtlServiceModuleT::OnContinue	Eseguire l'override di questo metodo per continuare il servizio.
CAtlServiceModuleT::OnInterrogate	Eseguire l'override di questo metodo per interrogare il servizio.
CAtlServiceModuleT::OnPause	Eseguire l'override di questo metodo per sospendere il servizio.
CAtlServiceModuleT::OnShutdown	Eseguire l'override di questo metodo per arrestare il servizio
CAtlServiceModuleT::OnStop	Eseguire l'override di questo metodo per arrestare il servizio
CAtlServiceModuleT::OnUnknownRequest	Eseguire l'override di questo metodo per gestire le richieste sconosciute al servizio
CAtlServiceModuleT::P arseCommandLine	Analizza la riga di comando ed esegue la registrazione, se necessario.
CAtlServiceModuleT::P reMessageLoop	Questo metodo viene chiamato immediatamente prima di immettere il ciclo di messaggi.
CAtlServiceModuleT::RegisterAppId	Registra il servizio nel Registro di sistema.
CAtlServiceModuleT::Run	Esegue il servizio.
CAtlServiceModuleT::ServiceMain	Metodo chiamato da Service Control Manager.
CAtlServiceModuleT::SetServiceStatus	Aggiorna lo stato del servizio.
CAtlServiceModuleT::Start	Chiamato da all'avvio CAtlServiceModuleT::WinMain del servizio.
CAtlServiceModuleT::Uninstall	Arresta e rimuove il servizio.
CAtlServiceModuleT::Unlock	Decrementa il conteggio dei blocchi del servizio.
CAtlServiceModuleT::UnregisterAppId	Rimuove il servizio dal Registro di sistema.
CAtlServiceModuleT::WinMain	Questo metodo implementa il codice necessario per eseguire il servizio.

Membri dati pubblici

Nome	Descrizione
CAtlServiceModuleT::m_bService	Flag che indica che il programma è in esecuzione come servizio.
CAtlServiceModuleT::m_dwThreadID	Variabile membro che archivia l'identificatore del thread.
CAtlServiceModuleT::m_hServiceStatus	Variabile membro che archivia un handle per la struttura delle informazioni sullo stato per il servizio corrente.
CAtlServiceModuleT::m_status	Variabile membro che archivia la struttura delle informazioni sullo stato per il servizio corrente.
CAtlServiceModuleT::m_szServiceName	Nome del servizio registrato.

Osservazioni:

CAtlServiceModuleT, derivato da CAtlExeModuleT, implementa un modulo del servizio ATL. CAtlServiceModuleT fornisce metodi per l'elaborazione della riga di comando, l'installazione, la registrazione e la rimozione. Se sono necessarie funzionalità aggiuntive, è possibile eseguire l'override di questi e altri metodi.

Questa classe sostituisce la classe CComModule obsoleta usata nelle versioni precedenti di ATL. Per altri dettagli, vedere Classi di moduli ATL.

Gerarchia di ereditarietà

_ATL_MODULE

CAtlModule

CAtlModuleT

CAtlExeModuleT

CAtlServiceModuleT

Requisiti

Intestazione: atlbase.h

CAtlServiceModuleT::CAtlServiceModuleT

Costruttore.

CAtlServiceModuleT() throw();

Osservazioni:

Inizializza i membri dati e imposta lo stato iniziale del servizio.

CAtlServiceModuleT::Handler

Routine del gestore per il servizio.

void Handler(DWORD dwOpcode) throw();

Parametri

dwOpcode
Opzione che definisce l'operazione del gestore. Per informazioni dettagliate, vedere la sezione Osservazioni.

Osservazioni:

Si tratta del codice chiamato da Service Control Manager (SCM) per recuperare lo stato del servizio e rilasciare istruzioni, ad esempio arrestare o sospendere. SCM passa un codice dell'operazione, illustrato di seguito, per Handler indicare le operazioni che il servizio deve eseguire.

Codice operazione	significato
SERVICE_CONTROL_STOP	arresta il servizio. Eseguire l'override del metodo CAtlServiceModuleT::OnStop in atlbase.h per modificare il comportamento.
SERVICE_CONTROL_PAUSE	Implementato dall'utente. Eseguire l'override del metodo vuoto CAtlServiceModuleT::OnPause in atlbase.h per sospendere il servizio.
SERVICE_CONTROL_CONTINUE	Implementato dall'utente. Eseguire l'override del metodo vuoto CAtlServiceModuleT::OnContinue in atlbase.h per continuare il servizio.
SERVICE_CONTROL_INTERROGATE	Implementato dall'utente. Eseguire l'override del metodo vuoto CAtlServiceModuleT::OnInterrogate in atlbase.h per interrogare il servizio.
SERVICE_CONTROL_SHUTDOWN	Implementato dall'utente. Eseguire l'override del metodo vuoto CAtlServiceModuleT::OnShutdown in atlbase.h per arrestare il servizio.

Se il codice dell'operazione non viene riconosciuto, viene chiamato il metodo CAtlServiceModuleT::OnUnknownRequest .

Un servizio predefinito generato da ATL gestisce solo l'istruzione di arresto. Se SCM passa l'istruzione di arresto, il servizio indica a SCM che il programma sta per essere arrestato. Il servizio chiama PostThreadMessage quindi per pubblicare un messaggio di chiusura a se stesso. In questo modo viene terminato il ciclo di messaggi e il servizio verrà chiuso.

CAtlServiceModuleT::InitializeSecurity

Fornisce le impostazioni di sicurezza predefinite per il servizio.

HRESULT InitializeSecurity() throw();

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

Osservazioni:

Qualsiasi classe che deriva da CAtlServiceModuleT deve implementare questo metodo nella classe derivata.

Usare l'autenticazione a livello PKT, il livello di rappresentazione di RPC_C_IMP_LEVEL_IDENTIFY e un descrittore di sicurezza non Null appropriato nella chiamata a CoInitializeSecurity.

Per i progetti di servizio non con attributi generati dalla procedura guidata, si tratterebbe di

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

Per i progetti di servizio con attributi, si tratterebbe di

[ 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

Installa e crea il servizio.

BOOL Install() throw();

Valore restituito

Restituisce TRUE in caso di esito positivo, FALSE in caso di errore.

Osservazioni:

Installa il servizio nel database di Service Control Manager (SCM) e quindi crea l'oggetto servizio. Se non è stato possibile creare il servizio, viene visualizzata una finestra di messaggio e il metodo restituisce FALSE.

CAtlServiceModuleT::IsInstalled

Conferma che il servizio è stato installato.

BOOL IsInstalled() throw();

Valore restituito

Restituisce TRUE se il servizio è installato, FALSE in caso contrario.

CAtlServiceModuleT::LogEvent

Scrive nel registro eventi.

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

Parametri

pszFormat
Stringa da scrivere nel registro eventi.

...
Stringhe aggiuntive facoltative da scrivere nel registro eventi.

Osservazioni:

Questo metodo scrive i dettagli in un registro eventi usando la funzione ReportEvent. Se non è in esecuzione alcun servizio, la stringa viene inviata alla console.

CAtlServiceModuleT::m_bService

Flag che indica che il programma è in esecuzione come servizio.

BOOL m_bService;

Osservazioni:

Utilizzato per distinguere un file EXE del servizio da un file EXE dell'applicazione.

CAtlServiceModuleT::m_dwThreadID

Variabile membro che archivia l'identificatore del thread del servizio.

DWORD m_dwThreadID;

Osservazioni:

Questa variabile archivia l'identificatore del thread corrente.

CAtlServiceModuleT::m_hServiceStatus

Variabile membro che archivia un handle per la struttura delle informazioni sullo stato per il servizio corrente.

SERVICE_STATUS_HANDLE m_hServiceStatus;

Osservazioni:

La struttura SERVICE_STATUS contiene informazioni su un servizio.

CAtlServiceModuleT::m_status

Variabile membro che archivia la struttura delle informazioni sullo stato per il servizio corrente.

SERVICE_STATUS m_status;

Osservazioni:

La struttura SERVICE_STATUS contiene informazioni su un servizio.

CAtlServiceModuleT::m_szServiceName

Nome del servizio registrato.

TCHAR [256] m_szServiceName;

Osservazioni:

Stringa con terminazione Null che archivia il nome del servizio.

CAtlServiceModuleT::OnContinue

Eseguire l'override di questo metodo per continuare il servizio.

void OnContinue() throw();

CAtlServiceModuleT::OnInterrogate

Eseguire l'override di questo metodo per interrogare il servizio.

void OnInterrogate() throw();

CAtlServiceModuleT::OnPause

Eseguire l'override di questo metodo per sospendere il servizio.

void OnPause() throw();

CAtlServiceModuleT::OnShutdown

Eseguire l'override di questo metodo per arrestare il servizio.

void OnShutdown() throw();

CAtlServiceModuleT::OnStop

Eseguire l'override di questo metodo per arrestare il servizio.

void OnStop() throw();

CAtlServiceModuleT::OnUnknownRequest

Eseguire l'override di questo metodo per gestire le richieste sconosciute al servizio.

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

Parametri

dwOpcode
Riservato.

CAtlServiceModuleT::P arseCommandLine

Analizza la riga di comando ed esegue la registrazione, se necessario.

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

Parametri

lpCmdLine
Riga di comando.

pnRetCode
HRESULT corrispondente alla registrazione (se è stata eseguita).

Valore restituito

Restituisce true in caso di esito positivo o false se non è stato possibile registrare il file RGS fornito nella riga di comando.

Osservazioni:

Analizza la riga di comando e registra o annulla la registrazione del file RGS fornito, se necessario. Questo metodo chiama CAtlExeModuleT::P arseCommandLine per verificare la presenza di /RegServer e /UnregServer. L'aggiunta dell'argomento -/Service registrerà il servizio.

CAtlServiceModuleT::P reMessageLoop

Questo metodo viene chiamato immediatamente prima di immettere il ciclo di messaggi.

HRESULT PreMessageLoop(int nShowCmd) throw();

Parametri

nShowCmd
Questo parametro viene passato a CAtlExeModuleT::P reMessageLoop.

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

Osservazioni:

Eseguire l'override di questo metodo per aggiungere codice di inizializzazione personalizzato per il servizio.

CAtlServiceModuleT::RegisterAppId

Registra il servizio nel Registro di sistema.

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

Parametri

bService
Deve essere true per la registrazione come servizio.

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

CAtlServiceModuleT::Run

Esegue il servizio.

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

Parametri

nShowCmd
Specifica la modalità di visualizzazione della finestra. Questo parametro può essere uno dei valori descritti nella sezione WinMain . Il valore predefinito è SW_HIDE.

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

Osservazioni:

Dopo essere stato chiamato, Run chiama CAtlServiceModuleT::P reMessageLoop, CAtlExeModuleT::RunMessageLoop e CAtlExeModuleT::P ostMessageLoop.

CAtlServiceModuleT::ServiceMain

Questo metodo viene chiamato da Service Control Manager.

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

Parametri

dwArgc
Argomento argc.

lpszArgv
Argomento argv.

Osservazioni:

Service Control Manager (SCM) chiama ServiceMain quando si apre l'applicazione Servizi nella Pannello di controllo, selezionare il servizio e fare clic su Avvia.

Dopo che SCM chiama ServiceMain, un servizio deve assegnare a SCM una funzione del gestore. Questa funzione consente a SCM di ottenere lo stato del servizio e di passare istruzioni specifiche, ad esempio la sospensione o l'arresto. Successivamente, viene chiamato CAtlServiceModuleT::Run per eseguire il lavoro principale del servizio. Run continua a essere eseguito fino a quando il servizio non viene arrestato.

CAtlServiceModuleT::SetServiceStatus

Questo metodo aggiorna lo stato del servizio.

void SetServiceStatus(DWORD dwState) throw();

Parametri

dwState
Nuovo stato. Per i valori possibili, vedere SetServiceStatus .

Osservazioni:

Aggiorna le informazioni sullo stato di Service Control Manager per il servizio. Viene chiamato da CAtlServiceModuleT::Run, CAtlServiceModuleT::ServiceMain e da altri metodi del gestore. Lo stato viene archiviato anche nella variabile membro CAtlServiceModuleT::m_status.

CAtlServiceModuleT::Start

Chiamato da all'avvio CAtlServiceModuleT::WinMain del servizio.

HRESULT Start(int nShowCmd) throw();

Parametri

nShowCmd
Specifica la modalità di visualizzazione della finestra. Questo parametro può essere uno dei valori descritti nella sezione WinMain .

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

Osservazioni:

Il metodo CAtlServiceModuleT::WinMain gestisce sia la registrazione che l'installazione, nonché le attività coinvolte nella rimozione delle voci del Registro di sistema e nella disinstallazione del modulo. Quando il servizio viene eseguito, WinMain chiama Start.

CAtlServiceModuleT::Uninstall

Arresta e rimuove il servizio.

BOOL Uninstall() throw();

Valore restituito

Restituisce TRUE in caso di esito positivo, FALSE in caso di errore.

Osservazioni:

Arresta l'esecuzione del servizio e la rimuove dal database di Service Control Manager.

CAtlServiceModuleT::Unlock

Decrementa il conteggio dei blocchi del servizio.

LONG Unlock() throw();

Valore restituito

Restituisce il conteggio dei blocchi, che può essere utile per la diagnostica e il debug.

CAtlServiceModuleT::UnregisterAppId

Rimuove il servizio dal Registro di sistema.

HRESULT UnregisterAppId() throw();

Valore restituito

Restituisce S_OK in caso di esito positivo o errore HRESULT in caso di errore.

CAtlServiceModuleT::WinMain

Questo metodo implementa il codice necessario per avviare il servizio.

int WinMain(int nShowCmd) throw();

Parametri

nShowCmd
Specifica la modalità di visualizzazione della finestra. Questo parametro può essere uno dei valori descritti nella sezione WinMain .

Valore restituito

Restituisce il valore restituito del servizio.

Osservazioni:

Questo metodo elabora la riga di comando (con CAtlServiceModuleT::P arseCommandLine) e quindi avvia il servizio (usando CAtlServiceModuleT::Start).

Vedi anche

Classe CAtlExeModuleT
Cenni preliminari sulla classe