The following functions are provided by the Prosody generic API:
| API call | W | Description |
|---|---|---|
| sm_channel_alloc_placed() | Allocate a channel on a specific module | |
| sm_channel_collector_connect() | Connect a collector to a channel | |
| sm_channel_datafeed_connect() | Connect a datafeed to a channel | |
| sm_channel_dispatcher_connect() | Connect a channel to a dispatcher | |
| sm_channel_get_datafeed() | Obtain a datafeed from an output channel | |
| sm_channel_info() | Get channel information so data can be switched through to it | |
| sm_channel_input_data_redirect() | Redirect the data received by an input channel to a datafeed | |
| sm_channel_output_source_datafeed_connect() | Provide alternative source data to an output channel | |
| sm_channel_release() | Release a previously allocated channel | |
| sm_channel_set_event() | Associate event with specific/any channel | |
| sm_channel_set_output_rate() | Configure the sample rate for a channel's output | |
| sm_close_module() | Close a Prosody module | |
| sm_close_prosody() | Closes a card, finishing potential use with Prosody. | |
| sm_collector_destroy() | Destroy a data collector | |
| sm_collector_get_event() | Obtain an event for a collector | |
| sm_collector_status() | Determine collector status | |
| sm_dispatcher_destroy() | Destroy a data dispatcher | |
| sm_error_name() | Generate a name from an error code | |
| sm_get_card_info() | Return information about card hosting one or more modules | |
| sm_get_card_rev() | Return information about card hardware revision | |
| sm_get_channel_type() | Determine channel type | |
| sm_get_driver_info() | Return driver version information | |
| sm_get_module_info() | Determine if firmware running, obtain module workload | |
| sm_get_stream_info() | Return information about a TDM stream associated with a module | |
| sm_module_get_event() | Obtain an event for a module | |
| sm_module_status() | Report the status of a Prosody module connection | |
| sm_open_module() | Open a Prosody module | |
| sm_sec_module() | Configure module for API related traffic to be encrypted | |
| sm_shutdown_module() | Initiate the closing of a Prosody module | |
| sm_switch_channel_input() | Switch data from TDM timeslot to channel | |
| sm_switch_channel_output() | Switch channel data to TDM timeslot | |
| sm_tdmrx_create() | Create a TDM[rx] endpoint | |
| sm_tdmrx_destroy() | Destroy a previously allocated TDM[rx] | |
| sm_tdmrx_get_datafeed() | Obtain a datafeed from a TDM[rx] | |
| sm_tdmtx_create() | Create a TDM[tx] endpoint | |
| sm_tdmtx_datafeed_connect() | Connect a datafeed to a TDM[tx] | |
| sm_tdmtx_destroy() | Destroy a previously allocated TDM[tx] | |
| sm_udp_collector_create() | Create a UDP data collector | |
| sm_udp_dispatcher_create() | Create a UDP data dispatcher | |
| smd_ev_create() | Create operating system event for channel | |
| smd_ev_free() | Free previously created operating system event | |
| smd_ev_wait() | Wait for notification of operating system event | |
| sm_config_module_switching() | D | Control assignment of channels to external bus timeslots |
| sm_get_card_switch_id() | D | Determine switch driver associated with card |
| sm_get_channel_ix() | D | Map channel identifier to integer |
| sm_get_channel_module_id() | D | Return the module on which a channel is located. |
| sm_get_firmware_info() | D | Determine what firmware has been downloaded. |
| sm_get_module_card_id() | D | Return the card on which a module is located. |
| sm_reset_module() | D | Hardware reset a module |
Key to W column:
| D | Deprecated |
|---|
This document is also available as separate pages for each function.
int sm_channel_alloc_placed(struct sm_channel_alloc_placed_parms *channelp)
typedef struct sm_channel_alloc_placed_parms {
tSMChannelId channel; /* out */
enum kSMChannelType {
kSMChannelTypeInput,
kSMChannelTypeOutput,
kSMChannelTypeHalfDuplex,
kSMChannelTypeFullDuplex,
} type; /* in */
tSMModuleId module; /* in */
tSM_INT caps_mask; /* in */
} SM_CHANNEL_ALLOC_PLACED_PARMS;
Allocates, on a specific module, 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 the identifier for that channel.
The task of supporting this channel is assigned by the driver to the module specified by the module parameter.
The caps_mask parameter is ignored.
0 if call completed successfully, otherwise a standard error such as:
int sm_channel_collector_connect(struct sm_channel_collector_connect_parms *dp)
typedef struct sm_channel_collector_connect_parms {
tSMCollectorId source; /* in */
tSMChannelId channel; /* in */
} SM_CHANNEL_COLLECTOR_CONNECT_PARMS;
Connects a collector to an output channel, replacing the
previous collector connected to it. The
source
must be a collector created by a call to
sm_udp_collector_create().
or the value kSMNullCollectorId.
The output channel,
channel,
will use data collector as its source of
data (e.g. for replay or transmit operations).
There must be no operation in progress (e.g. replay) on the output half of the channel when this function is called.
The default collector for a channel is
kSMNullCollectorId, which collects data through the API
(e.g. via
smdc_tx_data()).
0 if call completed successfully, otherwise a standard error such as:
int sm_channel_datafeed_connect(struct sm_channel_datafeed_connect_parms *datafeedp)
typedef struct sm_channel_datafeed_connect_parms {
tSMDatafeedId data_source; /* in */
tSMChannelId channel; /* in */
} SM_CHANNEL_DATAFEED_CONNECT_PARMS;
Connects a datafeed to an input channel. The
data_source
must be a datafeed obtained a call to any of the
*_get_datafeed() functions.
The input channel,
channel,
will receive any data that is generated by the object from which
data_source
was derived.
To disconnect a channel from a datafeed, specify
kSMNullDatafeedId as the tSMDatafeedId in
data_source.
Requires the module datafeed to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
int sm_channel_dispatcher_connect(struct sm_channel_dispatcher_connect_parms *dp)
typedef struct sm_channel_dispatcher_connect_parms {
tSMDispatcherId dest; /* in */
tSMChannelId channel; /* in */
} SM_CHANNEL_DISPATCHER_CONNECT_PARMS;
Connects an input channel to a dispatcher, replacing the
previous dispatcher connected to it. The
dest
must be a dispatcher created by a call to
sm_udp_dispatcher_create().
or the value kSMNullDispatcherId.
The input channel,
channel,
will use data dispatcher to pass on data it produces
(e.g. for record or receive operations).
There must be no operation in progress (e.g. record) on the input half of the channel when this function is called.
The default dispatcher for a channel is
kSMNullDispatcherId, which dispatches data through
the API (e.g. via
smdc_rx_data()).
0 if call completed successfully, otherwise a standard error such as:
int sm_channel_get_datafeed(struct sm_channel_datafeed_parms *datafeedp)
typedef struct sm_channel_datafeed_parms {
tSMChannelId channel; /* in */
tSMDatafeedId datafeed; /* out */
} SM_CHANNEL_DATAFEED_PARMS;
Request a datafeed identifier from an output channel. This identifer
can subsequently be used in a call to any of the
*_datafeed_connect() functions
to connect the output from the channel to a destination.
It is valid until the channel is released.
Datafeed connections can only be made between objects allocated
on the same tSMModuleId.
Requires the module datafeed to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
int sm_channel_info(struct sm_channel_info_parms *infop)
typedef struct sm_channel_info_parms {
tSMChannelId channel; /* in */
tSM_INT card; /* out */
tSM_INT ost; /* out */
tSM_INT ots; /* out */
enum kSMTimeslotType otype; /* out */
tSM_INT ist; /* out */
tSM_INT its; /* out */
enum kSMTimeslotType itype; /* out */
tSM_INT group; /* out */
tSM_INT caps_mask; /* out */
} SM_CHANNEL_INFO_PARMS;
This call allows an application to locate a previously allocated speech processing resource so that a data can be switched through to it by means of a call to the Aculab switch driver API.
If
channel
is an identifier for a previously allocated
input, half-duplex, or full-duplex channel, then the parameters
ist,
and
its
returned by this call
may be assigned to the ost and ots
parameters of a switch driver CONNECT_MODE call to
sw_set_output, with <ist, its> in the OUTPUT_PARMS
parameter block being set to the source of the data to be
processed by the channel.
If channel is an identifier for a previously allocated output, half-duplex, or full-duplex channel, then the parameters ost, and ots returned by this call may be assigned to the ist and its parameters of a switch driver CONNECT_MODE call to sw_set_output with <ost, ots> int the OUTPUT_PARMS parameter block being set to the destination for data to be generated by the channel.
The parameter card is an obsolete parameter set to the value -1
The parameter group is an obsolete parameter set to the value zero.
The parameter caps_mask is an obsolete parameter set to the value zero.
0 if call completed successfully, otherwise a standard error such as:
int sm_channel_input_data_redirect(struct sm_channel_input_data_redirect_parms *redp)
typedef struct sm_channel_input_data_redirect_parms {
tSMChannelId channel; /* in */
tSM_INT enable; /* in */
tSMDatafeedId datafeed; /* out */
} SM_CHANNEL_INPUT_DATA_REDIRECT_PARMS;
When
enable
is non-zero, request a datafeed identifier from an input channel that
will carry the data usually retrieved through the api (e.g.
sm_get_recorded_data()
). This identifer can subsequently be used in a call to any of the
*_datafeed_connect() functions to connect the input data
from the channel to a destination. Note though that the data will be
raw octets and not audio data, so the destination must be expecting
raw octets. The identifier is valid until the channel is released or
this function is called with
enable
set to zero.
There must be no operation in progress (e.g. record) on the input half of the channel when this function is called.
Datafeed connections can only be made between objects allocated
on the same tSMModuleId.
Requires the modules datafeed and redirect to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
int sm_channel_output_source_datafeed_connect(struct sm_channel_output_source_datafeed_connect_parms *outsrcp)
typedef struct sm_channel_output_source_datafeed_connect_parms {
tSMChannelId channel; /* in */
tSMDatafeedId data_source; /* in */
tSM_INT threshold; /* in */
tSM_INT timeout; /* in */
} SM_CHANNEL_OUTPUT_SOURCE_DATAFEED_CONNECT_PARMS;
Connects a datafeed to an output channel. The output channel will use the datafeed as its source of data (e.g. for replay or transmit operations).
The data can be buffered before being made available to the output channel for processing. The buffer will wait until it has either threshold octets of data, or timeout milliseconds have passed since data was last provided to the buffer, before allowing the output channel to process the data. This buffering is repeated if the buffer underruns.
There must be no operation in progress (e.g. replay) on the output half of the channel when this function is called.
Datafeed connections can only be made between objects allocated
on the same tSMModuleId.
Requires the modules datafeed and redirect to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
int sm_channel_release(tSMChannelId channel)
Releases previously allocated channel. All resources used by the channel are freed. Any operations in progress on the channel are aborted. It is an error to attempt to refer to a channel which has been released.
0 if call completed successfully, otherwise a standard error such as:
int sm_channel_set_event(struct sm_channel_set_event_parms *eventp)
typedef struct sm_channel_set_event_parms {
tSMChannelId channel; /* in */
tSM_INT event_type; /* in */
tSM_INT issue_events; /* in */
tSMEventId event; /* in */
} SM_CHANNEL_SET_EVENT_PARMS;
This call may be used to control read/write and/or recognition event notification for channels.
Channel associated events must be allocated through a call to smd_ev_create().
In general an application can hibernate in an operating system specific way waiting for data activity on specific channels, or on any channel.
A channel may have events associated with reading data, writing data and recognition. The event_type parameter should be set to the type required as follows:
| Type | Associated with |
|---|---|
| kSMEventTypeReadData | Recording of data |
| kSMEventTypeWriteData | Replay of data, dial completion, tone generation |
| kSMEventTypeRecog | Recognition of tone, digit etc |
To enable channel specific event notification for a particular
channel, set
channel
to the required channel,
issue_events
to kSMChannelSpecificEvent, and
event
to an operating system specific event handle.
To specify the event to be used when waiting for
read/write/recognition activity on any channel, set
channel
to kSMNullChannelId,
issue_events
to kSMAnyChannelEvent, and
event
to an operating system specific event handle. To disable further
use of this event make the same call but with
issue_events
set to kSMChannelNoEvent.
To enable "any channel" event notification for a
particular channel, set
channel
to the required channel,
issue_events
to kSMAnyChannelEvent, the
event
parameter is not used.
To disable read/write/recognition event notification for a
particular channel, set
channel
to the required channel, and
issue_events
to kSMChannelNoEvent.
By default, no events are associated with a channel.
kSMEventTypeReadData,
kSMEventTypeWriteData, or
kSMEventTypeRecog.
kSMChannelNoEvent,
kSMChannelSpecificEventNonIdle,
kSMChannelSpecificEvent, or
kSMAnyChannelEvent.
0 if call completed successfully, otherwise a standard error such as:
int sm_channel_set_output_rate(struct sm_channel_set_output_rate_parms *ratep)
typedef struct sm_channel_set_output_rate_parms {
tSMChannelId channel; /* in */
tSM_INT sample_rate; /* in */
} SM_CHANNEL_SET_OUTPUT_RATE_PARMS;
Configures the sample rate (in samples per second) to be used by the output half of a channel.
The sample rate should be configured before using the channel for any operation (such as replay) which depends on it. otherwise it will default to 8000 samples per second.
If a channel is connected to a timeslot using sm_switch_channel_output() the sample rate must be 8000, whether set explicitly or allowed to default to 8000.
0 if call completed successfully, otherwise a standard error such as:
int sm_close_module(struct sm_close_module_parms *closep)
typedef struct sm_close_module_parms {
tSMModuleId module_id; /* in */
} SM_CLOSE_MODULE_PARMS;
Closes a Prosody module that was opened with sm_open_module(). Note that this function only releases any resources allocated by sm_open_module() and does not tidy up other resources connected with the module which may have been allocated by other API functions or the application. It is a serious error to close a module on which there are open channels.
0 if call completed successfully, otherwise a standard error.
int sm_close_prosody(struct sm_close_prosody_parms *closep)
typedef struct sm_close_prosody_parms {
tSMCardId card_id; /* in */
} SM_CLOSE_PROSODY_PARMS;
Reverses the effect of sm_open_prosody_x(), or sm_open_prosody_s_v3(). If, after closing the card, you want to use Prosody API functions which refer to this card you must invoke sm_open_prosody_x(), or sm_open_prosody_s_v3() again. It is a serious error to close a card on which there are open modules.
0 if call completed successfully, otherwise a standard error.
int sm_collector_destroy(tSMCollectorId collector)
Destroys collector invalidating the tSMCollectorId.
0 if call completed successfully, otherwise a standard error such as:
int sm_collector_get_event(struct sm_collector_event_parms *eventp)
typedef struct sm_collector_event_parms {
tSMCollectorId collector; /* in */
tSMEventId event; /* out */
} SM_COLLECTOR_EVENT_PARMS;
If the call completes successfully event will hold the tSMEventId belonging to collector. The tSMEventId is valid until the collector is destroyed using sm_collector_destroy(). This event will be signalled when a status change occurs on the collector. When the event is signalled the user must call sm_collector_status() to discover the nature of the status change.
0 if call completed successfully, otherwise a standard error such as:
int sm_collector_status(struct sm_collector_status_parms *statusp)
typedef struct sm_collector_status_parms {
tSMCollectorId collector; /* in */
enum kSMCollectorStatus {
kSMCollectorStatusRunning,
kSMCollectorStatusGotPorts,
kSMCollectorStatusNewPeer,
kSMCollectorStatusGotPortsIPv6,
kSMCollectorStatusNewPeerIPv6,
} status; /* out */
union {
struct {
struct in_addr address; /* out */
int port; /* out */
} ports; /* out */
struct {
struct in_addr address; /* out */
int port; /* out */
} peer; /* out */
struct {
struct in6_addr address; /* out */
int port; /* out */
} ports_ipv6; /* out */
struct {
struct in6_addr address; /* out */
int port; /* out */
} peer_ipv6; /* out */
} u; /* out */
} SM_COLLECTOR_STATUS_PARMS;
Returns the current status of the collector or an error to indicate that an error has occurred.
When the collector event, obtained from sm_collector_get_event(), is signalled the user must call this function to determine the nature of the status change. The change in status may indicate that an error occurred whilst processing a user request or it may be notifiying the user of a change to the previous state of the collector.
0 if call completed successfully, otherwise a standard error such as:
int sm_dispatcher_destroy(tSMDispatcherId dispatcher)
Destroys dispatcher invalidating the tSMDispatcherId.
0 if call completed successfully, otherwise a standard error such as:
char *sm_error_name(struct sm_error_name_parms *errp)
typedef struct sm_error_name_parms {
tSM_INT code; /* in */
char name[80]; /* out */
} SM_ERROR_NAME_PARMS;
Generates a name for the supplied Prosody error code. The name is one of the standard names, unless the error code is unrecognised, in which case a suitable representation is used.
Returns the address of the name field in the supplied parameter structure. This allows the function return value to be used as a parameter to another function call. For example:
printf("Error calling sm_replay_start(): %s\n", sm_error_name(&e));
Since this is never null, it can be safely used immediately. .
int sm_get_card_info(struct sm_card_info_parms *cardinfop)
typedef struct sm_card_info_parms {
tSMCardId card; /* in */
enum kSMCarrierCardType {
kSMCarrierCardTypeYetUnknown,
kSMCarrierCardTypeISAS2,
kSMCarrierCardTypeBR4,
kSMCarrierCardTypeBR8,
kSMCarrierCardTypePCIP1,
kSMCarrierCardTypePCIC1,
kSMCarrierCardTypePS,
kSMCarrierCardTypePX,
} card_type; /* out */
tSM_INT card_detected; /* out */
tSM_INT module_count; /* out */
tSM_UT32 physical_address; /* out */
tSM_UT32 io_address; /* out */
tSM_UT32 physical_irq; /* out */
char serial_no[kSMMaxSerialNoText]; /* out */
} SM_CARD_INFO_PARMS;
Retrieves information about card hosting Prosody modules installed in system.
On return, card_type will be set to one of the following values:
| Card Type | Use |
|---|---|
| kSMCarrierCardTypeYetUnknown | Card type not yet determined by driver. |
| kSMCarrierCardTypeISAS2 | Obsolete card. |
| kSMCarrierCardTypeBR4 | Obsolete card. |
| kSMCarrierCardTypeBR8 | Obsolete card. |
| kSMCarrierCardTypePCIP1 | Obsolete card. |
| kSMCarrierCardTypePCIC1 | Obsolete card. |
| kSMCarrierCardTypePS | Prosody S virtual 'card' |
| kSMCarrierCardTypePX | Prosody X card |
The parameter card_detected is obsolete.
The number of modules detected on the card is returned in module_count.
The parameters physical_address , io_address , and physical_irq are obsolete.
Some carrier cards have a machine readable serial number. For such cards the serial number is returned as a zero terminated text string in the character array serial_no.
0 if call completed successfully, otherwise a standard error such as:
int sm_get_card_rev(struct sm_card_rev_parms *cardrevp)
typedef struct sm_card_rev_parms {
tSMCardId card; /* in */
tSM_INT rev[8]; /* out */
char rev_additional[kSMMaxRevAddText]; /* out */
} SM_CARD_REV_PARMS;
Obsolete call - not applicable to Prosody X or Prosody S.
0 if call completed successfully, otherwise a standard error such as:
int sm_get_channel_type(tSMChannelId channel)
Given a channel identifier, channel, returns its type as was specified for sm_channel_alloc_placed() type parameter when channel allocated.
Channel type value (greater than or equal to zero) if call completed successfully, otherwise a standard error such as:
int sm_get_driver_info(struct sm_driver_info_parms *drvinfop)
typedef struct sm_driver_info_parms {
tSM_INT major; /* out */
tSM_INT minor; /* out */
tSM_INT step; /* out */
tSM_INT custom; /* out */
tSM_INT quality; /* out */
tSM_INT buildno0; /* out */
tSM_INT buildno1; /* out */
} SM_DRIVER_INFO_PARMS;
Retrieves information about TiNG library version controlling Prosody modules installed in system.
On return, the parameters
major,
minor
and
step
will be set to the values X, Y, and
Z respectively of the three element version no. for
the library X.Y.Z.
The custom parameter will be set to a non-zero value if the driver build is a custom special build of the driver for a specific customer.
The quality parameter will be set to one of the following character values:
| Quality | Character |
|---|---|
| 'B' | Beta quality version |
| 'T' | Test version |
| 'D' | Development (or alpha quality) version |
| 'I' | Released version |
The buildno0 and buildno1 parameters are for Aculab use only. However, note that it is essential to include these two parameters when describing the version to Aculab support staff.
0 if call completed successfully, otherwise a standard error such as:
int sm_get_module_info(struct sm_module_info_parms *moduleinfop)
typedef struct sm_module_info_parms {
tSMModuleId module; /* in */
tSM_INT firmware_running; /* out */
tSM_INT firmware_id; /* out */
tSM_INT average_loading; /* out */
tSM_INT max_loading; /* out */
tSM_INT module_slot; /* out */
tSM_INT min_stream; /* out */
tSM_INT stream_count; /* out */
} SM_MODULE_INFO_PARMS;
Fetches information about a module. Note that fields apart from module_slot , min_stream and stream_count are undefined for Prosody S and for Prosody X. The cpumon facility should be used to obtain work load information.
0 if call completed successfully, otherwise a standard error such as:
int sm_get_stream_info(struct sm_stream_info_parms *streaminfop)
typedef struct sm_stream_info_parms {
tSMModuleId module; /* in */
tSM_INT stream; /* in */
char serial_no[kSMMaxSerialNoText]; /* out */
tSM_INT serial_port_ix; /* out */
tSM_INT timeslot_count; /* out */
} SM_STREAM_INFO_PARMS;
Retrieves information about a TDM stream associated with ProsodyS virtual card and provided by a thin TDM interface card installed in system.
On entry the parameter stream indicates module TDM stream for which information is required. On return the parameter serial_no indicates serial number of thin TDM interface card, serial_port_ix indicates stream index (starting from zero) relative to that thin TDM interface card. timeslot_count indicates number of timeslots in stream.
0 if call completed successfully, otherwise a standard error such as:
int sm_module_get_event(struct sm_module_event_parms *eventp)
typedef struct sm_module_event_parms {
tSMModuleId module_id; /* in */
tSMEventId event; /* out */
} SM_MODULE_EVENT_PARMS;
If the call completes successfully event will hold the tSMEventId belonging to module_id. The tSMEventId is valid until the module is closed using sm_close_module(). This event will be signalled when a status change occurs on the module. When the event is signalled the user must call sm_module_status() to discover the nature of the status change.
0 if call completed successfully, otherwise a standard error such as:
int sm_module_status(struct sm_module_status_parms *statusp)
typedef struct sm_module_status_parms {
tSMModuleId module_id; /* in */
enum kSMModuleStatus {
kSMModuleStatusRunning,
kSMModuleStatusShutdown,
} status; /* out */
} SM_MODULE_STATUS_PARMS;
Reports the status of a Prosody module connection that was opened with sm_open_module(). Card types that use asynchronous control methods may block in sm_close_module(). After using sm_shutdown_module() to initiate the closing of a module, this function will report a status of kSMModuleStatusShutdown when sm_close_module() will not block.
0 if call completed successfully, otherwise a standard error.
int sm_open_module(struct sm_open_module_parms *module_parmsp)
typedef struct sm_open_module_parms {
tSMCardId card_id; /* in */
tSM_UT32 module_ix; /* in */
tSMModuleId module_id; /* out */
} SM_OPEN_MODULE_PARMS;
Opens a specified Prosody module.
0 if call completed successfully, otherwise a standard error such as:
int sm_sec_module(struct sm_sec_module_parms *module_parmsp)
typedef struct sm_sec_module_parms {
tSMModuleId module_id; /* in */
tSM_INT exclude_data_to_module; /* in */
tSM_INT exclude_data_from_module; /* in */
tSM_INT key_id; /* in */
char *context; /* in */
tSMSecCallback encdec; /* in */
} SM_SEC_MODULE_PARMS;
Sets up encrypted communication with module. Must be used in conjunction with a compatible external encryption library, for example kmlib3des. If encryption is required, this function must be invoked immediately after calling sm_open_module(). Requires an encryption capable kernel to be running on the module.
0 if call completed successfully, otherwise a standard error such as:
int sm_shutdown_module(struct sm_shutdown_module_parms *shutdownp)
typedef struct sm_shutdown_module_parms {
tSMModuleId module_id; /* in */
} SM_SHUTDOWN_MODULE_PARMS;
Initiates the closing of a Prosody module that was opened with sm_open_module(). Card types that use asynchronous control methods may block in sm_close_module(). This function initiates the close procedure and does not block. The resources used are not released until sm_close_module() is called, which may still block unless sm_module_status() has reported a status of kSMModuleStatusShutdown. It is a serious error to close a module on which there are open channels.
0 if call completed successfully, otherwise a standard error.
int sm_switch_channel_input(struct sm_switch_channel_parms *switchp)
typedef struct sm_switch_channel_parms {
tSMChannelId channel; /* in */
tSM_INT st; /* in */
tSM_INT ts; /* in */
enum kSMTimeslotType type; /* in */
} SM_SWITCH_CHANNEL_PARMS;
Assigns (or de-assigns) a timeslot to channel. The same timeslot may be used as input to several channels.
This function can be used with Prosody X cards in TDM only applications for backward compatibility. For new applications it is recommended that sm_tdmrx_create() and sm_tdmrx_get_datafeed() be used. To use this function with a Prosody X card the module datafeed must be downloaded.
0 if call completed successfully, otherwise a standard error such as:
int sm_switch_channel_output(struct sm_switch_channel_parms *switchp)
typedef struct sm_switch_channel_parms {
tSMChannelId channel; /* in */
tSM_INT st; /* in */
tSM_INT ts; /* in */
enum kSMTimeslotType type; /* in */
} SM_SWITCH_CHANNEL_PARMS;
Assigns (or de-assigns) a timeslot to channel. No timeslot can be used as output by more than one channel at a time.
This function can be used with Prosody X cards in TDM only applications for backward compatibility. For new applications it is recommended that sm_tdmtx_create() and sm_tdmtx_datafeed_connect() be used. To use this function with a Prosody X card the module datafeed must be downloaded.
0 if call completed successfully, otherwise a standard error such as:
int sm_tdmrx_create(struct sm_tdmrx_create_parms *tdmrxp)
typedef struct sm_tdmrx_create_parms {
tSMTDMrxId tdmrx; /* out */
tSMModuleId module; /* in */
tSM_INT stream; /* in */
tSM_INT timeslot; /* in */
enum kSMTimeslotType type; /* in */
} SM_TDMRX_CREATE_PARMS;
Allocates, on a specific module, a new TDM[rx] to receive incoming TDM data. The TDM[rx] will receive it's data from the specified stream and timeslot. The streams which can be used with this call depend on the type of Prosody carrier card being used. They are special internal streams which are only accessible to Prosody and the switch driver. All data received by the tdmrx can be read from its datafeed. The datafeed may be obtained using sm_tdmrx_get_datafeed().
If the call completes successfully, the parameter tdmrx will be set to the identifier for that tdmrx.
On Prosody X this function requires the module datafeed to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
int sm_tdmrx_destroy(tSMTDMrxId tdmrx)
Destroys tdmrx and invalidates the tSMTDMrxId.
0 if call completed successfully, otherwise a standard error such as:
int sm_tdmrx_get_datafeed(struct sm_tdmrx_datafeed_parms *datafeedp)
typedef struct sm_tdmrx_datafeed_parms {
tSMTDMrxId tdmrx; /* in */
tSMDatafeedId datafeed; /* out */
} SM_TDMRX_DATAFEED_PARMS;
Request a datafeed identifier from a TDM[rx]. This identifer can
subsequently be used in a call to any of the
*_datafeed_connect() functions except
sm_tdmtx_datafeed_connect().
It is valid until the TDM[rx] is destroyed.
Datafeed connections can only be made between objects allocated
on the same tSMModuleId.
Requires the module datafeed to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
int sm_tdmtx_create(struct sm_tdmtx_create_parms *tdmtxp)
typedef struct sm_tdmtx_create_parms {
tSMTDMtxId tdmtx; /* out */
tSMModuleId module; /* in */
tSM_INT stream; /* in */
tSM_INT timeslot; /* in */
enum kSMTimeslotType type; /* in */
} SM_TDMTX_CREATE_PARMS;
Allocates, on a specific module, a new TDM[tx] to send TDM data. The TDM[tx] will send it's data to the specified stream and timeslot. The streams which can be used with this call depend on the type of Prosody carrier card being used. They are special internal streams which are only accessible to Prosody and the switch driver. The tdmtx will begin sending data when it has been succesfully connected to a valid datafeed using sm_tdmtx_datafeed_connect().
If the call completes successfully, the parameter tdmtx will be set to the identifier for that tdmtx.
0 if call completed successfully, otherwise a standard error such as:
int sm_tdmtx_datafeed_connect(struct sm_tdmtx_datafeed_connect_parms *datafeedp)
typedef struct sm_tdmtx_datafeed_connect_parms {
tSMDatafeedId data_source; /* in */
tSMTDMtxId tdmtx; /* in */
} SM_TDMTX_DATAFEED_CONNECT_PARMS;
Connects a datafeed to a TDM[tx]. The
data_source
must be a datafeed obtained from any of the
*_get_datafeed() functions except
sm_tdmrx_get_datafeed().
The TDM[tx]
tdmtx
will receive any data that is generated by the output task from which
data_source
was derived.
To disconnect a TDM[tx] from a datafeed, specify
kSMNullDatafeedId as the tSMDatafeedId in
data_source
Requires the module datafeed to have been downloaded.
0 if call completed successfully, otherwise a standard error.
int sm_tdmtx_destroy(tSMTDMtxId tdmtx)
Destroys tdmtx and invalidates the tSMTDMtxId.
0 if call completed successfully, otherwise a standard error such as:
int sm_udp_collector_create(struct sm_udp_collector_create_parms *dp)
typedef struct sm_udp_collector_create_parms {
tSMCollectorId collector; /* out */
tSMModuleId module; /* in */
enum kSMCollectorType {
kSMCollectorTypeIPv4,
kSMCollectorTypeIPv6,
} type; /* in */
struct in_addr address; /* in */
struct in6_addr ipv6_address; /* in */
} SM_UDP_COLLECTOR_CREATE_PARMS;
Allocates, on a specific module, a new UDP collector to receive incoming UDP data. If the call completes successfully, the parameter collector will be set to the identifier for that collector.
A collector is automatically allocated a port number for incoming UDP data, this information may be obtained from sm_collector_status().
This requires the module fromudp to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
int sm_udp_dispatcher_create(struct sm_udp_dispatcher_create_parms *dp)
typedef struct sm_udp_dispatcher_create_parms {
tSMDispatcherId dispatcher; /* out */
tSMModuleId module; /* in */
enum kSMDispatcherType {
kSMDispatcherTypeIPv4,
kSMDispatcherTypeIPv6,
} type; /* in */
SOCKADDR_IN destination; /* in */
SOCKADDR_IN source; /* in */
int TOS; /* in */
SOCKADDR_IN6 destination_ipv6; /* in */
SOCKADDR_IN6 source_ipv6; /* in */
} SM_UDP_DISPATCHER_CREATE_PARMS;
Allocates, on a specific module, a new UDP dispatcher to transmit data. If the call completes successfully, the parameter dispatcher will be set to the identifier for that dispatcher.
This requires the module toudp to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
int smd_ev_create(tSMEventId *eventId, tSMChannelId channelId, int eventType, int eventChannelBinding)
kSMEventTypeReadData,
kSMEventTypeWriteData, or
kSMEventTypeRecog.
kSMChannelSpecificEvent,
kSMChannelSpecificEventNonIdle, or
kSMAnyChannelEvent.
Creates an operating system event object suitable for use with
a specific channel indicated by
channelId
(the parameter
eventChannelBinding
must be set to kSMChannelSpecificEvent in this
case) or, alternatively, creates an operating system event object for
collective use by all nominated channels (in which case
channelId
must be set to kSMNullChannelId and
eventChannelBinding
to kSMAnyChannelEvent).
An application which waits on a channel-specific event will be woken whenever the channel is ready for servicing. This includes whenever an operation on the channel may have a status change to report, as well as whenever there is no operation in progress on the channel (because the channel is ready to start a new operation).
An application which waits on an 'any channel' event will be woken when any of the channels which have been associated with that event are ready for servicing. In this case a channel which has no operation in progress is not considered to be ready for servicing. This is because 'any channel' events are provided for backward compatibility with Prosody version 1, which had this behaviour.
Note that an application may sometimes be woken even though no status change is found. This happens in certain cases where the API library discovers when checking the status that the change is not of a type appropriate to report to the application (which may be because it related to a facility not currently in use or because it is only for internal purposes within the library).
The eventType parameter indicates which type of event should be created, see sm_channel_set_event() API call description for more details.
An identifier for the new event object is stored in the location pointed at by eventId. You can wait on the event as described in smd_ev_wait().
0 if call completed successfully, otherwise a standard error such as:
int smd_ev_free(tSMEventId eventId)
Release operating system resources associated with use of event previously allocated by smd_ev_create().
0 if call completed successfully, otherwise a standard error such as:
int smd_ev_wait(tSMEventId eventId)
Wait until given event occurs.
Application developers may prefer to use the underlying operating system calls instead of this call, allowing them to exploit event wait timeouts, waiting for multiple events etc. The use of events on each operating system is described in Prosody events.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_config_module_switching(struct sm_config_module_sw_parms *configp)
typedef struct sm_config_module_sw_parms {
tSMModuleId module; /* in */
tSM_INT auto_assign_out_ts; /* in */
tSM_INT auto_assign_in_ts; /* in */
tSM_INT out_st0; /* in */
tSM_INT out_st1; /* in */
tSM_INT out_base_ts; /* in */
enum kSMTimeslotType {
kSMTimeslotTypeALaw,
kSMTimeslotTypeMuLaw,
kSMTimeslotTypeData,
} in_type; /* in */
tSM_INT in_st0; /* in */
tSM_INT in_st1; /* in */
tSM_INT in_base_ts; /* in */
enum kSMTimeslotType out_type; /* in */
} SM_CONFIG_MODULE_SW_PARMS;
Overrides default or configured assignment scheme used by driver to associate channels with timeslots on card external bus. The streams which can be used with this call depend on the type of Prosody carrier card being used. On the ISA Prosody card, the accessible streams are on the external bus (MVIP), while on other cards they are special internal streams which are only accessible to Prosody and the switch driver.
When a channel is allocated, it can have an associated external bus MVIP or SCbus timeslot automatically assigned to it. Alternatively, timeslot assignment may be left to the application which can call sm_switch_channel_output() or sm_switch_channel_input() following channel allocation to explicitly assign an external bus timeslot.
If output channel timeslots for module module are to be assigned by the application through calls to sm_switch_channel_output(), then auto_assign_out_ts must be set to zero.
If output channel timeslots for module module are to be automatically assigned, then auto_assign_out_ts must be set to 1 and the fields out_st0, out_st1 and out_base_ts must be set up to specify the external bus streams and timeslots to be assigned.
If SCbus external bus timeslots are to be assigned, out_st0 and out_st1 should both be set to 24 (the stream assigned to the SCbus) and out_base_ts should be set to the first SCbus timeslot to be assigned for this module.
If MVIP external bus timeslots are to be assigned, out_st0 and out_st1 should be set to DSo stream numbers (0..7) for the first 32 and second 32 timeslots assigned, and out_base_ts must be set to zero.
If input channel timeslots for module module are to be assigned by the application through calls to sm_switch_channel_input(), then auto_assign_in_ts must be set to zero.
If input channel timeslots for module module are to be automatically assigned, then auto_assign_in_ts must be set to 1 and the fields in_st0, in_st1 and in_base_ts must be set up to specify the external bus streams and timeslots to be assigned.
If SCbus external bus timeslots are to be assigned, in_st0 and in_st1 should both be set to 24 (the stream assigned to the SCbus) and in_base_ts should be set to the first SCbus timeslot to be assigned for this module.
If MVIP external bus timeslots are to be assigned, in_st0 and in_st1 should be set to DSi stream numbers (0..7) for the first 32 and second 32 timeslots assigned, and in_base_ts must be set to zero.
The use of automatic timeslot assignment is not recommended. It prevents the sharing of a timeslot between multiple channels (which is useful when debugging as it permits the recording of an input without interfering with normal processing of that input). Normally it is trivial to assign timeslots explicitly (for example, by deriving the timeslot number from some property of a call, such as the port and timeslot number of the call).
The use of automatic timeslot assignment is not supported on ProsodyS or ProsodyX.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_get_card_switch_id(tSMCardId card)
Given a Prosody carrier card, returns card ID for use in switch
driver API calls such as sw_set_output.
Note that this function is deprecated. It is present only to permit certain backward compatibility functionality to be implemented, should not be used by applications, and shall eventually be withdrawn from the API.
Switch card ID if call completed successfully, otherwise a standard error.
This function is deprecated.
int sm_get_channel_ix(tSMChannelId channel)
Converts a channel identifier to a integer index unique to that channel.
Channel index value (greater than or equal to zero) if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_get_channel_module_id(tSMChannelId channel)
Given a channel returns the module on which the channel is located.
Note that this function no longer implemented, and shall eventually be withdrawn from the API.
Always returns the error ERR_SM_NOT_IMPLEMENTED .
This function is deprecated.
int sm_get_firmware_info(struct sm_fwinfo_parms *fp)
typedef struct sm_fwinfo_parms {
tSMModuleId module; /* in */
tSM_UT32 position; /* inout */
tSM_UT32 tasktypecode; /* out */
tSM_UT32 version; /* out */
} SM_FWINFO_PARMS;
Obsolete function that is not supported on ProsodyX cards or with ProsodyS v3 servers.
0 if call completed successfully, otherwise a standard error such as:
This function is deprecated.
int sm_get_module_card_id(tSMModuleId mod_id)
Given a module returns the card on which the module is located.
Note that this function is deprecated. It is present only to permit certain backward compatibility functionality to be implemented, should not be used by applications, and shall eventually be withdrawn from the API.
tSMCardId if call completed successfully, otherwise a standard error.
This function is deprecated.
int sm_reset_module(tSMModuleId module)
This function is deprecated. Since a module only needs to be reset when downloading a new kernel, the download program should be used to reset a module.
Performs hardware reset on given module, module, which will then require a new firmware download before it may be used for speech processing.
Any channels previously associated with the module must be released before invoking this call.
0 if call completed successfully, otherwise a standard error such as:
These functions constitute the Prosody generic API.