3.1.4.1.38 FAX_GetDeviceStatus (Opnum 8)

The FAX_GetDeviceStatus (Opnum 8) method is called by the client to retrieve information about a specified fax device (port).

In response, the server MUST validate that the client's fax user account has access to query configuration. The server SHOULD validate that the FaxPortHandle parameter is not set to NULL. It MUST then allocate memory for the status buffer to be passed out and fill it with data.

The fax server MUST ignore the access mode of the fax port specified by the FaxPortHandle.

To indicate success, the server MUST return the buffer that contains the status information, along with the buffer size.

The client SHOULD free the buffer.

 error_status_t FAX_GetDeviceStatus(
   [in] RPC_FAX_PORT_HANDLE FaxPortHandle,
   [out, size_is(,*BufferSize)] LPBYTE* StatusBuffer,
   [out, ref] LPDWORD BufferSize
 );

FaxPortHandle: An RPC context handle that references a specified fax port. This context handle MUST be obtained using the FAX_OpenPort (section 3.1.4.1.65) method.

StatusBuffer: A pointer to the address of a buffer to receive a FAX_DEVICE_STATUS structure. The structure describes the status of one fax device. The fax server MUST set the SizeOfStruct member of this structure to the correct size for the Fixed_Portion block of the FAX_DEVICE_STATUS, as described in section 2.2.10.

BufferSize: A variable to return the size, in bytes, of the data returned in the buffer referenced by the StatusBuffer parameter.

Return Values: This method MUST return 0x00000000 (ERROR_SUCCESS) for success; otherwise, it MUST return one of the following error codes, one of the fax-specific errors that are defined in section 2.2.52, or one of the other standard errors defined in [MS-ERREF] section 2.2.

Return value/code	Description
ERROR_ACCESS_DENIED 0x00000005	Access is denied. The client's fax user account does not have the FAX_ACCESS_QUERY_CONFIG access rights required for this operation.
ERROR_NOT_ENOUGH_MEMORY 0x00000008	The server cannot allocate sufficient memory to hold the FAX_DEVICE_STATUS to be returned to the client.
ERROR_INVALID_DATA 0x0000000D	The FaxPortHandle parameter is not set to a valid port handle obtained using FAX_OpenPort.<106>
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned under any of the following conditions: § The StatusBuffer parameter is set to a NULL pointer value.<107> § The FaxPortHandle parameter is set to a NULL value.<108>
ERROR_INTERNAL_ERROR 0x0000054F	The server failed to custom marshal the FAX_DEVICE_STATUS to be returned to the client.

Exceptions Thrown: No exceptions are thrown except those that are thrown by the underlying RPC protocol, [MS-RPCE].