MSGSERVICEENTRY

Gilt für: Outlook 2013 | Outlook 2016

Definiert einen Prototyp für eine Nachrichtendienst-Einstiegspunktfunktion, um die Konfiguration des Nachrichtendiensts zu unterstützen.

HRESULT MSGSERVICEENTRY(
  HINSTANCE hInstance,
  LPMALLOC lpMalloc,
  LPMAPISUP lpMAPISup,
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  ULONG ulContext,
  ULONG cValues,
  LPSPropValue lpProps,
  LPPROVIDERADMIN lpProviderAdmin,
  LPMAPIERROR FAR * lppMapiError
);

Parameter

hInstance

[in] Handle der Instanz der Dienstanbieter-DLL. Das Handle wird in der Regel zum Abrufen von Ressourcen verwendet.

lpMalloc

[in] Zeiger auf ein Speicherzuweisungsobjekt, das die OLE-IMalloc-Schnittstelle bereitstellt. Der Nachrichtendienst muss diese Zuordnungsmethode möglicherweise verwenden, wenn er mit bestimmten Schnittstellen wie IStream arbeitet.

lpMAPISup

[in] Zeiger auf eine IMAPISupport: IUnknown-Schnittstellenimplementierung..

ulUIParam

[in] Ein implementierungsspezifischer Wert, der zum Übergeben von Benutzeroberflächeninformationen an eine Funktion oder null verwendet wird. Der ulUIParam-Parameter ist das übergeordnete Fensterhandle für das Konfigurationsdialogfeld und hat den Typ HWND (umgewandelt in einen ULONG_PTR). Der Wert 0 gibt an, dass kein übergeordnetes Fenster vorhanden ist.

ulFlags

[in] Bitmaske von Kennzeichnungen, die Optionen für die Diensteintragsfunktion angeben. Die folgenden Kennzeichen können festgelegt werden:

MAPI_UNICODE

Die übergebenen Zeichenfolgen weisen das Unicode-Format auf. Wenn die MAPI_UNICODE-Kennzeichnung nicht festgelegt ist, liegen die Zeichenfolgen im ANSI-Format vor.

MSG_SERVICE_UI_READ_ONLY

Die Benutzeroberfläche für die Konfiguration des Diensts sollte die aktuelle Konfiguration anzeigen, dem Benutzer jedoch nicht erlauben, sie zu ändern.

SERVICE_UI_ALLOWED

Ermöglicht bei Bedarf die Anzeige eines Konfigurationsdialogfelds. Wenn die Kennzeichnung SERVICE_UI_ALLOWED festgelegt ist, sollte das Dialogfeld nur angezeigt werden, wenn das lpProps-Eigenschaftswertarray leer ist oder keine gültige Konfiguration enthält. Wenn SERVICE_UI_ALLOWED nicht festgelegt ist, wird möglicherweise weiterhin ein Dialogfeld angezeigt, wenn die SERVICE_UI_ALWAYS-Kennzeichnung festgelegt ist.

UI_CURRENT_PROVIDER_FIRST

Fordert an, dass das Konfigurationsdialogfeld für den aktiven Anbieter über anderen Dialogfeldern angezeigt wird.

SERVICE_UI_ALWAYS

Erfordert, dass der Nachrichtendienst ein Konfigurationsdialogfeld anzeigt. Wenn die SERVICE_UI_ALWAYS-Kennzeichnung nicht festgelegt ist, wird möglicherweise weiterhin ein Konfigurationsdialogfeld angezeigt, wenn die SERVICE_UI_ALLOWED-Kennzeichnung festgelegt ist und im lpProps-Eigenschaftswertarray keine gültigen Konfigurationsinformationen verfügbar sind. Es muss entweder SERVICE_UI_ALLOWED oder SERVICE_UI_ALWAYS festgelegt werden, damit eine Benutzeroberfläche angezeigt werden kann.

ulContext

[in] Der Konfigurationsvorgang, den MAPI derzeit ausführt. Der ulContext-Parameter enthält einen der folgenden Werte:

MSG_SERVICE_CONFIGURE

Änderungen an der Konfiguration des Diensts sollten im Profil vorgenommen werden. Wenn die SERVICE_UI_ALWAYS-Kennzeichnung festgelegt ist, sollte der Dienst sein Konfigurationsdialogfeld anzeigen. Das Dialogfeld sollte auch angezeigt werden, wenn die SERVICE_UI_ALLOWED-Kennzeichnung festgelegt ist und der lpProps-Parameter leer ist oder keine gültigen Konfigurationsdaten enthält. Wenn lpProps gültige Daten enthält, sollte kein Dialogfeld angezeigt werden, und der Dienst sollte diese Daten für die Konfigurationsänderung verwenden.

MSG_SERVICE_CREATE

Der Dienst wird einem Profil hinzugefügt. Wenn entweder die SERVICE_UI_ALWAYS- oder SERVICE_UI_ALLOWED-Kennzeichnung festgelegt ist, sollte der Dienst sein Konfigurationsdialogfeld anzeigen. Wenn keine Kennzeichnung festgelegt ist, sollte der Dienst fehlschlagen.

MSG_SERVICE_DELETE

Der Dienst wird aus einem Profil entfernt. Nach dem Empfang dieses Ereignisses sollte der Dienst S_OK zurückgeben.

MSG_SERVICE_INSTALL

Der Dienst wurde auf der Arbeitsstation des Benutzers über ein Netzwerk, eine Diskette oder ein anderes externes Medium installiert. Nach dem Empfang dieses Ereignisses gibt der Dienst in der Regel S_OK zurück.

MSG_SERVICE_PROVIDER_CREATE

Fordert an, dass der Dienst eine zusätzliche Instanz eines Anbieters erstellt. Wenn der Dienst diesen Vorgang unterstützt, sollte er IProviderAdmin::CreateProvider aufrufen. Wenn der Dienst diesen Vorgang nicht unterstützt, kann er MAPI_E_NO_SUPPORT zurückgeben.

MSG_SERVICE_PROVIDER_DELETE

Fordert an, dass der Dienst eine Anbieterinstanz löscht. Wenn der Dienst diesen Vorgang unterstützt, sollte er IProviderAdmin::DeleteProvider aufrufen. Wenn der Dienst diesen Vorgang nicht unterstützt, kann er MAPI_E_NO_SUPPORT zurückgeben.

MSG_SERVICE_UNINSTALL

Der Dienst wird entfernt. Nach dem Empfang dieses Ereignisses kann der Dienst alle Bereinigungsaufgaben ausführen, die vor dem Beenden des Diensts ausgeführt werden sollen, und dann mit einem Erfolgswert zurückkehren. Wenn der Benutzer das Entfernen abbricht, sollte der Dienst MAPI_E_USER_CANCEL zurückgeben.

cValues

[in] Anzahl der Eigenschaftswerte im Array, auf die der lpProps-Parameter zeigt. Der Wert des cValues-Parameters ist null, wenn MAPI keine Eigenschaftswerte übergibt.

lpProps

[in] Zeiger auf ein optionales Array von SPropValue-Strukturen, das Werte für vom Anbieter unterstützte Eigenschaften angibt, die die Funktion beim Konfigurieren des Nachrichtendiensts verwendet. Die Funktion verwendet diesen Parameter nur, wenn der ulContext-Parameter auf MSG_SERVICE_CONFIGURE festgelegt ist. Dieser Parameter wird häufig verwendet, um den Pfad zu einer Datei für einen dateibasierten Dienst zu übergeben, z. B. einen persönlichen Adressbuchdienst. Wenn die MSG_SERVICE_CONFIGURE-Kennzeichnung nicht im ulFlags-Parameter übergeben wird, muss der lpProps-Parameter null sein.

lpProviderAdmin

[in] Zeiger auf eine IProviderAdmin:IUnknown-Schnittstelle, mit der die Funktion Profilabschnitte für einen bestimmten Anbieter im aktuellen Nachrichtendienst suchen kann.

lppMAPIError

[out] Zeiger auf eine MAPIERROR-Struktur. Die Struktur wird mit der MAPIAllocateBuffer-Funktion zugeordnet. Alle Member sind optional, obwohl die meisten Strukturen eine gültige Fehlermeldungszeichenfolge im lpszError-Member enthalten. Wenn die lpszComponent- oder lpszErro-Member der Struktur vorhanden sind, muss ihr Arbeitsspeicher schließlich durch einen einzelnen Aufruf von MAPIFreeBuffer in der Basisstruktur freigegeben werden.

Rückgabewert

S_OK

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

MAPI_E_UNCONFIGURED

Der Dienstanbieter wurde nicht konfiguriert.

MAPI_E_USER_CANCEL

Der Benutzer hat den Vorgang abgebrochen, in der Regel durch Klicken auf die Schaltfläche Abbrechen in einem Dialogfeld.

MAPI_E_NO_SUPPORT

Der Anbieter unterstützt entweder keine Änderungen an seinen Objekten oder keine Benachrichtigung über Änderungen.

MAPI_E_BAD_CHARWIDTH

Entweder wurde die MAPI_UNICODE-Kennzeichnung festgelegt und die Implementierung unterstützt Unicode nicht, oder MAPI_UNICODE wurde nicht festgelegt und die Implementierung unterstützt nur Unicode.

Hinweise

Eine Funktion, die mithilfe des MSGSERVICEENTRY-Funktionsprototyps definiert wird, ermöglicht es Nachrichtendiensten, sich selbst zu konfigurieren oder andere dienstspezifische Aktionen auszuführen. Die Funktion gibt in erster Linie ein Dialogfeld an, in dem der Benutzer spezifische Einstellungen für den Nachrichtendienst ändern kann. Sie kann auch die programmgesteuerte Konfiguration unterstützen, indem das im lpProps-Parameter übergebene Eigenschaftswertarray verwendet wird. Die programmgesteuerte Konfiguration ist optional, es sei denn, der Dienst unterstützt den Profil-Assistenten, für den er erforderlich ist.

MAPI ruft diesen Einstiegspunkt aus der Systemsteuerung Anwendung oder als Reaktion auf eine Clientanwendung auf, die IMsgServiceAdmin::CreateMsgService oder IMsgServiceAdmin::ConfigureMsgService aufruft.

MAPI legt keine Einschränkung für den Funktionsnamen fest, den ein Nachrichtendienst für den MSGSERVICEENTRY-Prototyp verwendet, bevorzugt jedoch den Namen ServiceEntry. Es gibt keine Einschränkung für die Ordnungszahl für die Funktion, und eine einzelne Anbieter-DLL kann mehr als eine Funktion enthalten. Allerdings kann nur eine der Funktionen den Namen ServiceEntry haben.

Ein Nachrichtendienst kann die BuildDisplayTable-Funktion und die IMAPISupport::DoConfigPropsheet-Methode verwenden, um die Implementierung des Konfigurationsdialogfelds zu vereinfachen.

Es ist möglich, dass ein Benutzer einen MSG_SERVICE_UNINSTALL-Vorgang abbricht. In diesem Fall sollte die ServiceEntry-Funktion mit dem Benutzer überprüfen, ob der Dienst nicht entfernt werden soll, und MAPI_E_USER_CANCEL zurückgeben, wenn der Dienst installiert bleibt.

Eine Funktion, die auf dem MSGSERVICEENTRY-Prototyp basiert, gibt einen der aufgelisteten HRESULT-Werte zurück. MAPI leitet diesen Wert weiter, wenn er auf den Aufruf von IMsgServiceAdmin::ConfigureMsgService durch einen Client reagiert.

Nachrichtendienste, die eine Diensteintragsfunktion exportieren, müssen die PR_SERVICE_DLL_NAME (PidTagServiceDllName)- und PR_SERVICE_ENTRY_NAME (PidTagServiceEntryName)-Eigenschaften im Nachrichtendienstabschnitt von MAPISVC.INF enthalten.