Controlling a Running Service
A version of this page is also available for
4/8/2010
A running service can be controlled in much the same way as a device driver can be controlled using Device.exe. To do this, you need to open a handle to the service using the CreateFile function with the appropriate prefix and index values for a previously registered service.
You can use Input/Output Controls (IOCTLs) to control a running service. A set of IOCTLs are available to perform different tasks, such as stopping or starting a server. These IOCTLs facilitate the task of administering servers by providing a common interface for different services. Although servers are not required to implement handling for these IOCTLs, it is recommended that they do so.
To send an IOCTL to the service, the application must call the DeviceIoControl function on an open service handle.** DeviceIoControl then calls the xxx_IOControl (Services.exe) function related to that service. The following code sample shows how to obtain the current state of a Telnet server.
HANDLE hService = CreateFile(L"TEL0:",0,0,NULL,OPEN_EXISTING,0,NULL);
if(hService != INVALID_HANDLE_VALUE){
DWORD dwState; //state values are defined in service.h
DeviceIoControl(hService, IOCTL_SERVICE_STATUS, NULL, 0, &dwState,
sizeof(DWORD), NULL, NULL);
if (DeviceIOControl(hService, IOCTL_SERVICE_REFRESH, NULL, 0, NULL,
0, NULL, NULL))
_tprintf(TEXT(("Service refresh successful"));
else
_tprintf((TEXT("Service refresh failed!"));
CloseHandle(hService);
}
Some of the IOCTLs for Services.exe require an input or output parameter, or both. The input parameters refer to the pBufIn and dwLenIn parameters of the xxx_IOControl function. The output parameters refer to the pOutBuf, dwLenOut, and pdwActualOut parameters of xxx_IOControl. Unless noted otherwise in the reference page for a specific IOCTL, the service will ignore input parameters and is not responsible for setting output parameters for a specific IOCTL. You can also define customized IOCTLs that are specific to a particular application. These IOCTLs will also have customized input and output buffers. For more information, see IOCTLs that are Sent by Applications.
Not all IOCTLs that a service receives are sent by applications. Services.exe also generates some IOCTLs internally because it calls services from time to time when certain events occur. It is not necessary to implement all or any of these IOCTLs for some services. Certain scenarios may require the implementation of a specific IOCTL depending on what function your service performs. For more information, see IOCTLs that are Sent by Services.exe.
If the service supports a stream-based interface, you can also use the ReadFile, WriteFile, and SetFilePointer functions to control a running service. The implementation of these functions is specific to the desired service.
See Also
Reference
Services.exe Functions
ServiceClosePort
xxx_IOControl (Services.exe)
GetServiceHandle
Concepts
IOCTLs that are Sent by Applications
IOCTLs that are Sent by Services.exe
Other Resources
Services.exe
CreateFile
DeviceIoControl
ReadFile
WriteFile
SetFilePointer