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

BytesMessage

位元組訊息是一種其主體包含一個位元組串流的訊息。

相關參考
位元組訊息

函數

函數摘要:
函數 說明
xmsBytesMsgGetBodyLength 在訊息主體為唯讀時,取得訊息主體的長度。
xmsBytesMsgReadBoolean 從位元組訊息串流中讀取 Boolean 值。
xmsBytesMsgReadByte 從位元組訊息串流中讀取下一個位元組, 以當成一個帶正負號的 8 位元整數。
xmsBytesMsgReadBytes 在位元組訊息串流中,從游標的現行位置開始讀取位元組陣列。
xmsBytesMsgReadBytesByRef 取得指向位元組訊息串流開頭的指標,以及取得字串的長度。
xmsBytesMsgReadChar 從位元組訊息串流中讀取下兩個位元組,以當成一個字元。
xmsBytesMsgReadDouble 從位元組訊息串流中讀取下 8 個位元組, 以當成一個倍精準度浮點數。
xmsBytesMsgReadFloat 從位元組訊息串流中讀取下 4 個位元組, 以當成一個浮點數。
xmsBytesMsgReadInt 從位元組訊息串流中讀取下 4 個位元組, 以當成一個帶正負號的 32 位元整數。
xmsBytesMsgReadLong 從位元組訊息串流中讀取下 8 個位元組, 以當成一個帶正負號的 64 位元整數。
xmsBytesMsgReadShort 從位元組訊息串流中讀取下 2 個位元組, 以當成一個帶正負號的 16 位元整數。
xmsBytesMsgReadUnsignedByte 從位元組訊息串流中讀取下一個位元組, 以當成一個不帶正負號的 8 位元整數。
xmsBytesMsgReadUnsignedShort 從位元組訊息串流中讀取下 2 個位元組, 以當成一個不帶正負號的 16 位元整數。
xmsBytesMsgReadUTF 從位元組訊息串流讀取一個以 UTF-8 編碼的字串。
xmsBytesMsgReset 將訊息主體變成唯讀模式, 並將游標重新定位在位元組訊息串流開頭。
xmsBytesMsgWriteBoolean 將 Boolean 值寫入位元組訊息串流中。
xmsBytesMsgWriteByte 將位元組寫入位元組訊息串流中。
xmsBytesMsgWriteBytes 將位元組陣列寫入位元組訊息串流中。
xmsBytesMsgWriteChar 將字元當成 2 位元組寫入位元組訊息串流中, 並從次序高的位元組開始。
xmsBytesMsgWriteDouble 將倍精準度浮點數轉換成長整數, 並將長整數當成 8 位元組寫入位元組訊息串流中,且從次序高的位元組開始。
xmsBytesMsgWriteFloat 將浮點數轉換成整數, 並將整數當成 4 位元組寫入位元組訊息串流中,且從次序高的位元組開始。
xmsBytesMsgWriteInt 將整數當成 4 位元組寫入位元組訊息串流中, 並從次序高的位元組開始。
xmsBytesMsgWriteLong 將長整數當成 8 位元組寫入位元組訊息串流中, 並從次序高的位元組開始。
xmsBytesMsgWriteShort 將短整數當成 2 位元組寫入位元組訊息串流中, 並從次序高的位元組開始。
xmsBytesMsgWriteUTF 將以 UTF-8 編碼的字串寫入位元組訊息串流中。

xmsBytesMsgGetBodyLength – 取得主體長度

介面:
xmsRC xmsBytesMsgGetBodyLength(xmsHMsg message,
                               xmsLONG *bodyLength,
                               xmsHErrorBlock errorBlock);

在訊息主體為唯讀時,取得訊息主體的長度。

參數:
message(輸入)
訊息的控點。
bodyLength(輸出)
訊息主體的長度(以位元組計)。此函數會傳回整個主體的長度,而不管讀取訊息的游標目前位於何處。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION

xmsBytesMsgReadBoolean – 讀取 Boolean 值

介面:
xmsRC xmsBytesMsgReadBoolean(xmsHMsg message,
                             xmsBOOL *value,
                             xmsHErrorBlock errorBlock);

從位元組訊息串流中讀取 Boolean 值。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的 Boolean 值。如果您在輸入中指定一個空值指標, 則函數會略過 Boolean 值而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadByte – 讀取位元組

介面:
xmsRC xmsBytesMsgReadByte(xmsHMsg message,
                          xmsSBYTE *value,
                          xmsHErrorBlock errorBlock);

從位元組訊息串流中讀取下一個位元組, 以當成一個帶正負號的 8 位元整數。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的位元組。如果您在輸入中指定一個空值指標, 則函數會略過該位元組而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadBytes – 讀取位元組

介面:
xmsRC xmsBytesMsgReadBytes(xmsHMsg message,
                           xmsSBYTE *buffer,
                           xmsINT bufferLength,
                           xmsINT *returnedLength,
                           xmsHErrorBlock errorBlock);

在位元組訊息串流中,從游標的現行位置開始讀取位元組陣列。

參數:
message(輸入)
訊息的控點。
buffer(輸出)
內含所讀取之位元組陣列的緩衝區。如果在呼叫前,要從串流中讀取的剩餘位元組數, 大於或等於緩衝區長度,則會填入緩衝區中。否則,緩衝區只是被局部填入所有剩餘的位元組。

如果您在輸入中指定一個空值指標, 則函數會略過位元組而不會讀取。如果在呼叫前,要從串流中讀取的剩餘位元組數, 大於或等於緩衝區的長度,則所略過的位元組數等於緩衝區長度。否則,會略過所有剩餘的位元組。

bufferLength(輸入)
緩衝區的長度(以位元組計)。如果您指定的是 XMSC_QUERY_SIZE, 則不會將位元組讀入緩衝區中,但串流中所剩的位元組數(從游標的現行位置算起)會放在 returnedLength 參數中傳回,且游標不會前進。
returnedLength(輸出)
要讀入緩衝區中的位元組數。如果緩衝區只被局部填入, 則其值小於緩衝區長度,這表示已無位元組要讀取。在呼叫前,如果串流中已無留待讀取的位元組, 則其值為 XMSC_END_OF_STREAM

如果您在輸入中指定一個空值指標, 則函數不會傳回任何值。

errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadBytesByRef – 讀取參照形式的位元組

介面:
xmsRC xmsBytesMsgReadBytesByRef(xmsHMsg message,
                                xmsSBYTE **stream,
                                xmsINT *length,
                                xmsHErrorBlock errorBlock);

取得指向位元組訊息串流開頭的指標,以及取得字串的長度。

如需如何使用此函數的相關資訊, 請參閱會以參照形式來傳回字串或位元組陣列的 C 函數

參數:
message(輸入)
訊息的控點。
stream(輸出)
指向位元組訊息串流開頭的指標。
length(輸出)
位元組訊息串流中的位元組數。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadChar – 讀取字元

介面:
xmsRC xmsBytesMsgReadChar(xmsHMsg message,
                          xmsCHAR16 *value,
                          xmsHErrorBlock errorBlock);

從位元組訊息串流中讀取下兩個位元組,以當成一個字元。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的字元。如果您在輸入中指定一個空值指標, 則函數會略過位元組而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadDouble – 讀取倍精準度浮點數

介面:
xmsRC xmsBytesMsgReadDouble(xmsHMsg message,
                            xmsDOUBLE *value,
                            xmsHErrorBlock errorBlock);

從位元組訊息串流中讀取下 8 個位元組, 以當成一個倍精準度浮點數。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的倍精準度浮點數。如果您在輸入中指定一個空值指標, 則函數會略過位元組而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadFloat – 讀取浮點數

介面:
xmsRC xmsBytesMsgReadFloat(xmsHMsg message,
                           xmsFLOAT *value,
                           xmsHErrorBlock errorBlock);

從位元組訊息串流中讀取下 4 個位元組, 以當成一個浮點數。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的浮點數。如果您在輸入中指定一個空值指標, 則函數會略過位元組而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadInt – 讀取整數

介面:
xmsRC xmsBytesMsgReadInt(xmsHMsg message,
                         xmsINT *value,
                         xmsHErrorBlock errorBlock);

從位元組訊息串流中讀取下 4 個位元組, 以當成一個帶正負號的 32 位元整數。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的整數。如果您在輸入中指定一個空值指標, 則函數會略過位元組而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadLong – 讀取長整數

介面:
xmsRC xmsBytesMsgReadLong(xmsHMsg message,
                          xmsLONG *value,
                          xmsHErrorBlock errorBlock);

從位元組訊息串流中讀取下 8 個位元組, 以當成一個帶正負號的 64 位元整數。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的長整數。如果您在輸入中指定一個空值指標, 則函數會略過位元組而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadShort – 讀取短整數

介面:
xmsRC xmsBytesMsgReadShort(xmsHMsg message,
                           xmsSHORT *value,
                           xmsHErrorBlock errorBlock);

從位元組訊息串流中讀取下 2 個位元組, 以當成一個帶正負號的 16 位元整數。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的短整數。如果您在輸入中指定一個空值指標, 則函數會略過位元組而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadUnsignedByte – 讀取不帶正負號的位元組

介面:
xmsRC xmsBytesMsgReadUnsignedByte(xmsHMsg message,
                                  xmsBYTE *value,
                                  xmsHErrorBlock errorBlock);

從位元組訊息串流中讀取下一個位元組, 以當成一個不帶正負號的 8 位元整數。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的位元組。如果您在輸入中指定一個空值指標, 則函數會略過該位元組而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadUnsignedShort – 讀取不帶正負號的短整數

介面:
xmsRC xmsBytesMsgReadUnsignedShort(xmsHMsg message,
                                   xmsUSHORT *value,
                                   xmsHErrorBlock errorBlock);

從位元組訊息串流中讀取下 2 個位元組, 以當成一個不帶正負號的 16 位元整數。

參數:
message(輸入)
訊息的控點。
value(輸出)
所讀取的不帶正負號短整數。如果您在輸入中指定一個空值指標, 則函數會略過位元組而不會讀取。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadUTF – 讀取 UTF 字串

介面:
xmsRC xmsBytesMsgReadUTF(xmsHMsg message,
                         xmsCHAR *buffer,
                         xmsINT bufferLength,
                         xmsINT *actualLength,
                         xmsHErrorBlock errorBlock);

從位元組訊息串流讀取一個以 UTF-8 編碼的字串。 必要時, XMS 會將字串中的字元從 UTF-8 轉換成區域字碼頁。

如需如何使用此函數的相關資訊, 請參閱會以值形式來傳回字串的 C 函數

參數:
message(輸入)
訊息的控點。
buffer(輸出)
內含所讀取之字串的緩衝區。如果需要轉換資料, 則此為轉換後的字串。
bufferLength(輸入)
緩衝區的長度(以位元組計)。

如果您指定 XMSC_QUERY_SIZE, 則不會傳回字串,而會將其長度放在 actualLength 參數中傳回,且游標不會前進。

如果您指定 XMSC_SKIP, 則函數會略過該字串而不會讀取。

actualLength(輸出)
字串的長度(以位元組計)。如果需要轉換資料, 則此為轉換後的字串長度。如果您在輸入中指定一個空值指標, 則不會傳回長度。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
  • XMS_X_MESSAGE_EOF_EXCEPTION
附註:
  1. 如果緩衝區不夠儲存整個字串,XMS 會傳回截斷成符合緩衝區長度的字串, 而將 actualLength 參數設為字串的實際長度,並傳回 XMS_E_DATA_TRUNCATED 錯誤碼。XMS 不會使內部游標前進。
  2. 如果在試著讀取字串期間發生其他任何錯誤, XMS 會報告錯誤,但不會設定 actualLength 參數或使內部游標前進。

xmsBytesMsgReset – 重設

介面:
xmsRC xmsBytesMsgReset(xmsHMsg message,
                       xmsHErrorBlock errorBlock);

將訊息主體變成唯讀模式, 並將游標重新定位在位元組訊息串流開頭。

參數:
message(輸入)
訊息的控點。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_READABLE_EXCEPTION

xmsBytesMsgWriteBoolean – 寫入 Boolean 值

介面:
xmsRC xmsBytesMsgWriteBoolean(xmsHMsg message,
                              xmsBOOL value,
                              xmsHErrorBlock errorBlock);

將 Boolean 值寫入位元組訊息串流中。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的 Boolean 值。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteByte – 寫入位元組

介面:
xmsRC xmsBytesMsgWriteByte(xmsHMsg message,
                           xmsSBYTE value,
                           xmsHErrorBlock errorBlock);

將位元組寫入位元組訊息串流中。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的位元組。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteBytes – 寫入多個位元組

介面:
xmsRC xmsBytesMsgWriteBytes(xmsHMsg message,
                            xmsSBYTE *value,
                            xmsINT length,
                            xmsHErrorBlock errorBlock);

將位元組陣列寫入位元組訊息串流中。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的位元組陣列。
length(輸入)
陣列中的位元組數。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteChar – 寫入字元

介面:
xmsRC xmsBytesMsgWriteChar(xmsHMsg message,
                           xmsCHAR16 value,
                           xmsHErrorBlock errorBlock);

將字元當成 2 位元組寫入位元組訊息串流中, 並從次序高的位元組開始。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的字元。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteDouble – 寫入倍精準度浮點數

介面:
xmsRC xmsBytesMsgWriteDouble(xmsHMsg message,
                             xmsDOUBLE value,
                             xmsHErrorBlock errorBlock);

將倍精準度浮點數轉換成長整數, 並將長整數當成 8 位元組寫入位元組訊息串流中,且從次序高的位元組開始。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的倍精準度浮點數。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteFloat – 寫入浮點數

介面:
xmsRC xmsBytesMsgWriteFloat(xmsHMsg message,
                            xmsFLOAT value,
                            xmsHErrorBlock errorBlock);

將浮點數轉換成整數, 並將整數當成 4 位元組寫入位元組訊息串流中,且從次序高的位元組開始。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的浮點數。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteInt – 寫入整數

介面:
xmsRC xmsBytesMsgWriteInt(xmsHMsg message,
                          xmsINT value,
                          xmsHErrorBlock errorBlock);

將整數當成 4 位元組寫入位元組訊息串流中, 並從次序高的位元組開始。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的整數。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteLong – 寫入長整數

介面:
xmsRC xmsBytesMsgWriteLong(xmsHMsg message,
                           xmsLONG value,
                           xmsHErrorBlock errorBlock);

將長整數當成 8 位元組寫入位元組訊息串流中, 並從次序高的位元組開始。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的長整數。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteShort – 寫入短整數

介面:
xmsRC xmsBytesMsgWriteShort(xmsHMsg message,
                            xmsSHORT value,
                            xmsHErrorBlock errorBlock);

將短整數當成 2 位元組寫入位元組訊息串流中, 並從次序高的位元組開始。

參數:
message(輸入)
訊息的控點。
value(輸入)
要寫入的短整數。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteUTF – 寫入 UTF 字串

介面:
xmsRC xmsBytesMsgWriteUTF(xmsHMsg message,
                          xmsCHAR *value,
                          xmsINT length,
                          xmsHErrorBlock errorBlock);

將以 UTF-8 編碼的字串寫入位元組訊息串流中。 必要時,XMS 會將字串中的字元從區域字碼頁轉換成 UTF-8。

參數:
message(輸入)
訊息的控點。
value(輸入)
內含所要寫入之字串的字元陣列。
length(輸入)
字串的長度(以位元組計)。如果字串在沒有內嵌空值字元下空值終止, 您可以指定 XMSC_CALCULATE_STRING_SIZE,以容許 XMS 計算其長度。
errorBlock(輸入)
錯誤區塊的控點或空值控點。
異常狀況:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

Reference topic

使用條款 | 評比此網頁

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