IFaxJob::get_DeviceStatus

The IFaxJob::get_DeviceStatus method retrieves the DeviceStatus property for a FaxJob object. The DeviceStatus property is a null-terminated string that describes the status of the port associated with the fax job.

Visual Basic Reference

HRESULT get_DeviceStatus(
  BSTR *pVal  // receives device status
);

Parameters

pVal

[out] Pointer to a localized null-terminated string that contains a fax device status. Following are the English string equivalents.

Value	Meaning
"Dialing"	The device is dialing a fax number.
"Sending"	The device is sending a fax document.
"Receiving"	The device is receiving a fax document.
"Completed"	The device completed sending or receiving a fax transmission.
"Unavailable"	The device is not available because it is in use by another application.
"Busy"	The device encountered a busy signal.
"No Answer"	The receiving device did not answer the call.
"Bad Address"	The device dialed an invalid fax number.
"No Dial Tone"	The sending device cannot complete the call because it does not detect a dial tone.
"Disconnected"	The fax call was disconnected by the sender or the caller.
"Fatal Error"	The device has encountered a fatal protocol error.
"Not a Fax Call"	The device received a call that was a data call or a voice call.
"Call Delayed"	The device delayed a fax call because the sending device received a busy signal multiple times. The device cannot retry the call because dialing restrictions exist. (Some countries restrict the number of retry attempts when a number is busy.)
"Call Blacklisted"	The device could not complete a call because the telephone number was blocked or reserved; emergency numbers such as 911 are blocked.
"Initializing"	The device is initializing a call.
"Offline"	The device is offline and unavailable.
"Ringing"	The device is ringing.
"Available"	The device is available.
"Aborting"	The device is aborting a fax job.
"Routing"	The device is routing a received fax document.
"Answered"	The device answered a new call.
"Handled"	The fax service processed the outbound fax document; the fax service provider will transmit the document.

Return Values

Returns an HRESULT value indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns a COM-defined error code.

You should not check directly for success or failure. Use the COM SUCCEEDED and FAILED macros instead.

Remarks

If the job is in the job queue waiting transmission, the fax server has not associated a device with the job. In this instance, the IFaxJob::get_DeviceStatus method returns an empty string.

The IFaxJob::get_DeviceStatus method allocates the memory required for the buffer pointed to by the pVal parameter. The client application must call the SysFreeString function to deallocate the resources associated with this parameter. For more information, see Freeing Fax Resources.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in faxcom.h.
  Import Library: Included as a resource in faxcom.dll.

See Also

Fax Service Client Application Programming Interface Overview, Fax Service Client API Interfaces, IFaxJob, IFaxJobs, SysFreeString