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 identificadores al administrador de controles 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 más 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 debe ser un identificador para el servicio. |
|
Informe cuando una aplicación ha 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 debe ser un identificador para el servicio. |
|
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 debe ser un identificador para el servicio. |
|
Informe cuando el servicio se haya pausado.
El parámetro hService debe ser un identificador para el servicio. |
|
Notificar cuándo se está ejecutando el servicio.
El parámetro hService debe ser un identificador para el servicio. |
|
Informe cuando se inicia el servicio.
El parámetro hService debe ser un identificador para el servicio. |
|
Informe cuando el servicio se detenga.
El parámetro hService debe ser un identificador para el servicio. |
|
Informe cuando el servicio se haya detenido.
El parámetro hService debe ser un identificador para el servicio. |
[in] pNotifyBuffer
Puntero a una estructura 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 la función de devolución de llamada de la primera llamada haya finalizado con el búfer o se haya cancelado 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, el valor devuelto es ERROR_SUCCESS. Si el servicio se ha marcado para su eliminación, el valor devuelto se ERROR_SERVICE_MARKED_FOR_DELETE y el identificador del servicio debe cerrarse. Si la notificación del 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 volver a llamar a esta función.
Si se produce un error en la función, el valor devuelto es uno de los códigos de error del sistema.
Comentarios
La función NotifyServiceStatusChange se puede usar para recibir notificaciones sobre las aplicaciones de servicio. No se puede usar para recibir notificaciones sobre los servicios de controladores.
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 alertable (por ejemplo, mediante una llamada a la función SleepEx ) para recibir una notificación. Para obtener más información, vea Llamadas asincrónicas a procedimientos.
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 llama a la función OpenThread en el subproceso que realiza la llamada con el derecho de acceso THREAD_SET_CONTEXT. Si el subproceso que realiza la llamada no tiene este derecho de acceso, NotifyServiceStatusChange produce un error. Si el subproceso que realiza la llamada suplanta a otro usuario, es posible que no tenga permiso suficiente para establecer el contexto.
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 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 CloseServiceHandle . Después de que CloseServiceHandle se realice correctamente, no se pondrá en cola más API de notificación. Si el subproceso que realiza la llamada se cierra sin cerrar el identificador del servicio o esperando hasta que se genere el APC, se puede producir una pérdida de memoria.
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 Convenciones para prototipos de función.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows Vista [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2008 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | winsvc.h (incluye Windows.h) |
| Library | Advapi32.lib |
| Archivo DLL | Advapi32.dll |
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de