| Return code | Description |
|---|---|
| ERROR_FAILED_SERVICE_CONTROLLER_CONNECT | This error is returned if the program is being run as a console application rather than as a service. If the program will be run as a console application for debugging purposes, structure it such that service-specific code is not called when this error is returned. |
| ERROR_INVALID_DATA | The specified dispatch table contains entries that are not in the proper format. |
| ERROR_SERVICE_ALREADY_RUNNING | The process has already called StartServiceCtrlDispatcher. Each process can call StartServiceCtrlDispatcher only one time. |
This function has been superseded by the RegisterServiceCtrlHandlerEx - * function. A service can use either function, but the new function - * supports user-defined context data, and the new handler function supports - * additional extended control codes.
- * - * @param lpServiceName The name of the service run by the calling thread. - * This is the service name that the service control - * program specified in the CreateService function when - * creating the service. - * - *If the service type is SERVICE_WIN32_OWN_PROCESS, - * the function does not verify that the specified name - * is valid, because there is only one registered - * service in the process.
- * - * @param lpHandlerProc A pointer to the handler function to be registered. - * For more information, see {@link Handler}. - * - * @return A service status handle, NULL on error. Call GetLastError to - * get extended error condition. Possible error codes: - *| Return code | Description |
|---|---|
| ERROR_NOT_ENOUGH_MEMORY | Not enough memory is available to convert an ANSI string parameter to Unicode. This error does not occur for Unicode string parameters. |
| ERROR_SERVICE_NOT_IN_EXE | The service entry was specified incorrectly when the process called the {@link #StartServiceCtrlDispatcher} function. |
| Return code | Description |
|---|---|
| ERROR_NOT_ENOUGH_MEMORY | Not enough memory is available to convert an ANSI string parameter to Unicode. This error does not occur for Unicode string parameters. |
| ERROR_SERVICE_NOT_IN_EXE | The service entry was specified incorrectly when the process called the {@link #StartServiceCtrlDispatcher} function. |
| Return code | Description |
|---|---|
| ERROR_INVALID_DATA | The specified service status structure is invalid. |
| ERROR_INVALID_HANDLE | The specified handle is invalid. |
| Value | Meaning |
|---|---|
| SERVICE_ADAPTER 0x00000004 | Reserved. |
| SERVICE_FILE_SYSTEM_DRIVER 0x00000002 | File system driver service. |
| SERVICE_KERNEL_DRIVER 0x00000001 | Driver service. |
| SERVICE_RECOGNIZER_DRIVER 0x00000008 | Reserved. |
| SERVICE_WIN32_OWN_PROCESS 0x00000010 | Service that runs in its own process. |
| SERVICE_WIN32_SHARE_PROCESS 0x00000020 | Service that shares a process with one or more other services. For more information, see Service Programs. |
If you specify either SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS, and the service is running in the context of the LocalSystem account, you can also specify the following value.
- * - *| Value | Meaning |
|---|---|
| SERVICE_INTERACTIVE_PROCESS 0x00000100 | The service can interact with the desktop. |
| Value | Meaning |
|---|---|
| SERVICE_AUTO_START 0x00000002 | A service started automatically by the service control manager during system startup. |
| SERVICE_BOOT_START 0x00000000 | A device driver started by the system loader. This value is valid only for driver services. |
| SERVICE_DEMAND_START 0x00000003 | A service started by the service control manager when a process calls the StartService function. |
| SERVICE_DISABLED 0x00000004 | A service that cannot be started. Attempts to start the service result in the error code ERROR_SERVICE_DISABLED. |
| SERVICE_SYSTEM_START 0x00000001 | A device driver started by the IoInitSystem function. This value is valid only for driver services. |
| Value | Meaning |
|---|---|
| SERVICE_ERROR_CRITICAL 0x00000003 | The startup program logs the error in the event log, if possible. If the last-known-good configuration is being started, the startup operation fails. Otherwise, the system is restarted with the last-known good configuration. |
| SERVICE_ERROR_IGNORE 0x00000000 | The startup program ignores the error and continues the startup operation. |
| SERVICE_ERROR_NORMAL 0x00000001 | The startup program logs the error in the event log but continues the startup operation. |
| SERVICE_ERROR_SEVERE 0x00000002 | The startup program logs the error in the event log. If the last-known-good configuration is being started, the startup operation continues. Otherwise, the system is restarted with the last-known-good configuration. |
The path can also include arguments for an - * auto-start service. For example, - * "d:\\myshare\\myservice.exe arg1 arg2". These - * passed to the service entry point (typically - * the main function).
- * - *If you specify a path on another computer, - * the share must be accessible by the computer - * account of the local computer because this is - * the security context used in the remote call. - * However, this requirement allows any potential - * vulnerabilities in the remote computer to - * affect the local computer. Therefore, it is - * best to use a local file.
- * - * @param lpLoadOrderGroup [in, optional] The names of the load ordering - * group of which this service is a member. - * Specify NULL or an empty string if the service - * does not belong to a group. - * - *The startup program uses load ordering - * groups to load groups of services in a - * specified order with respect to the other - * groups. The list of load ordering groups is - * contained in the following registry value:
- * - *HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ServiceGroupOrder
- * @param lpdwTagId [out, optional] A pointer to a variable that - * receives a tag value that is unique in the - * group specified in the lpLoadOrderGroup - * parameter. Specify NULL if you are not changing - * the existing tag. - * - *You can use a tag for ordering service - * startup within a load ordering group by - * specifying a tag order vector in the following - * registry value:
- * - *HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\GroupOrderList
- * - *Tags are only evaluated for driver services - * that have SERVICE_BOOT_START or - * SERVICE_SYSTEM_START start types.
- * @param lpDependencies [in, optional] A pointer to a double - * null-terminated array of null-separated names - * of services or load ordering groups that the - * system must start before this service. Specify - * NULL or an empty string if the service has no - * dependencies. Dependency on a group means that - * this service can run if at least one member of - * the group is running after an attempt to start - * all members of the group. - * - *You must prefix group names with - * SC_GROUP_IDENTIFIER so that they can be - * distinguished from a service name, because - * services and service groups share the same name - * space.
- * @param lpServiceStartName [in, optional] The name of the account under - * which the service should run. If the service - * type is SERVICE_WIN32_OWN_PROCESS, use an - * account name in the form DomainName\UserName. - * The service process will be logged on as this - * user. If the account belongs to the built-in - * domain, you can specify .\UserName. - * - *If this parameter is NULL, CreateService - * uses the LocalSystem account. If the service - * type specifies SERVICE_INTERACTIVE_PROCESS, the - * service must run in the LocalSystem account.
- * - *If this parameter is NT AUTHORITY\LocalService, - * CreateService uses the LocalService account. If - * the parameter is NT AUTHORITY\NetworkService, - * CreateService uses the NetworkService account.
- * - *A shared process can run as any user.
- * - *If the service type is SERVICE_KERNEL_DRIVER - * or SERVICE_FILE_SYSTEM_DRIVER, the name is the - * driver object name that the system uses to load - * the device driver. Specify NULL if the driver - * is to use a default object name created by the - * I/O system.
- * - *A service can be configured to use a managed - * account or a virtual account. If the service is - * configured to use a managed service account, - * the name is the managed service account name. - * If the service is configured to use a virtual - * account, specify the name as NT - * SERVICE\ServiceName. For more information about - * managed service accounts and virtual accounts, - * see the Service Accounts Step-by-Step Guide. - * - *
Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: - * Managed service accounts and virtual accounts are not supported until - * Windows 7 and Windows Server 2008 R2.
- * @param lpPassword [in, optional] The password to the account name - * specified by the lpServiceStartName parameter. - * Specify an empty string if the account has no - * password or if the service runs in the - * LocalService, NetworkService, or LocalSystem - * account. For more information, see Service - * Record List. - * - *If the account name specified by the - * lpServiceStartName parameter is the name of a - * managed service account or virtual account - * name, the lpPassword parameter must be NULL.
- * - *Passwords are ignored for driver services.
- * - * @return SC_HANDLE on success, NULL on error. Call GetLastError to - * get extended error condition. Possible error codes: - * - *| Return code | Description |
|---|---|
| ERROR_ACCESS_DENIED | The handle to the SCM database does not have the SC_MANAGER_CREATE_SERVICE access right. |
| ERROR_CIRCULAR_DEPENDENCY | A circular service dependency was specified. |
| ERROR_DUPLICATE_SERVICE_NAME | The display name already exists in the service control manager database either as a service name or as another display name. |
| ERROR_INVALID_HANDLE | The handle to the specified service control manager database is invalid. |
| ERROR_INVALID_NAME | The specified service name is invalid. |
| ERROR_INVALID_PARAMETER | A parameter that was specified is invalid. |
| ERROR_INVALID_SERVICE_ACCOUNT | The user account name specified in the lpServiceStartName parameter does not exist. |
| ERROR_SERVICE_EXISTS | The specified service already exists in this database. |
| ERROR_SERVICE_MARKED_FOR_DELETE | The specified service already exists in this database and has been marked for deletion. |
| Return code | Description |
|---|---|
| ERROR_ACCESS_DENIED | The handle does not have the DELETE access right. |
| ERROR_INVALID_HANDLE | The specified handle is invalid. |
| ERROR_SERVICE_MARKED_FOR_DELETE | The specified service has already been marked for deletion. |
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.) - */ - public void callback(int dwArgc, Pointer lpszArgv); - } - - /** - * An application-defined callback function used with the - * RegisterServiceCtrlHandler function. A service program can use it as the - * control handler function of a particular service. - * - *
- * This function has been superseded by the {@link HandlerEx} control handler - * function used with the {@link #RegisterServiceCtrlHandlerEx} function. A service - * can use either control handler, but the new control handler supports - * user-defined context data and additional extended control codes.
- */ - interface Handler extends StdCallCallback { - - /** - * @param fdwControl [in] The control code. This parameter can be one of - * the following values. - *| Control code | Meaning |
|---|---|
| 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_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 a user-defined control code, as described in the following table.
- * - *| Control code | Meaning |
|---|---|
| Range 128 to 255. | The service defines the action associated with the control code. |
This function supersedes the Handler control handler function used - * with the {@link RegisterServiceCtrlHandler} function. A service can use either - * control handler, but the new control handler supports user-defined - * context data and additional extended control codes.
- */ - interface HandlerEx extends StdCallCallback { - - /** - * @param dwControl [in] The control code. This parameter can be one of - * the following values. - *| Control code | Meaning |
|---|---|
| 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 {@link Handler} function.
- * - *| Control code | Meaning |
|---|---|
| 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 code | Meaning |
|---|---|
| Range 128 to 255. | The service defines the action associated with the control code. |
If dwControl is SERVICE_CONTROL_DEVICEEVENT, this parameter can be - * one of the following values:
- * - *If dwControl is SERVICE_CONTROL_HARDWAREPROFILECHANGE, this parameter - * can be one of the following values:
- * - *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.
- * - * @param 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.
- * - * @param lpContext [in] User-defined data passed from - * {@link RegisterServiceCtrlHandlerEx}. When multiple - * services share a process, the lpContext parameter - * can help identify the service. - * - * @return The return value for this function depends on the control - * code received. - * - *The following list identifies the rules for this return value:
- * - *- * If the service is installed with the SERVICE_WIN32_OWN_PROCESS - * service type, this member is ignored, but cannot be NULL. This member - * can be an empty string ("").
- *- * If the service is installed with the SERVICE_WIN32_SHARE_PROCESS - * service type, this member specifies the name of the service that uses - * the ServiceMain function pointed to by the lpServiceProc member.
- */ - public String lpServiceName; - public SERVICE_MAIN_FUNCTION lpServiceProc; - - public SERVICE_TABLE_ENTRY() { - super(W32APITypeMapper.DEFAULT); - } - - @Override - protected List- * The description of the service. If this member is NULL, the description - * remains unchanged. If this value is an empty string (""), the current - * description is deleted.
- *- * The service description must not exceed the size of a registry value of - * type REG_SZ.
- *- * This member can specify a localized string using the following - * format:
- *- * @[path\]dllname,-strID
- *- * The string with identifier strID is loaded from dllname; the path is - * optional. For more information, see RegLoadMUIString.
- *- * Windows Server 2003 and Windows XP: Localized strings - * are not supported until Windows Vista.
- * - */ - public static class SERVICE_DESCRIPTION extends ChangeServiceConfig2Info { - - public static final List| Return code | Description |
|---|---|
| ERROR_FAILED_SERVICE_CONTROLLER_CONNECT | This error is returned if the program is being run as a console application rather than as a service. If the program will be run as a console application for debugging purposes, structure it such that service-specific code is not called when this error is returned. |
| ERROR_INVALID_DATA | The specified dispatch table contains entries that are not in the proper format. |
| ERROR_SERVICE_ALREADY_RUNNING | The process has already called StartServiceCtrlDispatcher. Each process can call StartServiceCtrlDispatcher only one time. |
This function has been superseded by the RegisterServiceCtrlHandlerEx + * function. A service can use either function, but the new function + * supports user-defined context data, and the new handler function supports + * additional extended control codes.
+ * + * @param lpServiceName The name of the service run by the calling thread. + * This is the service name that the service control + * program specified in the CreateService function when + * creating the service. + * + *If the service type is SERVICE_WIN32_OWN_PROCESS, + * the function does not verify that the specified name + * is valid, because there is only one registered + * service in the process.
+ * + * @param lpHandlerProc A pointer to the handler function to be registered. + * For more information, see {@link Handler}. + * + * @return A service status handle, NULL on error. Call GetLastError to + * get extended error condition. Possible error codes: + *| Return code | Description |
|---|---|
| ERROR_NOT_ENOUGH_MEMORY | Not enough memory is available to convert an ANSI string parameter to Unicode. This error does not occur for Unicode string parameters. |
| ERROR_SERVICE_NOT_IN_EXE | The service entry was specified incorrectly when the process called the {@link #StartServiceCtrlDispatcher} function. |
| Return code | Description |
|---|---|
| ERROR_NOT_ENOUGH_MEMORY | Not enough memory is available to convert an ANSI string parameter to Unicode. This error does not occur for Unicode string parameters. |
| ERROR_SERVICE_NOT_IN_EXE | The service entry was specified incorrectly when the process called the {@link #StartServiceCtrlDispatcher} function. |
| Return code | Description |
|---|---|
| ERROR_INVALID_DATA | The specified service status structure is invalid. |
| ERROR_INVALID_HANDLE | The specified handle is invalid. |
| Value | Meaning |
|---|---|
| SERVICE_ADAPTER 0x00000004 | Reserved. |
| SERVICE_FILE_SYSTEM_DRIVER 0x00000002 | File system driver service. |
| SERVICE_KERNEL_DRIVER 0x00000001 | Driver service. |
| SERVICE_RECOGNIZER_DRIVER 0x00000008 | Reserved. |
| SERVICE_WIN32_OWN_PROCESS 0x00000010 | Service that runs in its own process. |
| SERVICE_WIN32_SHARE_PROCESS 0x00000020 | Service that shares a process with one or more other services. For more information, see Service Programs. |
If you specify either SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS, and the service is running in the context of the LocalSystem account, you can also specify the following value.
+ * + *| Value | Meaning |
|---|---|
| SERVICE_INTERACTIVE_PROCESS 0x00000100 | The service can interact with the desktop. |
| Value | Meaning |
|---|---|
| SERVICE_AUTO_START 0x00000002 | A service started automatically by the service control manager during system startup. |
| SERVICE_BOOT_START 0x00000000 | A device driver started by the system loader. This value is valid only for driver services. |
| SERVICE_DEMAND_START 0x00000003 | A service started by the service control manager when a process calls the StartService function. |
| SERVICE_DISABLED 0x00000004 | A service that cannot be started. Attempts to start the service result in the error code ERROR_SERVICE_DISABLED. |
| SERVICE_SYSTEM_START 0x00000001 | A device driver started by the IoInitSystem function. This value is valid only for driver services. |
| Value | Meaning |
|---|---|
| SERVICE_ERROR_CRITICAL 0x00000003 | The startup program logs the error in the event log, if possible. If the last-known-good configuration is being started, the startup operation fails. Otherwise, the system is restarted with the last-known good configuration. |
| SERVICE_ERROR_IGNORE 0x00000000 | The startup program ignores the error and continues the startup operation. |
| SERVICE_ERROR_NORMAL 0x00000001 | The startup program logs the error in the event log but continues the startup operation. |
| SERVICE_ERROR_SEVERE 0x00000002 | The startup program logs the error in the event log. If the last-known-good configuration is being started, the startup operation continues. Otherwise, the system is restarted with the last-known-good configuration. |
The path can also include arguments for an + * auto-start service. For example, + * "d:\\myshare\\myservice.exe arg1 arg2". These + * passed to the service entry point (typically + * the main function).
+ * + *If you specify a path on another computer, + * the share must be accessible by the computer + * account of the local computer because this is + * the security context used in the remote call. + * However, this requirement allows any potential + * vulnerabilities in the remote computer to + * affect the local computer. Therefore, it is + * best to use a local file.
+ * + * @param lpLoadOrderGroup [in, optional] The names of the load ordering + * group of which this service is a member. + * Specify NULL or an empty string if the service + * does not belong to a group. + * + *The startup program uses load ordering + * groups to load groups of services in a + * specified order with respect to the other + * groups. The list of load ordering groups is + * contained in the following registry value:
+ * + *HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ServiceGroupOrder
+ * @param lpdwTagId [out, optional] A pointer to a variable that + * receives a tag value that is unique in the + * group specified in the lpLoadOrderGroup + * parameter. Specify NULL if you are not changing + * the existing tag. + * + *You can use a tag for ordering service + * startup within a load ordering group by + * specifying a tag order vector in the following + * registry value:
+ * + *HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\GroupOrderList
+ * + *Tags are only evaluated for driver services + * that have SERVICE_BOOT_START or + * SERVICE_SYSTEM_START start types.
+ * @param lpDependencies [in, optional] A pointer to a double + * null-terminated array of null-separated names + * of services or load ordering groups that the + * system must start before this service. Specify + * NULL or an empty string if the service has no + * dependencies. Dependency on a group means that + * this service can run if at least one member of + * the group is running after an attempt to start + * all members of the group. + * + *You must prefix group names with + * SC_GROUP_IDENTIFIER so that they can be + * distinguished from a service name, because + * services and service groups share the same name + * space.
+ * @param lpServiceStartName [in, optional] The name of the account under + * which the service should run. If the service + * type is SERVICE_WIN32_OWN_PROCESS, use an + * account name in the form DomainName\UserName. + * The service process will be logged on as this + * user. If the account belongs to the built-in + * domain, you can specify .\UserName. + * + *If this parameter is NULL, CreateService + * uses the LocalSystem account. If the service + * type specifies SERVICE_INTERACTIVE_PROCESS, the + * service must run in the LocalSystem account.
+ * + *If this parameter is NT AUTHORITY\LocalService, + * CreateService uses the LocalService account. If + * the parameter is NT AUTHORITY\NetworkService, + * CreateService uses the NetworkService account.
+ * + *A shared process can run as any user.
+ * + *If the service type is SERVICE_KERNEL_DRIVER + * or SERVICE_FILE_SYSTEM_DRIVER, the name is the + * driver object name that the system uses to load + * the device driver. Specify NULL if the driver + * is to use a default object name created by the + * I/O system.
+ * + *A service can be configured to use a managed + * account or a virtual account. If the service is + * configured to use a managed service account, + * the name is the managed service account name. + * If the service is configured to use a virtual + * account, specify the name as NT + * SERVICE\ServiceName. For more information about + * managed service accounts and virtual accounts, + * see the Service Accounts Step-by-Step Guide. + * + *
Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: + * Managed service accounts and virtual accounts are not supported until + * Windows 7 and Windows Server 2008 R2.
+ * @param lpPassword [in, optional] The password to the account name + * specified by the lpServiceStartName parameter. + * Specify an empty string if the account has no + * password or if the service runs in the + * LocalService, NetworkService, or LocalSystem + * account. For more information, see Service + * Record List. + * + *If the account name specified by the + * lpServiceStartName parameter is the name of a + * managed service account or virtual account + * name, the lpPassword parameter must be NULL.
+ * + *Passwords are ignored for driver services.
+ * + * @return SC_HANDLE on success, NULL on error. Call GetLastError to + * get extended error condition. Possible error codes: + * + *| Return code | Description |
|---|---|
| ERROR_ACCESS_DENIED | The handle to the SCM database does not have the SC_MANAGER_CREATE_SERVICE access right. |
| ERROR_CIRCULAR_DEPENDENCY | A circular service dependency was specified. |
| ERROR_DUPLICATE_SERVICE_NAME | The display name already exists in the service control manager database either as a service name or as another display name. |
| ERROR_INVALID_HANDLE | The handle to the specified service control manager database is invalid. |
| ERROR_INVALID_NAME | The specified service name is invalid. |
| ERROR_INVALID_PARAMETER | A parameter that was specified is invalid. |
| ERROR_INVALID_SERVICE_ACCOUNT | The user account name specified in the lpServiceStartName parameter does not exist. |
| ERROR_SERVICE_EXISTS | The specified service already exists in this database. |
| ERROR_SERVICE_MARKED_FOR_DELETE | The specified service already exists in this database and has been marked for deletion. |
| Return code | Description |
|---|---|
| ERROR_ACCESS_DENIED | The handle does not have the DELETE access right. |
| ERROR_INVALID_HANDLE | The specified handle is invalid. |
| ERROR_SERVICE_MARKED_FOR_DELETE | The specified service has already been marked for deletion. |
+ * Required to call the NotifyServiceStatusChange function to receive + * notification when a service changes status.
+ */ int SERVICE_QUERY_STATUS = 0x0004; int SERVICE_ENUMERATE_DEPENDENTS = 0x0008; + /** + * Required to call the + * {@link com.sun.jna.platform.win32.Advapi32#StartService} function to + * start the service. + */ int SERVICE_START = 0x0010; - int SERVICE_STOP = 0x0020; - int SERVICE_PAUSE_CONTINUE = 0x0040; - int SERVICE_INTERROGATE = 0x0080; + /** + * Required to call the + * {@link com.sun.jna.platform.win32.Advapi32#ControlService} function to + * stop the service. + */ + int SERVICE_STOP = 0x0020; + /** + * Required to call the + * {@link com.sun.jna.platform.win32.Advapi32#ControlService} function to + * pause or continue the service. + */ + int SERVICE_PAUSE_CONTINUE = 0x0040; + /** + * Required to call the + * {@link com.sun.jna.platform.win32.Advapi32#ControlService} function to + * pause or continue the service. + */ + int SERVICE_INTERROGATE = 0x0080; + /** + * Required to call the + * {@link com.sun.jna.platform.win32.Advapi32#ControlService} function to + * ask the service to report its status immediately. + */ int SERVICE_USER_DEFINED_CONTROL = 0x0100; int SERVICE_ALL_ACCESS = @@ -399,15 +446,63 @@ public static class SC_HANDLE extends HANDLE { } // // Controls // + /** + * Notifies a service that it should stop. The hService handle must have the + * {@link #SERVICE_STOP} access right. + * + *After sending the stop request to a service, you should not send other + * controls to the service.
+ */ int SERVICE_CONTROL_STOP = 0x00000001; + /** + * Notifies a service that it should pause. The hService handle must have + * the {@link #SERVICE_PAUSE_CONTINUE} access right. + */ int SERVICE_CONTROL_PAUSE = 0x00000002; + /** + * Notifies a service that its startup parameters have changed. The hService + * handle must have the {@link #SERVICE_PAUSE_CONTINUE} access right. + */ int SERVICE_CONTROL_CONTINUE = 0x00000003; + /** + * Notifies a service that it should report its current status information + * to the service control manager. The hService handle must have the + * {@link #SERVICE_INTERROGATE} access right. + * + *+ * Note that this control is not generally useful as the SCM is aware of the + * current state of the service.
+ */ int SERVICE_CONTROL_INTERROGATE = 0x00000004; int SERVICE_CONTROL_SHUTDOWN = 0x00000005; int SERVICE_CONTROL_PARAMCHANGE = 0x00000006; + /** + * Notifies a network service that there is a new component for binding. The + * hService handle must have the {@link #SERVICE_PAUSE_CONTINUE} access + * right. However, this control code has been deprecated; use Plug and Play + * functionality instead. + */ int SERVICE_CONTROL_NETBINDADD = 0x00000007; + /** + * Notifies a network service that a component for binding has been removed. + * The hService handle must have the {@link #SERVICE_PAUSE_CONTINUE} access + * right. However, this control code has been deprecated; use Plug and Play + * functionality instead. + */ int SERVICE_CONTROL_NETBINDREMOVE = 0x00000008; + /** + * Notifies a network service that a disabled binding has been enabled. The + * hService handle must have the {@link #SERVICE_PAUSE_CONTINUE} access + * right. However, this control code has been deprecated; use Plug and Play + * functionality instead. + */ int SERVICE_CONTROL_NETBINDENABLE = 0x00000009; + /** + * Notifies a network service that one of its bindings has been disabled. + * The hService handle must have the {@link #SERVICE_PAUSE_CONTINUE} access + * right. However, this control code has been deprecated; use Plug and Play + * functionality instead. + */ int SERVICE_CONTROL_NETBINDDISABLE = 0x0000000A; int SERVICE_CONTROL_DEVICEEVENT = 0x0000000B; int SERVICE_CONTROL_HARDWAREPROFILECHANGE = 0x0000000C; @@ -472,4 +567,284 @@ public static class SC_HANDLE extends HANDLE { } public abstract class SC_STATUS_TYPE { public static final int SC_STATUS_PROCESS_INFO = 0; } + + /** + * The entry point for a service. + */ + interface SERVICE_MAIN_FUNCTION extends StdCallLibrary.StdCallCallback { + + /** + * + * @param dwArgc [in] The number of arguments in the lpszArgv array. + * @param 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.) + */ + public void callback(int dwArgc, Pointer lpszArgv); + } + + /** + * An application-defined callback function used with the + * RegisterServiceCtrlHandler function. A service program can use it as the + * control handler function of a particular service. + * + *
+ * This function has been superseded by the {@link HandlerEx} control handler + * function used with the {@link #RegisterServiceCtrlHandlerEx} function. A service + * can use either control handler, but the new control handler supports + * user-defined context data and additional extended control codes.
+ */ + interface Handler extends StdCallLibrary.StdCallCallback { + + /** + * @param fdwControl [in] The control code. This parameter can be one of + * the following values. + *| Control code | Meaning |
|---|---|
| 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_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 a user-defined control code, as described in the following table.
+ * + *| Control code | Meaning |
|---|---|
| Range 128 to 255. | The service defines the action associated with the control code. |
This function supersedes the Handler control handler function used + * with the {@link RegisterServiceCtrlHandler} function. A service can use either + * control handler, but the new control handler supports user-defined + * context data and additional extended control codes.
+ */ + interface HandlerEx extends StdCallLibrary.StdCallCallback { + + /** + * @param dwControl [in] The control code. This parameter can be one of + * the following values. + *| Control code | Meaning |
|---|---|
| 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 {@link Handler} function.
+ * + *| Control code | Meaning |
|---|---|
| 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 code | Meaning |
|---|---|
| Range 128 to 255. | The service defines the action associated with the control code. |
If dwControl is SERVICE_CONTROL_DEVICEEVENT, this parameter can be + * one of the following values:
+ * + *If dwControl is SERVICE_CONTROL_HARDWAREPROFILECHANGE, this parameter + * can be one of the following values:
+ * + *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.
+ * + * @param 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.
+ * + * @param lpContext [in] User-defined data passed from + * {@link RegisterServiceCtrlHandlerEx}. When multiple + * services share a process, the lpContext parameter + * can help identify the service. + * + * @return The return value for this function depends on the control + * code received. + * + *The following list identifies the rules for this return value:
+ * + *+ * If the service is installed with the SERVICE_WIN32_OWN_PROCESS + * service type, this member is ignored, but cannot be NULL. This member + * can be an empty string ("").
+ *+ * If the service is installed with the SERVICE_WIN32_SHARE_PROCESS + * service type, this member specifies the name of the service that uses + * the ServiceMain function pointed to by the lpServiceProc member.
+ */ + public String lpServiceName; + public SERVICE_MAIN_FUNCTION lpServiceProc; + + public SERVICE_TABLE_ENTRY() { + super(W32APITypeMapper.DEFAULT); + } + + @Override + protected List+ * The description of the service. If this member is NULL, the description + * remains unchanged. If this value is an empty string (""), the current + * description is deleted.
+ *+ * The service description must not exceed the size of a registry value of + * type REG_SZ.
+ *+ * This member can specify a localized string using the following + * format:
+ *+ * @[path\]dllname,-strID
+ *+ * The string with identifier strID is loaded from dllname; the path is + * optional. For more information, see RegLoadMUIString.
+ *+ * Windows Server 2003 and Windows XP: Localized strings + * are not supported until Windows Vista.
+ * + */ + public static class SERVICE_DESCRIPTION extends ChangeServiceConfig2Info { + + public static final List