linePickup
The linePickup
function picks up a call alerting at the specified destination address and
returns a call handle for the picked-up call. If invoked with NULL for the lpszDestAddress
parameter, a group pickup is performed. If required by the device, lpszGroupID
specifies the group ID to which the alerting station belongs.
LONG linePickup(
|
HLINE hLine, |
|
|
DWORD dwAddressID, |
|
|
LPHCALL lphCall, |
|
|
LPCSTR lpszDestAddress, |
|
|
LPCSTR lpszGroupID |
|
|
); |
|
Parameters
hLine
A handle to
the open line device on which a call is to be picked up.
dwAddressID
The address
on hLine at which the pickup is to be originated.
lphCall
A pointer to
a memory location where the handle to the picked up call will be returned. The
application will be the initial sole owner of the call.
lpszDestAddress
A pointer to
a NULL-terminated character buffer that contains the address whose call is to
be picked up. The address is in standard dialable address format.
lpszGroupID
A pointer to
a NULL-terminated character buffer containing the group ID to which the
alerting station belongs. This parameter is required on some switches to pick
up calls outside of the current pickup group.
Note that lpszGroupID
can be specified by itself with a NULL pointer for lpszDestAddress.
Alternatively, lpszGroupID can be specified in addition to lpszDestAddress,
if required by the device.
Return Values
Returns a
positive request ID if the function will be completed asynchronously, or a
negative error number if an error has occurred. The dwParam2 parameter
of the corresponding LINE_REPLY
message is zero if the function is successful or it is a negative error number
if an error has occurred. Possible return values are:
LINEERR_INVALADDRESS,
LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL,
LINEERR_INVALGROUPID, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE,
LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.
Remarks
When a call
has been picked up successfully, the application is notified by the LINE_CALLSTATE message about call state
changes. The LINECALLINFO
structure supplies information about the call that was picked up. It will list
the reason for the call as pickup. This structure is available using lineGetCallInfo.
If LINEADDRCAPFLAGS_PICKUPCALLWAIT
is TRUE, linePickup can be used to pick up a call for which the user has
audibly detected the call-waiting signal but for which the provider is unable
to perform the detection. This gives the user a mechanism to "answer"
a waiting call even though the service provider was unable to detect the
call-waiting signal. Both lpszDestAddress and lpszGroupID pointer
parameters must be NULL to pick up a call-waiting call. The linePickup
function will create a new call handle for the waiting call and pass that
handle to the user. dwAddressID will most often be zero (particularly in
single-line residential cases).
Once linePickup
has been used to pick up the second call, lineSwapHold can be used to
toggle between them. The lineDrop function can be used to drop one (and
toggle to the other), and so forth. If the user wants to drop the current call
and pick up the second call, they should call lineDrop when they get the
call-waiting beep, wait for the second call to ring, and then call lineAnswer
on the new call handle. The LINEADDRFEATURE_PICKUP flag in the dwAddressFeatures
field in LINEADDRESSSTATUS indicates when pickup is actually possible.
See Also