Prosody generic: API: sm_channel_alloc

This function is only in Prosody version 1 (but see the conversion guide for further details, including a facility that emulates it).

Prototype Definition

int sm_channel_alloc(struct sm_channel_alloc_parms *channelp)

Parameters

*channelp
a structure of the following type: 
typedef struct sm_channel_alloc_parms {
	tSMChannelId channel;					/* out */
	enum kSMChannelType type;				/* in */
	tSM_INT firmware_id;					/* in */
	tSM_INT group;						/* inout */
	tSM_INT caps_mask;					/* in */
} SM_CHANNEL_ALLOC_PARMS;

Description

Allocates, from among all free speech processing resources, a new channel to generate output data and/or process input data. The type parameter determines which kind of channel is allocated.

If the call completes successfully, the parameter channel will be set to an identifier for that channel.

The task of supporting this channel may be assigned by the driver to any module which has a suitable unused timeslot. However if the firmware_id is set to a non-zero firmware identifier (such as may be specified on firmware download to a module), the channel will be assigned to a module running that type of firmware. This feature allows an application to specify that channels should be allocated to a module capable of running a particular algorithm.

Normally the group parameter is set to zero. However when conferencing features are going to be used, it is essential that all the channels participating in a conference be processed by the same module (this is also the case for replay on one channel being combined with a background signal from another). This is achieved by associating channels with groups, all channels in the same group being processed by the same module. For a new group of channels, group should be set to -1, on return it will have been assigned a non-zero group identifier for the new group of channels. To associate a channel with an existing group, group must be set to an identifier previously obtained from a previous call to sm_channel_alloc().

Normally the caps_mask parameter is set to zero. However, if only a subset of the capabilities provided by the firmware for the input channel is needed, then caps_mask should be set with bits indicating the actual capabilities required. Using this parameter may enable the driver to allocate resources more efficiently. The following bits may be set in caps_mask for an output channel:

Capability Bit Use
kSMChannelCapsWriteDataAbility Application can playback to channel

The following bits may be set in caps_mask for an input channel:

Capability Bit Use
kSMChannelCapsReadDataAbility Application can record from channel
kSMChannelCapsRecogAbility Application can recognise tones and digits on channel

Half duplex and full duplex channels may have bits from both the above set in caps_mask. Other firmware specific capability bits may be defined, see firmware specific API documentation.

Fields

channel (Only in Prosody version 1)
The allocated channel.
type (Only in Prosody version 1)
The type of channel to allocate.
One of these values:
kSMChannelTypeInput
An input channel, which can be used to record data, recognise digits and tones etc.
kSMChannelTypeOutput
An output channel, which can be used to replay data, generate tones, dial DTMF digits etc.
kSMChannelTypeHalfDuplex
A channel that may operate either in input mode or in output mode (but not both simultaneously, except for DTMF detection).
Only on Prosody version 2 (TiNG): Resources required by a channel are allocated only as soon as they are needed, so there is no advantage in using a half-duplex channel over a full-duplex channel, and since it is typically more complicated for an application to handle half-duplex channels than full-duplex channels, it is recommended that full-duplex channels always be used in preference to half-duplex channels.
kSMChannelTypeFullDuplex
A channel that may operate both in input mode and in output mode (simultaneous input and output possible).
firmware_id (Only in Prosody version 1)
The firmware id of suitable modules where the channel may be allocated, or zero if any module is acceptable.
group (Only in Prosody version 1)
The group in which the channel must be allocated (or zero for any group). This field is always set to the channel's group on return.
caps_mask (Only in Prosody version 1)
Bitmask of required capabilities, or zero to indicate that the default capabilities are required.

Returns

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

This function is part of the Prosody generic API.