Función QueryServiceStatusEx (winsvc.h)

  • Artículo

Recupera el estado actual del servicio especificado en función del nivel de información especificado.

Sintaxis

BOOL QueryServiceStatusEx(
  [in]            SC_HANDLE      hService,
  [in]            SC_STATUS_TYPE InfoLevel,
  [out, optional] LPBYTE         lpBuffer,
  [in]            DWORD          cbBufSize,
  [out]           LPDWORD        pcbBytesNeeded
);

Parámetros

[in] hService

Identificador del servicio. La función CreateService o OpenService devuelve este identificador y debe tener el derecho de acceso SERVICE_QUERY_STATUS. Para obtener más información, consulte Derechos de acceso y seguridad del servicio.

[in] InfoLevel

Atributos de servicio que se van a devolver. Use SC_STATUS_PROCESS_INFO para recuperar la información de estado del servicio. El parámetro lpBuffer es un puntero a una estructura SERVICE_STATUS_PROCESS .

Actualmente, no se definen otros niveles de información.

[out, optional] lpBuffer

Puntero al búfer que recibe la información de estado. El formato de estos datos depende del valor del parámetro InfoLevel .

El tamaño máximo de esta matriz es de 8 000 bytes. Para determinar el tamaño necesario, especifique NULL para este parámetro y 0 para el parámetro cbBufSize . Se producirá un error en la función y GetLastError devolverá ERROR_INSUFFICIENT_BUFFER. El parámetro pcbBytesNeeded recibirá el tamaño necesario.

[in] cbBufSize

Tamaño del búfer al que apunta el parámetro lpBuffer , en bytes.

[out] pcbBytesNeeded

Puntero a una variable que recibe el número de bytes necesarios para almacenar toda la información de estado, si se produce un error en la función con ERROR_INSUFFICIENT_BUFFER.

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. Se pueden devolver los errores siguientes.

Código devuelto Descripción
ERROR_INVALID_HANDLE
 El identificador no es válido.
ERROR_ACCESS_DENIED
 El identificador no tiene el derecho de acceso SERVICE_QUERY_STATUS.
ERROR_INSUFFICIENT_BUFFER
 El búfer es demasiado pequeño para la estructura de SERVICE_STATUS_PROCESS . No se escribió nada en la estructura.
ERROR_INVALID_PARAMETER
 El miembro cbSize de SERVICE_STATUS_PROCESS no es válido.
ERROR_INVALID_LEVEL
 El parámetro InfoLevel contiene un valor no admitido.
ERROR_SHUTDOWN_IN_PROGRESS
 El sistema está apagando; No se puede llamar a esta función.

Comentarios

La función QueryServiceStatusEx devuelve la información de estado del servicio más reciente notificada al administrador de control de servicios. Si el servicio acaba de cambiar su estado, es posible que aún no haya actualizado el administrador de control de servicios.

El identificador de proceso devuelto en la estructura SERVICE_STATUS_PROCESS es válido siempre que el estado del servicio sea uno de SERVICE_RUNNING, SERVICE_PAUSE_PENDING, SERVICE_PAUSED o SERVICE_CONTINUE_PENDING. Sin embargo, si el servicio está en un estado SERVICE_START_PENDING o SERVICE_STOP_PENDING, es posible que el identificador de proceso no sea válido y, si el servicio está en el estado SERVICE_STOPPED, nunca es válido.

Ejemplos

Para obtener un ejemplo, consulte Inicio de un servicio o Detención de un servicio.

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

Consulte también

SERVICE_STATUS_PROCESS

Funciones de servicio

Inicio del servicio