Interface Winsvc.HandlerEx

    • Method Detail

      • callback

        int callback​(int dwControl,
                     int dwEventType,
                     Pointer lpEventData,
                     Pointer lpContext)
        Parameters:
        dwControl - [in] The control code. This parameter can be one of the following values.
        Control codeMeaning
        SERVICE_CONTROL_CONTINUE
        0x00000003
        Notifies a paused service that it should resume.
        SERVICE_CONTROL_INTERROGATE
        0x00000004
        Notifies a service that it should report its current status information to the service control manager.
        The handler should simply return NO_ERROR; the SCM is aware of the current state of the service.
        SERVICE_CONTROL_NETBINDADD
        0x00000007
        Notifies a network service that there is a new component for binding. The service should bind to the new component.
        Applications should use Plug and Play functionality instead.
        SERVICE_CONTROL_NETBINDDISABLE
        0x0000000A
        Notifies a network service that one of its bindings has been disabled. The service should reread its binding information and remove the binding.
        Applications should use Plug and Play functionality instead.
        SERVICE_CONTROL_NETBINDENABLE
        0x00000009
        Notifies a network service that a disabled binding has been enabled. The service should reread its binding information and add the new binding.
        Applications should use Plug and Play functionality instead.
        SERVICE_CONTROL_NETBINDREMOVE
        0x00000008
        Notifies a network service that a component for binding has been removed. The service should reread its binding information and unbind from the removed component.
        Applications should use Plug and Play functionality instead.
        SERVICE_CONTROL_PARAMCHANGE
        0x00000006
        Notifies a service that its startup parameters have changed. The service should reread its startup parameters.
        SERVICE_CONTROL_PAUSE
        0x00000002
        Notifies a service that it should pause.
        SERVICE_CONTROL_PRESHUTDOWN
        0x0000000F
        Notifies a service that the system will be shutting down. Services that need additional time to perform cleanup tasks beyond the tight time restriction at system shutdown can use this notification. The service control manager sends this notification to applications that have registered for it before sending a SERVICE_CONTROL_SHUTDOWN notification to applications that have registered for that notification.
        A service that handles this notification blocks system shutdown until the service stops or the preshutdown time-out interval specified through SERVICE_PRESHUTDOWN_INFO expires. Because this affects the user experience, services should use this feature only if it is absolutely necessary to avoid data loss or significant recovery time at the next system start.
        Windows Server 2003 and Windows XP: This value is not supported.
        SERVICE_CONTROL_SHUTDOWN
        0x00000005
        Notifies a service that the system is shutting down so the service can perform cleanup tasks.
        If a service accepts this control code, it must stop after it performs its cleanup tasks and return NO_ERROR. After the SCM sends this control code, it will not send other control codes to the service.
        SERVICE_CONTROL_STOP
        0x00000001
        Notifies a service that it should stop.
        If a service accepts this control code, it must stop upon receipt and return NO_ERROR. After the SCM sends this control code, it does not send other control codes.
        Windows XP: If the service returns NO_ERROR and continues to run, it continues to receive control codes. This behavior changed starting with Windows Server 2003 and Windows XP with SP2.

        This parameter can also be one of the following extended control codes. Note that these control codes are not supported by the Winsvc.Handler function.

        Control codeMeaning
        SERVICE_CONTROL_DEVICEEVENT
        0x0000000B
        Notifies a service of device events. (The service must have registered to receive these notifications using the RegisterDeviceNotification function.) The dwEventType and lpEventData parameters contain additional information.
        SERVICE_CONTROL_HARDWAREPROFILECHANGE
        0x0000000C
        Notifies a service that the computer's hardware profile has changed. The dwEventType parameter contains additional information.
        SERVICE_CONTROL_POWEREVENT
        0x0000000D
        Notifies a service of system power events. The dwEventType parameter contains additional information. If dwEventType is PBT_POWERSETTINGCHANGE, the lpEventData parameter also contains additional information.
        SERVICE_CONTROL_SESSIONCHANGE
        0x0000000E
        Notifies a service of session change events. Note that a service will only be notified of a user logon if it is fully loaded before the logon attempt is made. The dwEventType and lpEventData parameters contain additional information.
        SERVICE_CONTROL_TIMECHANGE
        0x00000010
        Notifies a service that the system time has changed. The lpEventData parameter contains additional information. The dwEventType parameter is not used.
        Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This control code is not supported.
        SERVICE_CONTROL_TRIGGEREVENT
        0x00000020
        Notifies a service registered for a service trigger event that the event has occurred.
        Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This control code is not supported.
        SERVICE_CONTROL_USERMODEREBOOT
        0x00000040
        Notifies a service that the user has initiated a reboot.
        Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This control code is not supported.

        This parameter can also be a user-defined control code, as described in the following table.

        Control codeMeaning
        Range 128 to 255.The service defines the action associated with the control code.
        dwEventType - The type of event that has occurred. This parameter is used if dwControl is SERVICE_CONTROL_DEVICEEVENT, SERVICE_CONTROL_HARDWAREPROFILECHANGE, SERVICE_CONTROL_POWEREVENT, or SERVICE_CONTROL_SESSIONCHANGE. Otherwise, it is zero.

        If dwControl is SERVICE_CONTROL_DEVICEEVENT, this parameter can be one of the following values:

        • DBT_DEVICEARRIVAL
        • DBT_DEVICEREMOVECOMPLETE
        • DBT_DEVICEQUERYREMOVE
        • DBT_DEVICEQUERYREMOVEFAILED
        • DBT_DEVICEREMOVEPENDING DBT_CUSTOMEVENT

        If dwControl is SERVICE_CONTROL_HARDWAREPROFILECHANGE, this parameter can be one of the following values:

        • DBT_CONFIGCHANGED
        • DBT_QUERYCHANGECONFIG
        • DBT_CONFIGCHANGECANCELED

        If dwControl is SERVICE_CONTROL_POWEREVENT, this parameter can be one of the values specified in the wParam parameter of the WM_POWERBROADCAST message.

        If dwControl is SERVICE_CONTROL_SESSIONCHANGE, this parameter can be one of the values specified in the wParam parameter of the WM_WTSSESSION_CHANGE message.

        lpEventData - [in] Additional device information, if required. The format of this data depends on the value of the dwControl and dwEventType parameters.

        If dwControl is SERVICE_CONTROL_DEVICEEVENT, this data corresponds to the lParam parameter that applications receive as part of a WM_DEVICECHANGE message.

        If dwControl is SERVICE_CONTROL_POWEREVENT and dwEventType is PBT_POWERSETTINGCHANGE, this data is a pointer to a POWERBROADCAST_SETTING structure.

        If dwControl is SERVICE_CONTROL_SESSIONCHANGE, this parameter is a pointer to a WTSSESSION_NOTIFICATION structure.

        If dwControl is SERVICE_CONTROL_TIMECHANGE, this data is a pointer to a SERVICE_TIMECHANGE_INFO structure.

        lpContext - [in] User-defined data passed from Advapi32.RegisterServiceCtrlHandlerEx(java.lang.String, com.sun.jna.platform.win32.Winsvc.HandlerEx, com.sun.jna.Pointer). When multiple services share a process, the lpContext parameter can help identify the service.
        Returns:
        The return value for this function depends on the control code received.

        The following list identifies the rules for this return value:

        • In general, if your service does not handle the control, return ERROR_CALL_NOT_IMPLEMENTED. However, your service should return NO_ERROR for SERVICE_CONTROL_INTERROGATE even if your service does not handle it.
        • If your service handles SERVICE_CONTROL_STOP or SERVICE_CONTROL_SHUTDOWN, return NO_ERROR.
        • If your service handles SERVICE_CONTROL_DEVICEEVENT, return NO_ERROR to grant the request and an error code to deny the request.
        • If your service handles SERVICE_CONTROL_HARDWAREPROFILECHANGE, return NO_ERROR to grant the request and an error code to deny the request.
        • If your service handles SERVICE_CONTROL_POWEREVENT, return NO_ERROR to grant the request and an error code to deny the request.
        • For all other control codes your service handles, return NO_ERROR.