Prosody data communications: API: smdc_line_status

Prototype Definition

int smdc_line_status(struct smdc_line_status_parms *statusp)

Parameters

*statusp
a structure of the following type: 
typedef struct smdc_line_status_parms {
	tSMChannelId channel;					/* in */
	enum kSMDCLinkStatus {
		kSMDCLinkStatusNotConnected,
		kSMDCLinkStatusConnecting,
		kSMDCLinkStatusConnected,
		kSMDCLinkStatusDisconnecting,
	} link_status;						/* out */
	enum kSMDCLineRxStatus {
		kSMDCRxStatusNoCarrier,
		kSMDCRxStatusCarrierPresent,
		kSMDCRxStatusReceivingData,
	} rx_status;						/* out */
	enum kSMDCLineTxStatus {
		kSMDCTxStatusSilent,
		kSMDCTxStatusSendingCarrier,
		kSMDCTxStatusSendingData,
	} tx_status;						/* out */
	tSM_INT tx_cts;						/* out */
} SMDC_LINE_STATUS_PARMS;

Description

This function is deprecated in favour of using smdc_rx_status() and smdc_tx_status().

Reports the status of a channel used for data communications. If its input half has not been configured for data communications, then the field rx_status will contain the value kSMDCRxStatusNoCarrier, otherwise it indicates status of the input half of the channel. Note that it is not normally appropriate to distinguish between kSMDCRxStatusCarrierPresent and kSMDCRxStatusReceivingData since protocols can typically switch between them very quickly and the system only reports approximately to avoid the status changing very rapidly.

If the channel's output half has not been configured for data communications, then the field tx_status will contain the value kSMDCTxStatusSilent, otherwise it indicates the output half status. Note that it is not normally appropriate to distinguish between kSMDCTxStatusSendingCarrier and kSMDCTxStatusSendingData since protocols can typically switch between them very quickly and the system only reports approximately to avoid the status changing very rapidly.

The overall channel status is reported in link_status. Where the input half and output half have been configured with independent protocols, the status is reported as kSMDCLinkStatusConnected if either is connected. The status kSMDCLinkStatusNotConnected is reported only if both have finished data communications.

See also the document Prosody Data Communcations Protocols and Encodings for details of behaviour specific to individual protocols and encodings.

Fields

channel
The channel which has been configured for data communications.
link_status
The channel status. One of these values:
kSMDCLinkStatusNotConnected
The channel has finished with data communications. When this status is reported, the channel reverts to the idle state that it was in before smdc_channel_config() was used. Therefore it can be re-configured or used for another purpose and a subsequent call to smdc_line_status() will report the error ERR_SM_WRONG_CHANNEL_STATE.
kSMDCLinkStatusConnecting
Channel is waiting to connect. Either the appropriate command (kSMDCLineCtlCmdInitiatorConnect or kSMDCLineCtlCmdResponderConnect) has not yet been used in a call to smdc_line_control() or the connection handshake procedures have not yet completed.
kSMDCLinkStatusConnected
Connection handshake procedures have been completed or are not applicable.
kSMDCLinkStatusDisconnecting
The channel is in the process of disconnecting.
rx_status
One of these values:
kSMDCRxStatusNoCarrier
The input half is not receiving a meaningful signal.
kSMDCRxStatusCarrierPresent
The input half is receiving a meaningful signal, but it does not contain data.
kSMDCRxStatusReceivingData
The input half is receiving a meaningful signal, and it contains data.
tx_status
One of these values:
kSMDCTxStatusSilent
The output half is not sending any signal.
kSMDCTxStatusSendingCarrier
The output half is sending a signal which does not contain data (e.g. a carrier or framing pattern).
kSMDCTxStatusSendingData
The output half is sending a signal which contains data.
tx_cts
Indicator of whether the transmitter is ready to transmit (non-zero) or not (zero).

Returns

0 if call completed successfully, otherwise a standard error such as:

This function is part of the Prosody data communications API.