LINE_CALLSTATE
The
LINE_CALLSTATE message is sent when the status of the specified call has
changed. Several such messages will typically be received during the lifetime
of a call. Applications are notified of new incoming calls with this message;
the new call will be in the offering state. The application can use lineGetCallStatus to retrieve more detailed
information about the current status of the call.
LINE_CALLSTATE
dwDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 =
(DWORD) CallState;
dwParam2 =
(DWORD) CallStateDetail;
dwParam3 =
(DWORD) CallPrivilege;
Parameters
dwDevice
A handle to
the call.
dwCallbackInstance
The callback
instance supplied when opening the call's line.
dwParam1
The new call
state. This parameter must be one and only one of the following LINECALLSTATE_
values:
LINECALLSTATE_IDLE
The call is
idle no call actually exists.
LINECALLSTATE_OFFERING
The call is
being offered to the station, signaling the arrival of a new call. In some
environments, a call in the offering state does not automatically alert the
user. Alerting is done by the switch instructing the line to ring; it does not
affect any call states.
LINECALLSTATE_ACCEPTED
The call was
offering and has been accepted. This indicates to other (monitoring)
applications that the current owner application has claimed responsibility for
answering the call. In ISDN, this also indicates that alerting to both parties
has started.
LINECALLSTATE_DIALTONE
The call is
receiving a dial tone from the switch, which means that the switch is ready to
receive a dialed number.
LINECALLSTATE_DIALING
Destination
address information (a phone number) is being sent to the switch over the call.
Note that lineGenerateDigits
does not place the line into the dialing state.
LINECALLSTATE_RINGBACK
The call is
receiving ringback from the called address. Ringback indicates that the other station
has been reached and is being alerted.
LINECALLSTATE_BUSY
The call is
receiving a busy tone. Busy tone indicates that the call cannot be completed either a circuit (trunk) or the remote party's station
are in use.
LINECALLSTATE_SPECIALINFO
Special
information is sent by the network. Special information is typically sent when
the destination cannot be reached.
LINECALLSTATE_CONNECTED
The call has
been established and the connection is made. Information is able to flow over
the call between the originating address and the destination address.
LINECALLSTATE_PROCEEDING
Dialing has
completed and the call is proceeding through the switch or telephone network.
LINECALLSTATE_ONHOLD
The call is
on hold by the switch.
LINECALLSTATE_CONFERENCED
The call is
currently a member of a multiparty conference call.
LINECALLSTATE_ONHOLDPENDCONF
The call is
currently on hold while it is being added to a conference.
LINECALLSTATE_ONHOLDPENTRANSFER
The call is currently
on hold awaiting transfer to another number.
LINECALLSTATE_DISCONNECTED
The remote
party has disconnected from the call.
LINECALLSTATE_UNKNOWN
The state of
the call is not known. This may be due to limitations of the call-progress
detection implementation.
dwParam2
Call-state-dependent
information.
If dwParam1
is LINECALLSTATE_BUSY, dwParam2 contains details about the busy mode.
This parameter uses the following LINEBUSYMODE_ constants:
LINEBUSYMODE_STATION
The busy
signal indicates that the called party's station is busy. This is usually
signaled by means of a "normal" busy tone.
LINEBUSYMODE_TRUNK
The busy
signal indicates that a trunk or circuit is busy. This is usually signaled with
a "long" busy tone.
LINEBUSYMODE_UNKNOWN
The busy
signal's specific mode is currently unknown, but may become known later.
LINEBUSYMODE_UNAVAIL
The busy
signal's specific mode is unavailable and will not become known.
If dwParam1
is LINECALLSTATE_CONNECTED, dwParam2 contains details about the connected
mode. This parameter uses the following LINECONNECTEDMODE_ constants:
LINECONNECTEDMODE_ACTIVE
Indicates
that the call is connected at the current station (the current station is a
participant in the call).
LINECONNECTEDMODE_INACTIVE
Indicates
that the call is active at one or more other stations, but the current station
is not a participant in the call.
If dwParam1
is LINECALLSTATE_DIALTONE, dwParam2 contains the details about the dial
tone mode. This parameter uses the following LINEDIALTONEMODE_ constants:
LINEDIALTONEMODE_NORMAL
This is a
"normal" dial tone, which typically is a continuous tone.
LINEDIALTONEMODE_SPECIAL
This is a
special dial tone indicating that a certain condition is currently in effect.
LINEDIALTONEMODE_INTERNAL
This is an
internal dial tone, as within a PBX.
LINEDIALTONEMODE_EXTERNAL
This is an
external (public network) dial tone.
LINEDIALTONEMODE_UNKNOWN
The dial tone
mode is currently unknown, but may become known later.
LINEDIALTONEMODE_UNAVAIL
The dial tone
mode is unavailable and will not become known.
If dwParam1
is LINECALLSTATE_OFFERING, dwParam2 contains details about the connected
mode. This parameter uses the following LINEOFFERINGMODE_ constants:
LINEOFFERINGMODE_ACTIVE
Indicates
that the call is alerting at the current station (will be accompanied by
LINEDEVSTATE_RINGING messages), and if any application is set up to
automatically answer, it may do so.
LINEOFFERINGMODE_INACTIVE
Indicates
that the call is being offered at more than one station, but the current
station is not alerting (for example, it may be an attendant station where the
offering status is advisory, such as blinking a light).
If dwParam1
is LINECALLSTATE_SPECIALINFO, dwParam2 contains the details about the
special information mode. This parameter uses the following LINESPECIALINFO_
constants:
LINESPECIALINFO_NOCIRCUIT
This special
information tone precedes a "no circuit" or emergency announcement
(trunk blockage category).
LINESPECIALINFO_CUSTIRREG
This special
information tone precedes a vacant number, AIS, Centrex number change and
nonworking station, access code not dialed or dialed in error, or manual
intercept operator message (customer irregularity category).
LINESPECIALINFO_REORDER
This special
information tone precedes a reorder announcement (equipment irregularity
category).
LINESPECIALINFO_UNKNOWN
Specifics
about the special information tone are currently unknown but may become known
later.
LINESPECIALINFO_UNAVAIL
Specifics
about the special information tone are unavailable and will not become known.
If dwParam1
is LINECALLSTATE_DISCONNECTED, dwParam2 contains details about the
disconnect mode. This parameter uses the following LINEDISCONNECTMODE_
constants:
LINEDISCONNECTMODE_NORMAL
This is a
"normal" disconnect request by the remote party, the call was
terminated normally.
LINEDISCONNECTMODE_UNKNOWN
The reason
for the disconnect request is unknown.
LINEDISCONNECTMODE_REJECT
The remote
user has rejected the call.
LINEDISCONNECTMODE_PICKUP
The call was
picked up from elsewhere.
LINEDISCONNECTMODE_FORWARDED
The call was
forwarded by the switch.
LINEDISCONNECTMODE_BUSY
The remote
user's station is busy.
LINEDISCONNECTMODE_NOANSWER
The remote
user's station does not answer.
LINEDISCONNECTMODE_NODIALTONE
A dial tone
was not detected within a service-provider defined timeout, at a point during
dialing when one was expected (such as at a "W" in the dialable
string). This can also occur without a service-provider-defined timeout period
or without a value specified in the dwWaitForDialTone member of the LINEDIALPARAMS structure.
LINEDISCONNECTMODE_BADADDRESS
The
destination address in invalid.
LINEDISCONNECTMODE_UNREACHABLE
The remote
user could not be reached.
LINEDISCONNECTMODE_CONGESTION
The network
is congested.
LINEDISCONNECTMODE_INCOMPATIBLE
The remote
user's station equipment is incompatible for the type of call requested.
LINEDISCONNECTMODE_UNAVAIL
The reason
for the disconnect is unavailable and will not become known later.
If dwParam1
is LINECALLSTATE_CONFERENCED, dwParam2 contains the hConfCall of
the parent call of the conference of which the subject hCall is a
member. If the call specified in dwParam2 was not previously considered
by the application to be a parent conference call (hConfCall), the
application must do so as a result of this message. If the application does not
have a handle to the parent call of the conference (because it has previously
called lineDeallocateCall
on that handle) dwParam2 will be set to null.
dwParam3
If zero, this
parameter indicates that there has been no change in the application's
privilege for the call.
If non-zero,
it specifies the application's privilege to the call. This will occur in the
following situations: (1) The first time that the application is given a handle
to this call; (2) When the application is the target of a call handoff (even if
the application already was an owner of the call). This parameter uses the
following LINECALLPRIVILEGE_ constants:
LINECALLPRIVILEGE_MONITOR
The application
has monitor privilege.
LINECALLPRIVILEGE_OWNER
The
application has owner privilege.
Return Values
No return
value.
Remarks
This message
is sent to any application that has a handle for the call. The LINE_CALLSTATE
message also notifies applications that monitor calls on a line about the
existence and state of outbound calls established by other applications or
manually by the user (for example, on an attached phone device). The call state
of such calls reflects the actual state of the call, which will not be offering.
By examining the call state, the application can determine whether the call is
an inbound call that needs to be answered or not.
A
LINE_CALLSTATE message with an unknown call state may be sent to a monitoring
application as the result of a successful lineMakeCall, lineForward, lineUnpark, lineSetupTransfer, linePickup, lineSetupConference, or linePrepareAddToConference that has been requested by
another application. At the same time that the requesting application is sent a
LINE_REPLY
(success) for the requested operation, any monitoring applications on the line
will be sent the LINE_CALLSTATE (unknown) message. A LINE_CALLSTATE indicating
the "real" call state of the newly generated call will be sent (using
information provided by the service provider) to the requesting and monitoring
applications shortly thereafter.
A LINE_CALLSTATE
(unknown) message is sent to monitoring applications only if lineCompleteTransfer
causes calls to be resolved into a three-way conference.
For backward
compatibility, older applications will not be expecting any particular value in
dwParam2 of a LINECALLSTATE_CONFERENCED message. TAPI will therefore
pass the parent call hConfCall in dwParam2 regardless of the API
version of the application receiving the message. In the case of a conference
call initiated by the service provider, the older application will not be aware
that the parent call has become a conference call unless it happens to spontaneously
examine other information (for example, call lineGetConfRelatedCalls)
This message
cannot be disabled.
See Also