C 應用程式會使用訊息接聽器函數以非同步接收訊息, 以及使用異常狀況接聽器函數以非同步獲知有問題的連線。
若要非同步接收訊息,C 應用程式必須向一或多個訊息使用端登錄一個訊息接聽器函數與環境定義資料。其做法是應用程式針對每一個訊息使用端呼叫 xmsMsgConsumerSetMessageListener() 函數, 以便將訊息接聽器函數的指標和環境定義資料當成參數傳遞。
訊息接聽器函數是一種由使用者撰寫的回呼函數。當訊息使用端的訊息送達時, XMS 會呼叫訊息接聽器函數以遞送訊息,並將環境定義資料的指標當成一個參數傳遞, 以及將訊息的控點當成另一個參數傳遞。
環境定義資料的格式和內容由應用程式定義, 資料本身會佔據應用程式所擁有的記憶體。例如, 環境定義資料可能是配置在資料堆上的一個結構。環境定義資料含有訊息接聽器函數在處理訊息時必須參照的所有資訊。XMS 不會建立環境定義資料的副本,因此,當 XMS 呼叫訊息接聽器函數時,應用程式必須確定環境定義資料仍為可用的。
請注意,應用程式有責釋放非同步接收之訊息所用的資源。XMS 不會釋放這些資源。
若要停止非同步遞送訊息給訊息使用端, 應用程式可再次呼叫 xmsMsgConsumerSetMessageListener() 函數, 此時會將訊息接聽器函數的空值指標(而非指標)當成參數傳遞。
新訊息接聽器函數和環境定義資料可向訊息使用端登錄,而不需取消現有訊息接聽器函數的登錄。當登錄新訊息接聽器函數時, 如果現有訊息接聽器函數正在執行,則作用中的訊息接聽器函數仍會正常完成, 而任何後續的訊息則藉由呼叫新訊息接聽器函數來處理。當訊息接聽器函數有變時, 若有交易正在進行,則交易會藉由呼叫新訊息接聽器函數來完成。
如需訊息接聽器函數的相關資訊(包括其簽章),請參閱 MessageListener。
異常狀況接聽器函數的使用原則和訊息接聽器函數相同。
C 應用程式必須向連線登錄一個異常狀況接聽器函數,其做法是呼叫 xmsConnSetExceptionListener() 函數,將異常狀況接聽器函數和環境定義資料的指標當成參數傳遞。異常狀況接聽器函數是一種由使用者撰寫的回呼函數。如果 XMS 偵測到連線問題, XMS 會呼叫異常狀況接聽器函數, 以便將環境定義資料的指標當成一個參數傳遞,以及將錯誤區塊的控點當成另一個參數傳遞。
環境定義資料含有異常狀況接聽器函數在處理錯誤區塊時必須參照的所有資訊。而在其他所有方面中, 環境定義資料搭配異常狀況接聽器函數的用法,和其搭配訊息接聽器函數一樣。
如需異常狀況接聽器函數的相關資訊(包括其簽章),請參閱 MessageListener。
請注意,應用程式有責釋放以相同方式接收之錯誤區塊所用的資源。XMS 不會釋放這些資源。
若要停止非同步報告連線問題, 應用程式可再次呼叫 xmsConnSetExceptionListener() 函數, 此時會將異常狀況接聽器函數的空值指標(而非指標)當成參數傳遞。