C language API > Server and device status

Server and device status

Details of the status of the server and the configured devices and links may be obtained using the ZfxGetServerStatusEx function. It is passed a structure of type ZFSERVERSTATUSEX which defines what information is required. The structure includes the addresses of three further structures of type ZFSERVERINFOEX, ZFDEVICEINFOEX and ZFLINKINFOEX, which are used to return the information.

Below you will find information on:

Server information	Server status
Device information	Device status
Link information	Link status

Server status

Field	Description
ServerInfoExSize	Should be set to sizeof(ZFSERVERINFOEX)
IpServerInfoEx	Address of a SERVERINFOEX structure, to be filled on return
MaxDevices	Maximum number of device entries to be returned (i.e. number of elements in the DeviceInfo array)
lpNumDevices	Address of short integer variable used to return the number of devices in the file. Note: that the returned value may be larger than the value given for MaxDevices if the buffer was not large enough for all entries.
DeviceInfoEx	Size Should be set to sizeof(ZFDEVICEINFOEX)
IpDeviceInfoEx	Address of array of 'n' ZFDEVICEINFOEX structures, where 'n' is the value given by the MaxDevices parameter.
MaxLinks	Maximum number of LCR link entries to be returned (ie number of elements in the LinkInfoEx array)
lpNumLinks	Address of short integer variable used to return the number of links in the file. Note that the returned value may be larger than the value given for MaxLinks if the buffer was not large enough for all entries.
LinkInfoExSize	Should be set to sizeof(ZFLINKINFOEX)
lpLinkInfoEx	Address of array of 'n' ZFLINKINFOEX structures, where 'n' is the value given by the MaxLinks parameter.

Server information

The fields in the ZFSERVERINFOEX structure are as follows:

Field	Description
Queue	Deferred Number of items in queue waiting until a given time (excluding those waiting before retrying after failure).
QueueWaitingResend	Number of items in queue waiting before retrying after a send attempt has failed.
QueueWaitingConvert	Number of items in queue waiting to be converted (prepared for sending).
QueueConverting	Number of items in queue being converted (prepared for sending) - currently either 0 or 1.
QueueWaitingDevice	Number of items in queue waiting for a device to become available
QueueSending	Number of send requests in queue being processed by a device - either connecting or sending.
QueueScanning	Number of scan requests items in queue being processed by a scanning device.
QueueSubRouter	Number of items submitted to Router for sending, and awaiting acceptance by a remote server.
QueueAcceptRemote	Number of items currently accepted for sending by remote servers

Device information

The fields in the ZFDEVICEINFOEX structure are as follows:

Field	Description
szDevice	Name of the device. Device names comprise a device type and device number, separated by a hyphen (eg "FCLASS-3"). Two devices of different types can have the same number. The maximum length of this string (excluding terminating NULL) is given by the constant ZFDEV_NAME_LEN.
Status	Current status of the device. This is a variable of ZFDEVSTATUS, and the value is one of the ZFDEV_??? values listed below.
szUser	User name of owner of message currently being processed by the device (or null string if no message being processed). The maximum length of this string (excluding terminating NULL) is given by the constant ZFUSER_NAME_LEN.
szMsgBody	Body name of message CONTROL file currently being processed by the device (or null string if no message being processed).
NumPages	Number of pages in message currently being processed (including coversheet if used)
CurrentPage	Page number currently being sent.
NumConnect Fails	Number of send attempts by this device which have failed to connect.
NumSendFails	Number of send attempts by this device which have failed after connection.
NumSentOK	Number of messages sent successfully by the device.

Device status

The following list gives the possible status values for a device (variable of type ZFDEVSTATUS).

Field	Description
ZFDEV_UNKNOWN_STATE	Status unknown (eg not initialized yet). This could also occur if an API program is run with a later version of the Zetafax server which supports additional device states.
ZFDEV_IDLE	Ready for sending
ZFDEV_ERROR	Trying to recover from error
ZFDEV_FAILED	Unable to recover from error. The device status changes to ZFDEV_FAILED when the device is unable to recover from a status of ZFDEV_ERROR (generally after a fixed period of time).
ZFDEV_OFFLINE	Device set offline by user, and unavailable for sending
ZFDEV_BUSY	Generally busy, and unavailable for sending
ZFDEV_WAITING_CONNECT	Waiting for connection (for fax messages, this is the status between dialing the fax number and completing the fax handshake). Note that for dialed calls, the connection time starts from when the modem reports that the remote device has answered the call - the device status will generally be ZFDEV_WAITING_CONNECT for several seconds after this.
ZFDEV_SENDING	Connected to the remote device and sending the message.
ZFDEV_RECEIVING	Receiving an incoming message
ZFDEV_POLL_SEND	Not supported
ZFDEV_POLL_RECEIVE	Not supported
ZFDEV_WAITING_SCAN_ DOC	For scanning requests, waiting for the document to be scanned to be placed on the device.
ZFDEV_SCANNING	Not supported
ZFDEV_INCOMING_CALL	Answering an incoming call - state will change to ZFDEV_RECEIVING once the correct handshaking has occurred

Link information

The fields in the ZFLINKINFOEX structure are as follows:

Field	Description
szRemoteServer	Name of the remote server to which the link is configured. The maximum length of this string (excluding terminating NULL) is given by the constant ZFDEV_NAME_LEN.
RemoteLinkStatus	Current status of the remote server on the link. This is a variable of type ZFLINKSTATUS, and the value is one of the ZFLINK_??? values listed below.
LocalLinkStatus	Current status of the local server on the link. This is a variable of type ZFLINKSTATUS, and the value is one of the ZFLINK_??? values listed below.
fConnectionOK	Current status of the connection (mail or WAN) to the remote server. This is a Boolean value, 1 for a good connection, 0 for no connection.
fLinkActive	This is a Boolean value indicating whether the link is active, and available for sending and receiving (1 if the link is active, 0 if the link is not active). This value is computed from RemoteLinkStatus, LocalLinkStatus and fConnectionOK fields.
NumSentOK	Number of messages sent successfully by the remote server.
NumTimedOut	Number of messages timed out waiting for responses over the link.
NumRejected	Number of messages rejected by the remote server.
NumDeviceError	Number of messages failed to be sent by the remote server as a result of device errors.
NumRemoteServerErr	Number of messages failed to be sent by the remote server as a result of other errors at the remote server.
NumUnack	Number of messages submitted to the remote server and still awaiting acknowledgement.
NumAck	Number of messages submitted to the remote server and acknowledged.
NumReceived	Number of messages received from the remote server for sending locally.

Link status

The following list gives the possible status values for a link (variable of type ZFLINKSTATUS).

Field	Description
ZFLINK_UNKNOWN_STATE	Remote link status unknown. This occurs when the Zetafax server has not received any communication from the remote server.
ZFLINK_INITIALISING	Link is currently being initialised.
ZFLINK_ONLINE	Link is online.
ZFLINK_OFFLINE	Link has been set to offline by the administrator, and is unavailable for sending.
ZFLINK_FAILED_WDOG	The link watchdog failed to receive an expected message.
ZFLINK_SHUTDOWN	The link has been shut down.
ZFLINK_UNRECOGNISED_STATE	Unrecognised state. This could occur if an API program is run with a later version of the Zetafax server which supports additional link states.