FAX_DEV_STATUS structure (faxdev.h)

The FAX_DEV_STATUS structure contains status and identification information about an individual active fax operation.

Syntax

typedef struct _FAX_DEV_STATUS {
  DWORD  SizeOfStruct;
  DWORD  StatusId;
  DWORD  StringId;
  DWORD  PageCount;
  LPWSTR CSI;
  LPWSTR CallerId;
  LPWSTR RoutingInfo;
  DWORD  ErrorCode;
  DWORD  Reserved[3];
} FAX_DEV_STATUS, *PFAX_DEV_STATUS;

Members

SizeOfStruct

Type: DWORD

Specifies the size, in bytes, of the FAX_DEV_STATUS structure. Before responding to the FaxDevReportStatus function, the FSP must set this member to sizeof(FAX_DEV_STATUS).

StatusId

Type: DWORD

Specifies a fax status code or value. This can be a predefined fax status code (shown following), one of the TAPI LINEERR_ Constants error codes, or a value that the FSP defines. If the status identifier is provider-defined, the FSP must also supply a value for the StringId member. Following are the predefined fax status codes.

The fax status codes FS_BAD_ADDRESS, FS_CALL_BLACKLISTED and FS_USER_ABORT will result in no retry attempts. The fax status code FS_LINE_UNAVAILABLE will result in an immediate retry attempt in the case when the line is unavailable because the service lost the connection to the device (TAPI sent LINE_CLOSE, and the FSP reported FS_LINE_UNAVAILABLE). The retry depends on whether the device is detected back online. All other fax status codes will result in allowing the fax service to manage retry attempts.

StringId

Type: DWORD

Specifies a string resource identifier for the StatusId member if the StatusId is provider-defined. The fax service loads the string from the FSP's image. If StatusId contains a provider-defined status code or value, this member is required. If StatusId contains a predefined status code or value, this member is ignored.

PageCount

Type: DWORD

Specifies the number of the page in the fax transmission that the FSP is receiving. The page count is relative to one.

CSI

Type: LPWSTR

Pointer to a null-terminated Unicode character string that specifies an identifier of the remote fax device that is connected with the current call to either the FaxDevReceive or FaxDevSend function.

If the operation is sending a fax, the identifier specifies the CSID of the remote device; if the operation is receiving a fax, the identifier specifies the TSID of the remote device.

CallerId

Type: LPWSTR

Pointer to a null-terminated Unicode character string that identifies the calling device that sent the received fax document. This string can include the telephone number of the calling device.

RoutingInfo

Type: LPWSTR

Pointer to a null-terminated Unicode character string that specifies the routing string for an inbound fax. The string must be of the form:

Canonical-Phone-Number[|Additional-Routing-Info]

where Canonical-Phone-Number is defined in the Address topic of the TAPI documentation (see the Canonical Address subheading); and Additional-Routing-Info is the subaddress of a Canonical Address, and uses the subaddress format.

For DID routing, append the specific DID digits to the telephone number prefix. The DID address must be the canonical telephone number that corresponds to the fully qualified telephone number that the sender would have dialed.

If there is additional routing information, for example, subaddressing or DTMF tones, separate it from the canonical telephone number by a vertical bar character as indicated in the TAPI specification. You can specify multiple recipients.

For more information, see the Dialable Address and Canonical Address subheadings in the Address topic of the TAPI documentation.

ErrorCode

Type: DWORD

Specifies one of the Win32 System Error Codes [Base] that the FSP should use to report an error that occurs. The FSP should set this value to NO_ERROR when it is running and after a fax job completes normally.

Reserved[3]

Type: DWORD

This member is reserved by Microsoft. It must be set to zero.

Remarks

The FSP must either set all of the members of the FAX_DEV_STATUS structure to the status information for the active fax operation, or set them to zero.

The fax service allocates the memory for the strings pointed to by the CSI, CallerId and RoutingInfo members. The size of the memory the service allocates is equal to sizeof(FAX_DEV_STATUS) + FAXDEVREPORTSTATUS_SIZE. The FSP must place the strings in the block of memory that immediately follows the FAX_DEV_STATUS structure. The CSI, CallerId and RoutingInfo members must point to the location of the strings in the memory block.

Requirements

See also

Fax Service Provider Structures

FaxDevReceive

FaxDevReportStatus

FaxDevSend

Using the Fax Service Provider API