Prosody data communications: API: smdc_line_control

Prototype Definition

int smdc_line_control(struct smdc_line_control_parms *controlp)

Parameters

*controlp
a structure of the following type: 
typedef struct smdc_line_control_parms {
	tSMChannelId channel;					/* in */
	enum kSMDCLineCtlCmd {
		kSMDCLineCtlCmdInitiatorConnect,
		kSMDCLineCtlCmdResponderConnect,
		kSMDCLineCtlCmdDisconnect,
		kSMDCLineCtlCmdAssertRTS,
		kSMDCLineCtlCmdUnassertRTS,
		kSMDCLineCtlCmdSetAux,
		kSMDCLineCtlCmdSetPrefixSuffix,
		kSMDCLineCtlCmdSuspend,
		kSMDCLineCtlCmdResume,
		kSMDCLineCtlCmdResumeMonitorCarrier,
		kSMDCLineCtlCmdRetrain,
	} cmd;							/* in */
	tSM_UT32 aux_mask;					/* in */
	tSM_UT32 aux_toggle;					/* in */
	tSM_UT32 shorttrain;					/* in */
	tSM_INT tep;						/* in */
	tSM_UT32 prefix_bitlength;				/* in */
	tSM_UT32 *prefix_data;					/* in */
	tSM_UT32 suffix_bitlength;				/* in */
	tSM_UT32 *suffix_data;					/* in */
	tSM_UT32 retrain_speed;					/* in */
} SMDC_LINE_CONTROL_PARMS;

Description

Perform a command on the halves of a channel which have been configured for data communications. If the channel has been configured with independent input and output halves, the operation requested by cmd is performed separately on both. It is an error to attempt to perform a command on a protocol which does not implement it.

If a protocol has an auxiliary configuration value, the aux_mask and aux_toggle fields are used by the kSMDCLineCtlCmdSetAux command to modify this value as shown in this table:

bit in aux_mask bit in aux_toggle effect on configuration bit
0 0 clear it
0 1 set it
1 0 leave it unchanged
1 1 invert it

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.
cmd
The control operation to perform. One of these values:
kSMDCLineCtlCmdInitiatorConnect
Initiate the connection handshake required by the configured protocol. If the protocol distinguishes between an originator (or caller) and a responder (or answerer), then act as the originator.
kSMDCLineCtlCmdResponderConnect
For a protocol which distinguishes between an originator (or caller) and a responder (or answerer), initiate the connection handshake acting as responder.
kSMDCLineCtlCmdDisconnect
Initiate the disconnection procedures for the configured protocol.
kSMDCLineCtlCmdAssertRTS
For a protocol which uses a carrier or equivalent mechanism, turn on the carrier. If there is more than one way to do this (e.g. a long or a short training sequence) then the field shorttrain selects the one to use. If a protocol specification requires RTS to be used, the Prosody implementation may provide automatic RTS. Automatic RTS control is triggered when data is presented for transmission without RTS being asserted. The protocol acts as if RTS had been asserted, sends the data, and acts as if RTS was then deasserted.
kSMDCLineCtlCmdUnassertRTS
For a protocol which uses a carrier or equivalent mechanism, turn off the carrier. The effect of this command is delayed while the transmitter sends data which is queued.
kSMDCLineCtlCmdSetAux
For a protocol which has auxiliary configuration, modify the current configuration value by ANDing with aux_mask and XORing aux_toggle.
kSMDCLineCtlCmdSetPrefixSuffix
Set the bit patterns to be used as a prefix and a suffix on transmissions. The prefix is set to prefix_bitlength bits of data at prefix_data and the suffix is set to suffix_bitlength bits of data at suffix_data. These are arbitrary sequences of bits which are added when the normal data has been encoded and, therefore, are not affected by the type of encoding in use. The prefix is sent as soon as the protocol is ready to transmit (which is typically when the kSMDCLineCtlCmdAssertRTS command is issued), and the suffix is sent just before the carrier is turned off (which is typically when the kSMDCLineCtlCmdUnassertRTS command is issued). If a protocol has no RTS control, the prefix is sent as soon as possible, and the suffix is never sent. If the protocol permits RTS to be turned on automatically when data is ready to be sent, then the prefix is sent as soon as there is data ready to be sent and the suffix is sent when there is no remaining data to be sent. See the documentation for each protocol to determine which protocols support this feature. Requires the module prefsuf.
kSMDCLineCtlCmdSuspend
Suspend modem receiver. The modem no longer processes the incoming signal. This command is only valid for the modem types which state they support it.
kSMDCLineCtlCmdResume
Resume modem receiver. The modem must have been suspended with kSMDCLineCtlCmdSuspend and it now resumes processing the incoming signal. Typically, this allows the modem to make use of a shorter training sequence as some of the signal analysis saved when the modem was suspended can be re-used.
kSMDCLineCtlCmdResumeMonitorCarrier
Resume modem receiver but only for purposes of monitoring signal following a previous loss of synchronisation. The modem must have been suspended with kSMDCLineCtlCmdSuspend when the previous loss of carrier occurred and it is now resumed but solely to monitor the nature/energy of following signal. The application will notified with a carrier on and carrier off notification if what looks like an additional segment of modem modulated signal is present - so an application can determine where modem modulated signal ended following any dropout. Demodulated data will not be supplied. Typically, this allows the application to avoid a timeout following a fax modem dropout. The modem must be suspended again, using kSMDCLineCtlCmdSuspend, before kSMDCLineCtlCmdResume is used to resume wait for a shorter training sequence.
kSMDCLineCtlCmdRetrain
Initiate a modem retrain. This command is only valid for the modem types which state they support it.
aux_mask
A bitmask used with the kSMDCLineCtlCmdSetAux command.
aux_toggle
A bitmask used with the kSMDCLineCtlCmdSetAux command.
shorttrain
Select whether the protocol should use short training (non-zero) or long training (zero). Only valid when the cmd field is kSMDCLineCtlCmdAssertRTS.
tep
Indicator of whether the transmitter should use Talker Echo Protection tone (non-zero) or not (zero). Only valid when the cmd field is kSMDCLineCtlCmdAssertRTS.
prefix_bitlength
The number of bits in the prefix. Must be zero or a multiple of 8. Only valid when the cmd field is kSMDCLineCtlCmdSetPrefixSuffix.
prefix_data
The prefix to be used with transmission. Only valid when the cmd field is kSMDCLineCtlCmdSetPrefixSuffix. The data is sent least significant bit first, and any extra bits in the last word are ignored.
suffix_bitlength
The number of bits in the suffix. Must be zero or a multiple of 8. Only valid when the cmd field is kSMDCLineCtlCmdSetPrefixSuffix.
suffix_data
The suffix to be used with transmission. Only valid when the cmd field is kSMDCLineCtlCmdSetPrefixSuffix. The data is sent least significant bit first, and any extra bits in the last word are ignored.
retrain_speed
The speed to retrain to. Only valid when the cmd field is kSMDCLineCtlCmdRetrain.

Returns

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

This function is part of the Prosody data communications API.