(Engine-Level Function)
| Description: | Enables you to determine the media mode of a serial stream open on a modem, and change it if necessary (for example, if you require the ability to be able to handle both incoming voice mode and data mode calls). |
| Returns: | Numeric |
Usage:  |
Script Only. |
| Function Groups: | Modem |
| Related to: | ModemDev | ModemDial | ModemDigits | ModemList | ModemStream | ModemTransfer | Sound |
| Format: |
ModemMedia(ModemStream [, MediaMode]) |
| Parameters: |
| ModemStream | ||||||||||||||||||
| Required. The connected modem stream (returned from a ModemStream function call) that is to be handed off to another interested application. | ||||||||||||||||||
| MediaMode | ||||||||||||||||||
Optional. Specifies the desired media mode for the call. Valid values are bit significant, and more than one may be specified.
|
| Comments: | MediaMode is important when handling multi-mode calls. It may be specified when dialing a call (ModemDial) or preparing a modem for answering incoming calls (ModemStream), and is a consideration before handing off a call to another service (ModemTransfer). If more than one MediaMode bit is set, then the call type is undetermined, and Unknown (2) should also be set. It is not possible to change the media mode to a mode other than those specified when the ModemStream was created. If the requested Media change cannot be implemented, the function will return Invalid. The function will also return Invalid if there is no active call in progress on ModemStream. If Interactive Voice (4), or Automated Voice (8) is specified, then the modem will be initialized in voice mode. On outgoing calls, this has the effect that progress indication is unreliable - the call will be reported as connected as soon as dialing completes. This is a limitation of analog voice modems. Changes to media mode may not happen instantly. For example, changing a call from voice mode to data mode initiates the modem training sequence that may take several seconds to complete. The return value of the ModemMedia function indicates the current state, and so can be used to determine when the change has completed. |
Example:
As an example, the following steps would be required to provide an automated alarm reporting system that hands off incoming data calls to the system RAS service.
- Enumerate the available modems with ModemList and choose one with DataModem and Automated Voice facilities.
- Use ModemStream to prepare the modem for incoming calls, specifying Datamodem, Automated Voice, and Unknown as the media mode.
- When a call arrives, it will initially be answered in voice mode. Use ModemDigits to set up digit monitoring.
- Use ModemDev to obtain the handle for the wave/out device. This handle can then be used with the Sound function to play a wave file, or with the SpeechSpeak function to play simulated speech. A typical initial function would be to request that the caller press a digit key on the phone.
- If, for example, no DTMF digit is received within a few seconds, then it may be assumed that this is actually a data call. In this case, ModemMedia should be called to set the Datamodem media mode. If the return value is valid, then the mode should be polled approximately every 0.5 second, until ModemMedia returns a value that no longer contains Automated Voice. The ModemTransfer function may now be called to transfer the call, and the modem stream can be closed.
