IMAPIProp::GetProps

Artikel
04/04/2023

Gilt für: Outlook 2013 | Outlook 2016

Ruft den Eigenschaftswert einer oder mehrerer Eigenschaften eines Objekts ab.

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

Parameter

lpPropTagArray

[in] Ein Zeiger auf ein Array von Eigenschaftstags, die die Eigenschaften identifizieren, deren Werte abgerufen werden sollen. Der lpPropTagArray-Parameter muss entweder NULL sein, was angibt, dass Werte für alle Eigenschaften des Objekts zurückgegeben werden sollen, oder auf eine SPropTagArray-Struktur verweisen, die ein oder mehrere Eigenschaftstags enthält.

ulFlags

[in] Eine Bitmaske von Flags, die das Format für Eigenschaften angibt, die den Typ PT_UNSPECIFIED haben. Das folgende Flag kann festgelegt werden:

MAPI_UNICODE

Die Zeichenfolgenwerte für diese Eigenschaften sollten im Unicode-Format zurückgegeben werden. Wenn das MAPI_UNICODE-Flag nicht festgelegt ist, sollten die Zeichenfolgenwerte im ANSI-Format zurückgegeben werden.

lpcValues

[out] Ein Zeiger auf die Anzahl der Eigenschaftswerte, auf die der lppPropArray-Parameter verweist. Wenn lppPropArray NULL ist, ist der Inhalt des lpcValues-Parameters null.

lppPropArray

[out] Ein Zeiger auf einen Zeiger auf die abgerufenen Eigenschaftswerte.

Rückgabewert

S_OK

Die Eigenschaftswerte wurden erfolgreich abgerufen.

MAPI_W_ERRORS_RETURNED

Der Aufruf war insgesamt erfolgreich, aber auf eine oder mehrere Eigenschaften konnte nicht zugegriffen werden. Der aulPropTag-Member des Eigenschaftswerts für jede nicht verfügbare Eigenschaft weist den Eigenschaftentyp PT_ERROR und den Bezeichner 0 (null) auf. Wenn diese Warnung zurückgegeben wird, sollte der Aufruf als erfolgreich behandelt werden. Verwenden Sie zum Testen auf diese Warnung das Makro HR_FAILED . Weitere Informationen finden Sie unter Verwenden von Makros für die Fehlerbehandlung.

MAPI_E_INVALID_PARAMETER

Null wurde im cValues-Member der SPropTagArray-Struktur übergeben, auf die von lpPropTagArray verwiesen wird.

Hinweise

Die IMAPIProp::GetProps-Methode ruft die Eigenschaftswerte einer oder mehrerer Eigenschaften eines Objekts ab.

Die Eigenschaftswerte werden in derselben Reihenfolge zurückgegeben, in der sie angefordert wurden (d. a. die Reihenfolge der Eigenschaften im Eigenschaftentagarray, auf das von lpPropTagArray verwiesen wird, entspricht der Reihenfolge im Array von Eigenschaftswertstrukturen, auf die von lppPropArray verwiesen wird).

Die in den aulPropTag-Membern des Eigenschaftentagarrays angegebenen Eigenschaftentypen geben den Typ des Werts an, der im Value-Element jeder Eigenschaftenwertstruktur zurückgegeben werden soll. Wenn der Aufrufer jedoch den Typ einer Eigenschaft nicht kennt, kann der Typ im aulPropTag-Member stattdessen auf PT_UNSPECIFIED festgelegt werden. Beim Abrufen des Werts legt GetProps den richtigen Typ im aulPropTag-Member der Eigenschaftswertstruktur für die Eigenschaft fest.

Wenn Eigenschaftstypen im SPropTagArray in lpPropTagArray angegeben werden, verfügen die eigenschaftswerte im in lppPropArrayzurückgegebenen SPropValue über Typen, die genau mit den angeforderten Typen übereinstimmen, es sei denn, stattdessen wird ein Fehlerwert zurückgegeben.

Zeichenfolgeneigenschaften können einen von zwei Eigenschaftentypen aufweisen: PT_UNICODE, um das Unicode-Format darzustellen, und PT_STRING8, um das ANSI-Format darzustellen. Wenn das MAPI_UNICODE-Flag im ulFlags-Parameter festgelegt ist, gibt GetProps das entsprechende Format für eine Zeichenfolgeneigenschaft nicht ermitteln kann, seinen Wert im Unicode-Format zurück. GetProps kann in den folgenden Situationen keinen genauen Zeichenfolgeneigenschaftstyp ermitteln:

Der lpPropTagArray-Parameter wird auf NULL festgelegt, um alle Eigenschaften anzufordern.
Das aulPropTag-Element enthält den Wert PT_UNSPECIFIED als Eigenschaftentyp im Eigenschaftentagarray.

Wenn der lpPropTagArray-Parameter auf NULL festgelegt ist, um alle Eigenschaften des Objekts abzurufen, und keine Eigenschaften vorhanden sind, führt GetProps folgendes aus:

Gibt S_OK zurück.
Legt den Count-Wert im cValues-Element der Eigenschaftswertstruktur auf 0 fest.
Legt den Inhalt von lpcValues auf 0 fest.
Legt lppPropArray auf NULL fest.

GetProps darf keine Eigenschaften mit mehreren Werten zurückgeben, wenn cValues auf 0 festgelegt ist.

Hinweise für Implementierer

Rufen Sie die MAPIAllocateBuffer-Funktion auf, um zunächst Arbeitsspeicher für die SPropValue-Struktur zuzuweisen, auf die von lpPropTagArray verwiesen wird. rufen Sie MAPIAllocateMore auf, um zusätzlichen Arbeitsspeicher zuzuweisen, der für die Member der Struktur erforderlich ist.

Geben Sie MAPI_W_ERRORS_RETURNED zurück, wenn Sie den Wert für eine oder mehrere der angeforderten Eigenschaften nicht abrufen können. Legen Sie in der Eigenschaftswertstruktur den Typ im aulPropTag-Member auf PT_ERROR und das Value-Element auf einen status Code fest, der den Fehler beschreibt. Wenn Sie beispielsweise eine Zeichenfolge in Unicode konvertieren müssen und Unicode nicht unterstützen, legen Sie das Element Value auf MAPI_E_BAD_CHARWIDTH fest. Wenn die Eigenschaft zu groß ist, legen Sie sie auf MAPI_E_NOT_ENOUGH_MEMORY fest. Wenn das Objekt die -Eigenschaft nicht unterstützt, legen Sie sie auf MAPI_E_NOT_FOUND fest.

Die Implementierung der GetProps-Methode eines Remotetransportanbieters muss die Eigenschaftswerte des Ordners für vom Aufrufer angeforderte Eigenschaften zurückgeben. Ihre Implementierung muss folgende Aktionen ausführen:

Ordnen Sie ein Eigenschaftswertarray zu, das an den Aufrufer zurückgegeben werden soll, und speichern Sie dessen Adresse im Eigenschaftswertzeigerparameter, der zu diesem Zweck übergeben wird.
Kopieren Sie die Eigenschaftstags aus den Eigenschaften des Ordners in die Eigenschaftstags im Eigenschaftenwertarray entsprechend dem Array von Eigenschaftstags, das an GetProps übergeben wird.
Stellen Sie sicher, dass der Eigenschaftentyp für alle Eigenschaftstags festgelegt ist, die an GetProps übergeben werden. Der Aufrufer kann einen Eigenschaftstyp von PT_UNSPECIFIED übergeben. In diesem Fall muss GetProps den richtigen Eigenschaftentyp für dieses Eigenschaftentag festlegen.
Legen Sie den Wert jeder Eigenschaft im Eigenschaftenwertarray entsprechend ihrem Tag fest. Wenn das vom Aufrufer angeforderte Eigenschaftstag beispielsweise PR_OBJECT_TYPE (PidTagObjectType) ist, kann GetProps den Wert auf MAPI_FOLDER festlegen.
Wenn der Aufrufer Eigenschaftentags übergibt, die ihre Implementierung nicht behandelt, können Sie das Eigenschaftstag für diese Eigenschaften auf PT_ERROR und den Eigenschaftswert auf MAPI_E_NOT_FOUND festlegen.
Gibt S_OK zurück, wenn keine Fehler aufgetreten sind, oder MAPI_W_ERRORS_RETURNED, wenn Fehler aufgetreten sind.

Die Implementierung der GetProps-Methode eines Remotetransportanbieters muss mindestens die folgenden Eigenschaften unterstützen:

PR_ACCESS (PidTagAccess)
PR_ACCESS_LEVEL (PidTagAccessLevel)
PR_ASSOC_CONTENT_COUNT (PidTagAssociatedContentCount)
PR_CONTENT_COUNT (PidTagContentCount)
PR_CREATION_TIME (PidTagCreationTime)
PR_DISPLAY_NAME (PidTagDisplayName)
PR_DISPLAY_TYPE (PidTagDisplayType)
PR_FOLDER_TYPE (PidTagFolderType)
PR_OBJECT_TYPE
PR_SUBFOLDERS (PidTagSubfolders)

Hinweise für Aufrufer

Rufen Sie für Eigenschaften vom Typ PT_OBJECT die IMAPIProp::OpenProperty-Methode anstelle von GetProps auf.

Erwarten Sie bei sicheren Eigenschaften nicht, dass sie durch Aufrufen von GetProps abgerufen werden, wobei der lppPropTagArray-Parameter auf NULL festgelegt ist. Sie müssen den Bezeichner einer sicheren Eigenschaft explizit im aulPropTag-Member des Eigenschaftentagarrays festlegen, wenn Sie GetProps aufrufen. Wann und wie eine sichere Eigenschaft verfügbar ist, hängt vom Dienstanbieter ab.

Geben Sie die zurückgegebene SPropValue-Struktur durch Aufrufen der MAPIFreeBuffer-Funktion nur frei, wenn GetProps S_OK oder MAPI_W_ERRORS_RETURNED zurückgibt.

Wenn GetProps MAPI_W_ERRORS_RETURNED zurückgibt, weil es nicht auf eine oder mehrere Eigenschaften zugreifen konnte, überprüfen Sie die Eigenschaftentags der zurückgegebenen Eigenschaften. Für die fehlerhaften Eigenschaften werden die folgenden Werte in ihrer Eigenschaftswertstruktur festgelegt:

Der Eigenschaftentyp im aulPropTag-Member , der auf PT_ERROR festgelegt ist.
Der Eigenschaftswert im Wertmember, der auf einen status Code für den Fehler festgelegt ist, z. B. MAPI_E_NOT_FOUND.

Bei Eigenschaften, die fehlschlagen, weil sie zu groß sind, um bequem in der Eigenschaftswertstruktur zurückgegeben zu werden, ist das Value-Element auf MAPI_E_NOT_ENOUGH_MEMORY festgelegt. In der Regel tritt dies bei Zeichenfolgen- oder binäreigenschaften vom Typ PT_STRING8, PT_UNICODE oder PT_BINARY auf, wenn der Wert der Eigenschaft 4 KB oder größer ist. Rufen Sie IMAPIProp::OpenProperty auf, um große Eigenschaften abzurufen.

Nicht alle Implementierungen von GetProps unterstützen sowohl das Unicode- als auch das ANSI-Format für Zeichenfolgen. Wenn eine bestimmte Eigenschaft eine Zeichenfolgenformatkonvertierung erfordert und GetProps sie nicht unterstützen kann, wird der Value-Member für die Eigenschaft auf MAPI_E_BAD_CHARWIDTH festgelegt.

Um zu überprüfen, ob ein PST ein SharePoint-PST ist, binden Sie das PST mithilfe von IMAPISession::OpenMsgStore ein, und rufen Sie dann GetProps für das Nachrichtenspeicherobjekt auf, das diese Eigenschaft anfordert. Falls vorhanden, können Sie davon ausgehen, dass das PST für SharePoint konfiguriert wurde. Andernfalls wurde das PST nicht als SharePoint-PST konfiguriert.

Weitere Informationen zur Verwendung von GetProps für den Zugriff auf Eigenschaften finden Sie unter Abrufen von MAPI-Eigenschaften.

MFCMAPI-Referenz

Einen MFCMAP-Beispielcode finden Sie in der folgenden Tabelle.

Datei	Funktion	Kommentar
MAPIFunctions.cpp	GetPropsNULL	MFCMAPI verwendet die IMAPIProp::GetProps-Methode , um alle Eigenschaften für ein Objekt abzurufen, indem entweder NULL oder das array übergeben wird, das von der IMAPIPropProp::GetPropList-Methode im lpPropTagArray-Parameter zurückgegeben wird.