Compartir por

CAtlServiceModuleT (clase)

  • Artigo

Esta clase implementa un servicio.

Importante

Esta clase y sus miembros no se pueden usar en las aplicaciones que se ejecutan en Windows Runtime.

Sintaxis

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

Parámetros

T
La clase se deriva de CAtlServiceModuleT.

nServiceNameID
Identificador de recurso del servicio.

Miembros

Constructores públicos

Nombre Descripción
CAtlServiceModuleT::CAtlServiceModuleT Constructor .

Métodos públicos

Nombre Descripción
CAtlServiceModuleT::Handler Rutina de controlador del servicio.
CAtlServiceModuleT::InitializeSecurity Proporciona la configuración de seguridad predeterminada para el servicio.
CAtlServiceModuleT::Install Instala y crea el servicio.
CAtlServiceModuleT::IsInstalled Confirma que el servicio se ha instalado.
CAtlServiceModuleT::LogEvent Escribe en el registro de eventos.
CAtlServiceModuleT::OnContinue Invalida este método para continuar con el servicio.
CAtlServiceModuleT::OnInterrogate Invalida este método para interrogar el servicio.
CAtlServiceModuleT::OnPause Invalida este método para pausar el servicio.
CAtlServiceModuleT::OnShutdown Invalida este método para apagar el servicio
CAtlServiceModuleT::OnStop Invalida este método para detener el servicio
CAtlServiceModuleT::OnUnknownRequest Invalida este método para controlar solicitudes desconocidas al servicio.
CAtlServiceModuleT::ParseCommandLine Analiza la línea de comandos y realiza el registro si es necesario.
CAtlServiceModuleT::PreMessageLoop Se llama a este método inmediatamente antes de escribir el bucle de mensajes.
CAtlServiceModuleT::RegisterAppId Registra el servicio en el Registro.
CAtlServiceModuleT::Run Ejecuta el servicio.
CAtlServiceModuleT::ServiceMain Método al que llama el Administrador de control de servicios.
CAtlServiceModuleT::SetServiceStatus Actualiza el estado del servicio.
CAtlServiceModuleT::Start CAtlServiceModuleT::WinMain lo llama cuando se inicia el servicio.
CAtlServiceModuleT::Uninstall Detiene y quita el servicio.
CAtlServiceModuleT::Unlock Disminuye el número de bloqueos del servicio.
CAtlServiceModuleT::UnregisterAppId Quita el servicio del Registro.
CAtlServiceModuleT::WinMain Este método implementa el código necesario para ejecutar el servicio.

Miembros de datos públicos

Nombre Descripción
CAtlServiceModuleT::m_bService Marca que indica que el programa se está ejecutando como un servicio.
CAtlServiceModuleT::m_dwThreadID Variable miembro que almacena el identificador del subproceso.
CAtlServiceModuleT::m_hServiceStatus Variable miembro que almacena un identificador de la estructura de información del estado del servicio actual.
CAtlServiceModuleT::m_status Variable miembro que almacena la estructura de información de estado del servicio actual.
CAtlServiceModuleT::m_szServiceName Nombre del servidor que se va a registrar.

Comentarios

CAtlServiceModuleT, derivado de CAtlExeModuleT, implementa un módulo de servicio ATL. CAtlServiceModuleT proporciona métodos para el procesamiento, la instalación, el registro y la eliminación mediante la línea de comandos. Si se requiere funcionalidad adicional, estos y otros métodos se pueden invalidar.

Esta clase reemplaza a la clase CComModule obsoleta usada en versiones anteriores de ATL. Consulte Clases de módulo ATL para más información.

Jerarquía de herencia

_ATL_MODULE

CAtlModule

CAtlModuleT

CAtlExeModuleT

CAtlServiceModuleT

Requisitos

Encabezado: atlbase.h

CAtlServiceModuleT::CAtlServiceModuleT

Constructor .

CAtlServiceModuleT() throw();

Comentarios

Inicializa los miembros de datos y establece el estado inicial del servicio.

CAtlServiceModuleT::Handler

Rutina de controlador del servicio.

void Handler(DWORD dwOpcode) throw();

Parámetros

dwOpcode
Modificador que define la operación del controlador. Consulte la sección de comentarios para más información.

Comentarios

Este es el código al que llama el Administrador de control de servicios (SCM) para recuperar el estado del servicio y emitir instrucciones, como detener o pausar. El SCM pasa un código de operación, que se muestra a continuación, a Handler para indicar lo que debe hacer el servicio.

Código de operación Significado
SERVICE_CONTROL_STOP detiene el servicio. Invalide el método CAtlServiceModuleT::OnStop en atlbase.h para cambiar el comportamiento.
SERVICE_CONTROL_PAUSE Usuario implementado. Invalide el método vacío CAtlServiceModuleT::OnPause en atlbase.h para pausar el servicio.
SERVICE_CONTROL_CONTINUE Usuario implementado. Invalide el método vacío CAtlServiceModuleT::OnContinue en atlbase.h para continuar con el servicio.
SERVICE_CONTROL_INTERROGATE Usuario implementado. Invalide el método vacío CAtlServiceModuleT::OnInterrogate en atlbase.h para interrogar el servicio.
SERVICE_CONTROL_SHUTDOWN Usuario implementado. Invalide el método vacío CAtlServiceModuleT::OnShutdown en atlbase.h para apagar el servicio.

Si no se reconoce el código de operación, se llama al método CAtlServiceModuleT::OnUnknownRequest.

Un servicio generado por ATL predeterminado solo controla la instrucción de detener. Si el SCM pasa la instrucción de detener, el servicio indica al SCM que el programa está a punto de detenerse. Después, el servicio llama a PostThreadMessage para publicarse él mismo un mensaje de salir. Esta acción finaliza el bucle de mensajes y el servicio acaba cerrándose.

CAtlServiceModuleT::InitializeSecurity

Proporciona la configuración de seguridad predeterminada para el servicio.

HRESULT InitializeSecurity() throw();

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Cualquier clase que derive de CAtlServiceModuleT debe implementar este método en la clase derivada.

Use la autenticación de nivel PKT, el nivel de suplantación de RPC_C_IMP_LEVEL_IDENTIFY y un descriptor de seguridad no NULL adecuado en la llamada a CoInitializeSecurity.

En el caso de proyectos de servicio sin atributos generados por el asistente, estaría en:

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

En el caso de proyectos de servicio con atributos, estaría en:

[ 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

Instala y crea el servicio.

BOOL Install() throw();

Valor devuelto

Devuelve TRUE si la operación se realiza correctamente; de lo contrario, devuelve FALSE.

Comentarios

Instala el servicio en la base de datos del Administrador de control de servicios (SCM) y, luego, crea el objeto de servicio. Si no se pudo crear el servicio, se muestra un cuadro de mensaje y el método devuelve FALSE.

CAtlServiceModuleT::IsInstalled

Confirma que el servicio se ha instalado.

BOOL IsInstalled() throw();

Valor devuelto

Devuelve TRUE si el servicio está instalado; de lo contrario, FALSE.

CAtlServiceModuleT::LogEvent

Escribe en el registro de eventos.

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

Parámetros

pszFormat
Cadena que se va a escribir en el registro de eventos.

...
Cadenas adicionales opcionales que se van a escribir en el registro de eventos.

Comentarios

Este método escribe detalles en un registro de eventos mediante la función ReportEvent. Si no se está ejecutando ningún servicio, la cadena se envía a la consola.

CAtlServiceModuleT::m_bService

Marca que indica que el programa se está ejecutando como un servicio.

BOOL m_bService;

Comentarios

Se usa para distinguir un EXE de servicio de un EXE de aplicación.

CAtlServiceModuleT::m_dwThreadID

Variable miembro que almacena el identificador de subproceso del servicio.

DWORD m_dwThreadID;

Comentarios

Esta variable almacena el identificador de subproceso del subproceso actual.

CAtlServiceModuleT::m_hServiceStatus

Variable miembro que almacena un identificador de la estructura de información del estado del servicio actual.

SERVICE_STATUS_HANDLE m_hServiceStatus;

Comentarios

La estructura SERVICE_STATUS contiene información sobre un servicio.

CAtlServiceModuleT::m_status

Variable miembro que almacena la estructura de información de estado del servicio actual.

SERVICE_STATUS m_status;

Comentarios

La estructura SERVICE_STATUS contiene información sobre un servicio.

CAtlServiceModuleT::m_szServiceName

Nombre del servidor que se va a registrar.

TCHAR [256] m_szServiceName;

Comentarios

Cadena terminada en NULL que almacena el nombre del servicio.

CAtlServiceModuleT::OnContinue

Invalida este método para continuar con el servicio.

void OnContinue() throw();

CAtlServiceModuleT::OnInterrogate

Invalida este método para interrogar el servicio.

void OnInterrogate() throw();

CAtlServiceModuleT::OnPause

Invalida este método para pausar el servicio.

void OnPause() throw();

CAtlServiceModuleT::OnShutdown

Invalida este método para apagar el servicio.

void OnShutdown() throw();

CAtlServiceModuleT::OnStop

Invalida este método para detener el servicio.

void OnStop() throw();

CAtlServiceModuleT::OnUnknownRequest

Invalida este método para controlar solicitudes desconocidas al servicio.

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

Parámetros

dwOpcode
Reservado.

CAtlServiceModuleT::ParseCommandLine

Analiza la línea de comandos y realiza el registro si es necesario.

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

Parámetros

lpCmdLine
La línea de comandos.

pnRetCode
El valor HRESULT correspondiente al registro (si tuvo lugar).

Valor devuelto

Devuelve true si se ha realizado correctamente o false si no se pudo registrar el archivo RGS proporcionado en la línea de comandos.

Comentarios

Analiza la línea de comandos y registra o anula el registro del archivo RGS proporcionado si es necesario. Este método llama a CAtlExeModuleT::P arseCommandLine para buscar /RegServer y /UnregServer. Al agregar el argumento -/Service se registrará el servicio.

CAtlServiceModuleT::PreMessageLoop

Se llama a este método inmediatamente antes de escribir el bucle de mensajes.

HRESULT PreMessageLoop(int nShowCmd) throw();

Parámetros

nShowCmd
Este parámetro se pasa a CAtlExeModuleT::P reMessageLoop.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Invalide este método para agregar código de inicialización personalizado para el servicio.

CAtlServiceModuleT::RegisterAppId

Registra el servicio en el Registro.

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

Parámetros

bService
Debe ser true para registrarse como servicio.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

CAtlServiceModuleT::Run

Ejecuta el servicio.

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

Parámetros

nShowCmd
Especifica cómo se va a mostrar la ventana. Este parámetro puede ser uno de los valores descritos en la sección WinMain. El valor predeterminado es SW_HIDE.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Después de que se llama, Run llama a CAtlServiceModuleT::P reMessageLoop, CAtlExeModuleT::RunMessageLoop y CAtlExeModuleT::P ostMessageLoop.

CAtlServiceModuleT::ServiceMain

El Administrador de control de servicios llama a este método.

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

Parámetros

dwArgc
Argumento argc.

lpszArgv
Argumento argv.

Comentarios

El Administrador de control de servicios (SCM) llama a ServiceMain al abrir la aplicación Servicios en el Panel de control, seleccionar el servicio y hacer clic en Iniciar.

Una vez que el SCM llama a ServiceMain, un servicio debe proporcionar al SCM una función de controlador. Esta función permite al SCM obtener el estado del servicio y pasar instrucciones específicas (como pausar o detener). Posteriormente, se llama a CAtlServiceModuleT::Run para realizar el trabajo principal del servicio. Run continúa en ejecución hasta que se detiene el servicio.

CAtlServiceModuleT::SetServiceStatus

Este método actualiza el estado del servicio.

void SetServiceStatus(DWORD dwState) throw();

Parámetros

dwState
El nuevo estado. Consulte SetServiceStatus para ver los valores posibles.

Comentarios

Actualiza la información de estado del Administrador de control de servicios para el servicio. Lo llaman CAtlServiceModuleT::Run, CAtlServiceModuleT::ServiceMain y otros métodos de controlador. El estado también se almacena en la variable miembro CAtlServiceModuleT::m_status.

CAtlServiceModuleT::Start

CAtlServiceModuleT::WinMain lo llama cuando se inicia el servicio.

HRESULT Start(int nShowCmd) throw();

Parámetros

nShowCmd
Especifica cómo se va a mostrar la ventana. Este parámetro puede ser uno de los valores descritos en la sección WinMain.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

El método CAtlServiceModuleT::WinMain controla tanto el registro como la instalación, así como las tareas implicadas en la eliminación de entradas del Registro y la desinstalación del módulo. Cuando se ejecuta el servicio, WinMain llama a Start.

CAtlServiceModuleT::Uninstall

Detiene y quita el servicio.

BOOL Uninstall() throw();

Valor devuelto

Devuelve TRUE si la operación se realiza correctamente; de lo contrario, devuelve FALSE.

Comentarios

Detiene la ejecución del servicio y lo quita de la base de datos del Administrador de control de servicios.

CAtlServiceModuleT::Unlock

Disminuye el número de bloqueos del servicio.

LONG Unlock() throw();

Valor devuelto

Devuelve el recuento de bloqueos, que puede ser útil para los diagnósticos y la depuración.

CAtlServiceModuleT::UnregisterAppId

Quita el servicio del Registro.

HRESULT UnregisterAppId() throw();

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

CAtlServiceModuleT::WinMain

Este método implementa el código necesario para iniciar el servicio.

int WinMain(int nShowCmd) throw();

Parámetros

nShowCmd
Especifica cómo se va a mostrar la ventana. Este parámetro puede ser uno de los valores descritos en la sección WinMain.

Valor devuelto

Devuelve el valor devuelto del servicio.

Comentarios

Este método procesa la línea de comandos (con CAtlServiceModuleT::P arseCommandLine) y, luego, inicia el servicio (mediante CAtlServiceModuleT::Start).

Consulte también

CAtlExeModuleT (clase)
Información general sobre la clase