Función StartServiceCtrlDispatcherA (winsvc.h)

Artículo
03/04/2024

Conecta el subproceso principal de un proceso de servicio al administrador de control de servicios, lo que hace que el subproceso sea el subproceso del distribuidor de control de servicio para el proceso de llamada.

Sintaxis

BOOL StartServiceCtrlDispatcherA(
  [in] const SERVICE_TABLE_ENTRYA *lpServiceStartTable
);

Parámetros

[in] lpServiceStartTable

Puntero a una matriz de estructuras de SERVICE_TABLE_ENTRY que contienen una entrada para cada servicio que se puede ejecutar en el proceso de llamada. Los miembros de la última entrada de la tabla deben tener valores NULL para designar el final de la tabla.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

El administrador de control de servicios puede establecer el siguiente código de error. Otros códigos de error se pueden establecer mediante las funciones del Registro a las que llama el administrador de control de servicios.

Código devuelto	Descripción
ERROR_FAILED_SERVICE_CONTROLLER_CONNECT	Este error se devuelve si el programa se ejecuta como una aplicación de consola en lugar de como servicio. Si el programa se ejecutará como una aplicación de consola con fines de depuración, estructure dicho código específico del servicio no se llama cuando se devuelve este error.
ERROR_INVALID_DATA	La tabla de distribución especificada contiene entradas que no tienen el formato adecuado.
ERROR_SERVICE_ALREADY_RUNNING	El proceso ya ha llamado StartServiceCtrlDispatcher. Cada proceso solo puede llamar a StartServiceCtrlDispatcher una vez.

Comentarios

Cuando el administrador de control de servicios inicia un proceso de servicio, espera a que el proceso llame a la función StartServiceCtrlDispatcher . El subproceso principal de un proceso de servicio debe realizar esta llamada lo antes posible después de que se inicie (en un plazo de 30 segundos). Si StartServiceCtrlDispatcher se realiza correctamente, conecta el subproceso de llamada al administrador de controles de servicio y no vuelve hasta que todos los servicios en ejecución del proceso hayan entrado en el estado de SERVICE_STOPPED. El administrador de control de servicios usa esta conexión para enviar solicitudes de inicio de servicio y control al subproceso principal del proceso de servicio. El subproceso principal actúa como distribuidor invocando la función HandlerEx adecuada para controlar las solicitudes de control o creando un subproceso para ejecutar la función ServiceMain adecuada cuando se inicia un nuevo servicio.

El parámetro lpServiceTable contiene una entrada para cada servicio que se puede ejecutar en el proceso de llamada. Cada entrada especifica la función ServiceMain para ese servicio. Para SERVICE_WIN32_SHARE_PROCESS servicios, cada entrada debe contener el nombre de un servicio. Este nombre es el nombre del servicio especificado por la función CreateService cuando se instaló el servicio. Para SERVICE_WIN32_OWN_PROCESS servicios, se omite el nombre del servicio en la entrada de tabla.

Si un servicio se ejecuta en su propio proceso, el subproceso principal del proceso de servicio debe llamar inmediatamente a StartServiceCtrlDispatcher. Todas las tareas de inicialización se realizan en la función ServiceMain del servicio cuando se inicia el servicio.

Si varios servicios comparten un proceso y es necesario realizar alguna inicialización común para todo el proceso antes de llamar a cualquier función ServiceMain , el subproceso principal puede realizar el trabajo antes de llamar a StartServiceCtrlDispatcher, siempre y cuando tarde menos de 30 segundos. De lo contrario, se debe crear otro subproceso para realizar la inicialización en todo el proceso, mientras que el subproceso principal llama a StartServiceCtrlDispatcher y se convierte en el distribuidor de control de servicio. Cualquier inicialización específica del servicio debe realizarse en las funciones principales del servicio individuales.

Los servicios no deben intentar mostrar directamente una interfaz de usuario. Para obtener más información, consulte Interactive Services.

Ejemplos

Para obtener un ejemplo, consulte Escritura de una función principal del programa de servicios.

Nota

El encabezado winsvc.h define StartServiceCtrlDispatcher como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winsvc.h (incluye Windows.h)
Library	Advapi32.lib
Archivo DLL	Advapi32.dll