LINE_APPNEWCALL message
The TAPI LINE_APPNEWCALL message is sent to inform an application when a new call handle has been spontaneously created on its behalf (other than through an API call from the application, in which case the handle would have been returned through a pointer parameter passed into the function).
Parameters
-
hDevice
-
The application's handle to the line device on which the call has been created.
-
dwCallbackInstance
-
The callback instance supplied when opening the call's line.
-
dwParam1
-
Identifier of the address on the line on which the call appears. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
-
dwParam2
-
The application's handle to the new call.
-
dwParam3
-
The applications privilege to the new call (LINECALLPRIVILEGE_OWNER or LINECALLPRIVILEGE_MONITOR).
Return value
No return value.
Remarks
Applications supporting TAPI version 2.0 or later are sent a LINE_APPNEWCALL message whenever the application is spontaneously given a handle to a new call. Because the message includes the hLine and dwAddressID parameters on which the call exists, the application can readily create a new call object in the correct context. The LINE_APPNEWCALL message is always immediately followed by a LINE_CALLSTATE message indicating the initial state of the call.
Older applications (that negotiated an API version earlier than 2.0) are sent only a LINE_CALLSTATE message, as documented in previous versions of the API. Such applications would create a new call object upon receiving a LINE_CALLSTATE message that has dwParam3 set to a nonzero value and containing a call handle not presently known by the application. The disadvantages are that (a) the application must call lineGetCallInfo to determine the hLine and dwAddressID parameters associated with the call; (b) the application must scan all known call handles to determine that the call is a new call; and (c) it is possible, under certain conditions, for the application to think it is receiving a new call handle when in reality it has just deallocated its handle to the call (for example, the application has just deallocated a call handle, but a LINE_CALLSTATE message giving the application ownership of the call due to a lineHandoff from another application was already in the application's TAPI message queue).
Requirements
| Requirement | Value |
|---|---|
| TAPI version |
Requires TAPI 2.0 or later |
| Header |
|