Prosody data communications: API: smdc_tx_control

Prototype Definition

int smdc_tx_control(struct smdc_tx_control_parms *controlp)

Parameters

*controlp

a structure of the following type:

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;

Description

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:

• a call to smdc_tx_data() will not block
• the associated event (if any) is signalled

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

Fields

channel

The data communication channel.

cmd

The operation to perform. One of these values:

kSMDCTxCtlDiscard

Attempt to discard all data which has been buffered but has not yet been sent.

kSMDCTxCtlNotifyOnCapacity

Set the parameter which controls when this output reports that there is capacity for more data. The value is taken from the capacity field. Also enable notification of the presence of capacity. The blocking indicator is also set from the blocking field.

kSMDCTxCtlNotifyOnEmpty

Reserved value.

kSMDCTxCtlNoNotifyOnEmpty

Reserved value.

kSMDCTxCtlFinish

Indicate that there is no more data to be sent and that the transmitter should cease transmission when it has sent any data currently buffered. The channel's tx status becomes kSMDCTxStatusFinishing and any associated event will no longer be set by space being available for more data. It is an error to attempt to send more data after using this command.

capacity

The capacity (in octets) for the notification threshold. Only valid when the cmd field is kSMDCTxCtlNotifyOnCapacity. If this value is greater than zero, notification occurs when that number of octets of space is available. If it is less than zero, notification occurs when the amount of buffered data falls below that value. For example, the value -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.

blocking

This field is currently ignored.

Returns

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

• ERR_SM_DEVERR - device error

This function is part of the Prosody data communications API.