lineAccept
The lineAccept
function accepts the specified offered call. It may optionally send the
specified user-to-user information to the calling party.
LONG lineAccept(
|
HCALL hCall, |
|
|
LPCSTR lpsUserUserInfo, |
|
|
DWORD dwSize |
|
|
); |
|
Parameters
hCall
A handle to
the call to be accepted. The application must be an owner of the call. Call
state of hCall must be offering.
lpsUserUserInfo
A pointer to
a string containing user-to-user information to be sent to the remote party as
part of the call accept. This pointer can be left NULL if no user-to-user
information is to be sent. User-to-user information is only sent if supported
by the underlying network (see LINEDEVCAPS). The protocol discriminator field for the
user-to-user information, if required, should appear as the first byte of the
buffer pointed to by lpsUserUserInfo, and must be accounted for in dwSize.
dwSize
The size in
bytes of the user-to-user information in lpsUserUserInfo. If lpsUserUserInfo
is NULL, no user-to-user information is sent to the calling party and dwSize
is ignored.
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_INVALCALLHANDLE,
LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL,
LINEERR_NOTOWNER, LINEERR_UNINITIALIZED, LINEERR_INVALPOINTER,
LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG.
Remarks
The lineAccept
function is used in telephony environments like Integrated Services Digital
Network (ISDN) that allow alerting associated with incoming calls to be
separate from the initial offering of the call. When a call comes in, it is
first offered. For some small amount of time, the application may have the
option to reject the call using lineDrop, redirect the call to another station using lineRedirect, answer the call using lineAnswer, or accept the call using lineAccept.
After a call has been successfully accepted, alerting at both the called and
calling device begins. After a call has been accepted by an application, the
call state typically transitions to accepted.
Alerting is
reported to the application by the LINE_LINEDEVSTATE message with the ringing
indication.
The lineAccept
function may also be supported by non-ISDN service providers. The call state
transition to accepted can be used by other applications as an
indication that another application has claimed responsibility for the call and
has presented the call to the user.
The
application has the option to send user-to-user information at the time of the
accept. Even if user-to-user information is sent, there is no guarantee that
the network will deliver this information to the calling party. An application
should consult a line's device capabilities to determine whether call accept is
available.
For
information about the listing of service dependencies, see Service
Dependencies..
See Also