ServiceMain

ServiceMain

A ServiceMain function is the starting point for a service.

The LPSERVICE_MAIN_FUNCTION type defines a pointer to this callback function. ServiceMain is a placeholder for an application-defined function name.

VOID WINAPI ServiceMain(
  DWORD dwArgc,
  LPTSTR* lpszArgv
);

Parameters

dwArgc

[in] Number of arguments in the lpszArgv array.

lpszArgv

[in] Pointer to an array of pointers to null-terminated argument strings. The first argument in the array is the name of the service, and subsequent arguments are any strings passed to the service by the process that called the StartService function to start the service.

Return Values

This function does not return a value.

Remarks

A service program can start one or more services. A service process has a SERVICE_TABLE_ENTRY structure for each service that it can start. The structure specifies the service name and a pointer to the ServiceMain function for that service.

When the service control manager receives a request to start a service, it starts the service process (if it is not already running). The main thread of the service process calls the StartServiceCtrlDispatcher function with a pointer to an array of SERVICE_TABLE_ENTRY structures. Then the service control manager sends a start request to the service control dispatcher for this service process. The service control dispatcher creates a new thread to execute the ServiceMain function of the service being started.

The ServiceMain function should immediately call the RegisterServiceCtrlHandlerEx function to specify a HandlerEx function to handle control requests. Next, it should call the SetServiceStatus function to send status information to the service control manager. After these calls, the function should complete the initialization of the service. Do not attempt to start another service in the ServiceMain function.

The Service Control Manager (SCM) waits until the service reports a status of SERVICE_RUNNING. It is recommended that the service reports this status as quickly as possible, as other components in the system that require interaction with SCM will be blocked during this time. Some functions may require interaction with the SCM either directly or indirectly.

The SCM locks the service control database during initialization, so if a service attempts to call StartService during initialization, the call will block. When the service reports to the SCM that it has successfully started, it can call StartService. If the service requires another service to be running, the service should set the required dependencies.

Furthermore, you should not call any system functions during service initialization. The service code should call system functions only after it reports a status of SERVICE_RUNNING.

The ServiceMain function should call the RegisterWaitForSingleObject function on an event and exit. This will terminate the thread that is running the ServiceMain function, but will not terminate the service. The service control handler should signal this event when the service stops. A thread from the thread pool will execute the code that performs the cleanup and calls SetServiceStatus with SERVICE_STOPPED.

Windows NT:  On earlier platforms where RegisterWaitForSingleObject is not available, it is common practice for the thread executing the ServiceMain function to wait on an event that is signaled by the service control handler when the service stops. When the event is signaled, ServiceMain itself performs any cleanup and calls SetServiceStatus with SERVICE_STOPPED.

Example Code

For an example, see Writing a ServiceMain Function.

Requirements

Client	Requires Windows XP, Windows 2000 Professional, or Windows NT Workstation.
Server	Requires Windows Server 2003, Windows 2000 Server, or Windows NT Server.
Header	Declared in Winsvc.h; include Windows.h.