| Comments: |
The return value for this function will be one of the following integer values until the modem has a valid connection with a remote modem:Return | Status |
|---|
0 | Idle (no connection), waiting for a call | 1 | Starting outbound call | 2 | Outgoing call request accepted by modem | 3 | Dial tone on outbound call | 4 | Dialing outbound call | 5 | Remote phone ringing on outbound call | 6 | Remote phone busy on outbound call | 7 | Connected (should not be seen since a stream value will be returned at this point) | 8 | Another application is handling the call after a ModemTransfer | 9 | Incoming call detected. The modem is being called, but has not yet answered. Changes to 11 when the modem answers. | 10 | The modem is temporarily unavailable. Occurs when trying to place an outgoing call and either the modem is still initializing or another TAPI aware application has the modem. | 11 | The modem has answered a call. Modem training in progress. Normally followed by a valid stream connection. If an error has occurred, the return values will be one of the following error codes: |
Error code | Meaning |
|---|
-1 | The (numeric) first parameter to the function is out of range | -2 | No dial tone detected on outbound call | -3 | Remote phone busy on outbound call | -4 | No answer on outbound call | -5 | Remote hung up on incoming call | -6 | Modem unavailable | -7 | Other call termination condition |
Errors equal to or less than -101 correspond to the Microsoft Telephony Interface (TAPI) errors (which are normally numbered from 1). Specific errors that may be encountered are: -101 TAPI error code 1
(LINEERR_ALLOCATED) | the serial port is in exclusive use by some other process | -112 TAPI error code 12
(LINEERR_INCOMPATIBLEAPIVERSION) | the system does not have the required version of telephony support (TAPI 2.0 required) | -115 TAPI error code 15
(LINEERR_INUSE) | the line device is in use and cannot currently be configured, nor can it allow a party to be added or a call to be answered, placed or transferred | -147 TAPI error code 47
(LINEERR_INVALMEDIAMODE) | the requested media mode could not be accommodated (e.g. voice call request on a non-voice modem). | -167 TAPI error code 67
(LINEERR_NODEVICE) | the specified device identifier, which was previously valid, is no longer accepted because the associated device has been removed from the system since TAPI was last initialized. Alternately, the line device has no associated device for the given device class | -168 TAPI error code 68
(LINEERR_NODRIVER) | either TAPIAddr.DLL could not be located or the telephone service provider for the specified device found that one of its components is missing or corrupt in a way that was not detected at initialization time. Use the Telephony Control Panel to correct the problem | -169 TAPI error code 69
(LINEERR_NOMEM) | insufficient memory to perform the operation, or unable to lock memory | -175 TAPI error code 75
(LINEERR_RESOURCEUNAVAIL ) | insufficient resources to complete the operation (e.g. a line cannot be opened due to a dynamic resource over commitment). Also occurs where a modem is being used by a non-TAPI application |
If the PhoneNumber parameter is invalid, a pass-through connection will be obtained. This allows the application to send and receive raw modem commands as if it had exclusive access to the serial port. The difference is that pass-through allows the modem to be shared with other TAPI applications. If the modem is not currently involved in a call then a stream value is returned immediately and may be used to read/write modem commands and data. If the modem is currently involved in a call then the return value will be 10 (modem temporarily unavailable) - wait for a period and then retry. While a pass-through connection is open, the application has complete control over the modem. If an incoming call arrives, then a notification will be given by the modem (usually "\r\nRING\r\n"). If handling of incoming calls is not required and some other TAPI application does require call handling (e.g. RAS) then the stream should be closed immediately after a ring is detected. Handing off the call using ModemTransfer will not work, because as far as TAPI is concerned there is no call in progress at that stage. When a modem is in voice mode it is not able to detect call progress accurately. The Microsoft Telephony Service still returns call progress indications but they are fallible. For example, call connected state is returned immediately dialing is complete. It is not possible to change the media mode of a call after the ModemDial function has been invoked. Due to operating system restrictions audio mode is only available with Windows 98/ME/2000. |
