WebSphere Message Service Clients for C/C++ and .NET, Version 1.2 作業系統: Linux, Windows

Message

Message 物件代表應用程式所傳送或接收的一則訊息。

繼承階層:
xms::PropertyContext
   |
   +----xms::Message

有關 Message 物件中的 JMS 訊息標頭欄位清單,請參閱XMS 訊息中的標頭欄位。有關 JMS 所定義的 Message 物件內容清單, 請參閱JMS 定義的訊息內容。有關 IBM 所定義的 Message 物件內容清單,請參閱IBM 定義的訊息內容

相關參考
XMS 訊息

方法

方法摘要:
方法 說明
~Message 刪除訊息。
acknowledge 確認此訊息以及階段作業所收到的所有先前未確認的訊息。
clearBody 清除訊息的主體。
clearProperties 清除訊息的內容。
getHandle 取得 C 應用程式在存取訊息時所要使用的控點。
getJMSCorrelationID 取得訊息的相互關係 ID。
getJMSDeliveryMode 取得訊息的遞送模式。
getJMSDestination 取得訊息的目的地。
getJMSExpiration 取得訊息的有效期限。
getJMSMessageID 取得訊息的訊息 ID。
getJMSPriority 取得訊息的優先順序。
getJMSRedelivered 取得訊息是否正在重新遞送的指示。
getJMSReplyTo 取得訊息回覆將送往的目的地。
getJMSTimestamp 取得訊息的傳送時間。
getJMSType 取得訊息的類型。
getProperties 取得訊息的內容清單。
isNull 判斷 Message 物件是否為一個空值物件。
propertyExists 檢查訊息是否含有一個指定名稱的內容。
setJMSCorrelationID 設定訊息的相互關係 ID。
setJMSDeliveryMode 設定訊息的遞送模式。
setJMSDestination 設定訊息的目的地。
setJMSExpiration 設定訊息的有效期限。
setJMSMessageID 設定訊息的訊息 ID。
setJMSPriority 設定訊息的優先順序。
setJMSRedelivered 指出訊息是否正在重新遞送。
setJMSReplyTo 設定訊息回覆將送往的目的地。
setJMSTimestamp 設定訊息的傳送時間。
setJMSType 設定訊息的類型。

~Message – 刪除訊息

介面:
virtual ~Message();

刪除訊息。

如果應用程式試著刪除已刪除的訊息, 則會忽略該呼叫。

參數:
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

acknowledge – 確認

介面:
xmsVOID acknowledge();

確認此訊息以及階段作業所收到的所有先前未確認的訊息。

如果階段作業的確認模式為 XMSC_CLIENT_ACKNOWLEDGE, 則應用程式可呼叫這個方法。如果階段作業具有其他任何的確認模式或者為交易式, 則會忽略方法的呼叫。

已收到但未確認的訊息可能會重新遞送。

如需確認訊息的相關資訊, 請參閱在階段作業中確認收到訊息

參數:
傳回:
Void
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION

clearBody – 清除主體

介面:
xmsVOID clearBody();

清除訊息的主體。標頭欄位和訊息內容不會清除。

如果應用程式清除訊息主體, 該主體所處的狀態和新建訊息中的空主體一樣。新建訊息中之空主體的狀態視訊息主體的類型而定。如果需要詳細資訊,請參閱XMS 訊息的主體

不論訊息主體處於何種狀態, 應用程式隨時都可以將它清除。如果訊息主體為唯讀, 應用程式唯一能寫入主體的方法是先清除主體。

參數:
傳回:
Void
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

clearProperties – 清除內容

介面:
xmsVOID clearProperties();

清除訊息的內容。標頭欄位和訊息主體不會清除。

如果應用程式清除訊息的內容, 則內容即變成可讀寫。

不論訊息內容處於何種狀態, 應用程式隨時都可以將它清除。如果訊息內容為唯讀, 唯一可將內容變成可寫入的方法是先讓應用程式清除內容。

參數:
傳回:
Void
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

getHandle – 取得控點

介面:
xmsHMsg getHandle() const;

取得 C 應用程式在存取訊息時所要使用的控點。

參數:
傳回:
訊息的控點。
執行緒環境定義:
任何
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

getJMSCorrelationID – 取得 JMSCorrelationID

介面:
String getJMSCorrelationID() const;

取得訊息的相互關係 ID。

參數:
傳回:
封裝相互關係 ID 的 String 物件。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

getJMSDeliveryMode – 取得 JMSDeliveryMode

介面:
xmsINT getJMSDeliveryMode() const;

取得訊息的遞送模式。遞送模式是在傳送訊息時由 MessageProducer.send() 呼叫所設。

參數:
傳回:
訊息的遞送模式,其值為下列之一:
  • XMSC_DELIVERY_PERSISTENT
  • XMSC_DELIVERY_NON_PERSISTENT

如果是尚未傳送的新建訊息,遞送模式為 XMSC_DELIVERY_PERSISTENT,但如果是和分配管理系統間的即時連線, 則遞送模式會是 XMSC_DELIVERY_NON_PERSISTENT。如果是已接收的訊息, 方法會傳回當初在傳送訊息時由 MessageProducer.send() 呼叫所設的遞送模式, 除非接收端應用程式因呼叫 setJMSDeliveryMode() 而變更了遞送模式。

異常狀況:
  • XMS_X_GENERAL_EXCEPTION

getJMSDestination – 取得 JMSDestination

介面:
Destination getJMSDestination() const;

取得訊息的目的地。目的地是在傳送訊息時由 MessageProducer.send() 呼叫所設。

參數:
傳回:
Destination 物件。

如果是尚未傳送的新建訊息,方法會傳回一個空值 Destination 物件並擲出一個 錯誤碼為 XMS_E_NOT_SET 的異常狀況, 除非傳送端應用程式因呼叫 setJMSDestination() 而設定了一個目的地。如果是已接收的訊息, 方法會傳回當初在傳送訊息時由 MessageProducer.send() 呼叫所設之目的地的 Destination 物件, 除非接收端應用程式因呼叫 setJMSDestination() 而變更了目的地。

異常狀況:
  • XMS_X_GENERAL_EXCEPTION

getJMSExpiration – 取得 JMSExpiration

介面:
xmsLONG getJMSExpiration() const;

取得訊息的有效期限。

有效期限是在傳送訊息時由 MessageProducer.send() 呼叫所設。其值的計算方式是, 傳送端應用程式指定的存活時間加上送出訊息的時間。有效期限是以毫秒表示, 並從 1970 年 1 月 1 日 00:00:00 GMT 開始。

如果存活時間為 0, 則 MessageProducer.send() 呼叫會將有效期限設為 0,表示該訊息沒有期限。

XMS 會捨棄過期的訊息,而不會遞送給應用程式。

參數:
傳回:
訊息的有效期限。

如果是尚未傳送的新建訊息,則有效期限為 0, 除非傳送端應用程式因呼叫 setJMSExpiration() 而設定了一個不同的有效期限。如果是已接收的訊息, 方法會傳回當初在傳送訊息時由 MessageProducer.send() 呼叫所設的有效期限, 除非接收端應用程式因呼叫 setJMSExpiration() 而變更了有效期限。

異常狀況:
  • XMS_X_GENERAL_EXCEPTION

getJMSMessageID – 取得 JMSMessageID

介面:
String getJMSMessageID() const;

取得訊息的訊息 ID。訊息 ID 是在傳送訊息時由 MessageProducer.send() 呼叫所設。

參數:
傳回:
封裝訊息 ID 的 String 物件。

如果是已接收的訊息, 方法會傳回當初在傳送訊息時由 MessageProducer.send() 呼叫所設的訊息 ID, 除非接收端應用程式因呼叫 setJMSMessageID() 而變更了訊息 ID。

異常狀況:
  • XMS_X_GENERAL_EXCEPTION
附註:
  1. 如果訊息沒有訊息 ID,則方法會擲出一個錯誤碼為 XMS_E_NOT_SET 的異常狀況。

getJMSPriority – 取得 JMSPriority

介面:
xmsINT getJMSPriority() const;

取得訊息的優先順序。優先順序是在傳送訊息時由 MessageProducer.send() 呼叫所設。

參數:
傳回:
訊息的優先順序。此值為一個 0(最低優先順序)到 9(最高優先順序)範圍間的整數。

如果是尚未傳送的新建訊息, 則優先順序為 4, 除非傳送端應用程式因呼叫 setJMSPriority() 而設定了一個不同的優先順序。如果是已接收的訊息, 方法會傳回當初在傳送訊息時由 MessageProducer.send() 呼叫所設的優先順序, 除非接收端應用程式因呼叫 setJMSPriority() 而變更了優先順序。

異常狀況:
  • XMS_X_GENERAL_EXCEPTION

getJMSRedelivered – 取得 JMSRedelivered

介面:
xmsBOOL getJMSRedelivered() const;

取得訊息是否正在重新遞送的指示。此指示是在接收訊息時由 MessageConsumer.receive() 呼叫所設。

參數:
傳回:
  • 如果正在重新遞送訊息,則為 xmsTRUE
  • 如果不在重新遞送訊息,則為 xmsFALSE

若為和分配管理系統間的即時連線, 方法會固定傳回 xmsFALSE

異常狀況:
  • XMS_X_GENERAL_EXCEPTION

getJMSReplyTo – 取得 JMSReplyTo

介面:
Destination getJMSReplyTo() const;

取得訊息回覆將送往的目的地。

參數:
傳回:
訊息回覆將送往之目的地的 Destination 物件。空值 Destination 物件表示不預期會有回覆。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

getJMSTimestamp – 取得 JMSTimestamp

介面:
xmsLONG getJMSTimestamp() const;

取得訊息的傳送時間。時間戳記是在傳送訊息時由 MessageProducer.send() 呼叫所設, 是以毫秒表示,並從 1970 年 1 月 1 日 00:00:00 GMT 開始。

參數:
傳回:
訊息的傳送時間。

如果是尚未傳送的新建訊息,則時間戳記為 0, 除非傳送端應用程式因呼叫 setJMSTimestamp() 而設定了一個不同的時間戳記。如果是已接收的訊息, 方法會傳回當初在傳送訊息時由 MessageProducer.send() 呼叫所設的時間戳記, 除非接收端應用程式因呼叫 setJMSTimestamp() 而變更了時間戳記。

異常狀況:
  • XMS_X_GENERAL_EXCEPTION
附註:
  1. 如果未定義時間戳記,則方法會傳回 0,但不會傳回任何異常狀況。

getJMSType – 取得 JMSType

介面:
String getJMSType() const;

取得訊息的類型。

參數:
傳回:
封裝訊息類型的 String。如果需要轉換資料, 則此為轉換後的類型。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

getProperties – 取得內容

介面:
Iterator getProperties() const;

取得訊息的內容清單。

此方法會傳回一個疊代子, 其中封裝了一份 Properties 物件清單。如此一來, 應用程式可使用疊代子依序存取每一個內容。

註: 同等 JMS 方法所執行的功能略有差異。JMS 方法會傳回訊息內容名稱的列舉表, 但其中不含其值。
參數:
傳回:
Iterator 物件。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

isNull – 檢查是否為空值

介面:
xmsBOOL isNull() const;

判斷 Message 物件是否為一個空值物件。

參數:
傳回:
  • 如果 Message 物件為空值物件,則為 xmsTRUE
  • 如果 Message 物件不是空值物件,則為 xmsFALSE
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

propertyExists – 檢查內容是否存在

介面:
xmsBOOL propertyExists(const String & propertyName) const;

檢查訊息是否含有一個指定名稱的內容。

參數:
propertyName(輸入)
封裝內容名稱的 String 物件。
傳回:
  • 如果訊息含有一個指定名稱的內容,則為 xmsTRUE
  • 如果訊息沒有一個指定名稱的內容,則為 xmsFALSE
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

setJMSCorrelationID – 設定 JMSCorrelationID

介面:
xmsVOID setJMSCorrelationID(const String correlID);

設定訊息的相互關係 ID。

參數:
correlID(輸入)
封裝相互關係 ID 的 String 物件。
傳回:
Void
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

setJMSDeliveryMode – 設定 JMSDeliveryMode

介面:
xmsVOID setJMSDeliveryMode(const xmsINT deliveryMode);

設定訊息的遞送模式。

在傳送訊息前由此方法所設的遞送模式會被忽略, 並在傳送訊息時由 MessageProducer.send() 呼叫所取代。不過,您可以使用此方法來變更已接收之訊息的遞送模式。

參數:
deliveryMode(輸入)
訊息的遞送模式,其值必須是下列之一:
  • XMSC_DELIVERY_PERSISTENT
  • XMSC_DELIVERY_NON_PERSISTENT
傳回:
Void
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

setJMSDestination – 設定 JMSDestination

介面:
xmsVOID setJMSDestination(const Destination & destination);

設定訊息的目的地。

在傳送訊息前由此方法所設的目的地會被忽略, 並在傳送訊息時由 MessageProducer.send() 呼叫所取代。不過,您可以使用此方法來變更已接收之訊息的目的地。

參數:
destination(輸入)
代表訊息目的地的 Destination 物件。
傳回:
Void
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

setJMSExpiration – 設定 JMSExpiration

介面:
xmsVOID setJMSExpiration(const xmsLONG expiration);

設定訊息的有效期限。

在傳送訊息前由此方法所設的有效期限會被忽略, 並在傳送訊息時由 MessageProducer.send() 呼叫所取代。不過,您可以使用此方法來變更已接收之訊息的有效期限。

參數:
expiration(輸入)
訊息的有效期限是以毫秒表示, 並從 1970 年 1 月 1 日 00:00:00 GMT 開始。
傳回:
Void
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

setJMSMessageID – 設定 JMSMessageID

介面:
xmsVOID setJMSMessageID(const String & msgID);

設定訊息的訊息 ID。

在傳送訊息前由此方法所設的訊息 ID 會被忽略, 並在傳送訊息時由 MessageProducer.send() 呼叫所取代。不過,您可以使用此方法來變更已接收之訊息的訊息 ID。

參數:
msgID(輸入)
封裝訊息 ID 的 String 物件。
傳回:
Void
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

setJMSPriority – 設定 JMSPriority

介面:
xmsVOID setJMSPriority(const xmsINT priority);

設定訊息的優先順序。

在傳送訊息前由此方法所設的優先順序會被忽略, 並在傳送訊息時由 MessageProducer.send() 呼叫所取代。不過,您可以使用此方法來變更已接收之訊息的優先順序。

參數:
priority(輸入)
訊息的優先順序。此值可以是一個 0(最低優先順序)到 9(最高優先順序)範圍間的整數。
傳回:
Void
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

setJMSRedelivered – 設定 JMSRedelivered

介面:
xmsVOID setJMSRedelivered(const xmsBOOL redelivered);

指出訊息是否正在重新遞送。

在傳送訊息前由此方法所設的重新遞送指示會被 MessageProducer.send() 呼叫忽略, 並在接收訊息時由 MessageConsumer.receive() 呼叫所取代。不過,您可以使用此方法來變更已接收之訊息的指示。

參數:
redelivered(輸入)
xmsTRUE 表示正在重新遞送訊息。值 xmsFALSE 表示並未重新遞送訊息。
傳回:
Void
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

setJMSReplyTo – 設定 JMSReplyTo

介面:
xmsVOID setJMSReplyTo(const Destination & destination);

設定訊息回覆將送往的目的地。

參數:
destination(輸入)
代表訊息回覆將送往之目的地的 Destination 物件。空值 Destination 物件表示不預期會有回覆。
傳回:
Void
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

setJMSTimestamp – 設定 JMSTimestamp

介面:
xmsVOID setJMSTimestamp(const xmsLONG timeStamp);

設定訊息的傳送時間。

在傳送訊息前由此方法所設的時間戳記會被忽略, 並在傳送訊息時由 MessageProducer.send() 呼叫所取代。不過,您可以使用此方法來變更已接收之訊息的時間戳記。

參數:
timeStamp(輸入)
訊息的傳送時間是以毫秒表示, 並從 1970 年 1 月 1 日 00:00:00 GMT 開始。
傳回:
Void
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

setJMSType – 設定 JMSType

介面:
xmsVOID setJMSType(const String & type);

設定訊息的類型。

參數:
type(輸入)
封裝訊息類型的 String 物件。
傳回:
Void
異常狀況:
  • XMS_X_GENERAL_EXCEPTION

繼承的方法


Reference topic

使用條款 | 評比此網頁

時間戳記前次更新: 25 Apr 2006
(C) Copyright IBM Corporation 2005. All Rights Reserved.
本資訊中心採用 Eclipse 技術。(http://www.eclipse.org)