3.1.4.4 Status (Opnum 10)
This method returns the status of the Internet services.
The server can have all functionality through this interface disabled using actions taken local to the server machine. In this case the function MUST return an error when called (E_ERROR_RESOURCE_DISABLED) and MUST NOT perform any other action.
If the interface functionality is not disabled, the following SHOULD take place on the server when this method is called:
The method SHOULD return a buffer of unsigned chars as described in section 2.2.2. This buffer of unsigned chars MUST contain data about the status of the Internet services.
If it is not possible to return all the data in the buffer provided, then the following conditional behavior MUST occur.
For more information about the unsigned char buffer returned, see section 2.2.2.
-
HRESULT Status( [in] DWORD dwBufferSize, [out, size_is(dwBufferSize)] unsigned char* pbBuffer, [out] DWORD* pdwMDRequiredBufferSize, [out] DWORD* pdwNumServices );
dwBufferSize: Size, in bytes, of the pbBuffer parameter. If this parameter is not greater than the amount of data the server wants to return in pbBuffer, the conditional behavior that follows MUST occur.
-
If the dwBufferSize parameter value indicates that pbBuffer is too small to contain all the status information about the Internet services, the following actions MUST occur:
The pdwMDRequiredBufferSize parameter MUST be set to the number of bytes needed to contain the data that is to be returned.
The pbBuffer parameter MUST be set to zero.
The method MUST be failed with code 0x8007007A (E_ERROR_INSUFFICIENT_BUFFER).
pbBuffer: An array of unsigned chars that will be filled with information about the status of the Internet services. For more information, see section 2.2.2.
-
pbBuffer MAY be set to null. In this case, the size will be calculated by the system for the buffer (regardless of whether a size was passed in for the buffer size) and E_ERROR_INSUFFICIENT_BUFFER will be returned. If pdwMDRequiredBufferSize is not null, it will be used to return the calculated size.
pdwMDRequiredBufferSize: On return from this method, if this parameter is not null, this parameter points to a DWORD containing the number of bytes that pbBuffer must be able to contain for the method to return the services status information. This field MAY be used.
pdwNumServices: The number of services for which status is returned.
Return Values: A signed, 32-bit value indicating return status. If the method returns a negative value, it has failed. If the 12-bit facility code (bits 16–27) is set to 0x007, the value contains a Win32 error code in the lower 16 bits. 0 or positive values indicate success, with the lower 16 bits in positive nonzero values containing warnings or flags defined in the method implementation. For more information about HRESULT, see [MS-ERREF] section 2.1.
-
The method MUST return S_OK (0x00000000) upon success.
-
Return value/code
Description
0x00000000
S_OK
The call was successful.
0x8007007A
E_ERROR_INSUFFICIENT_BUFFER
The size of the pbBuffer is too small to return the status data based on its size being declared in dwBufferSize parameter.
0x80070008
E_ERROR_NOT_ENOUGH_MEMORY
Not enough memory is available to process this command.
0x800710D5
E_ERROR_RESOURCE_DISABLED
The IIisServiceControl interface is disabled.