Prosody data communications: API: smdc_rx_control

Prototype Definition

int smdc_rx_control(struct smdc_rx_control_parms *controlp)

Parameters

*controlp
a structure of the following type: 
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;

Description

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 at least min_to_collect octets of data are waiting. It is also ready when any data arrives, followed by a period of T mS in which no data arrives. The channel ceases to be ready when the amount waiting falls to zero (i.e. when all the data has been read).

Note that, although times can be specified to the nearest millisecond, the measurement of time is limited by the host operating system. For example, on Unix systems the timer often measures hundreths of a seond (10mS), so a protocol which receives one byte at regular millisecond intervals would appear to receive 10 bytes in zero time, followed by an idle period of 10mS. Additionally, data transferred by Prosody is handled in batches with a granularity of 8mS, so this is the best accuracy that can be achieved even if the host has a finer granularity timer.

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.

Fields

channel
The data communication channel.
cmd
The operations to perform. One of these values:
kSMDCRxCtlDiscard
Discard any buffered data not yet collected.
kSMDCRxCtlNotifyOnData
Set the criteria for determining when the input half of the channel is ready.
kSMDCRxCtlStop
Use any flow control mechanism available in the configured protocol to stop the incoming data flow.
kSMDCRxCtlResume
Use any flow control mechanism available in the configured protocol to resume the incoming data flow.
min_to_collect
Channel ready threshold (in octets). The input half of the channel is ready when at least this much data is buffered. This field is only used when the cmd field holds kSMDCRxCtlNotifyOnData. If this value is negative, it represents the amount of space remaining. For example, the value -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.
min_idle
Channel ready timeout (in mS). This field is only used when the cmd field holds kSMDCRxCtlNotifyOnData. The value zero indicates that no timer is to be used.
blocking
Indicator of whether smdc_rx_data() should block if it attempts to read data when the channel is not ready. A non-zero value indicates that the function should block until the channel is ready. The value zero indicates that it should return immediately indicating that no data was read. Only valid when the cmd field is kSMDCRxCtlNotifyOnData. [Not currently implemented - reserved for future use]

Returns

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

This function is part of the Prosody data communications API.