ServiceMain callback function

The entry 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.

Syntax


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

Parameters

dwArgc [in]

The number of arguments in the lpszArgv array.

lpszArgv [in]

The null-terminated argument strings passed to the service by the call to the StartService function that started the service. If there are no arguments, this parameter can be NULL. Otherwise, the first argument (lpszArgv[0]) is the name of the service, followed by any additional arguments (lpszArgv[1] through lpszArgv[dwArgc-1]).

If the user starts a manual service using the Services snap-in from the Control Panel, the strings for the lpszArgv parameter come from the properties dialog box for the service (from the Services snap-in, right-click the service entry, click Properties, and enter the parameters in Start parameters.)

Return value

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 create a global event, call the RegisterWaitForSingleObject function on this event, and exit. This will terminate the thread that is running the ServiceMain function, but will not terminate the service. When the service is stopping, the service control handler should call SetServiceStatus with SERVICE_STOP_PENDING and signal this event. A thread from the thread pool will execute the wait callback function; this function should perform clean-up tasks, including closing the global event, and call SetServiceStatus with SERVICE_STOPPED. After the service has stopped, you should not execute any additional service code because you can introduce a race condition if the service receives a start control and ServiceMain is called again. Note that this problem is more likely to occur when multiple services share a process.

Examples

For an example, see Writing a ServiceMain Function.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Winsvc.h (include Windows.h)

See also

HandlerEx
RegisterServiceCtrlHandlerEx
RegisterWaitForSingleObject
Service Functions
Service ServiceMain Function
SERVICE_TABLE_ENTRY
SetServiceStatus
StartServiceCtrlDispatcher

 

 

Community Additions

ADD
Show:
© 2014 Microsoft