OpenIMsgOnIStg

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.

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 Zuordnen von Arbeitsspeicher verwendet werden soll.

lpAllocateMore

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

lpFreeBuffer

[in] Zeiger auf die Funktion MAPIFreeBuffer, die zum Freigeben von Speicher verwendet wird.

lpMalloc

[in] Zeiger auf ein Speicherzuteilungsobjekt, das die OLE-Schnittstelle IMallocoffenlegt. Die IMessage-Schnittstelle muss diese Zuteilungsmethode verwenden, wenn sie mit Schnittstellen wie IStorage und IStream arbeitet.

lpMapiSup

Optionaler Zeiger auf ein MAPI-Unterstützungsobjekt, das ein Dienstanbieter zum Aufrufen der Methoden der IMAPISupport: IUnknown-Schnittstelle verwenden kann.

lpStg

[in, out] Zeiger auf ein OLE-Objekt IStorage, das geöffnet ist und über Lese- oder Lese-/Schreibberechtigung verfügt. Da IMessage keinen Schreibzugriff unterstützt, akzeptiert OpenIMsgOnIStg kein Speicherobjekt, das im Schreibmodus geöffnet wurde.

lpfMsgCallRelease

[in] Optionaler Zeiger auf eine Rückruffunktion basierend auf dem Prototyp MSGCALLRELEASE, die MAPI nach der letzten Freigabe für das Objekt IMessage-on-IStorage aufrufen soll.

ulCallerData

[in] Aufruferdaten, die von MAPI mit dem IMessage-on-IStorage-Objekt gespeichert und an die auf MSGCALLRELEASE basierende Rückruffunktion übergeben wurden. Die Daten liefern Kontextinformationen zum freigegebenen IMessage-Objekt und zum IStorage-Objekt, auf dem es aufgebaut ist.

ulFlags

[in] Bitmaske aus Kennzeichen, mit der gesteuert wird, ob die OLE-Methode IStorage::Commit aufgerufen wird, wenn die Clientanwendung oder der Dienstanbieter die Methode IMessage::SaveChanges aufruft. Die folgenden Kennzeichen 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 in ihrer PR_STORE_SUPPORT_MASK an und unterstützt Unicode-Eigenschaften.

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 bei Eigenschaftsobjekten zugegriffen werden, d. h. bei Objekten, die die Schnittstelle IMAPIProp : IUnknown 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 Eigenschaften dieser 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. Durch die Angabe eines gültigen Parameters lpMsgSess wird sichergestellt, dass die neue Nachricht innerhalb einer Nachrichtensitzung erstellt wird, sodass sie beim Schließen der Sitzung ebenfalls geschlossen wird. Wenn lpMsgSess NULL ist, wird die Nachricht unabhängig von einer Nachrichtensitzung erstellt. Wenn die Clientanwendung oder der Dienstanbieter, der die Nachricht erstellt hat, diese nicht freigibt, werden alle Anhänge und offenen Tabellen nicht freigegeben, sodass Speicher verloren geht und die Anwendung möglicherweise beendet wird.

MAPI verwendet die Funktionen, auf die lpAllocateBuffer, lpAllocateMore und lpFreeBuffer verweisen, für die meisten Speicherzuweisungen und -freigaben, insbesondere um Speicher für Clientanwendungen zuzuweisen, die Objekt-Schnittstellen wie IMAPIProp::GetProps und IMAPITable::QueryRows aufrufen. Die Zeiger lpAllocateBuffer, lpAllocateMore, und lpFreeBuffer sind optional, wenn die Funktion OpenIMsgOnIStg mit einem gültigenlpMapiSup-Parameter aufgerufen wird.

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

Wenn für lpMapiSup ein gültiger Wert angegeben wird, unterstützt IMessage die Kennzeichen MAPI_DIALOG und ATTACH_DIALOG, indem die Methode IMAPISupport::DoProgressDialog aufgerufen wird, um eine Benutzeroberfläche für den Fortschritt der Methoden IMAPIProp::CopyTo und IMessage::DeleteAttach bereitzustellen. Außerdem versucht die Methode IMessage::ModifyRecipients, Kurzzeit-Eintragbezeichner in Langzeit-Eintragbezeichner umzuwandeln, indem sie die Methode IMAPISupport::OpenAddressBook aufruft und Aufrufe an das resultierende Adressbuchobjekt sendet. Wenn NULL für lpMapiSup übergeben wird, ignoriert IMessage MAPI_DIALOG und ATTACH_DIALOG und speichert kurzfristige Eintragbezeichner ohne Konvertierung.

Das vom Parameter lpStg angegebene IStorage-Objekt muss im Modus STGM_READ oder STGM_READWRITE geöffnet sein. Wenn der Modus STGM_READWRITE verwendet wird, muss auch der Modus STGM_TRANSACTED gesetzt werden.

Die Rückruffunktion, auf die der Parameter lpfMsgCallRelease verweist, ist optional. Wenn sie angegeben wird, 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 seiner Release-Methode auf null gesetzt wird. Die Rückruffunktion wird in der Regel verwendet, um die zugrunde liegende IStorage-Schnittstelle freizugeben. IMessage versucht nicht, auf das IStorage-Objekt zuzugreifen, auf das der Parameter lpStg verweist, nachdem der Rückruf erfolgt ist.

Einige Clients oder Anbieter schreiben möglicherweise zusätzliche Daten in das IStorage-Objekt, die über die Daten hinausgehen, die IMessage selbst schreibt, wenn die Methode SaveChanges aufgerufen wird. Der Client oder Anbieter kann das Kennzeichen IMSG_NO_ISTG_COMMIT verwenden, um zu verhindern, dass IMessage während der Verarbeitung eines SaveChanges-Aufrufs die OLE-Methode IStorage::Commit aufruft. In diesem Fall muss der Client oder Anbieter das IStorage-Objekt selbst committen, wenn die zusätzlichen Daten geschrieben werden. Um dies zu erleichtern, garantiert die IMessage-Implementierung, dass alle von ihr im IStorage-Objekt erstellten Subspeicher mit der Zeichenfolge „__“, also mit zwei Unterstrichen, benannt werden. Der Client oder Anbieter kann Namenskonflikte vermeiden, indem er die Namen seiner Subspeicher außerhalb dieses Namensraums hält.

MAPI definiert nicht das Verhalten mehrerer Vorgänge, die auf ein Unterobjekt einer Nachricht ausgeführt werden, z. B. eine Anlage, einen Stream oder eine eingebettete Nachricht. MAPI erlaubt derzeit, dass ein bereits geöffnetes Unterobjekt erneut geöffnet wird. MAPI führt den Vorgang „Öffnen“ jedoch aus, indem es die Verweisanzahl für das vorhandene geöffnete Objekt erhöht und es an den Client oder Anbieter zurückgibt, der die Methode IMessage::OpenAttach oder IMAPIProp::OpenProperty aufgerufen hat. Das bedeutet, dass der für den ersten Öffnungsvorgang eines Teilobjekts angeforderte Zugriff für alle nachfolgenden Öffnungsvorgänge bereitgestellt wird, unabhängig davon, welcher Zugriff durch die Vorgänge angefordert wird.

Um eine Nachricht in eine Anlage einzufügen, rufen Sie die Methode IMAPIProp::OpenProperty mit der Schnittstellenkennung IID_IMessage auf. OpenProperty unterstützt derzeit auch die Erstellung von Nachrichtenanhängen, die direkt über die OLE-Schnittstelle IStorage verfügbar sind, d. h. unter Verwendung der Schnittstellenkennung IID_IStorage. Der Zugriff auf IStorage wird unterstützt, um Microsoft Word-Dokumente auf einfache Weise als Anlage hinzuzufügen, ohne sie in die OLE IStream-Schnittstelle konvertieren zu müssen. IMessage verhält sich jedoch möglicherweise nicht wie erwartet, wenn OpenIMsgOnIStg ein IStorage-Zeiger auf die Anlagendaten übergeben wird und die Objekte anschließend in der falschen Reihenfolge freigegeben werden.

MFCMAPI-Referenz

Einen MFCMAP-Beispielcode finden Sie in der folgenden Tabelle.

Siehe auch

• MFCMAPI (engl.) als ein Codebeispiel