Share via

linePickup

  • Article

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

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 hLine at 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 lpszGroupID parameter 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 identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message 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.
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_CALLSTATE message about call state changes. The LINECALLINFO structure supplies information about the call that was picked up. It lists the reason for the call as pickup. This structure is available using the lineGetCallInfo function.

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 creates a new call handle for the waiting call and passes that handle to the user. The dwAddressID parameter is most often zero (particularly in single-line residential cases).

After linePickup has been used to pick up the second call, the lineSwapHold function 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 the lineAnswer function on the new call handle. The LINEADDRFEATURE_PICKUP flag in the dwAddressFeatures member in LINEADDRESSSTATUS indicates when pickup is actually possible.

Note   This function is for TAPI version 2.0 and later.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Tapi.h.
Link Library: Coredll.lib.

See Also

LINE_CALLSTATE | LINE_REPLY | lineAnswer | LINECALLINFO | lineDrop | lineGetCallInfo | lineSwapHold

 Last updated on Saturday, April 10, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.