Función EnumServicesStatusA (winsvc.h)

Artículo
11/20/2024

Enumera los servicios de la base de datos del administrador de control de servicios especificada. Se proporciona el nombre y el estado de cada servicio.

Esta función se ha reemplazado por la función EnumServicesStatusEx. Devuelve la misma información enumServicesStatus, además del identificador de proceso y la información adicional del servicio. Además, EnumServicesStatusEx le permite enumerar servicios que pertenecen a un grupo especificado.

Sintaxis

BOOL EnumServicesStatusA(
  [in]                SC_HANDLE              hSCManager,
  [in]                DWORD                  dwServiceType,
  [in]                DWORD                  dwServiceState,
  [out, optional]     LPENUM_SERVICE_STATUSA lpServices,
  [in]                DWORD                  cbBufSize,
  [out]               LPDWORD                pcbBytesNeeded,
  [out]               LPDWORD                lpServicesReturned,
  [in, out, optional] LPDWORD                lpResumeHandle
);

Parámetros

[in] hSCManager

Identificador de la base de datos del administrador de control de servicios. Este identificador lo devuelve la función OpenSCManager 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.

[in] dwServiceType

Tipo de servicios que se van a enumerar. Este parámetro puede ser uno o varios de los siguientes valores.

Valor	Significado
SERVICE_DRIVER 0x0000000B	Servicios de tipo SERVICE_KERNEL_DRIVER y SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_FILE_SYSTEM_DRIVER 0x00000002	Servicios de controladores del sistema de archivos.
SERVICE_KERNEL_DRIVER 0x00000001	Servicios de controladores.
SERVICE_WIN32 0x00000030	Servicios de tipo SERVICE_WIN32_OWN_PROCESS y SERVICE_WIN32_SHARE_PROCESS.
SERVICE_WIN32_OWN_PROCESS 0x00000010	Servicios que se ejecutan en sus propios procesos.
SERVICE_WIN32_SHARE_PROCESS 0x00000020	Servicios que comparten un proceso con uno o más servicios. Para obtener más información, consulte Programas de servicio.

[in] dwServiceState

Estado de los servicios que se van a enumerar. Este parámetro puede ser uno de los siguientes valores.

Valor	Significado
SERVICE_ACTIVE 0x00000001	Enumera los servicios que se encuentran en los siguientes estados: SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_RUNNING, SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING y SERVICE_PAUSED.
SERVICE_INACTIVE 0x00000002	Enumera los servicios que están en estado de SERVICE_STOPPED.
SERVICE_STATE_ALL 0x00000003	Combina los siguientes estados: SERVICE_ACTIVE y SERVICE_INACTIVE.

[out, optional] lpServices

Puntero a un búfer que contiene una matriz de estructuras de ENUM_SERVICE_STATUS que reciben la información de nombre y estado del servicio para cada servicio de la base de datos. El búfer debe ser lo suficientemente grande como para contener las estructuras, además de las cadenas a las que apuntan sus miembros.

El tamaño máximo de esta matriz es de 256 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 pcbBytesNeededed recibirá el tamaño necesario.

Windows Server 2003 y Windows XP: El tamaño máximo de esta matriz es de 64 000 bytes. Este límite se incrementó a partir de Windows Server 2003 con SP1 y Windows XP con SP2.

[in] cbBufSize

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

[out] pcbBytesNeeded

Puntero a una variable que recibe el número de bytes necesarios para devolver las entradas de servicio restantes, si el búfer es demasiado pequeño.

[out] lpServicesReturned

Puntero a una variable que recibe el número de entradas de servicio devueltas.

[in, out, optional] lpResumeHandle

Puntero a una variable que, en la entrada, especifica el punto inicial de la enumeración. Debe establecer este valor en cero la primera vez que se llama a esta función. En la salida, este valor es cero si la función se realiza correctamente. Sin embargo, si la función devuelve cero y la GetLastError función devuelve ERROR_MORE_DATA, este valor se usa para indicar la siguiente entrada de servicio que se va a leer cuando se llama a la función para recuperar los datos adicionales.

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 los siguientes códigos 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_ACCESS_DENIED	El identificador no tiene derecho de acceso SC_MANAGER_ENUMERATE_SERVICE.
ERROR_INVALID_HANDLE	El identificador especificado no es válido.
ERROR_INVALID_PARAMETER	Un parámetro que se especificó no es válido.
ERROR_MORE_DATA	Hay más entradas de servicio de las que caben en el búfer de lpServices. El número real de entradas de servicio escritas en lpServices se devuelve en el parámetro lpServicesReturned. El número de bytes necesarios para obtener las entradas restantes se devuelve en el parámetro pcbBytesNeededed. Los servicios restantes se pueden enumerar mediante llamadas adicionales a EnumServicesStatus con el parámetro lpResumeHandle que indica el siguiente servicio que se va a leer.

Observaciones

Nota

El encabezado winsvc.h define EnumServicesStatus 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