Función NotifyServiceStatusChangeA (winsvc.h)
Permite a una aplicación recibir notificaciones cuando se crea o elimina el servicio especificado o cuando cambia su estado.
Sintaxis
DWORD NotifyServiceStatusChangeA(
[in] SC_HANDLE hService,
[in] DWORD dwNotifyMask,
[in] PSERVICE_NOTIFYA pNotifyBuffer
);
Parámetros
[in] hService
Identificador del servicio o del administrador de control de servicios. Los identificadores de los servicios los devuelve la función OpenService o CreateService y deben tener el derecho de acceso SERVICE_QUERY_STATUS. La función OpenSCManager devuelve los identificadores del administrador de control de servicio y debe tener el derecho de acceso SC_MANAGER_ENUMERATE_SERVICE. Para obtener más información, consulte derechos de acceso y seguridad del servicio.
Solo puede haber una solicitud de notificación pendiente por servicio.
[in] dwNotifyMask
Tipo de cambios de estado que se deben notificar. Este parámetro puede ser uno o varios de los siguientes valores.
| Valor | Significado |
|---|---|
|
Informe cuando se haya creado el servicio.
El parámetro hService debe ser un identificador para el SCM. |
|
Informe cuando el servicio esté a punto de continuar.
El parámetro hService |
|
Informe cuando una aplicación haya especificado el servicio en una llamada a la función DeleteService. La aplicación debe cerrar los identificadores del servicio para que se pueda eliminar.
El parámetro hService |
|
Informe cuando se haya eliminado el servicio. Una aplicación no puede recibir esta notificación si tiene un identificador abierto para el servicio.
El parámetro hService debe ser un identificador para el SCM. |
|
Informe cuando el servicio se está pausando.
El parámetro hService |
|
Informe cuando el servicio se haya pausado.
El parámetro hService |
|
Informe cuando el servicio se está ejecutando.
El parámetro hService |
|
Informe cuando se inicie el servicio.
El parámetro hService |
|
Informe cuando el servicio se detenga.
El parámetro hService |
|
Informe cuando el servicio se haya detenido.
El parámetro hService |
[in] pNotifyBuffer
Puntero a una estructura de SERVICE_NOTIFY que contiene información de notificación, como un puntero a la función de devolución de llamada. Esta estructura debe permanecer válida hasta que se invoque la función de devolución de llamada o el subproceso que realiza la llamada cancele la solicitud de notificación.
No realice varias llamadas a NotifyServiceStatusChange con el mismo parámetro de búfer hasta que se haya cancelado la función de devolución de llamada de la primera llamada con el búfer o la primera solicitud de notificación. De lo contrario, no hay ninguna garantía de qué versión del búfer recibirá la función de devolución de llamada.
Windows Vista: La dirección de la función de devolución de llamada debe estar dentro del intervalo de direcciones de un módulo cargado. Por lo tanto, la función de devolución de llamada no puede ser código generado en tiempo de ejecución (por ejemplo, código administrado generado por el compilador JIT) o código nativo que se descomprime en tiempo de ejecución. Esta restricción se quitó en Windows Server 2008 y Windows Vista con SP1.
Valor devuelto
Si la función se ejecuta correctamente, se ERROR_SUCCESS el valor devuelto. Si el servicio se ha marcado para su eliminación, el valor devuelto es ERROR_SERVICE_MARKED_FOR_DELETE y el identificador del servicio debe cerrarse. Si la notificación de servicio se retrasa demasiado lejos del estado del sistema, la función devuelve ERROR_SERVICE_NOTIFY_CLIENT_LAGGING. En este caso, el cliente debe cerrar el identificador al SCM, abrir un nuevo identificador y llamar a esta función de nuevo.
Si se produce un error en la función, el valor devuelto es uno de los códigos de error del sistema .
Observaciones
La función
Cuando cambia el estado del servicio, el sistema invoca la función de devolución de llamada especificada como una llamada de procedimiento asincrónica (APC) en cola al subproceso que realiza la llamada. El subproceso que realiza la llamada debe especificar una espera que se pueda alertar (por ejemplo, llamando a la función SleepEx
Si el servicio ya está en cualquiera de los estados solicitados cuando se llama a NotifyServiceStatusChange, la función de devolución de llamada se pone en cola inmediatamente. Si el estado del servicio no ha cambiado la próxima vez que se llame a la función con el mismo servicio y estado, la función de devolución de llamada no se pone en cola inmediatamente; La función de devolución de llamada se pone en cola la próxima vez que el servicio entre en el estado solicitado.
La función NotifyServiceStatusChange
Es más eficaz llamar a NotifyServiceStatusChange desde un subproceso que realiza una espera que crear un subproceso adicional.
Una vez invocada la función de devolución de llamada, el autor de la llamada debe llamar a NotifyServiceStatusChange para recibir notificaciones adicionales. Tenga en cuenta que ciertas funciones de la API de Windows, incluidas las NotifyServiceStatusChange y otras funciones de SCM, usan llamadas a procedimientos remotos (RPC); estas funciones pueden realizar una operación de espera alertable, por lo que no son seguras para llamar desde dentro de la función de devolución de llamada. En su lugar, la función de devolución de llamada debe guardar los parámetros de notificación y realizar cualquier trabajo adicional fuera de la devolución de llamada.
Para cancelar las notificaciones pendientes, cierre el identificador de servicio mediante la función
Nota
El encabezado winsvc.h define NotifyServiceStatusChange 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 Vista [solo aplicaciones de escritorio] |
| servidor mínimo admitido | Windows Server 2008 [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 |