Events
Nov 19, 11 PM - Nov 21, 11 PM
Gain the competitive edge you need with powerful AI and Cloud solutions by attending Microsoft Ignite online.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Retrieves the current status of the specified service based on the specified information level.
BOOL QueryServiceStatusEx(
[in] SC_HANDLE hService,
[in] SC_STATUS_TYPE InfoLevel,
[out, optional] LPBYTE lpBuffer,
[in] DWORD cbBufSize,
[out] LPDWORD pcbBytesNeeded
);
[in] hService
A handle to the service. This handle is returned by the CreateService or OpenService function, and it must have the SERVICE_QUERY_STATUS access right. For more information, see Service Security and Access Rights.
[in] InfoLevel
The service attributes to be returned. Use SC_STATUS_PROCESS_INFO to retrieve the service status information. The lpBuffer parameter is a pointer to a SERVICE_STATUS_PROCESS structure.
Currently, no other information levels are defined.
[out, optional] lpBuffer
A pointer to the buffer that receives the status information. The format of this data depends on the value of the InfoLevel parameter.
The maximum size of this array is 8K bytes. To determine the required size, specify NULL for this parameter and 0 for the cbBufSize parameter. The function will fail and GetLastError will return ERROR_INSUFFICIENT_BUFFER. The pcbBytesNeeded parameter will receive the required size.
[in] cbBufSize
The size of the buffer pointed to by the lpBuffer parameter, in bytes.
[out] pcbBytesNeeded
A pointer to a variable that receives the number of bytes needed to store all status information, if the function fails with ERROR_INSUFFICIENT_BUFFER.
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError. The following errors can be returned.
Return code | Description |
---|---|
|
The handle is invalid. |
|
The handle does not have the SERVICE_QUERY_STATUS access right. |
|
The buffer is too small for the SERVICE_STATUS_PROCESS structure. Nothing was written to the structure. |
|
The cbSize member of SERVICE_STATUS_PROCESS is not valid. |
|
The InfoLevel parameter contains an unsupported value. |
|
The system is shutting down; this function cannot be called. |
The QueryServiceStatusEx function returns the most recent service status information reported to the service control manager. If the service just changed its status, it may not have updated the service control manager yet.
The process identifier returned in the SERVICE_STATUS_PROCESS structure is valid provided that the state of the service is one of SERVICE_RUNNING, SERVICE_PAUSE_PENDING, SERVICE_PAUSED, or SERVICE_CONTINUE_PENDING. If the service is in a SERVICE_START_PENDING or SERVICE_STOP_PENDING state, however, the process identifier may not be valid, and if the service is in the SERVICE_STOPPED state, it is never valid.
For an example, see Starting a Service or Stopping a Service.
Requirement | Value |
---|---|
Minimum supported client | Windows XP [desktop apps only] |
Minimum supported server | Windows Server 2003 [desktop apps only] |
Target Platform | Windows |
Header | winsvc.h (include Windows.h) |
Library | Advapi32.lib |
DLL | Advapi32.dll |
Events
Nov 19, 11 PM - Nov 21, 11 PM
Gain the competitive edge you need with powerful AI and Cloud solutions by attending Microsoft Ignite online.
Register now