StartServiceCtrlDispatcherA-Funktion (winsvc.h)
Verbindet den Hauptthread eines Dienstprozesses mit dem Dienststeuerungs-Manager, wodurch der Thread der Dienststeuerungs-Dispatcherthread für den aufrufenden Prozess ist.
Syntax
BOOL StartServiceCtrlDispatcherA(
[in] const SERVICE_TABLE_ENTRYA *lpServiceStartTable
);
Parameter
[in] lpServiceStartTable
Ein Zeiger auf ein Array von SERVICE_TABLE_ENTRY Strukturen, die einen Eintrag für jeden Dienst enthalten, der im aufrufenden Prozess ausgeführt werden kann. Die Elemente des letzten Eintrags in der Tabelle müssen NULL-Werte aufweisen, um das Ende der Tabelle festzulegen.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.
Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Der folgende Fehlercode kann vom Dienststeuerungs-Manager festgelegt werden. Andere Fehlercodes können von den Registrierungsfunktionen festgelegt werden, die vom Dienststeuerungs-Manager aufgerufen werden.
| Rückgabecode | Beschreibung |
|---|---|
|
Dieser Fehler wird zurückgegeben, wenn das Programm nicht als Dienst, sondern als Konsolenanwendung ausgeführt wird.
Wenn das Programm zu Debuggingzwecken als Konsolenanwendung ausgeführt wird, strukturieren Sie es so, dass dienstspezifischer Code nicht aufgerufen wird, wenn dieser Fehler zurückgegeben wird. |
|
Die angegebene Verteilertabelle enthält Einträge, die nicht im richtigen Format vorliegen. |
|
Der Prozess hat bereits StartServiceCtrlDispatcheraufgerufen. Jeder Prozess kann StartServiceCtrlDispatcher- nur einmal aufrufen. |
Bemerkungen
Wenn der Dienststeuerungs-Manager einen Dienstprozess startet, wartet er auf den Prozess, um die StartServiceCtrlDispatcher--Funktion aufzurufen. Der Hauptthread eines Dienstprozesses sollte diesen Aufruf nach dem Start (innerhalb von 30 Sekunden) so schnell wie möglich ausführen. Wenn StartServiceCtrlDispatcher erfolgreich ist, wird der aufrufende Thread mit dem Dienststeuerungs-Manager verbunden und erst zurückgegeben, wenn alle ausgeführten Dienste im Prozess den status SERVICE_STOPPED eingegeben haben. Der Dienststeuerungs-Manager verwendet diese Verbindung zum Senden von Steuerelement- und Dienststartanforderungen an den Hauptthread des Dienstprozesses. Der Hauptthread fungiert als Verteiler, indem er die entsprechende HandlerEx--Funktion aufruft, um Steueranforderungen zu verarbeiten, oder indem ein neuer Thread erstellt wird, um die entsprechende ServiceMain--Funktion auszuführen, wenn ein neuer Dienst gestartet wird.
Der parameter lpServiceTable enthält einen Eintrag für jeden Dienst, der im aufrufenden Prozess ausgeführt werden kann. Jeder Eintrag gibt die ServiceMain--Funktion für diesen Dienst an. Für SERVICE_WIN32_SHARE_PROCESS Dienste muss jeder Eintrag den Namen eines Diensts enthalten. Dieser Name ist der Dienstname, der von der CreateService--Funktion angegeben wurde, wenn der Dienst installiert wurde. Für SERVICE_WIN32_OWN_PROCESS Dienste wird der Dienstname im Tabelleneintrag ignoriert.
Wenn ein Dienst in einem eigenen Prozess ausgeführt wird, sollte der Hauptthread des Dienstprozesses sofort StartServiceCtrlDispatcheraufrufen. Alle Initialisierungsaufgaben werden beim Starten des Diensts im ServiceMain--Funktion ausgeführt.
Wenn mehrere Dienste einen Prozess gemeinsam nutzen und einige allgemeine prozessweite Initialisierungen ausgeführt werden müssen, bevor eine ServiceMain--Funktion aufgerufen wird, kann der Hauptthread die Arbeit ausführen, bevor StartServiceCtrlDispatcheraufgerufen wird, solange es weniger als 30 Sekunden dauert. Andernfalls muss ein anderer Thread erstellt werden, um die prozessweite Initialisierung durchzuführen, während der Hauptthread StartServiceCtrlDispatcher aufruft und zum Dienststeuerungsverteiler wird. Alle dienstspezifischen Initialisierungen sollten weiterhin in den einzelnen Diensthauptfunktionen erfolgen.
Dienste sollten nicht versuchen, eine Benutzeroberfläche direkt anzuzeigen. Weitere Informationen finden Sie unter Interactive Services.
Beispiele
Ein Beispiel finden Sie unter Schreiben der Hauptfunktion eines Dienstprogramms.
Anmerkung
Der winsvc.h-Header definiert StartServiceCtrlDispatcher als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows XP [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows Server 2003 [Nur Desktop-Apps] |
| Zielplattform- | Fenster |
| Header- | winsvc.h (enthalten Windows.h) |
| Library | Advapi32.lib |
| DLL- | Advapi32.dll |