LINE_NEWCALL message

The TSPI LINE_NEWCALL message is sent to the LINEEVENT callback function whenever a new call that TAPI has not originated arrives on a line that TAPI has open. This must be the first message sent regarding that call. TAPI writes the htCall opaque handle to the location passed by the service provider as dwParam2. This gives the service provider the htCall value to be used in subsequent messages.

Parameters

htLine

The TAPI opaque object handle to the line device.

htCall

Unused.

dwMsg

The value LINE_NEWCALL.

dwParam1

The service provider's opaque handle for the call, of type HDRVCALL. TAPI passes this value as the hdCall parameter to identify the call in subsequent procedures it invokes to operate on the call.

dwParam2

A pointer of type LPHTAPICALL pointing to a HTAPICALL. TAPI writes the TAPI opaque handle for the call to the indicated location. The service provider must save this value and pass it as the htCall parameter to identify the call in subsequent events it reports for the call.

This parameter can also acquire a value of NULL (see the following Remarks section).

dwParam3

Unused.

Remarks

The service provider should send the LINE_CALLSTATE message as the next message for this call. The LINE_NEWCALL event is unusual in that it also passes a value back to the service provider.

This function reports any new calls that originate in the service provider (inbound, outbound, initiated at the phone, and so on) for which TAPI and the service provider have not yet exchanged opaque handles. The handles are exchanged so that TAPI and the service provider can subsequently make requests and report events involving the call. Because these new calls are not necessarily inbound, the calls can initially be in any state, not necessarily the offering state. If the service provider starts and discovers that one or more calls are already active on the line, it informs TAPI of them with LINE_NEWCALL messages followed by LINE_CALLSTATE messages indicating the current state. A new outgoing call, initiated on the phone by the user, would be reported with a LINE_NEWCALL message, and the initial LINE_CALLSTATE message would indicate that the call was in DIALTONE state (and then continuing on from there).

If the service provider passes a large number of calls to TAPI in a very short amount of time (during the same interrupt cycle), TAPI can become backlogged in processing those calls. When this happens, TAPI signals to the service provider to wait a short time before sending any more calls. It signals this by writing a value of NULL, instead of a valid HTAPICALL, into the location pointed to by the dwParam2 parameter of LINE_NEWCALL. This indicates that the attempt to process the newly offered call handle was not successful, most likely due to a temporary inability to allocate memory. The service provider can respond by dropping the call or by resending the LINE_NEWCALL message after a scheduling delay (during which time the service provider should yield the processor to allow TAPI to process other pending actions). In any case, no further messages regarding the new call can be passed to TAPI until the handle exchange succeeds. When the location pointed to by dwParam2 acquires a non-NULL value, the service provider knows that this value is a valid HTAPICALL handle to the call.

There is no directly corresponding message at the TAPI level. This message is used at the TSPI level to uniquely and unambiguously introduce a new incoming call to TAPI and retrieve the TAPI opaque identifier for the call.

Requirements

Requirement	Value
TAPI version	Requires TAPI 2.0 or later
Header	Tspi.h

See also

LINE_CALLSTATE

LINEEVENT