MSGSERVICEENTRY

Gilt für: Outlook 2013 | Outlook 2016

Definiert einen Prototyp für eine Nachrichtendiensteinstiegspunktfunktion zur Unterstützung der Nachrichtendienstkonfiguration.

Eigenschaft	Wert
Headerdatei	Mapispi.h
Definierte Funktion implementiert von:	Nachrichtendienste
Definierte Funktion aufgerufen von:	MAPI

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 instance des DienstanbietersDLL. Das Handle wird in der Regel zum Abrufen von Ressourcen verwendet.

lpMalloc

[in] Zeiger auf ein Speicherzuweisungsobjekt, das die OLE IMalloc-Schnittstelle verfügbar macht. 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 0 (null) verwendet wird. Der ulUIParam-Parameter ist das übergeordnete Fensterhandle für das Konfigurationsdialogfeld und hat den Typ HWND (in eine ULONG_PTR umgewandelt). Der Wert 0 (null) gibt an, dass kein übergeordnetes Fenster vorhanden ist.

ulFlags

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

MAPI_UNICODE

Die übergebenen Zeichenfolgen liegen im Unicode-Format vor. Wenn das MAPI_UNICODE-Flag 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 das SERVICE_UI_ALLOWED-Flag 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 das SERVICE_UI_ALWAYS-Flag 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 das SERVICE_UI_ALWAYS-Flag nicht festgelegt ist, wird möglicherweise weiterhin ein Konfigurationsdialogfeld angezeigt, wenn das SERVICE_UI_ALLOWED-Flag festgelegt ist und gültige Konfigurationsinformationen aus dem LpProps-Eigenschaftswertarray nicht verfügbar sind. Entweder SERVICE_UI_ALLOWED oder SERVICE_UI_ALWAYS muss so festgelegt werden, dass 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 Dienstkonfiguration sollten im Profil vorgenommen werden. Wenn das SERVICE_UI_ALWAYS-Flag festgelegt ist, sollte der Dienst sein Konfigurationsdialogfeld anzeigen. Das Dialogfeld sollte auch angezeigt werden, wenn das SERVICE_UI_ALLOWED-Flag 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 das SERVICE_UI_ALWAYS- oder SERVICE_UI_ALLOWED-Flag festgelegt ist, sollte der Dienst sein Konfigurationsdialogfeld anzeigen. Wenn keines der flags 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 instance 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 einen Anbieter instance löscht. Wenn der Dienst diesen Vorgang unterstützt, sollte er IProviderAdmin::D eleteProvider 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 ausgeführt werden sollten, bevor der Dienst beendet wird, und dann mit einem Erfolgswert zurückgegeben werden. Wenn der Benutzer die Entfernung abbricht, sollte der Dienst MAPI_E_USER_CANCEL zurückgeben.

cValues

[in] Anzahl der Eigenschaftswerte im Array, auf das der lpProps-Parameter verweist. Der Wert des cValues-Parameters ist 0 (null), wenn MAPI keine Eigenschaftswerte übergibt.

lpProps

[in] Zeiger auf ein optionales Array von SPropValue-Strukturen , die Werte für vom Anbieter unterstützte Eigenschaften angeben, 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 an eine Datei für einen dateibasierten Dienst zu übergeben, z. B. einen persönlichen Adressbuchdienst. Wenn das MSG_SERVICE_CONFIGURE-Flag im ulFlags-Parameter nicht übergeben wird, muss der lpProps-Parameter null sein.

lpProviderAdmin

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

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 lpszError-Member der -Struktur vorhanden sind, muss ihr Speicher schließlich durch einen einzelnen Aufruf von MAPIFreeBuffer für die 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 in der Regel abgebrochen, indem er in einem Dialogfeld auf die Schaltfläche Abbrechen geklickt hat.

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 das MAPI_UNICODE-Flag 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 Funktionsprototyps MSGSERVICEENTRY definiert wurde, ermöglicht es Nachrichtendiensten, sich selbst zu konfigurieren oder andere dienstspezifische Aktionen auszuführen. Die Funktion enthält in erster Linie ein Dialogfeld, in dem der Benutzer einstellungen für den Nachrichtendienst ändern kann. Es kann auch die programmgesteuerte Konfiguration mithilfe des Eigenschaftswertarrays unterstützen, das im lpProps-Parameter übergeben wird. Die programmgesteuerte Konfiguration ist optional, es sei denn, der Dienst unterstützt den Profil-Assistenten, für den sie 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 erhalten.

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

Ein Benutzer kann einen MSG_SERVICE_UNINSTALL Vorgang abbrechen. 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 weiterhin installiert ist.

Eine Funktion, die auf dem MSGSERVICEENTRY-Prototyp basiert, gibt einen der aufgelisteten HRESULT-Werte zurück. MAPI leitet diesen Wert weiter, wenn sie auf den Aufruf eines Clients an IMsgServiceAdmin::ConfigureMsgService antwortet.

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