The following functions are provided by the Prosody data communications API:
| API call | W | Description |
|---|---|---|
| smdc_channel_config() | Configure a channel (or half a channel) for data communications | |
| smdc_line_control() | Perform a general control operation on a data communications channel | |
| smdc_line_control_v34() | Perform a general control operation on a V.34 data communications channel | |
| smdc_line_status() | Check general status on a data communications channel | |
| smdc_line_status_v34() | Check general status on a V.34 data communications channel | |
| smdc_rx_config_t38() | Configure a channel's input for T.38 data communications | |
| smdc_rx_config_v34() | Configure a channel's input for V.34 data communications | |
| smdc_rx_control() | Perform a control operation on the input half of a data communications channel | |
| smdc_rx_data() | Read data from a channel configured for data communications | |
| smdc_rx_encoding() | Configure the receive encoding used by a channel for data communications | |
| smdc_rx_status() | Check the status of the input half of a data communication channel. | |
| smdc_rx_status_t38() | Check the status of the input half of a T.38 data communication channel. | |
| smdc_rx_stop() | Stop the receive data communications protocol on a channel. | |
| smdc_stop() | Stop data communications protocols on a channel. | |
| smdc_tx_config_t38() | Configure a channel's output for T.38 data communications | |
| smdc_tx_config_v34() | Configure a channel's output for V.34 data communications | |
| smdc_tx_control() | Perform a control operation on the output half of a data communications channel | |
| smdc_tx_data() | Write data to a channel configured for data communications | |
| smdc_tx_encoding() | Configure the transmit encoding used by a channel for data communications | |
| smdc_tx_status() | Check the status of the output half of a data communication channel. | |
| smdc_tx_stop() | Stop the transmit data communications protocol on a channel. | |
| smdc_tx_tone_indicator_t38() | Sends a T.38 tone indicator on the output half of a T.38 data communication channel | |
| smdc_tx_v34_indicator_t38() | Sends a T.38 v34 indicator on the output half of a T.38 data communication channel | |
| smdc_tx_v34_line_control_t38() | Control a channel's output for V34 over T.38 data communications |
This document is also available as separate pages for each function.
int smdc_channel_config(struct smdc_channel_config_parms *configp)
typedef struct smdc_channel_config_parms {
tSMChannelId channel; /* in */
tSM_INT protocol; /* in */
tSM_INT config_length; /* in */
void *config_data; /* in */
tSM_INT encoding; /* in */
tSM_INT encoding_config_length; /* in */
void *encoding_config_data; /* in */
} SMDC_CHANNEL_CONFIG_PARMS;
Configures a channel (or half a channel) for data communications using a specified protocol and preparing it to transfer data encoded according to the encoding type over that protocol.
For details of what protocols and encodings are available, and the format of their configuration data, see the document Prosody Data Communcations Protocols and Encodings.
Channels can have two halves: an input half and an output half. A protocol may occupy either or both of these. It is possible to configure a channel for two protocols if one is input-only and the other is output-only. In that case the channel operates as if it were two separate channels, one for each direction.
The input half of a channel is reserved for this data communications configuration until smdc_rx_status() returns the status kSMDCRxStatusFinished. No other activity can take place on the input half of the channel during this time.
The output half of a channel is reserved for this data communications configuration until smdc_tx_status() returns the status kSMDCTxStatusFinished. No other activity can take place on the output half of the channel during this time.
While the output half of a channel is configured for data communications, a write event associated with this channel using sm_channel_set_event() will be set while the channel is ready to accept more data or there may be a status change to report. See smdc_tx_control() for details of how this works. When an application discovers that this event is set, it may check the status using smdc_tx_status(). However, an application may simply try smdc_tx_data() immediately and check status when it refuses to accept data.
While the input half of a channel is configured for data communications, a read event associated with this channel using sm_channel_set_event() will be set while the channel is ready to allow data to be read or there may be a status change to report. See smdc_rx_control() for details of how this works. When an application discovers that this event is set, it should attempt to read data using smdc_rx_data(). See its description to see how this interacts with status changes.
Requires firmware modules applicable to protocol and encoding to have been downloaded. See Prosody Data Communcations Protocols and Encodings
0 if call completed successfully, otherwise a standard error such as:
int smdc_line_control(struct smdc_line_control_parms *controlp)
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;
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.
0 if call completed successfully, otherwise a standard error such as:
int smdc_line_control_v34(struct smdc_line_control_v34_parms *controlp)
typedef struct smdc_line_control_v34_parms {
tSMChannelId channel; /* in */
enum kSMDCV34LineCtlCmd {
kSMDCV34LineCtlCmdRetrain,
kSMDCV34LineCtlCmdRenegotiateUp,
kSMDCV34LineCtlCmdRenegotiateDown,
kSMDCV34LineCtlCmdEnablePrimary,
kSMDCV34LineCtlCmdEnableControl,
kSMDCV34LineCtlCmdBitrateTx,
kSMDCV34LineCtlCmdBitrateRx,
} cmd; /* in */
union {
struct {
tSM_INT min_bitrate; /* in */
tSM_INT max_bitrate; /* in */
} bitrate; /* in */
} u; /* in */
} SMDC_LINE_CONTROL_V34_PARMS;
Perform a command on a channel which has been configured for V.34 data communications.
0 if call completed successfully, otherwise a standard error such as:
int smdc_line_status(struct smdc_line_status_parms *statusp)
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;
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.
ERR_SM_WRONG_CHANNEL_STATE.
0 if call completed successfully, otherwise a standard error such as:
int smdc_line_status_v34(struct smdc_line_status_v34_parms *statusp)
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;
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.
ERR_SM_WRONG_CHANNEL_STATE.
0 if call completed successfully, otherwise a standard error such as:
int smdc_rx_config_t38(struct smdc_rx_config_t38_parms *configp)
typedef struct smdc_rx_config_t38_parms {
tSMChannelId channel; /* in */
tSM_INT PreCorrigendum; /* in */
tSM_INT Protocol; /* in */
} SMDC_RX_CONFIG_T38_PARMS;
Configures a channel's input for data communications using the T.38 protocol.
The input half of a channel is reserved for this data communications configuration until smdc_rx_status_t38() returns the status kSMDCRxT38StatusFinished. No other activity can take place on the input half of the channel during this time.
While the input half of a channel is configured for data communications, a read event associated with this channel using sm_channel_set_event() will be set while the channel is ready to allow data to be read or there may be a status change to report. See smdc_rx_control() for details of how this works. When an application discovers that this event is set, it should attempt to read data using smdc_rx_data(). See its description to see how this interacts with status changes.
Requires the module ifprx to have been downloaded.
kSMDCT38ProtocolAll may be used to allow all received
data to be read. In this case,
smdc_rx_status_t38()
will report the protocol being received and all data read will be in
the appropriate format until a new protocol is reported.
0 if call completed successfully, otherwise a standard error such as:
int smdc_rx_config_v34(struct smdc_rx_config_v34_parms *configp)
typedef struct smdc_rx_config_v34_parms {
tSMChannelId channel; /* in */
enum kSMDCV34Duplex {
kSMDCV34HalfDuplex,
kSMDCV34FullDuplex,
} duplex; /* in */
tSM_INT min_bitrate; /* in */
tSM_INT max_bitrate; /* in */
tSM_INT v8fsk_metric; /* in */
} SMDC_RX_CONFIG_V34_PARMS;
Configures a channel's input for data communications using the V.34 protocol. The V.34 modem operates in a duplex manner (even when duplex is kSMDCV34HalfDuplex), so channel must be a full-duplex channel and its output half must also be configured using smdc_tx_config_v34().
The channel input is reserved for this data communications configuration until smdc_line_status_v34() returns the status kSMDCLinkStatusNotConnected. No other activity can take place on the channel during this time.
While the input half of a channel is configured for data communications, a read event associated with this channel using sm_channel_set_event() will be set while the channel is ready to allow data to be read or there may be a status change to report. See smdc_rx_control() for details of how this works. When an application discovers that this event is set, it should attempt to read data using smdc_rx_data(). See its description to see how this interacts with status changes.
Requires the module v34fdx to have been downloaded if configuring for full duplex operation.
Requires the module v34 to have been downloaded if configuring for half duplex operation.
0 if call completed successfully, otherwise a standard error such as:
int smdc_rx_control(struct smdc_rx_control_parms *controlp)
typedef struct smdc_rx_control_parms {
tSMChannelId channel; /* in */
enum kSMDCRxCtl {
kSMDCRxCtlDiscard,
kSMDCRxCtlNotifyOnData,
kSMDCRxCtlStop,
kSMDCRxCtlResume,
} cmd; /* in */
tSM_INT min_to_collect; /* in */
tSM_INT min_idle; /* in */
tSM_INT blocking; /* in */
} SMDC_RX_CONTROL_PARMS;
Performs a control operation on the input half of a data communications channel.
When the cmd field holds kSMDCRxCtlNotifyOnData, the values min_to_collect and min_idle configure the criteria used to determine when the input half of the channel is ready. There are two cases:
| min_idle | Meaning |
|---|---|
0 |
The channel is ready when at least min_to_collect octets of data are waiting. It ceases to be ready when the amount waiting falls below min_to_collect. |
T != 0 |
The channel is ready when any data can be
collected. Data becomes ready for collection when either
min_to_collect
octets of data are waiting, or data is waiting and no
further data has been received for a period of T mS.
|
Note that, although times can be specified to the nearest millisecond, the measurement of time is limited to the epoch period of the Prosody device.
When the input half of a channel is ready:
See also the document Prosody Data Communcations Protocols and Encodings for details of behaviour specific to individual protocols and encodings.
-256 means
that the threshold is reached when there is space available
for no more than 256 further octets.
See also the document Prosody
application note: considerations for data transfer
thresholds.
0 if call completed successfully, otherwise a standard error such as:
int smdc_rx_data(struct smdc_data_parms *datap)
typedef struct smdc_data_parms {
tSMChannelId channel; /* in */
char *data; /* in */
tSM_INT max_length; /* in */
tSM_INT done_length; /* out */
} SMDC_DATA_PARMS;
Attempt to read data from a channel whose input half has been configured for a data communications protocol. Less than the maximum will be read when either:
To permit maximum system throughput, this function refuses to read from a channel whose status has changed since it was last checked. This allows an application to avoid checking the status during bulk data transfer. The application only needs to check the status when a call to smdc_rx_data() returns with done_length equal to zero. This also ensures that status changes are reported at the point in the data at which they occurred, which may be important for some applications.
If an error is reported, the done_length field indicates the amount of data which was read before the error occurred.
Any amount of data (up to max_length) may be returned - even less than configured with the min_to_collect, parameter set with smdc_rx_control(), which only controls when the channel is declared ready. Once a channel is ready, it may remain so until all the data is read from it. This means that if the first read does not read all the data (i.e. the buffer supplied is too small), the next read will return immediately with more.
See also the document Prosody Data Communcations Protocols and Encodings for details of behaviour specific to individual protocols and encodings.
0 if call completed successfully, otherwise a standard error such as:
int smdc_rx_encoding(struct smdc_encoding_parms *encp)
typedef struct smdc_encoding_parms {
tSMChannelId channel; /* in */
tSM_INT encoding; /* in */
tSM_INT encoding_config_length; /* in */
void *encoding_config_data; /* in */
} SMDC_ENCODING_PARMS;
Configures the receive encoding for the input half of a channel which must have been already configured for data communications using smdc_channel_config().
For details of what encodings are available, and the format of their configuration data, see the document Prosody data communications Encodings.
0 if call completed successfully, otherwise a standard error such as:
int smdc_rx_status(struct smdc_rx_status_parms *statusp)
typedef struct smdc_rx_status_parms {
tSMChannelId channel; /* in */
tSM_INT available_octets; /* out */
enum kSMDCRxStatus {
kSMDCRxStatusEmpty,
kSMDCRxStatusData,
kSMDCRxStatusOverrun,
kSMDCRxStatusCarrier,
kSMDCRxStatusFinished,
kSMDCRxStatusSigMetric,
} status; /* out */
tSM_INT flow; /* out */
union {
struct {
tSM_INT carrier; /* out */
} carrier; /* out */
struct {
tSM_INT metric; /* out */
} metric; /* out */
} u; /* out */
} SMDC_RX_STATUS_PARMS;
Reports the status of a channel whose input half has been configured for data communications.
See also the document Prosody Data Communcations Protocols and Encodings for details of behaviour specific to individual protocols and encodings.
ERR_SM_WRONG_CHANNEL_STATE.
0 if call completed successfully, otherwise a standard error such as:
int smdc_rx_status_t38(struct smdc_rx_status_t38_parms *statusp)
typedef struct smdc_rx_status_t38_parms {
tSMChannelId channel; /* in */
tSM_INT available_octets; /* out */
enum kSMDCRxT38Status {
kSMDCRxT38StatusEmpty,
kSMDCRxT38StatusTone,
kSMDCRxT38StatusV34,
kSMDCRxT38StatusData,
kSMDCRxT38StatusOverrun,
kSMDCRxT38StatusCarrier,
kSMDCRxT38StatusFinished,
kSMDCRxT38StatusProtocol,
kSMDCRxT38StatusRate,
} status; /* out */
tSM_INT flow; /* out */
union {
struct {
enum kSMDCT38ToneType tone_type; /* out */
} tone; /* out */
struct {
enum kSMDCT38_V34Type {
kSMDCT38_V34Type_V34_CC_1200,
kSMDCT38_V34Type_V34_PRI_CHAN,
kSMDCT38_V34Type_V34_CC_RETRAIN,
} v34_type; /* out */
} v34; /* out */
struct {
tSM_INT carrier; /* out */
} carrier; /* out */
struct {
tSM_INT rate; /* out */
} rate; /* out */
struct {
tSM_INT protocol; /* out */
} protocol; /* out */
} u; /* out */
} SMDC_RX_STATUS_T38_PARMS;
Reports the status of a channel whose input half has been configured for T.38 data communications.
ERR_SM_WRONG_CHANNEL_STATE.
0 if call completed successfully, otherwise a standard error such as:
int smdc_rx_stop(struct smdc_stop_parms *pp)
typedef struct smdc_stop_parms {
tSMChannelId channel; /* in */
} SMDC_STOP_PARMS;
This stops the receive protocol configured on a channel. Unlike the kSMDCLineCtlCmdDisconnect command of smdc_line_control(), this does not use any disconnection procedures of the protocol - it simply stops immediately. It is intended for situations where there is no need to disconnect properly, such as when call control indicates that the remote party has cleared the call.
When the input half of a channel has stopped, smdc_rx_status() returns the status kSMDCRxStatusFinished.
See also the document Prosody Data Communcations Protocols and Encodings for details of behaviour specific to individual protocols and encodings.
0 if call completed successfully, otherwise a standard error such as:
int smdc_stop(struct smdc_stop_parms *pp)
typedef struct smdc_stop_parms {
tSMChannelId channel; /* in */
} SMDC_STOP_PARMS;
This stops any protocol configured on a channel. If the input half and the output half are configured with independent protocols, both are stopped. Unlike the kSMDCLineCtlCmdDisconnect command of smdc_line_control(), this does not use any disconnection procedures of the protocols - it simply stops immediately. It is intended for situations where there is no need to disconnect properly, such as when call control indicates that the remote party has cleared the call.
This function is equivalent to calling both smdc_rx_stop() and smdc_tx_stop() on the channel, except that it does not report an error if only one half of the channel is configured with a protocol.
When the input half of a channel has stopped, smdc_rx_status() returns the status kSMDCRxStatusFinished. When the output half of a channel has stopped smdc_tx_status() returns the status kSMDCTxStatusFinished.
See also the document Prosody Data Communcations Protocols and Encodings for details of behaviour specific to individual protocols and encodings.
0 if call completed successfully, otherwise a standard error such as:
int smdc_tx_config_t38(struct smdc_tx_config_t38_parms *configp)
typedef struct smdc_tx_config_t38_parms {
tSMChannelId channel; /* in */
tSM_INT PreCorrigendum; /* in */
tSM_INT Protocol; /* in */
tSM_UT32 max_packet_length; /* in */
} SMDC_TX_CONFIG_T38_PARMS;
Configures a channel's output for data communications using the T.38 protocol.
The output half of a channel is reserved for this data communications configuration until smdc_tx_status() returns the status kSMDCTxStatusFinished. No other activity can take place on the output half of the channel during this time.
While the output half of a channel is configured for data communications, a write event associated with this channel using sm_channel_set_event() will be set while the channel is ready to allow data to be written or there may be a status change to report. See smdc_tx_control() for details of how this works. When an application discovers that this event is set, it should attempt to write data using smdc_tx_data(). See its description to see how this interacts with status changes.
The max_packet_length field is used to restrict the size of the IFP packet data produced by the channel. A value of zero will cause the maximum size to be the maximum permitted by the firmware, as will any value above that maximum.
Requires the module ifptx to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
int smdc_tx_config_v34(struct smdc_tx_config_v34_parms *configp)
typedef struct smdc_tx_config_v34_parms {
tSMChannelId channel; /* in */
enum kSMDCV34Mode {
kSMDCV34ModeOriginating,
kSMDCV34ModeAnswering,
} mode; /* in */
enum kSMDCV34Polling {
kSMDCV34ModeNormal,
kSMDCV34ModePolling,
} polling; /* in */
enum kSMDCV34Duplex duplex; /* in */
tSM_INT min_bitrate; /* in */
tSM_INT max_bitrate; /* in */
} SMDC_TX_CONFIG_V34_PARMS;
Configures a channel's output for data communications using the V.34 protocol. The V.34 modem operates in a duplex manner (even when duplex is kSMDCV34HalfDuplex), so channel must be a full-duplex channel and its input half must also be configured using smdc_rx_config_v34().
The channel output is reserved for this data communications configuration until smdc_line_status_v34() returns the status kSMDCLinkStatusNotConnected. No other activity can take place on the channel during this time.
While the output half of a channel is configured for data communications, a write event associated with this channel using sm_channel_set_event() will be set while the channel is ready to accept more data or there may be a status change to report. See smdc_tx_control() for details of how this works. When an application discovers that this event is set, it may check the status using smdc_tx_status(). However, an application may simply try smdc_tx_data() immediately and check status when it refuses to accept data.
Requires the module v34fdx to have been downloaded if configuring for full duplex operation.
Requires the module v34 to have been downloaded if configuring for half duplex operation.
0 if call completed successfully, otherwise a standard error such as:
int smdc_tx_control(struct smdc_tx_control_parms *controlp)
typedef struct smdc_tx_control_parms {
tSMChannelId channel; /* in */
enum kSMDCTxCtl {
kSMDCTxCtlDiscard,
kSMDCTxCtlNotifyOnCapacity,
kSMDCTxCtlNotifyOnEmpty,
kSMDCTxCtlNoNotifyOnEmpty,
kSMDCTxCtlFinish,
} cmd; /* in */
tSM_INT capacity; /* in */
tSM_INT blocking; /* in */
} SMDC_TX_CONTROL_PARMS;
Performs a control operation on the output half of a data communications channel.
If the cmd field holds kSMDCTxCtlNotifyOnCapacity, the criterion is set for determining when the output half of the channel is ready. A channel is ready when there is space to buffer the amount of data specified by capacity. It ceases to be ready when the space falls below this value. When the output half of a channel is ready:
See also the document Prosody Data Communcations Protocols and Encodings for details of behaviour specific to individual protocols and encodings.
-128 means that notification is to happen
when only 128 octets of data is waiting to be sent.
If it is zero, then any associated event will only be set when
smdc_tx_status()
needs to be called.
See also the document Prosody
application note: considerations for data transfer
thresholds.
0 if call completed successfully, otherwise a standard error such as:
int smdc_tx_data(struct smdc_data_parms *datap)
typedef struct smdc_data_parms {
tSMChannelId channel; /* in */
char *data; /* in */
tSM_INT max_length; /* in */
tSM_INT done_length; /* out */
} SMDC_DATA_PARMS;
Attempt to write data to a channel whose output half has been configured for a data commuications protocol. Less than the maximum will be written when either:
To permit maximum system throughput, this function refuses to write to a channel whose status has changed since it was last checked. This allows an application to avoid checking the status during bulk data transfer. The application only needs to check the status (using smdc_tx_status()) when a call to smdc_tx_data() returns with done_length equal to zero. If a status change occurs while writing data, done_length may indicate that some, but not all, of the data was written. In this case, the most convenient way for an application to react is often to note how much data has been sent, and to try to send more. Since the new attempt will indicate that no data was written, it means that the application does not need to have different cases to handle a status change at the beginning of the data buffer and a status change after a partial write.
See also the document Prosody Data Communcations Protocols and Encodings for details of behaviour specific to individual protocols and encodings.
0 if call completed successfully, otherwise a standard error such as:
int smdc_tx_encoding(struct smdc_encoding_parms *encp)
typedef struct smdc_encoding_parms {
tSMChannelId channel; /* in */
tSM_INT encoding; /* in */
tSM_INT encoding_config_length; /* in */
void *encoding_config_data; /* in */
} SMDC_ENCODING_PARMS;
Configures the transmit encoding for the output half of a channel which must have been already configured for data communications using smdc_channel_config().
For details of what encodings are available, and the format of their configuration data, see the document Prosody data communications Encodings.
0 if call completed successfully, otherwise a standard error such as:
int smdc_tx_status(struct smdc_tx_status_parms *statusp)
typedef struct smdc_tx_status_parms {
tSMChannelId channel; /* in */
tSM_INT capacity; /* out */
enum kSMDCTxStatus {
kSMDCTxStatusEmpty,
kSMDCTxStatusHasCapacity,
kSMDCTxStatusNoCapacity,
kSMDCTxStatusUnderrun,
kSMDCTxStatusFinishing,
kSMDCTxStatusFinished,
} status; /* out */
tSM_INT flow; /* out */
} SMDC_TX_STATUS_PARMS;
Report the status of the output half of a channel.
See also the document Prosody Data Communcations Protocols and Encodings for details of behaviour specific to individual protocols and encodings.
ERR_SM_WRONG_CHANNEL_STATE.
0 if call completed successfully, otherwise a standard error such as:
int smdc_tx_stop(struct smdc_stop_parms *pp)
typedef struct smdc_stop_parms {
tSMChannelId channel; /* in */
} SMDC_STOP_PARMS;
This stops the transmit protocol configured on a channel. Unlike the kSMDCLineCtlCmdDisconnect command of smdc_line_control(), this does not use any disconnection procedures of the protocol - it simply stops immediately. It is intended for situations where there is no need to disconnect properly, such as when call control indicates that the remote party has cleared the call.
When the output half of a channel has stopped smdc_tx_status() returns the status kSMDCTxStatusFinished.
See also the document Prosody Data Communcations Protocols and Encodings for details of behaviour specific to individual protocols and encodings.
0 if call completed successfully, otherwise a standard error such as:
int smdc_tx_tone_indicator_t38(struct smdc_tx_tone_indicator_t38_parms *tonep)
typedef struct smdc_tx_tone_indicator_t38_parms {
tSMChannelId channel; /* in */
enum kSMDCT38ToneType {
kSMDCT38ToneTypeCNG,
kSMDCT38ToneTypeCED,
kSMDCT38ToneTypeANSAM,
} tone_type; /* in */
} SMDC_TX_TONE_INDICATOR_T38_PARMS;
Sends a T.38 tone indicator on the output half of a T.38 data communication channel.
T.38 tone indicators must be sent before sending any T.38 data on a given channel.
0 if call completed successfully, otherwise a standard error such as:
int smdc_tx_v34_indicator_t38(struct smdc_tx_v34_indicator_t38_parms *tonep)
typedef struct smdc_tx_v34_indicator_t38_parms {
tSMChannelId channel; /* in */
enum kSMDCT38_V34Type v34_type; /* int */
} SMDC_TX_V34_INDICATOR_T38_PARMS;
Sends a T.38 v34 indicator on the output half of a T.38 data communication channel.
The T.38 V34_CC_1200 indicator is sent when a switch from primary channel to control channel is requested.
The T.38 V34_PRI_CHAN indicator is sent when a switch from control channel to primary channel is requested.
The T.38 V34_CC_RETRAIN indicator is sent when a new primary channel datarate is requested. This is usually followed by a T.38 data element with a field set to v34-pri-rate and the specific datarate.
0 if call completed successfully, otherwise a standard error such as:
int smdc_tx_v34_line_control_t38(struct smdc_tx_v34_line_control_t38_parms *configp)
typedef struct smdc_tx_v34_line_control_t38_parms {
tSMChannelId channel; /* in */
tSM_UT32 primary_bitrate; /* in */
} SMDC_TX_V34_LINE_CONTROL_T38_PARMS;
Configures a channel's output for data communications using the T.38 protocol.
The output half of a channel is reserved for this data communications configuration. The primary_bitrate returned from smdc_line_status_v34() may be used to configure the v34 t38 line control channel to the same bitrate.
0 if call completed successfully, otherwise a standard error such as:
These functions constitute the Prosody data communications API.