Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This 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 lpszDestAddressparameter, a group pickup is performed. If required by the device, the lpszGroupIDparameter specifies the group identifier to which the alerting station belongs.

Syntax 

LONG WINAPI linePickup(
  HLINE 
hLine,
  DWORD 
dwAddressID,
  LPHCALL 
lphCall,
  LPCSTR 
lpszDestAddress,
  LPCSTR 
lpszGroupID 
);

Parameters

hLine

Handle to the open line device on which a call is to be picked up.

dwAddressID

Address on hLineat which the pickup is to be originated. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.

lphCall

Pointer to a memory location where the handle to the picked up call is returned. The application is the initial sole owner of the call.

lpszDestAddress

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

Pointer to a null-terminated character buffer containing the group identifier to which the alerting station belongs. This parameter is required on some switches to pick up calls outside of the current pickup group.

The lpszGroupIDparameter can be specified by itself with a NULL pointer for lpszDestAddress. Alternatively, lpszGroupIDcan be specified in addition to lpszDestAddress, if required by the device.

Return Value

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2parameter of the corresponding LINE_REPLYmessage is zero if the function succeeds or it is a negative error number if an error occurs. The following table shows the return values for this function.

Value Description

LINEERR_INVALADDRESS

The address is invalid.

LINEERR_NOMEM

Not enough memory is available.

LINEERR_INVALADDRESSID

The address identifier is invalid.

LINEERR_OPERATIONUNAVAIL

The operation is unavailable. With code division multiple access (CDMA), this function will fail if a call is currently in progress.

CDMA does not provide the necessary functionality to support the following TAPI functions:

Some cellular carriers provide equivalent functionality through the flash feature, which with TAPI 2.2 can be accessed with the lineGenerateDigitsfunction. Because the exact flash sequences are controlled by the cellular providers, the application must be completely aware of the necessary codes implemented by the cellular providers.

LINEERR_INVALGROUPID

The group identifier is invalid.

LINEERR_OPERATIONFAILED

The operation failed.

LINEERR_INVALLINEHANDLE

The handle to the open line device is invalid.

LINEERR_RESOURCEUNAVAIL

The resources are unavailable.

LINEERR_INVALPOINTER

The pointer is invalid.

LINEERR_UNINITIALIZED

A parameter is uninitialized.

Remarks

When a call has been picked up successfully, the application is notified by the LINE_CALLSTATEmessage about call state changes. The LINECALLINFOstructure supplies information about the call that was picked up. It lists the reason for the call as pickup. This structure is available using the lineGetCallInfofunction.

If LINEADDRCAPFLAGS_PICKUPCALLWAIT is TRUE, linePickupcan 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 lpszDestAddressand lpszGroupIDpointer parameters must be NULL to pick up a call-waiting call. The linePickupfunction creates a new call handle for the waiting call and passes that handle to the user. The dwAddressIDparameter is most often zero (particularly in single-line residential cases).

After linePickuphas been used to pick up the second call, the lineSwapHoldfunction can be used to toggle between them. The lineDropfunction 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 lineDropwhen they get the call-waiting beep, wait for the second call to ring, and then call the lineAnswerfunction on the new call handle. The LINEADDRFEATURE_PICKUP flag in the dwAddressFeaturesmember in LINEADDRESSSTATUS indicates when pickup is actually possible.

Note:
This function is for TAPI version 2.0 and later.

Requirements

Header tapi.h
Library coredll.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also