MAPIADDRESS-Rückruffunktion (mapi.h)

Artikel
08/24/2023

[Von der Verwendung dieser Funktion wird abgeraten. Sie kann in nachfolgenden Versionen von Windows geändert oder nicht verfügbar sein.]

Die MAPIAddress-Funktion erstellt oder ändert einen Satz von Adresslisteneinträgen.

Syntax

MAPIADDRESS Mapiaddress;

ULONG Mapiaddress(
  [in]  LHANDLE lhSession,
  [in]  ULONG_PTR ulUIParam,
  [in]  LPSTR lpszCaption,
  [in]  ULONG nEditFields,
  [in]  LPSTR lpszLabels,
  [in]  ULONG nRecips,
  [in]  lpMapiRecipDesc lpRecips,
  [in]  FLAGS flFlags,
        ULONG ulReserved,
  [out] LPULONG lpnNewRecips,
        lpMapiRecipDesc *lppNewRecips
)
{...}

Parameter

[in] lhSession

Sitzungshandle, das eine einfache MAPI-Sitzung oder null darstellt. Wenn der Wert des lhSession-Parameters 0 ist, protokolliert MAPI den Benutzer und erstellt eine Sitzung, die nur für die Dauer des Aufrufs vorhanden ist. Diese temporäre Sitzung kann eine vorhandene freigegebene Sitzung oder eine neue sitzung sein. Bei Bedarf wird ein Anmeldedialogfeld angezeigt.

[in] ulUIParam

Übergeordnetes Fensterhandle oder Null, das angibt, dass es sich bei der Anzeige eines Dialogfelds um ein Modal der Anwendung handelt. Wenn der ulUIParam-Parameter ein übergeordnetes Fensterhandle enthält, ist er vom Typ HWND (in eine ULONG_PTR umgewandelt). Wenn während des Anrufs kein Dialogfeld angezeigt wird, wird ulUIParam ignoriert.

[in] lpszCaption

Zeiger auf den Untertitel für das Dialogfeld Adressliste, NULL oder eine leere Zeichenfolge. Wenn der lpszCaption-ParameterNULL ist oder auf eine leere Zeichenfolge verweist, verwendet MAPIAddress die Standardeinstellung Untertitel "Adressbuch".

[in] nEditFields

Die Anzahl der Bearbeitungssteuerelemente, die in der Adressliste vorhanden sein sollen. Die Werte 0 bis 4 sind gültig. Wenn der Wert des nEditFields-Parameters 4 ist, verfügt jede vom zugrunde liegenden Messagingsystem unterstützte Empfängerklasse über ein Bearbeitungssteuerelement. Wenn der Wert von nEditFields null ist, ist nur das Durchsuchen von Adresslisten möglich. Werte von 1, 2 oder 3 steuern die Anzahl der vorhandenen Bearbeitungssteuerelemente. Wenn jedoch die Anzahl der Empfängerklassen in dem Array, auf das vom lpRecips-Parameter verwiesen wird, größer ist als der Wert von nEditFields, wird die Anzahl der Klassen in lpRecips verwendet, um die Anzahl der Bearbeitungssteuerelemente anstelle des Werts von nEditFields anzugeben. Wenn der Wert von nEditFields 1 ist und mehr als eine Art von Eintrag in lpRecips vorhanden ist, wird der lpszLabels-Parameter ignoriert. Einträge, die für die verschiedenen Steuerelemente ausgewählt sind, werden durch das element ulRecipClass in der zurückgegebenen Empfängerstruktur unterschieden.

[in] lpszLabels

Zeiger auf eine Zeichenfolge, die als Steuerelementbeschriftung zum Bearbeiten im Dialogfeld Adressliste verwendet werden soll. Wenn der nEditFields-Parameter auf einen anderen Wert als 1 festgelegt ist, wird der lpszLabels-Parameter ignoriert und sollte NULL sein oder auf eine leere Zeichenfolge zeigen. Wenn der Aufrufer außerdem die Standardsteuerelementbezeichnung "To" erfordert, sollte lpszLabelsNULL sein oder auf eine leere Zeichenfolge zeigen.

[in] nRecips

Die Anzahl der Einträge im Array, die durch den lpRecips-Parameter angegeben wird. Wenn der Wert des nRecips-Parameters 0 ist, wird lpRecips ignoriert.

[in] lpRecips

Zeiger auf ein Array von MapiRecipDesc-Strukturen , die die anfänglichen Empfängereinträge definieren, die zum Auffüllen des Dialogfelds Adressliste verwendet werden sollen. Die Einträge müssen nicht nach Empfängerklasse gruppiert werden. sie unterscheiden sich durch die Werte der ulRecipClass-Member der MapiRecipDesc-Strukturen im Array. Wenn die Anzahl der verschiedenen Empfängerklassen größer als der durch den nEditFields-Parameter angegebene Wert ist, werden die Parameter nEditFields und lpszLabels ignoriert.

[in] flFlags

Bitmaske von Optionsflags. Die folgenden Flags können festgelegt werden.

Wert	Bedeutung
MAPI_LOGON_UI	Es sollte ein Dialogfeld angezeigt werden, in dem der Benutzer aufgefordert wird, sich bei Bedarf anzumelden. Wenn das flag MAPI_LOGON_UI nicht festgelegt ist, zeigt die Clientanwendung kein Anmeldedialogfeld an und gibt einen Fehlerwert zurück, wenn der Benutzer nicht angemeldet ist.
MAPI_NEW_SESSION	Es sollte versucht werden, eine neue Sitzung zu erstellen, anstatt die freigegebene Sitzung der Umgebung zu erhalten. Wenn das flag MAPI_NEW_SESSION nicht festgelegt ist, verwendet MAPIAddress eine vorhandene freigegebene Sitzung.

ulReserved

Reserviert; muss null sein.

[out] lpnNewRecips

Zeiger auf die Anzahl der Einträge im lppNewRecips-Empfängerausgabearray . Wenn der Wert des parameters lpnNewRecips null ist, wird der lppNewRecips-Parameter ignoriert.

lppNewRecips

Rückgabewert

Diese Funktion gibt einen der folgenden Werte zurück.

Rückgabecode	Beschreibung
MAPI_E_FAILURE	Mindestens ein nicht spezifizierter Fehler ist beim Adressieren der Nachricht aufgetreten. Es wurde keine Liste mit Empfängereinträgen zurückgegeben.
MAPI_E_INSUFFICIENT_MEMORY	Es war nicht genügend Arbeitsspeicher vorhanden, um fortzufahren. Es wurde keine Liste mit Empfängereinträgen zurückgegeben.
MAPI_E_INVALID_EDITFIELDS	Der Wert des nEditFields-Parameters lag außerhalb des Bereichs von 0 bis 4. Es wurde keine Liste mit Empfängereinträgen zurückgegeben.
MAPI_E_INVALID_RECIPS	Mindestens ein Empfänger in der Adressliste war ungültig. Es wurde keine Liste mit Empfängereinträgen zurückgegeben.
MAPI_E_INVALID_SESSION	Für den lhSession-Parameter wurde ein ungültiges Sitzungshandle verwendet. Es wurde keine Liste mit Empfängereinträgen zurückgegeben.
MAPI_E_LOGIN_FAILURE	Es gab keine Standardanmeldung, und der Benutzer konnte sich nicht erfolgreich anmelden, als das Anmeldedialogfeld angezeigt wurde. Es wurde keine Liste mit Empfängereinträgen zurückgegeben.
MAPI_E_NOT_SUPPORTED	Der Vorgang wurde vom zugrunde liegenden Messagingsystem nicht unterstützt.
MAPI_E_USER_ABORT	Der Benutzer hat eines der Dialogfelder abgebrochen. Es wurde keine Liste mit Empfängereinträgen zurückgegeben.
SUCCESS_SUCCESS	Der Aufruf war erfolgreich, und eine Liste der Empfängereinträge wurde zurückgegeben.

Hinweise

Die MAPIAddress-Funktion zeigt ein Standard-Adresslistendialogfeld an, um einen anfänglichen Satz von 0 oder mehr Empfängern anzuzeigen. Der Benutzer kann neue Einträge auswählen, die dem Satz hinzugefügt werden sollen, oder änderungen an vorhandenen Einträgen vornehmen. Dieses Dialogfeld kann nicht unterdrückt werden, aber der Aufrufer kann Dialogfeldeigenschaften festlegen. Der geänderte Empfängersatz wird an den Aufrufer zurückgegeben.

Bevor MAPIAddress neue oder geänderte Empfängerinformationen schreibt, muss es arbeitsspeicher für das Strukturarray zuweisen, das die Informationen enthält. Arbeitsspeicher wird auch im Rahmen des Vorabladens des Adressbuchs zugewiesen, unabhängig davon, ob neue oder geänderte Empfängerdaten geschrieben werden. Clientanwendungen müssen die MAPIFreeBuffer-Funktion aufrufen, um diesen Arbeitsspeicher nach der Rückgabe von MAPIAddress freizugeben. Wenn ein Fehler auftritt, wurde kein Arbeitsspeicher zugewiesen, und Clients müssen MAPIFreeBuffer nicht aufrufen.