這個主題說明以值形式來傳回字串之 C 函數所用的介面。
在 C API 中,某些函數會以參數形式傳回字串。這些函數皆使用相同的介面來擷取字串。以下是
PropertyContext 類別中的
xmsGetStringProperty() 函數(為這些函數之一)範例:
xmsRC xmsGetStringProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsCHAR *propertyValue,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);
以下三個參數控制字串的擷取:
- propertyValue
- 此參數為應用程式所提供之緩衝區的指標,
而 XMS 會將字串中的字元複製到這個緩衝區中。如果需要轉換資料,
XMS 會在將字元複製到緩衝區前,先轉換成應用程式所用的字碼頁。
- length
- 這個參數為緩衝區的長度(以位元組計)。應用程式在呼叫前必須先設定這個輸入參數。如果您指定的是 XMSC_QUERY_SIZE,
則不會傳回字串,而會將其長度放在 actualLength 參數中傳回。
- actualLength
- 這個輸出參數是 XMS 要複製到緩衝區中的字串長度。如果需要轉換資料,
則此為轉換後的長度。長度是以位元組為單位。XMS 會固定傳回一個空值終止字串,
且報告給應用程式的長度包含終止空值字元。如果您在輸入中為這個參數指定一個空值指標,
則不會傳回字串的長度。
如果緩衝區不夠儲存整個字串(包括終止中的空值字元),
XMS 會傳回截斷成符合緩衝區長度的字串,
以及將 actualLength 參數設為整個字串的長度,並傳回 XMS_E_DATA_TRUNCATED 錯誤碼。
請注意,如果 XMS 應用程式收到 JMS 應用程式所送的訊息,
則標頭欄位中的字串、內容以及訊息主體中可能含有內嵌空值字元。您無法使用標準 C 字串操作函數來處理含有內嵌空值的字串,
這是因為這些函數會假設字串中的第一個空值字元標示了字串的結束。