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:
- ERR_SM_DEVERR - device error
- ERR_SM_BAD_PARAMETER - configured protocol does not support this command
This function is part of the Prosody data communications API.