Controlling a Running Service

Article
06/30/2006

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. Windows CE .NET supports a set of IOCTLs 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 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.

Services may also be controlled by using the GetServiceHandle function. The ReadFile, WriteFile, and SetFilePointer functions will not work with a handle returned by GetServiceHandle. They can only use a handle returned by CreateFile. If a handle is used that is returned by GetServiceHandle, the ServiceIoControl function must be used in place of the similar DeviceIoControl function. The following code sample shows how to use the GetServiceHandle function.

HANDLE hService = GetServiceHandle("TEL0:", NULL, NULL);
if(hService != INVALID_HANDLE_VALUE){
     DWORD dwState;
     ServiceIoControl(hService, IOCTL_SERVICE_STATUS, NULL, 0, &dwState, sizeof(DWORD), NULL, NULL);
}

Share via

Controlling a Running Service

See Also

Additional resources