lineOpen 函式 (tapi.h)

發行項
03/05/2024

lineOpen 函式會開啟其裝置識別碼所指定的行裝置，並傳回對應開啟行裝置的行句柄。此行句柄用於線路裝置上的後續作業。

語法

LONG lineOpen(
  HLINEAPP               hLineApp,
  DWORD                  dwDeviceID,
  LPHLINE                lphLine,
  DWORD                  dwAPIVersion,
  DWORD                  dwExtVersion,
  DWORD_PTR              dwCallbackInstance,
  DWORD                  dwPrivileges,
  DWORD                  dwMediaModes,
  LPLINECALLPARAMS const lpCallParams
);

參數

hLineApp

使用 TAPI 處理應用程式的註冊。

dwDeviceID

識別要開啟的線路裝置。它可以是有效的裝置標識碼或值。

值	意義
LINEMAPPER	這個值是用來在系統中開啟支援 lpCallParams 中所指定屬性的線條裝置。應用程式可以使用 lineGetID 來判斷已開啟之線路裝置的標識碼。

lphLine

接著載入代表開啟行裝置之句柄的 HLINE 句柄指標。使用此句柄在開啟行裝置上叫用其他函式時識別裝置。

dwAPIVersion

應用程式與電話語音 API 同意運作的 API 版本號碼。此數位是使用 lineNegotiateAPIVersion取得。

dwExtVersion

應用程式與服務提供者同意運作的擴充功能版本號碼。如果應用程式不使用任何延伸模組，則此數位為零。此數位是使用 lineNegotiateExtVersion取得。

dwCallbackInstance

用戶實例數據會傳回給應用程式，其中包含與這一行相關聯的每則訊息，或與此行上的位址或呼叫。電話語音 API 不會解譯此參數。

dwPrivileges

當收到呼叫通知時，應用程式想要的許可權：此參數包含一或多個 LINECALLPRIVILEGE_常數。對於使用 TAPI 2.0 版或更新版本的應用程式，此參數的值也可以與一或多個 LINEOPENOPTION_常數結合。

如果指定了 LINEOPENOPTION_SINGLEADDRESS 選項，則應用程式只會對在 lpCallParams 參數所指向之 LINECALLPARAMS 結構中 dwAddressID 成員所指定位址上的新呼叫感興趣， (必須指定) 。

如果指定了 LINEOPENOPTION_SINGLEADDRESS，但 lpCallParams 無效，或該行上沒有包含 的 dwAddressID ，則開啟會失敗並LINERR_INVALADDRESSID。

除了將 LINECALLPARAMS 結構的 dwAddressID 成員設定為所需的位址之外，應用程式也必須將 LINECALLPARAMS 中的 dwAddressMode 設定為 LINEADDRESSMODE_ADDRESSID。

LINEOPENOPTION_SINGLEADDRESS選項只會影響 TAPI 使用 LINE_NEWCALL 訊息來指派服務提供者所建立呼叫的初始呼叫擁有權。開啟具有LINECALLPRIVILEGE_MONITOR行的應用程式會繼續接收該行上建立之所有呼叫的監視句柄。此外，應用程式不會以任何方式限制進行呼叫，或執行會影響開啟行上其他位址的其他作業。

LINEOPENOPTION_PROXY選項指定 (TAPI 2.0 或更高版本時，只有) ，應用程式也必須指出它準備處理的特定 Proxy 要求。它會在 lpCallParams 參數中傳遞 LINECALLPARAMS 結構的指標，其中 dwDevSpecificSize 和 dwDevSpecificOffset 成員已設定為分隔 DWORD的陣列。此陣列的每個元素都應該包含其中一個 LINEPROXYREQUEST_常數。例如，支援所有五個 Agent 相關函式的 Proxy 處理程式應用程式會傳入五個 DWORDs 陣列， (dwDevSpecificSize 為 20 個小數) 包含五個已定義LINEPROXYREQUEST_值。

Proxy 要求處理程式應用程式可以在有權控制線路裝置的任何電腦上執行。不過，要求一律會透過服務提供者執行且實際控制線路裝置的伺服器路由傳送。因此，如果應用程式處理 Proxy 要求 (，例如 ACD 代理程式控制) 直接與服務提供者一起在伺服器上執行，則最有效率。

後續嘗試由相同的應用程式或其他應用程式開啟線路裝置，並註冊以處理與已註冊的應用程式相同的 Proxy 要求，並LINEERR_NOTREGISTERED失敗。

若要停止處理該行上的要求，應用程式只會呼叫 lineClose。

其他旗標組合會傳回LINEERR_INVALPRIVSELECT錯誤。

dwMediaModes

應用程式感興趣的媒體類型或模式。此參數可用來將應用程式註冊為傳入呼叫的潛在目標，以及指定之媒體類型的呼叫接聽。只有當 dwPrivileges 中的位LINECALLPRIVILEGE_OWNER設定為 (且忽略時，此參數才有意義，否則會忽略) 。此參數使用一或多個 LINEMEDIAMODE_常數。

lpCallParams

LINECALLPARAMS 類型的結構的指標。只有在使用 LINEMAPPER 或LINEOPENOPTION_PROXY時，才會使用此指標;否則會忽略 lpCallParams 。它描述線路裝置應該可以提供的呼叫參數。

傳回值

如果要求成功，則傳回零，如果發生錯誤，則傳回負錯誤號碼。可能的傳回值為：

LINEERR_ALLOCATED、LINEERR_LINEMAPPERFAILED、LINEERR_BADDEVICEID、LINEERR_NODRIVER、LINEERR_INCOMPATIBLEAPIVERSION、LINEERR_NOMEM、LINEERR_INCOMPATIBLEEXTVERSION、LINEERR_OPERATIONFAILED、LINEERR_INVALAPPHANDLE、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALMEDIAMODE、LINEERR_STRUCTURETOOSMALL、LINEERR_INVALPOINTER、LINEERR_UNINITIALIZED、LINEERR_INVALPRIVSELECT、LINEERR_REINIT、LINEERR_NODEVICE LINEERR_OPERATIONUNAVAIL。

備註

如果傳回LINEERR_ALLOCATED，則因為「持續性」條件而無法開啟該行，例如另一個進程獨佔開啟的序列埠。如果傳回LINEERR_RESOURCEUNAVAIL，由於動態資源過度認可，例如在 DSP 處理器週期或記憶體中，因此無法開啟該行。這項過度認可可能是暫時性，可能是因為監視媒體類型或音調所造成，而其他應用程式對這些活動的變更，可以在短時間內重新開啟該行。如果傳回LINEERR_REINIT，而且已要求 TAPI 重新初始化 (例如，因為新增或移除電話語音服務提供者) ，則會拒絕 lineOpen 要求，直到最後一個應用程式使用 lineShutdown) 關閉其 API (使用量為止;此時，新的設定會生效，而且再次允許應用程式呼叫 lineInitializeEx。

開啟行一律會讓應用程式能夠呼叫該行上任何可用的位址。應用程式處理來電或成為該行上通話交接目標的能力取決於 dwMediaModes 參數。 lineOpen 函式會將應用程式註冊為有興趣監視呼叫，或接收屬於指定媒體類型的呼叫擁有權。如果應用程式只想要監視呼叫，則可以指定LINECALLPRIVILEGE_MONITOR。如果應用程式只想要進行傳出呼叫，它可以指定LINECALLPRIVILEGE_NONE。如果應用程式願意控制未知媒體類型) 呼叫 (未分類的呼叫，它可以指定LINECALLPRIVILEGE_OWNER和LINEMEDIAMODE_UNKNOWN。否則，應用程式應該指定它感興趣的媒體類型。應用程式可以呼叫 lineSetCallPrivilege 函式來變更LINECALLPRIVILEGES_Constants所指定的呼叫許可權。

以 lineOpen 指定的媒體類型會新增至提供者媒體類型監視的預設值，以判斷初始來電類型。 lineMonitorMedia 函式會修改控制LINE_MONITORMEDIA訊息的遮罩。如果以擁有者許可權開啟行裝置，且未註冊擴充媒體類型，則會傳回錯誤LINEERR_INVALMEDIAMODE。

成功開啟線路裝置的應用程式一律可以使用 lineMakeCall、 lineUnpark、 linePickup和 lineSetupConference (搭配 NULLhCall) 來起始呼叫，以及假設裝置功能、行狀態等) 允許使用 lineForward (。

單一應用程式可以同時指定多個旗標來處理多個媒體類型。如果多個應用程式針對相同的媒體類型開啟同一行裝置，可能會發生衝突。這些衝突的解決方式是優先順序配置，用戶會將相對優先順序指派給應用程式。用戶可以呼叫 lineSetAppPriority 函式來設定應用程式優先順序。只有指定媒體類型的最高優先順序應用程式將會收到 (該媒體類型呼叫的未經要求) 擁有權。當來電第一次送達或接聽通話時，可以接收擁有權。會呼叫lineHandoff函式，以將呼叫的擁有權交給另一個應用程式。如果使用者未將優先順序指派給應用程式，而且多個應用程式預設會開啟同一行裝置，則呼叫 lineOpen 的應用程式會優先擁有最高的優先順序。

任何應用程式 (包括任何較低優先順序的應用程式) 一律可以使用 lineGetNewCalls 或 lineGetConfRelatedCalls 取得擁有權。如果應用程式開啟一行來監視某個時間的呼叫存在於該行上，則不會自動為新的監視應用程式產生這些現有呼叫的訊息LINE_CALLSTATE 訊息。應用程式可以查詢行上目前呼叫的數目，以判斷有多少呼叫存在，如果想要的話，它可以呼叫 lineGetNewCalls 來取得這些呼叫的句柄。

處理自動化語音的應用程式也應該選取互動式語音開啟模式，並指派互動式語音的最低優先順序。這是因為服務提供者會將所有語音媒體類型回報為互動式語音。如果未知媒體類型的應用程式未執行媒體類型判斷，而且沒有互動式語音應用程式已開啟線路裝置，語音通話將無法連線到自動化語音應用程式，而且會捨棄。

相同應用程式或相同應用程式的不同具現化，可以使用相同或不同的參數多次開啟相同的行。

當應用程式開啟線路裝置時，它必須指定交涉的 API 版本，而且，如果想要使用該行的擴充功能，它應該指定該行的裝置特定擴充功能版本。這些版本號碼應該已使用 lineNegotiateAPIVersion 和 lineNegotiateExtVersion取得。版本編號允許混合和比對不同的應用程式版本與不同的 API 版本和服務提供者版本。

LINEMAPPER 可讓應用程式間接選取線條，方法是從中選取所需的服務。使用 LINEMAPPER 開啟線條裝置時，下列為 true：從 LINECALLPARAMS 數據結構開頭到 dwAddressMode 的所有成員都相關。如果 dwAddressMode 是LINEADDRESSMODE_ADDRESSID表示可以接受該行上的任何地址，否則 如果 dwAddressMode 是LINEADDRESSMODE_DIALABLEADDR，表示搜尋特定原始位址 (電話號碼) ，或者它是提供者特定的擴充功能，則 dwOrigAddressSize/Offset 和其所參考變數部分的部分也相關。如果 dwAddressMode 是提供者特定的擴充功能，則可以將其他資訊包含在 dwDeviceSpecific 可變大小的成員中。