Package com.installshield.wizard.platform.win32.win32service

Class NTServiceConfig

  • All Implemented Interfaces:
    PropertyAccessible
    public class NTServiceConfig
extends java.lang.Object
implements PropertyAccessible
    Stores all the values required for configuring a Windows NT Service. The properties of this class correspond directly to values passed to the CreateService and ChangeServiceConfig Win32 API's as well as values stored in the QUERY_SERVICE_CONFIG structure filled in by the QueryServiceConfig Win32 API.

    The table below identifies how properties within this class map to parameters passed to the Win32 CreateService API. See the Win32 API documentation for specific information on each of these parameters.

    CreateNTService Parameter CreateService Win32 API Parameter Additional Notes
    name lpServiceName
    displayName lpDisplayName
    serviceType dwServiceType
    startType dwStartType
    errorControl dwErrorControl
    command lpBinaryPathName
    loadOrderGroup lpLoadOrderGroup A value of null will result in passing NULL to the Win32 API.
    dependencies lpDependencies Each entry in the array should contain a service name or a load ordering group that is to be started before this service can be started. It will be translated to the appropriate format expected by the Win32 API. A value of null will result in passing NULL to the Win32 API.
    userName lpServiceStartName A value of null will result in passing NULL to the Win32 API.
    password lpPassword A value of null will result in passing NULL to the Win32 API.

    • Constructor Summary

      Constructors 
      Constructor Description
      NTServiceConfig()
      Constructs a new instance of a NTServiceConfig object and assigns its properties to default values.
      NTServiceConfig​(NTServiceConfig copyFrom)
      Constructs a new NTServiceConfig object as a deep copy of an existing one.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addDependency​(java.lang.String dependency)
      Adds a new service or load order group dependency for this service.
      java.lang.String getCommand()
      Returns the command (unresolved) that is used to start the service.
      java.lang.String[] getDependencies()
      Returns an array of service and/or load order group names that this service depends on.
      java.lang.String getDisplayName()
      Returns the current (unresolved) display name.
      boolean getEnableDesktopInteraction()
      Returns whether desktop interaction is enabled or not for this service configuration.
      int getErrorControl()
      Returns the error control assigned to this service configuration.
      java.lang.String getLoadOrderGroup()
      Returns the name of the load order group assigned to this configuration.
      java.lang.String getPassword()
      Returns the password to be used for the specified user account when starting this service
      int getServiceType()
      Returns the service type assigned to this service configuration.
      int getStartType()
      Returns the start type assigned to this service configuration.
      java.lang.String getUserName()
      Returns the name of the user under whose account this service will be started.
      NTServiceConfig resolve​(StringResolver resolver)
      Makes a deep copy of this NTServiceConfig object and resolves the appropriate fields within the new copy.
      void setCommand​(java.lang.String command)
      Sets the command that is used to start the service.
      void setDependencies​(java.lang.String[] dependencies)
      Sets the names of other services or load order groups that this service depends on.
      void setDisplayName​(java.lang.String displayName)
      Sets the display name to be used for the service.
      void setEnableDesktopInteraction​(boolean enableDesktopInteraction)
      Enables or disables desktop interaction in the service configuration.
      void setErrorControl​(int errorControl)
      Sets the error control to be used for the service.
      void setLoadOrderGroup​(java.lang.String loadOrderGroup)
      Sets the load order group name that this service is assigned to.
      void setPassword​(java.lang.String password)
      Sets the password that corresponds to the user name set by setUserName.
      void setServiceType​(int serviceType)
      Sets the service type to be used for the service.
      void setStartType​(int startType)
      Sets the start type to be used for the service.
      void setUserName​(java.lang.String userName)
      Sets the name of the user under whose account this service should be started.
      java.lang.String toString()
      Returns a string representation of this NTServiceConfig object.
      void validateForBuild​(com.installshield.util.Log log, java.lang.Object logSource)
      Validates the data stored in this object and logs an error if any problems are found.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • SERVICE_FILE_SYSTEM_DRIVER

        public static final int SERVICE_FILE_SYSTEM_DRIVER
        Can be used for serviceType.
        See Also:
        Constant Field Values

      • SERVICE_KERNEL_DRIVER

        public static final int SERVICE_KERNEL_DRIVER
        Can be used for serviceType.
        See Also:
        Constant Field Values

      • SERVICE_ADAPTER

        public static final int SERVICE_ADAPTER
        Can be used for serviceType.
        See Also:
        Constant Field Values

      • SERVICE_RECOGNIZER_DRIVER

        public static final int SERVICE_RECOGNIZER_DRIVER
        Can be used for serviceType.
        See Also:
        Constant Field Values

      • SERVICE_DRIVER

        public static final int SERVICE_DRIVER
        Can be used for serviceType.
        See Also:
        Constant Field Values

      • SERVICE_WIN32_OWN_PROCESS

        public static final int SERVICE_WIN32_OWN_PROCESS
        Can be used for serviceType.
        See Also:
        Constant Field Values

      • SERVICE_WIN32_SHARE_PROCESS

        public static final int SERVICE_WIN32_SHARE_PROCESS
        Can be used for serviceType.
        See Also:
        Constant Field Values

      • SERVICE_WIN32

        public static final int SERVICE_WIN32
        Can be used for serviceType.
        See Also:
        Constant Field Values

      • SERVICE_TYPE_ALL

        public static final int SERVICE_TYPE_ALL
        Can be used for serviceType.
        See Also:
        Constant Field Values

      • SERVICE_AUTO_START

        public static final int SERVICE_AUTO_START
        Can be used for startType
        See Also:
        Constant Field Values

      • SERVICE_BOOT_START

        public static final int SERVICE_BOOT_START
        Can be used for startType
        See Also:
        Constant Field Values

      • SERVICE_DEMAND_START

        public static final int SERVICE_DEMAND_START
        Can be used for startType
        See Also:
        Constant Field Values

      • SERVICE_DISABLED

        public static final int SERVICE_DISABLED
        Can be used for startType
        See Also:
        Constant Field Values

      • SERVICE_SYSTEM_START

        public static final int SERVICE_SYSTEM_START
        Can be used for startType
        See Also:
        Constant Field Values

      • SERVICE_ERROR_IGNORE

        public static final int SERVICE_ERROR_IGNORE
        Can be used for errorControl
        See Also:
        Constant Field Values

      • SERVICE_ERROR_NORMAL

        public static final int SERVICE_ERROR_NORMAL
        Can be used for errorControl
        See Also:
        Constant Field Values

      • SERVICE_ERROR_SEVERE

        public static final int SERVICE_ERROR_SEVERE
        Can be used for errorControl
        See Also:
        Constant Field Values

      • SERVICE_ERROR_CRITICAL

        public static final int SERVICE_ERROR_CRITICAL
        Can be used for errorControl
        See Also:
        Constant Field Values

    • Constructor Detail

      • NTServiceConfig

        public NTServiceConfig()
        Constructs a new instance of a NTServiceConfig object and assigns its properties to default values.

      • NTServiceConfig

        public NTServiceConfig​(NTServiceConfig copyFrom)
        Constructs a new NTServiceConfig object as a deep copy of an existing one.
        Parameters:
        copyFrom - The existing NTServiceConfig object to be copied

    • Method Detail

      • toString

        public java.lang.String toString()
        Returns a string representation of this NTServiceConfig object.
        Overrides:
        toString in class java.lang.Object
        Returns:
        the hard-coded string "Service Configuration"

      • setDisplayName

        public void setDisplayName​(java.lang.String displayName)
        Sets the display name to be used for the service.
        Parameters:
        displayName - The new display name.

      • getDisplayName

        public java.lang.String getDisplayName()
        Returns the current (unresolved) display name.
        Returns:
        the display name for this service configuration

      • setServiceType

        public void setServiceType​(int serviceType)
        Sets the service type to be used for the service. It should be one of:
        • SERVICE_FILE_SYSTEM_DRIVER
        • SERVICE_KERNEL_DRIVER
        • SERVICE_ADAPTER
        • SERVICE_RECOGNIZER_DRIVER
        • SERVICE_DRIVER
        • SERVICE_WIN32_OWN_PROCESS
        • SERVICE_WIN32_SHARE_PROCESS
        • SERVICE_WIN32
        • SERVICE_TYPE_ALL
        Parameters:
        serviceType - The service type for this configuration

      • getServiceType

        public int getServiceType()
        Returns the service type assigned to this service configuration.
        Returns:
        the service type

      • setEnableDesktopInteraction

        public void setEnableDesktopInteraction​(boolean enableDesktopInteraction)
        Enables or disables desktop interaction in the service configuration.
        Parameters:
        enableDesktopInteraction - True if desktop interaction should be enabled, and false otherwise.

      • getEnableDesktopInteraction

        public boolean getEnableDesktopInteraction()
        Returns whether desktop interaction is enabled or not for this service configuration.
        Returns:
        true if desktop interaction is enabled, false otherwise

      • setStartType

        public void setStartType​(int startType)
        Sets the start type to be used for the service. It should be one of:
        • SERVICE_AUTO_START
        • SERVICE_BOOT_START
        • SERVICE_DEMAND_START
        • SERVICE_DISABLED
        • SERVICE_SYSTEM_START
        Parameters:
        startType - The start type for the configuration

      • getStartType

        public int getStartType()
        Returns the start type assigned to this service configuration.
        Returns:
        the start type

      • setErrorControl

        public void setErrorControl​(int errorControl)
        Sets the error control to be used for the service. It should be one of:
        • SERVICE_ERROR_IGNORE
        • SERVICE_ERROR_NORMAL
        • SERVICE_ERROR_SEVERE
        • SERVICE_ERROR_CRITICAL
        Parameters:
        errorControl - The error control for the configuration

      • getErrorControl

        public int getErrorControl()
        Returns the error control assigned to this service configuration.
        Returns:
        the error control

      • setCommand

        public void setCommand​(java.lang.String command)
        Sets the command that is used to start the service. This value is resolved at install time.
        Parameters:
        command - The command that is executed when the service is started.

      • getCommand

        public java.lang.String getCommand()
        Returns the command (unresolved) that is used to start the service.
        Returns:
        The command used to start the service

      • setLoadOrderGroup

        public void setLoadOrderGroup​(java.lang.String loadOrderGroup)
        Sets the load order group name that this service is assigned to. Load order group names can be used for setting dependencies when configuring other services. This property is resolved at install time.
        Parameters:
        loadOrderGroup - The name of the load order group

      • getLoadOrderGroup

        public java.lang.String getLoadOrderGroup()
        Returns the name of the load order group assigned to this configuration.
        Returns:
        The load order group name.

      • setDependencies

        public void setDependencies​(java.lang.String[] dependencies)
        Sets the names of other services or load order groups that this service depends on. When this service is started, the services it depends on are started first. Load order group names must be preceeded by SC_GROUP_IDENTIFIER ('+' character). These names are resolved at install time.
        Parameters:
        dependencies - An array of zero or more service and/or load order group names.

      • getDependencies

        public java.lang.String[] getDependencies()
        Returns an array of service and/or load order group names that this service depends on.

      • addDependency

        public void addDependency​(java.lang.String dependency)
        Adds a new service or load order group dependency for this service.

      • setUserName

        public void setUserName​(java.lang.String userName)
        Sets the name of the user under whose account this service should be started. Use a blank string for the LocalSystem account. As documented in the Win32 API, this user name should be of the form Domain\UserName. If the domain is the same as the target machine, the Domain can be set to "." (e.g. ".\TestUser"). This value is resolved at install time.
        Parameters:
        userName - The name of the user account

      • getUserName

        public java.lang.String getUserName()
        Returns the name of the user under whose account this service will be started.

      • setPassword

        public void setPassword​(java.lang.String password)
        Sets the password that corresponds to the user name set by setUserName. This password is not encrypted before storing it in the project or the archive. This should not be a problem since the vast majority of installers will need to prompt the end user for the user name and the password. So, the value set for the password in this case will be a string that resolves to the password (e.g. "$W(myInputPanel.password)").
        Parameters:
        password - The password corresponding to the user set in setUserName

      • getPassword

        public java.lang.String getPassword()
        Returns the password to be used for the specified user account when starting this service

      • validateForBuild

        public void validateForBuild​(com.installshield.util.Log log,
                             java.lang.Object logSource)
        Validates the data stored in this object and logs an error if any problems are found. It verifies that if the start type is either SERVICE_SYSTEM_START or SERVICE_BOOT_START, that the serviceType is one of the driver types. It also validates that if enableDesktopInteraction is true, that the userName is blank (e.g. LocalSystem).
        Parameters:
        log - The object that performs the logging of the errors found
        logSource - The object that should be displayed in the error message as the owner of the error

      • resolve

        public NTServiceConfig resolve​(StringResolver resolver)
        Makes a deep copy of this NTServiceConfig object and resolves the appropriate fields within the new copy.
        Returns:
        A new NTServiceConfig which is a copy of the current object with resolved fields