linePark 函式 (tapi.h)

發行項
03/13/2024

LinePark 函式會根據指定的駐留模式來調整指定的呼叫。

語法

LONG linePark(
  HCALL       hCall,
  DWORD       dwParkMode,
  LPCSTR      lpszDirAddress,
  LPVARSTRING lpNonDirAddress
);

參數

hCall

要駐留之呼叫的句柄。應用程式必須是呼叫的擁有者。 hCall 的呼叫狀態必須連線。

dwParkMode

要停駐通話的駐留模式。此參數只能設定單一旗標，並使用其中一個 LINEPARKMODE_常數。

lpszDirAddress

Null 終止字串的指標，指出呼叫在使用導向駐留時要停駐的位址。位址是可撥號號碼格式。非目錄駐留會忽略此參數。

lpNonDirAddress

VARSTRING 類型的結構的指標。針對非直接駐留，呼叫停駐所在的位址會在此結構中傳回。系統會忽略導向駐留的此參數。在 VARSTRING 結構內， dwStringFormat 必須設定為STRINGFORMAT_ASCII (包含 null 終止字串的 ASCII 字串緩衝區) ，而終止 NULL 必須在 dwStringSize 中考慮。在呼叫 linePark之前，應用程式必須設定此結構的 dwTotalSize 成員，以指出TAPI可用來傳回資訊的記憶體數量。

傳回值

如果函式是以異步方式完成，則傳回正要求標識碼，如果發生錯誤，則傳回負錯誤號碼。如果函式成功或發生錯誤，則對應LINE_REPLY訊息的 dwParam2 參數為零。可能的傳回值為：

LINEERR_INVALADDRESS、LINEERR_NOTOWNER、LINEERR_INVALCALLHANDLE、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALCALLSTATE、LINEERR_OPERATIONFAILED、LINEERR_INVALPARKMODE、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALPOINTER、LINEERR_STRUCTURETOOSMALL、LINEERR_NOMEM LINEERR_UNINITIALIZED。

備註

透過導向駐留，應用程式會決定其想要將通話停駐的位址。使用非直接駐留時，參數會決定位址，並將此位址提供給應用程式。不論是哪一種情況，都可以藉由指定此位址來取消停駐通話。

駐留的呼叫通常會在成功駐留後進入閒置狀態，然後應用程式應該將其句柄解除分配給呼叫。如果應用程式在停駐呼叫上執行 lineUnpark ，即使應用程式尚未解除分配舊的呼叫句柄，也會為未停駐的呼叫建立新的呼叫句柄。

有些交換器可以在通話停駐一段時間后提醒使用者。應用程式會看到供應項目通話，並將通話原因設定為提醒。

在非導向的駐留上，如果 VARSTRING 結構中的 dwTotalSize 成員未指定足夠的記憶體數量來接收駐留位址，則對應的回復訊息會傳回LINEERR_STRUCTURETOOSMALL錯誤值。在這種情況下，無法擷取完整的駐留位址。傳回LINEERR_STRUCTURETOOSMALL錯誤值時，NonDirAddress 結構的 dwNeededSize 成員不包含有效的值。如果從非雙向 linePark收到LINEERR_STRUCTURETOOSMALL錯誤值，請增加緩衝區的大小，然後再次呼叫 linePark ，直到傳回成功或不同的LINEERR_XXX結果為止。