3.1.4.2.13 FaxObs_GetDeviceStatus (Opnum 11)

The FaxObs_GetDeviceStatus (Opnum 11) 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 MUST allocate memory for the status buffer to be passed out and to fill it with data.

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 FaxObs_GetDeviceStatus(
   [in] RPC_FAX_PORT_HANDLE FaxPortHandle,
   [in, out, unique, size_is(,*BufferSize)] 
     LPBYTE* StatusBuffer,
   [in, out] LPDWORD BufferSize
 );

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

StatusBuffer: A pointer to the address of the returned buffer containing a FAX_DEVICE_STATUS (section 2.2.10) structure. The structure describes the status of one fax device.

BufferSize: A variable to return the size, in bytes, of the status buffer.

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_PORT_QUERY access rights.
ERROR_NOT_ENOUGH_MEMORY 0x00000008	The fax server cannot allocate memory for the data to be returned to the client.
ERROR_INVALID_DATA 0x0000000D	This error SHOULD be returned if the FaxPortHandle parameter is not a valid handle obtained using FaxObs_OpenPort.<198>

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