Prosody data communications: API: smdc_line_status_v34

Prototype Definition

int smdc_line_status_v34(struct smdc_line_status_v34_parms *statusp)

Parameters

*statusp
a structure of the following type: 
typedef struct smdc_line_status_v34_parms {
	tSMChannelId channel;					/* in */
	enum kSMDCLinkStatus link_status;			/* out */
	enum kSMDCLineRxStatus rx_status;			/* out */
	enum kSMDCLineTxStatus tx_status;			/* out */
	tSM_INT control_bitrate;				/* out */
	tSM_INT primary_bitrate;				/* out */
	tSM_INT snr_status;					/* out */
	tSM_INT fdx_rx_bitrate;					/* out */
	tSM_INT fdx_tx_bitrate;					/* out */
} SMDC_LINE_STATUS_V34_PARMS;

Description

Reports the status of a channel used for data communications with the V.34 protocol. V.34 is a full-duplex modem so both the input and output halves of the channel must have been configured for data communications.

The field rx_status will indicate the 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.

The field tx_status will indicate 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.

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.
control_bitrate
In half-duplex mode, the currently-negotiated data rate of the control channel, in bits/second. This value will be zero before the rate has been negotiated, while the modem is in state kSMDCLinkStatusConnecting.
primary_bitrate
In half-duplex mode, the currently-negotiated data rate of the primary channel, in bits/second. This value will be zero before the rate has been negotiated, while the modem is in state kSMDCLinkStatusConnecting.
snr_status
A value representing the signal-to-noise ratio on the line, as an arbitrary integer representing quality. Numbers less than zero indicate a low SNR and indicate that it may be advisable to reduce the data rate. Numbers greater than zero indicate that the data rate could be safely increased.
fdx_rx_bitrate
In full-duplex mode, the currently-negotiated receive data rate of the primary channel, in bits/second. This value will be zero before the rate has been negotiated, while the modem is in state kSMDCLinkStatusConnecting.
fdx_tx_bitrate
In full-duplex mode, the currently-negotiated transmit data rate of the primary channel, in bits/second. This value will be zero before the rate has been negotiated, while the modem is in state kSMDCLinkStatusConnecting.

Returns

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

This function is part of the Prosody data communications API.