共用方式為

IMAPIProp：：GetProps

  • 發行項

適用於：Outlook 2013 |Outlook 2016

擷取物件之一或多個屬性的屬性值。

HRESULT GetProps(
  LPSPropTagArray lpPropTagArray,
  ULONG ulFlags,
  ULONG FAR * lpcValues,
  LPSPropValue FAR * lppPropArray
);

參數

lpPropTagArray

[in]屬性標記陣列的指標，識別要擷取其值的屬性。 lpPropTagArray 參數必須是 NULL，表示應該傳回物件之所有屬性的值，或指向包含一或多個屬性標記的 SPropTagArray 結構。

ulFlags

[in]旗標的位掩碼，表示類型為 PT_UNSPECIFIED 之屬性的格式。 您可以設定下列旗標：

MAPI_UNICODE

這些屬性的字串值應該以 Unicode 格式傳回。 如果未設定MAPI_UNICODE旗標，則應該以 ANSI 格式傳回字串值。

lpcValues

[out] lppPropArray 參數所指向之屬性值計數的指標。 如果 lppPropArray 為 NULL， 則 lpcValues 參數的內容為零。

lppPropArray

[out]指向所擷取屬性值之指標的指標。

傳回值

S_OK

已成功擷取屬性值。

MAPI_W_ERRORS_RETURNED

呼叫整體成功，但無法存取一或多個屬性。 每個無法使用屬性之屬性值的 aulPropTag 成員的屬性類型為 PT_ERROR 且標識碼為零。 傳回此警告時，應將呼叫視為成功處理。 若要測試此警告，請使用 HR_FAILED 宏。 如需詳細資訊，請 參閱使用宏進行錯誤處理。

MAPI_E_INVALID_PARAMETER

lpPropTagArray 所指向之 SPropTagArray 結構的 cValues 成員中傳遞了零。

註解

IMAPIProp：：GetProps 方法會取得物件之一或多個屬性的屬性值。

屬性值的傳回順序與要求的順序相同， (也就是 lpPropTagArray 所指向之屬性標籤列中的屬性順序符合 lppPropArray) 所指向之屬性值結構數位中的順序。

屬性標記陣列的 aulPropTag 成員中指定的屬性類型會指出應該在每個屬性值結構的 Value 成員中傳回的值類型。 不過，如果呼叫端不知道屬性的類型，則 aulPropTag 成員中的類型可以改為設定為 PT_UNSPECIFIED。 在擷取值時， GetProps 會在屬性值結構的 aulPropTag 成員中設定正確的類型。

如果在 lpPropTagArray 的 SPropTagArray 中指定屬性類型，則在 lppPropArray 中傳回之 SPropValue 中的屬性值會具有完全符合所要求類型的類型，除非改為傳回錯誤值。

字串屬性可以有兩種屬性類型之一：PT_UNICODE表示 Unicode 格式，PT_STRING8表示 ANSI 格式。 如果在 ulFlags 參數中設定MAPI_UNICODE旗標，每當 GetProps 無法判斷字串屬性的適當格式時，就會以 Unicode 格式傳回其值。 在下列情況下，GetProps 無法判斷確切的字串屬性類型：

  • lpPropTagArray 參數設定為 NULL 以要求所有屬性。

  • aulPropTag 成員在屬性標記數位中包含值PT_UNSPECIFIED為其屬性類型。

如果 lpPropTagArray 參數設定為 NULL 以擷取物件的所有屬性，而且沒有任何屬性存在， GetProps 會執行下列動作：

  • 傳回S_OK。

  • 將屬性值結構 之 cValues 成員中的計數值設定為 0。

  • 將 lpcValues 的內容設定 為 0。

  • 將 lppPropArray 設定為 NULL。

GetProps 不得傳回 cValues 設為 0 的多重值屬性。

實作者注意事項

呼叫MAPIAllocateBuffer函式，一開始會為 lpPropTagArray 所指向的 SPropValue 結構配置記憶體;呼叫MAPIAllocateMore以配置結構成員所需的任何其他記憶體。

如果您無法擷取一或多個要求屬性的值，請傳回MAPI_W_ERRORS_RETURNED。 在屬性值結構中，將 aulPropTag 成員中的類型設定為 PT_ERROR，並將 Value 成員設定為描述錯誤的狀態代碼。 例如，如果您必須將字串轉換成 Unicode 且不支援 Unicode，請將 Value 成員設定為 MAPI_E_BAD_CHARWIDTH。 如果屬性太大，請將它設定為 MAPI_E_NOT_ENOUGH_MEMORY。 如果物件不支援 屬性，請將它設定為 MAPI_E_NOT_FOUND。

遠端傳輸提供者的 GetProps 方法實作必須針對呼叫端所要求的屬性傳回資料夾的 屬性值。 您的實作必須執行下列動作：

  • 配置屬性值陣列以返回呼叫端，並將其位址儲存在針對該目的傳入的屬性值指標參數中。

  • 根據傳遞至 GetProps 的屬性標記陣列，將屬性標籤從資料夾的屬性複製到屬性值陣列中的屬性標記。

  • 確定已針對傳遞至 GetProps 的所有屬性標記設定屬性類型。 呼叫端可以傳入PT_UNSPECIFIED的屬性類型，在此情況下 ，GetProps 必須為該屬性標記設定正確的屬性類型。

  • 根據屬性值陣列的標記，設定屬性值陣列中每個屬性的值。 例如，如果呼叫端要求的屬性標記 PR_OBJECT_TYPE (PidTagObjectType) ，GetProps 可以將值設定為 MAPI_FOLDER。

  • 如果呼叫端傳入實作未處理的任何屬性標記，您可以將屬性標記設定為這些屬性的PT_ERROR，並將屬性值設定為 MAPI_E_NOT_FOUND。

  • 如果未發生任何錯誤，則傳回S_OK，如果發生錯誤，則傳回 MAPI_W_ERRORS_RETURNED。

遠端傳輸提供者的 GetProps 方法實作至少必須支援下列屬性：

呼叫者注意事項

針對類型為 PT_OBJECT 的屬性，請呼叫 IMAPIProp：：OpenProperty 方法，而不是 GetProps。

針對安全屬性，請勿預期呼叫 GetProps 並將 lppPropTagArray 參數設定為 NULL 來擷取它們。 呼叫 GetProps 時，您必須在其屬性標籤陣列的 aulPropTag 成員中明確設定安全屬性的識別碼。 安全屬性可用的時機和方式，由服務提供者決定。

只有在 GetProps 傳回 S_OK 或 MAPI_W_ERRORS_RETURNED 時，才呼叫 MAPIFreeBuffer 函式來釋放傳回的 SPropValue 結構。

如果 GetProps 因為無法存取一或多個屬性而傳回MAPI_W_ERRORS_RETURNED，請檢查所傳回屬性的屬性標記。 失敗的屬性會在其屬性值結構中設定下列值：

  • aulPropTag成員中設為 PT_ERROR 的屬性類型。

  • Value 成員中的屬性值會設定為錯誤的狀態代碼，例如MAPI_E_NOT_FOUND。

因為屬性值結構中太大而無法方便傳回而失敗的屬性，其 Value 成員會設定為 MAPI_E_NOT_ENOUGH_MEMORY。 一般而言，當屬性的值為 4 KB 或更大時，就會發生PT_STRING8、PT_UNICODE或PT_BINARY類型的字串或二進位屬性。 呼叫 IMAPIProp：：OpenProperty 以擷取大型屬性。

並非所有 GetProps 實作都支援字元字串的 Unicode 和 ANSI 格式。 當特定屬性需要字串格式轉換，且 GetProps 無法支援它時，屬性的 Value 成員會設定為 MAPI_E_BAD_CHARWIDTH。

若要檢查 PST 是否為 SharePoint PST，請使用 IMAPISession：：OpenMsgStore 掛接 PST，然後在要求此屬性的訊息存放區對象上呼叫 GetProps 。 如果存在，您可以假設 PST 已針對 SharePoint 設定;如果沒有，則 PST 尚未設定為 SharePoint PST。

如需如何使用 GetProps 存取屬性的詳細資訊，請參閱 擷取 MAPI 屬性。

MFCMAPI 參考

如需 MFCMAPI 範例程式代碼，請參閱下表。

檔案 Function Comment
MAPIFunctions.cpp
 GetPropsNULL
 MFCMAPI 會使用 IMAPIProp：：GetProps 方法，在 lpPropTagArray 參數中傳遞 NULL 或 IMAPIProp：：GetPropList 方法所傳回的陣列，以取得物件的所有屬性。

另請參閱

IMAPIProp：：GetPropList

IMAPIProp：：OpenProperty

MAPIAllocateBuffer

MAPIAllocateMore

MAPIFreeBuffer

SPropTagArray

SPropValue

IMAPIProp：IUnknown

MFCMAPI 作為程式碼範例

擷取MAPI屬性

使用宏處理錯誤