linePark
The linePark
function parks the specified call according to the specified park mode.
LONG linePark(
|
HCALL hCall, |
|
|
DWORD dwParkMode, |
|
|
LPCSTR lpszDirAddress, |
|
|
LPVARSTRING lpNonDirAddress |
|
|
); |
|
Parameters
hCall
A handle to
the call to be parked. The application must be an owner of the call. The call
state of hCall must be connected.
dwParkMode
The park mode
with which the call is to be parked. This parameter can have only a single flag
set, and it uses the following LINEPARKMODE_ constants:
LINEPARKMODE_DIRECTED
The
application specifies at which address the call is to be parked in lpszDirAddress.
LINEPARKMODE_NONDIRECTED
This
operation reports to the application where the call has been parked in lpNonDirAddress.
lpszDirAddress
A pointer to
a NULL-terminated string that indicates the address where the call is to be
parked when using directed park. The address is in dialable number format. This
parameter is ignored for nondirected park.
lpNonDirAddress
A pointer to
a structure of type VARSTRING.
For nondirected park, the address where the call is parked is returned in this
structure. This parameter is ignored for directed park. Within the VARSTRING
structure, dwStringFormat must be set to STRINGFORMAT_ASCII (an ASCII
string buffer containing a NULL-terminated string), and the terminating NULL
must be accounted for in the dwStringSize. Prior to calling linePark,
the application should set the dwTotalSize field of this structure to
indicate the amount of memory available to TAPI for returning information.
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_NOTOWNER, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL,
LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALPARKMODE,
LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL,
LINEERR_NOMEM, LINEERR_UNINITIALIZED.
Remarks
With directed
park, the application determines the address at which it wants to park the
call. With nondirected park, the switch determines the address and provides
this to the application. In either case, a parked call can be unparked by
specifying this address.
The parked
call typically enters the idle state after it has been successfully
parked and the application should then deallocate its handle to the call. If
the application performs a lineUnpark on the parked call, a new call handle will be
created for the unparked call even if the application has not deallocated its
old call handle.
Some switches
may remind the user after a call has been parked for some long amount of time.
The application will see an offering call with a call reason set to reminder.
On a nondirected
park, if the dwTotalSize member in the VARSTRING structure does not
specify a sufficient amount of memory to receive the park address, the
corresponding reply message returns a LINEERR_STRUCTURETOOSMALL error value. In
such cases, there is no way to retrieve the complete park address. Note that
when a LINEERR_STRUCTURETOOSMALL error value is returned, the dwNeededSize
field of the NonDirAddress structure does not contain a valid value. If a
LINEERR_STRUCTURETOOSMALL error value is received from a nondirected linePark,
then increase the size of the buffer and call linePark again until it
returns either success or a different LINEERR_XXX result.
See Also