interface .TEL

This API provides the high level telephony API for the speech link stack.

Public Methods

[more]SLTEL_API SLresult SLtelInit(void *args)
Initializes the Telephony platform.
[more]SLTEL_API SLresult SLtelShutdown(void *args)
Shutdown the telephony platform.
[more]SLTEL_API SLresult SLtelGetProperty(SLchar *prop_name, SLValue *value)
Gets the value of a property of the telephony platform.
[more]SLTEL_API SLresult SLtelSetProperty(SLchar *prop_name, SLValue *value)
Sets the value of a property of the underlying hardware.
[more]SLTEL_API SLresult SLtelProperties(SLVector *prop_names)
Gets the list of available properties.
[more]SLTEL_API SLresult SLtelReserveChannel(SLtelChn** channel)
Reserves an idle channel.
[more]SLTEL_API SLresult SLtelReleaseChannel(SLtelChn* channel)
Releases resources associated with channel and puts it back on the list of idle channels.
[more]SLTEL_API SLresult SLtelChnOpen(SLtelChn *channel)
Opens a channel to receive or initiate calls.
[more]SLTEL_API SLresult SLtelChnClose(SLtelChn *channel)
Closes a channel previously opened with SLtelChnOpen().
[more]SLTEL_API SLresult SLtelChnAddCallback(SLtelEvent e, SLtelChn* channel, SLtelEventInfo *info)
/
[more]SLTEL_API SLresult SLtelChnRemoveCallback(SLtelEvent e, SLtelChn* channel, SLtelEventInfo *info)
Removes the callback from the list of callbacks.
[more]SLTEL_API SLresult SLtelChnGetProperty(SLtelChn *channel, SLchar *prop_name, SLValue *value)
Gets the value of a property on the channel
[more]SLTEL_API SLresult SLtelChnSetProperty(SLtelChn *channel, SLchar *prop_name, SLValue *value)
Sets the value of a property of a property on the channel
[more]SLTEL_API SLresult SLtelChnProperties(SLtelChn *channel, SLVector *prop_names)
Get list of available properties.
[more]SLTEL_API SLresult SLtelChnConnect(SLtelChn* channel, const SLchar* mimetype, const void* userdata, SLuint dataSize)
Picks up a call.
[more]SLTEL_API SLresult SLtelChnDisconnect(SLtelChn* channel)
Disconnects caller (ie.
[more]SLTEL_API SLresult SLtelChnDial(SLtelChn* channel, SLchar* dest, SLbool call_prog, const SLchar *mimetype, const void* userdata, SLuint udataSize)
Makes a call asynchronously.
[more]SLTEL_API SLresult SLtelChnTransfer(SLtelChn* chn, const SLchar* dest, const SLchar *mimetype, const void* userdata, SLuint udataSize, SLbool callReturn)
Sends a transfer request to the other party.
[more]SLTEL_API SLresult SLtelChnSendDTMF(SLtelChn* ch, SLchar *digits)
Sends a DTMF digit sequence
[more]SLTEL_API SLresult SLtelChnPlayFile(SLtelChn* channel, SLchar *filename)
Plays a file.
[more]SLTEL_API SLresult SLtelChnRecordFile(SLtelChn* ch, SLuint nbSecs, SLchar *filename)
Starts recording into a file.


Documentation

This API provides the high level telephony API for the speech link stack. Applications should integrate to this level.
oSLTEL_API SLresult SLtelInit(void *args)
Initializes the Telephony platform.

Create a telephony platform API and instantiate it. Used by the Telephony service

Parameters:
args - An object containing args (implementation specific) and to enter return info needed by main.
Returns:
SL_SUCCESS if success, less than SL_SUCCESS otherwise.

oSLTEL_API SLresult SLtelShutdown(void *args)
Shutdown the telephony platform.

Parameters:
args - An object containing args (implementation specific) and to enter return info needed by main.
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure.

oSLTEL_API SLresult SLtelGetProperty(SLchar *prop_name, SLValue *value)
Gets the value of a property of the telephony platform.

Parameters:
prop_name - the name of the property
value - out[x] the value of the property
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure.

oSLTEL_API SLresult SLtelSetProperty(SLchar *prop_name, SLValue *value)
Sets the value of a property of the underlying hardware.

Parameters:
prop_name - the name of the property
value - the value of the property
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure.

oSLTEL_API SLresult SLtelProperties(SLVector *prop_names)
Gets the list of available properties.

Parameters:
prop_names - out[x] the list of available properties
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure.

oSLTEL_API SLresult SLtelReserveChannel(SLtelChn** channel)
Reserves an idle channel.

Channels are taken from a list of idle channels. The channel must be opened with SLhwTelChnOpen() before it is ready to receive or initiate calls.

Parameters:
channel - out[x] the channel structure.
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure.

oSLTEL_API SLresult SLtelReleaseChannel(SLtelChn* channel)
Releases resources associated with channel and puts it back on the list of idle channels.

The channel cannot receive or initiate calls until SLtelReserveChannel() and SLtelChnOpen() are called again.

Parameters:
channel - out[x] the channel structure to be released.
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure.

oSLTEL_API SLresult SLtelChnOpen(SLtelChn *channel)
Opens a channel to receive or initiate calls.

The channel must have been previously reserved with SLhwTelReserveChannel() prior to making this call. The channel remains open until SLhwTelChnClose() is called.

Parameters:
channel - in[x] The channel to be opened
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure.

oSLTEL_API SLresult SLtelChnClose(SLtelChn *channel)
Closes a channel previously opened with SLtelChnOpen(). The channel remains reserved until SLhwTelReleaseChannel() is called.

Parameters:
channel - in[x] The channel structure to be closed
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure.

oSLTEL_API SLresult SLtelChnAddCallback(SLtelEvent e, SLtelChn* channel, SLtelEventInfo *info)
/

/** Adds an event callback for the specified event and channel.

Only a reference to the callback information is copied, therefore the caller must ensure that the callback information remains in scope after the call returns. The reason is that the reference of the callback information is used for retrieval when removing a callback information.

Parameters:
e - An event which should be handled by this callback
channel - The channel on which to set the callback.
info - An event information structure to be used if there is an event on the telephony API
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure.

oSLTEL_API SLresult SLtelChnRemoveCallback(SLtelEvent e, SLtelChn* channel, SLtelEventInfo *info)
Removes the callback from the list of callbacks.

Parameters:
e - An event which should be handled by this callback
channel - The channel on which to remove the callback.
info - in[x] The callback structure to remove.
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure.

oSLTEL_API SLresult SLtelChnGetProperty(SLtelChn *channel, SLchar *prop_name, SLValue *value)
Gets the value of a property on the channel

Parameters:
channel - The channel on which the property is set
prop_name - the name of the property
value - out[x] the value of the property
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure.

oSLTEL_API SLresult SLtelChnSetProperty(SLtelChn *channel, SLchar *prop_name, SLValue *value)
Sets the value of a property of a property on the channel

Parameters:
channel - The channel on which to set the property
prop_name - the name of the property
value - the value of the property
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure.

oSLTEL_API SLresult SLtelChnProperties(SLtelChn *channel, SLVector *prop_names)
Get list of available properties.

Parameters:
channel - in[x] The channel on which to get the property names
prop_names - out[x] the set of available properties
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure.

oSLTEL_API SLresult SLtelChnConnect(SLtelChn* channel, const SLchar* mimetype, const void* userdata, SLuint dataSize)
Picks up a call. Transition the state from on hook to off hook. This function should be called in a event handler for the SLtel_RINGING event.

Parameters:
channel - A handle to the channel to pickup
mimetype - in[x] NULL terminated string providing the MIME type of the data to transmit on a speech links call.
userdata - in[x] The user data to transfer on the speech links call.
dataSize - in[x] The length in bytes of the userdata.
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure.

oSLTEL_API SLresult SLtelChnDisconnect(SLtelChn* channel)
Disconnects caller (ie. hangs up). This function can be called to terminate a connection and should also be called by a event handler for the SLtel_HANGUP event.

Parameters:
channel - A handle to the channel resource manager
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure.

oSLTEL_API SLresult SLtelChnDial(SLtelChn* channel, SLchar* dest, SLbool call_prog, const SLchar *mimetype, const void* userdata, SLuint udataSize)
Makes a call asynchronously. An SLtel_DIAL event is generated when dialing is completed.

Parameters:
channel - modify[x] A handle to the channel resource manager
dest - in[x] A URI specifying the phone number or SIP number to call
call_prog - in[x] Returns a call connect event using call progress detection if true.
mimetype - in[x] NULL terminated string providing the MIME type of the data to transmit on a speech links call.
userdata - in[x] The user data to transfer on the speech links call.
dataSize - in[x] The length in bytes of the userdata.
Returns:
Return SL_SUCCESS if the call method connects, unsupported if the number cannot be handled, and less than SL_SUCCESS on other errors.

oSLTEL_API SLresult SLtelChnTransfer(SLtelChn* chn, const SLchar* dest, const SLchar *mimetype, const void* userdata, SLuint udataSize, SLbool callReturn)
Sends a transfer request to the other party.

If the other party can perform the request, it will hangup the call (a SLtel_HANGUP event is thrown) and it invites the destination on a call. If the callReturn flag is set to true. The other party will call us back when the call call with the transfer target is over.

Parameters:
chn - in[x] A handle to the channel that is currently in the call on which to perform the blind transfer.
dest - in[x] The destination phone number of the transfer. This can be a URI
mimetype - in[x] NULL terminated string providing the MIME type of the data to transmit on a speech links call.
userdata - in[x] The user data to transfer on the speech links call.
udataSize - in[x] The length in bytes of the userdata.
callReturn - in[x] If true the transfer target should return the call on call termination
Returns:
SL_SUCCESS if successful, less than SL_SUCCESS otherwise.

oSLTEL_API SLresult SLtelChnSendDTMF(SLtelChn* ch, SLchar *digits)
Sends a DTMF digit sequence

Parameters:
ch - in[x] A handle to the channel on which to send the digits
digits - in[x] 0-terminated string of DTMFs to send.
Returns:
SL_SUCCESS if the digits where sent, less than SL_SUCCESS otherwise.

oSLTEL_API SLresult SLtelChnPlayFile(SLtelChn* channel, SLchar *filename)
Plays a file. The format of the file is implementation-dependant.

Parameters:
channel - in[x] The channel on which the file is to be played.
filename - The path of the file to be played.
Returns:
SL_SUCCESS if success, less than SL_RESULT if failure.

oSLTEL_API SLresult SLtelChnRecordFile(SLtelChn* ch, SLuint nbSecs, SLchar *filename)
Starts recording into a file. The recording is stopped when a DTMF is received or when the specified duration is reached. The format of the file is implementation-dependent.

Parameters:
channel - in[x] The channel on which the file is to be played.
nbSecs - The maximum number of seconds the recording should last. If set to 0, means no time limit.
filename - The path of the file in which the recording is to be saved.
Returns:
SL_SUCCESS if success, less than SL_RESULT if failure.


This class has no child classes.

Alphabetic index HTML hierarchy of classes or Java


Copyright © 2000-2001 SpeechWorks International, Inc. 
This work may only be distributed under the terms of the SpeechWorks Open Document License v1.0