Función StartServiceCtrlDispatcherA (winsvc.h)

Artículo
11/20/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 SERVICE_TABLE_ENTRY estructuras 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 ejecuta correctamente, el valor devuelto es distinto de cero.

Si se produce un error en la función, 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, estructurelo de forma que no se llame a código específico del servicio cuando se devuelva 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 a StartServiceCtrlDispatcher. Cada proceso puede llamar a StartServiceCtrlDispatcher solo una vez.

Observaciones

Cuando el administrador de control de servicio 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 control de servicio y no vuelve hasta que todos los servicios en ejecución del proceso hayan entrado en el estado SERVICE_STOPPED. El administrador de control de servicio 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 nuevo 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. En 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 en todo el proceso antes de que se llame 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 la 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	winsvc.h (incluya Windows.h)
biblioteca de	Advapi32.lib
DLL de	Advapi32.dll