IMAPIProp::GetNamesFromIDs

Artikel
04/04/2023

Gilt für: Outlook 2013 | Outlook 2016

Stellt die Eigenschaftennamen bereit, die einem oder mehreren Eigenschaftenbezeichnern entsprechen.

HRESULT GetNamesFromIDs(
  LPSPropTagArray FAR * lppPropTags,
  LPGUID lpPropSetGuid,
  ULONG ulFlags,
  ULONG FAR * lpcPropNames,
  LPMAPINAMEID FAR * FAR * lpppPropNames
);

Parameter

lppPropTags

[in, out] Bei der Eingabe ein Zeiger auf eine SPropTagArray-Struktur , die ein Array von Eigenschaftstags enthält; andernfalls NULL, der angibt, dass alle Namen zurückgegeben werden sollen. Der cValues-Member für das Eigenschaftentagarray darf nicht 0 sein. Wenn lppPropTags ein gültiger Zeiger für eingaben ist, gibt GetNamesFromIDs Namen für jeden Eigenschaftenbezeichner zurück, der im Array enthalten ist.

lpPropSetGuid

[in] Ein Zeiger auf eine GUID- oder GUID-Struktur , die einen Eigenschaftensatz identifiziert. Der lpPropSetGuid-Parameter kann auf einen gültigen Eigenschaftensatz verweisen oder NULL sein.

ulFlags

[in] Eine Bitmaske von Flags, die den Typ der zurückzugebenden Namen angibt. Die folgenden Flags können verwendet werden (wenn beide Flags festgelegt sind, werden keine Namen zurückgegeben):

MAPI_NO_IDS

Anforderungen, dass nur Namen zurückgegeben werden, die als Unicode-Zeichenfolgen gespeichert sind.

MAPI_NO_STRINGS

Fordert an, dass nur Namen zurückgegeben werden, die als numerische Bezeichner gespeichert sind.

lpcPropNames

[out] Ein Zeiger auf die Anzahl der Eigenschaftsnamenzeiger im Array, auf die der lppPropNames-Parameter zeigt.

lpppPropNames

[out] Ein Zeiger auf ein Array von Zeigern auf MAPINAMEID-Strukturen , das Eigenschaftsnamen enthält.

Rückgabewert

S_OK

Die Eigenschaftennamen wurden erfolgreich zurückgegeben.

MAPI_E_NO_SUPPORT

Das -Objekt unterstützt keine benannten Eigenschaften.

MAPI_W_ERRORS_RETURNED

Der Aufruf war insgesamt erfolgreich, aber Namen für eine oder mehrere Eigenschaften konnten nicht zurückgegeben werden. Die Eigenschaftentags für die fehlerhaften Eigenschaften weisen den Eigenschaftentyp PT_ERROR 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

Der cValues-Member eines oder mehrerer Einträge im Eigenschaftentagarray, auf das von lppPropTags verwiesen wird, ist auf 0 festgelegt.

Hinweise

Während der Zugriff auf die meisten Eigenschaften über den Eigenschaftenbezeichner erfolgt, kann auf einige Eigenschaften über den Namen zugegriffen werden. Die IMAPIProp::GetNamesFromIDs-Methode kann aufgerufen werden, um folgendes auszuführen:

Ruft Namen für bestimmte Eigenschaftsbezeichner in einem bestimmten Eigenschaftensatz ab.
Ruft Namen für bestimmte Eigenschaftsbezeichner in einem beliebigen Eigenschaftensatz ab.
Ruft Namen für alle benannten Eigenschaften ab, die in der Zuordnung des Objekts enthalten sind.

Wenn lppPropTags auf ein gültiges Eigenschaftentagarray mit einem oder mehreren Eigenschaftenbezeichnern verweist und lpPropSetGuid auf einen gültigen Eigenschaftensatz verweist, ignoriert GetNamesFromIDs den Eigenschaftensatz und die Eigenschaftentypen und gibt alle Namen zurück, die den angegebenen Bezeichnern zugeordnet sind.

Wenn lppPropTags auf ein gültiges Eigenschaftentagarray mit mindestens einem Eigenschaftsbezeichner verweist und lpPropSetGuid NULL ist, gibt GetNamesFromIDs alle Namen zurück, die den angegebenen Bezeichnern zugeordnet sind.

Wenn ein angegebener Bezeichner keinen Namen hat, gibt GetNamesFromIDs NULL an der Stelle dieses Bezeichners in der struktur zurück, die in lpppPropNames zurückgegeben wird, und gibt auch MAPI_W_ERRORS_RETURNED zurück.

Wenn lpPropSetGuid und lppPropTags NULL sind, ordnet GetNamesFromIDs ein neues Eigenschaftentagarray zu und gibt alle Namen für alle benannten Eigenschaften für das Objekt zurück.

Wenn keine Namen zurückgegeben werden sollen, z. B. weil keine Eigenschaften im angeforderten Eigenschaftensatz vorhanden sind oder alle Eigenschaften von einem Typ sind, der von den Flags ausgeschlossen wird, führt GetNamesFromIDs folgende Schritte aus:

Gibt S_OK zurück.
Ordnet eine neue SPropTagArray-Struktur zu, wobei das cValues-Element auf 0 festgelegt wird.
Legt den Inhalt von lpcPropNames auf 0 fest.
Legt den Inhalt von lpppPropNames auf NULL fest.

Hinweise für Implementierer

Wenn lpPropSetGuid auf einen gültigen Eigenschaftensatz verweist und lppPropTags NULL ist, ist das Ergebnis nicht definiert. Sie können eine der folgenden Strategien verwenden:

Ignorieren Sie den Eigenschaftensatz, und geben Sie die Namen für die Bezeichner im Eigenschaftentagarray zurück.
Gibt nur die Namen für die Bezeichner im Eigenschaftentagarray zurück, die zum angegebenen Eigenschaftensatz gehören.
Führen Sie einen Fehler beim Aufruf aus, und geben Sie MAPI_E_INVALID_PARAMETER zurück.

Hinweise für Aufrufer

Um alle benannten Eigenschaften für ein Objekt abzurufen, müssen Sie zuerst die IMAPIProp::GetPropList-Methode des Objekts aufrufen und dann die zurückgegebenen Bezeichner, die sich oberhalb des 0x8000 Bereichs befinden, an GetNamesFromIDs übergeben.

Wenn Sie einen gültigen Eigenschaftensatz, aber kein gültiges Eigenschaftentagarray übergeben, sollten Sie auf unvorhersehbare Ergebnisse vorbereitet sein. Einige Implementierungen von GetNamesFromIDs ignorieren den Eigenschaftensatz und geben die Namen für die Bezeichner im Eigenschaftentagarray zurück. Einige Implementierungen geben MAPI_E_INVALID_PARAMETER zurück. Andere Implementierungen geben Namen für Bezeichner aller Eigenschaften im Eigenschaftensatz zurück. Wenn der Eigenschaftensatz PS_PUBLIC_STRINGS ist, kann GetNamesFromIDs alle Namen zurückgeben, die jemals erstellt wurden. Ob der Dienstanbieter eine Eigenschaft unter den Bezeichnern speichert, die den öffentlichen Zeichenfolgen zugeordnet sind, ist unerheblich.

Wenn Sie mit den Eigenschaftennamen fertig sind, überprüfen Sie den Inhalt des lpcPropNames-Parameters , um zu ermitteln, ob Namen zurückgegeben wurden. Wenn ja, rufen Sie die MAPIFreeBuffer-Funktion auf, um den Speicher freizugeben, auf den lppPropTags und lpppPropNames verweisen, wenn ein erfolgreiches Ergebnis zurückgegeben wird. Ein Aufruf von MAPIFreeBuffer ist für jeden Parameter ausreichend. Sie müssen nicht das Array von Zeigern durchlaufen und jede MAPINAMEID-Struktur einzeln freigeben.

Weitere Informationen zu benannten Eigenschaften finden Sie unter Benannte MAPI-Eigenschaften.

MFCMAPI-Referenz

Einen MFCMAP-Beispielcode finden Sie in der folgenden Tabelle.

Datei	Funktion	Kommentar
SingleMAPIPropListCtrl.cpp	CSingleMAPIPropListCtrl::FindAllNamedProps	MFCMAPI verwendet die IMAPIProp::GetNamesFromIDs-Methode , um benannte Eigenschaften nachzuschlagen, die zuvor zugeordnet wurden.