OpenIMsgOnIStg

Artikel
04/04/2023

Gilt für: Outlook 2013 | Outlook 2016

Erstellt ein neues IMessage-Objekt auf einem vorhandenen OLE IStorage-Objekt , das innerhalb einer Nachrichtensitzung verwendet werden soll.

Eigenschaft	Wert
Headerdatei	Imessage.h
Implementiert von:	MAPI
Aufgerufen von:	Clientanwendungen und Dienstanbieter

SCODE OpenIMsgOnIStg(
  LPMSGSESS lpMsgSess,
  LPALLOCATEBUFFER lpAllocateBuffer,
  LPALLOCATEMORE lpAllocateMore,
  LPFREEBUFFER lpFreeBuffer,
  LPMALLOC lpmalloc,
  LPVOID lpMapiSup,
  LPSTORAGE lpStg,
  MSGCALLRELEASE FAR * lpfMsgCallRelease,
  ULONG ulCallerData,
  ULONG ulFlags,
  LPMESSAGE FAR * lppMsg
);

Parameter

lpMsgSess

[in] Zeiger auf ein Nachrichtensitzungsobjekt, in dem das neue IMessage-on-IStorage-Objekt erstellt werden soll.

lpAllocateBuffer

[in] Zeiger auf die MAPIAllocateBuffer-Funktion , die zum Zuweisen von Arbeitsspeicher verwendet werden soll.

lpAllocateMehr

[in] Zeiger auf die MAPIAllocateMore-Funktion , die zum Zuweisen von zusätzlichem Arbeitsspeicher verwendet werden soll.

lpFreeBuffer

[in] Zeiger auf die MAPIFreeBuffer-Funktion , die zum Freigeben von Arbeitsspeicher verwendet werden soll.

lpMalloc

[in] Zeiger auf ein Speicherzuweisungsobjekt, das die OLE IMalloc-Schnittstelle verfügbar macht. Die IMessage-Schnittstelle muss diese Zuordnungsmethode verwenden, wenn Sie mit Schnittstellen wie IStorage und IStream arbeiten.

lpMapiSup

[in] Optionaler Zeiger auf ein MAPI-Unterstützungsobjekt, das ein Dienstanbieter verwenden kann, um die Methoden der IMAPISupport: IUnknown-Schnittstelle aufzurufen.

lpStg

[in, out] Zeiger auf ein OLE IStorage-Objekt , das geöffnet ist und schreibgeschützt oder lese-/schreibgeschützt ist. Da IMessage keinen schreibgeschützten Zugriff unterstützt, akzeptiert OpenIMsgOnIStg kein Speicherobjekt, das im schreibgeschützten Modus geöffnet wurde.

lpfMsgCallRelease

[in] Optionaler Zeiger auf eine Rückruffunktion, die auf dem MSGCALLRELEASE-Prototyp basiert, den MAPI nach der letzten Version des IMessage-on-IStorage-Objekts aufrufen soll.

ulCallerData

[in] Aufruferdaten, die von MAPI mit dem IMessage-on-IStorage-Objekt gespeichert und an die MSGCALLRELEASE-basierte Rückruffunktion übergeben werden. Die Daten stellen Kontext zum freigegebenen IMessage-Objekt und zum IStorage-Objekt bereit, auf dem es erstellt wurde.

ulFlags

[in] Bitmaske von Flags, die verwendet werden, um zu steuern, ob die OLE IStorage::Commit-Methode aufgerufen wird, wenn die Clientanwendung oder der Dienstanbieter die IMessage::SaveChanges-Methode aufruft . Die folgenden Flags können festgelegt werden:

IMSG_NO_ISTG_COMMIT

Die OLE-Methode IStorage::Commit darf nicht aufgerufen werden, wenn der Client oder Anbieter SaveChanges aufruft.

MAPI_UNICODE

Ermöglicht die Erstellung von Unicode-.msg-Dateien. Die resultierende IMessage-Datei zeigt STORE_UNICODE_OK im PR_STORE_SUPPORT_MASK und unterstützt Unicode-Eigenschaften.

Hinweis

Das MAPI_UNICODE-Flag wird nur in dieser Funktion in Outlook 2003 oder höher unterstützt.

lppMsg

[out] Zeiger auf einen Zeiger auf das geöffnete IMessage-Objekt .

Rückgabewert

S_OK

Der Aufruf erfolgreich ausgef�hrt und der erwartete Wert oder Werte zur�ckgegeben hat.

Hinweise

Auf Eigenschaftsattribute kann nur für Eigenschaftsobjekte zugegriffen werden, d. h. auf Objekte, die die IMAPIProp:IUnknown-Schnittstelle implementieren. Um MAPI-Eigenschaften für ein strukturiertes OLE-Speicherobjekt verfügbar zu machen, erstellt OpenIMsgOnIStg ein IMessage: IMAPIProp-Objekt auf dem OLE IStorage-Objekt . Die Eigenschaftsattribute für solche Objekte können mit SetAttribIMsgOnIStg festgelegt oder geändert und mit GetAttribIMsgOnIStg abgerufen werden.

Hinweise für Aufrufer

Eine Nachrichtensitzung sollte mit OpenIMsgSession geöffnet werden, bevor OpenIMsgOnIStg aufgerufen wird. Wenn Sie einen gültigen lpMsgSess-Parameter angeben, stellen Sie sicher, dass die neue Nachricht innerhalb einer Nachrichtensitzung erstellt wird, sodass sie geschlossen wird, wenn die Sitzung geschlossen wird. Wenn lpMsgSess NULL ist, wird die Nachricht unabhängig von einer Nachrichtensitzung erstellt. Wenn die Clientanwendung oder der Dienstanbieter, der bzw. der die Nachricht erstellt hat, sie sowie alle anlagen und offenen Tabellen nicht freigeben, geht der Arbeitsspeicher verloren und kann dazu führen, dass die Anwendung beendet wird.

MAPI verwendet die Funktionen, auf die lpAllocateBuffer, lpAllocateMore und lpFreeBuffer für die meisten Speicherzuordnungen und -freigaben verweisen, insbesondere, um Arbeitsspeicher für die Verwendung durch Clientanwendungen zuzuweisen, wenn Objektschnittstellen wie IMAPIProp::GetProps und IMAPITable::QueryRows aufgerufen werden. Die Zeiger lpAllocateBuffer, lpAllocateMore und lpFreeBuffer sind optional, wenn die OpenIMsgOnIStg-Funktion mit einem gültigen lpMapiSup-Parameter aufgerufen wird.

Da es sich um ein zugrunde liegendes OLE-Objekt handelt, muss MAPI auch die OLE-Speicherbelegung verwenden. Weitere Informationen zu strukturierten OLE-Speicherobjekten und der OLE-Speicherbelegung finden Sie in der OLE-Programmierreferenz.

Wenn ein gültiger Wert für lpMapiSup angegeben wird, unterstützt IMessage die flags MAPI_DIALOG und ATTACH_DIALOG, indem die IMAPISupport::D oProgressDialog-Methode aufgerufen wird, um eine Fortschrittsbenutzeroberfläche für die Methoden IMAPIProp::CopyTo und IMessage::D eleteAttach anzugeben. Außerdem versucht die IMessage::ModifyRecipients-Methode , kurzfristige Eingabebezeichner in langfristige Eingabebezeichner zu konvertieren, indem die IMAPISupport::OpenAddressBook-Methode aufgerufen und aufruft das resultierende Adressbuchobjekt. Wenn NULL für lpMapiSup übergeben wird, ignoriert IMessage MAPI_DIALOG und ATTACH_DIALOG und speichert kurzfristige Eingabebezeichner ohne Konvertierung.

Das IStorage-Objekt , auf das der lpStg-Parameter verweist, muss entweder im STGM_READ- oder STGM_READWRITE Modus geöffnet werden. Wenn der STGM_READWRITE-Modus verwendet wird, muss auch der STGM_TRANSACTED-Modus festgelegt werden.

Die Rückruffunktion, auf die der Parameter lpfMsgCallRelease verweist, ist optional. Sofern angegeben, sollte sie auf dem Funktionsprototyp MSGCALLRELEASE basieren. Die IMessage-Schnittstelle ruft sie auf, wenn die Verweisanzahl des IMessage-on-IStorage-Objekts durch den letzten Aufruf der Release-Methode auf 0 festgelegt wird. Die Rückruffunktion wird häufig verwendet, um die zugrunde liegende IStorage-Schnittstelle freizugeben. IMessage versucht nicht, auf das IStorage-Objekt zuzugreifen, auf das der lpStg-Parameter nach dem Rückruf verweist.

Einige Clients oder Anbieter schreiben möglicherweise zusätzliche Daten in das IStorage-Objekt , die über das hinausgehen, was IMessage selbst schreibt, wenn die SaveChanges-Methode aufgerufen wird. Der Client oder Anbieter kann das IMSG_NO_ISTG_COMMIT-Flag verwenden, um zu verhindern, dass IMessage die OLE IStorage::Commit-Methode aufruft, während ein SaveChanges-Aufruf verarbeitet wird . In diesem Fall muss der Client oder Anbieter das IStorage-Objekt selbst committen, wenn die zusätzlichen Daten geschrieben werden. Um dies zu unterstützen, garantiert die IMessage-Implementierung , dass alle Unterspeicher, die sie im IStorage-Objekt erstellt, beginnend mit der Zeichenfolge "__", d. h. mit zwei Unterstrichen, benennen. Der Client oder Anbieter kann Namenskonflikte vermeiden, indem seine Unterspeichernamen aus diesem Namespace entfernt bleiben.

MAPI definiert nicht das Verhalten mehrerer geöffneter Vorgänge, die für ein Unterobjekt einer Nachricht wie eine Anlage, einen Stream oder eine eingebettete Nachricht ausgeführt werden. MAPI ermöglicht derzeit das erneute Öffnen eines bereits geöffneten Unterobjekts. MAPI führt jedoch den Öffnenvorgang durch, indem die Verweisanzahl für das vorhandene geöffnete Objekt erhöht und an den Client oder Anbieter zurückgegeben wird, der die IMessage::OpenAttach - oder IMAPIProp::OpenProperty-Methode aufgerufen hat. Dies bedeutet, dass der für den ersten offenen Vorgang für ein Unterobjekt angeforderte Zugriff der Zugriff ist, der für alle nachfolgenden offenen Vorgänge bereitgestellt wird, unabhängig vom von den Vorgängen angeforderten Zugriff.

Das richtige Verfahren zum Platzieren einer Nachricht in einer Anlage besteht darin, die IMAPIProp::OpenProperty-Methode mit dem Schnittstellenbezeichner IID_IMessage aufzurufen. OpenProperty unterstützt derzeit auch die Erstellung von Nachrichtenanlagen, die direkt auf der OLE IStorage-Schnittstelle verfügbar sind, d. h. mithilfe des schnittstellenbezeichners IID_IStorage. Der IStorage-Zugriff wird unterstützt, um eine einfache Möglichkeit zu ermöglichen, ein Microsoft Word-Dokument in eine Anlage einzufügen, ohne es in oder von der OLE IStream-Schnittstelle zu konvertieren. IMessage verhält sich jedoch möglicherweise nicht vorhersehbar, wenn OpenIMsgOnIStg einen IStorage-Zeiger auf die Anlagendaten übergeben wird und die Objekte dann in der falschen Reihenfolge freigegeben werden.

MFCMAPI-Referenz

Einen MFCMAP-Beispielcode finden Sie in der folgenden Tabelle.

Datei	Funktion	Kommentar
File.cpp	LoadMSGToMessage	MFCMAPI verwendet die OpenIMsgOnIStg-Methode , um eine IMessage-Schnittstelle über dem zu öffnen. MSG-Datei, sodass die Datei mit MAPI bearbeitet werden kann.

Siehe auch

MFCMAPI (engl.) als ein Codebeispiel

Freigeben über