StartServiceCtrlDispatcherA-Funktion (winsvc.h)
Verbindet den Standard Thread eines Dienstprozesses mit dem Dienststeuerungs-Manager, wodurch der Thread der Dienststeuerungsverteilerthread 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 Member 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 fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
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 als Konsolenanwendung und nicht als Dienst ausgeführt wird.
Wenn das Programm zu Debugzwecken 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 StartServiceCtrlDispatcher aufgerufen. Jeder Prozess kann StartServiceCtrlDispatcher nur einmal aufrufen. |
Hinweise
Wenn der Dienststeuerungs-Manager einen Dienstprozess startet, wartet er, bis der Prozess die Funktion StartServiceCtrlDispatcher aufruft. Der Standard Thread eines Dienstprozesses sollte diesen Aufruf so schnell wie möglich nach dem Start durchführen (innerhalb von 30 Sekunden). Wenn StartServiceCtrlDispatcher erfolgreich ist, verbindet es den aufrufenden Thread mit dem Dienststeuerungs-Manager und wird erst zurückgegeben, wenn alle ausgeführten Dienste im Prozess den SERVICE_STOPPED Zustand erhalten haben. Der Dienststeuerungs-Manager verwendet diese Verbindung, um Steuerelement- und Dienststartanforderungen an den Standard Thread des Dienstprozesses zu senden. Der Standard Thread fungiert als Dispatcher, indem die entsprechende HandlerEx-Funktion aufgerufen wird, um Steuerelementanforderungen zu verarbeiten, oder indem ein neuer Thread erstellt wird, um die entsprechende ServiceMain-Funktion auszuführen, wenn ein neuer Dienst gestartet wird.
Der lpServiceTable-Parameter 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, als der Dienst installiert wurde. Bei SERVICE_WIN32_OWN_PROCESS Diensten wird der Dienstname im Tabelleneintrag ignoriert.
Wenn ein Dienst in einem eigenen Prozess ausgeführt wird, sollte der Standard Thread des Dienstprozesses sofort StartServiceCtrlDispatcher aufrufen. Alle Initialisierungsaufgaben werden in der ServiceMain-Funktion des Diensts ausgeführt, wenn der Dienst gestartet wird.
Wenn mehrere Dienste einen Prozess gemeinsam nutzen und eine allgemeine prozessweite Initialisierung durchgeführt werden muss, bevor eine ServiceMain-Funktion aufgerufen wird, kann der Standard Thread die Arbeit vor dem Aufrufen von StartServiceCtrlDispatcher erledigen, solange dies weniger als 30 Sekunden dauert. Andernfalls muss ein weiterer Thread erstellt werden, um die prozessweite Initialisierung durchzuführen, während der Standard Thread StartServiceCtrlDispatcher aufruft und zum Dienststeuerungsverteiler wird. Jede dienstspezifische Initialisierung sollte weiterhin in den einzelnen Dienst-Standard-Funktionen erfolgen.
Dienste sollten nicht versuchen, eine Benutzeroberfläche direkt anzuzeigen. Weitere Informationen finden Sie unter Interaktive Dienste.
Beispiele
Ein Beispiel finden Sie unter Schreiben der Hauptfunktion eines Dienstprogramms.
Hinweis
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 nicht codierungsneutralem Code 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 |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winsvc.h (einschließen von Windows.h) |
| Bibliothek | Advapi32.lib |
| DLL | Advapi32.dll |