3.1.4.49 RCreateWowService (Opnum 60)

  • Article

The RCreateWowService method creates a service whose binary is compiled for a specified computer architecture.<83> The path to the file image is automatically adjusted to point to the correct WoW-redirected location.

 DWORD RCreateWowService(
   [in] SC_RPC_HANDLE hSCManager,
   [in, string, range(0, SC_MAX_NAME_LENGTH)] 
     wchar_t* lpServiceName,
   [in, string, unique, range(0, SC_MAX_NAME_LENGTH)] 
     wchar_t* lpDisplayName,
   [in] DWORD dwDesiredAccess,
   [in] DWORD dwServiceType,
   [in] DWORD dwStartType,
   [in] DWORD dwErrorControl,
   [in, string, range(0, SC_MAX_PATH_LENGTH)] 
     wchar_t* lpBinaryPathName,
   [in, string, unique, range(0, SC_MAX_NAME_LENGTH)] 
     wchar_t* lpLoadOrderGroup,
   [in, out, unique] LPDWORD lpdwTagId,
   [in, unique, size_is(dwDependSize)] 
     LPBYTE lpDependencies,
   [in, range(0, SC_MAX_DEPEND_SIZE)] 
     DWORD dwDependSize,
   [in, string, unique, range(0, SC_MAX_ACCOUNT_NAME_LENGTH)] 
     wchar_t* lpServiceStartName,
   [in, unique, size_is(dwPwSize)] 
     LPBYTE lpPassword,
   [in, range(0, SC_MAX_PWD_SIZE)] 
     DWORD dwPwSize,
   [in] USHORT dwServiceWowType,
   [out] LPSC_RPC_HANDLE lpServiceHandle
 );

hSCManager: An SC_RPC_HANDLE (section 2.2.4) data type that defines the handle to the SCM database created using one of the open methods specified in section 3.1.4. The SC_MANAGER_CREATE_SERVICE access right MUST have been granted to the caller when the RPC context handle to the SCM was created.

lpServiceName: A pointer to a null-terminated Unicode string that specifies the name of the service to install. This MUST NOT be NULL.

The forward slash, back slash, comma, and space characters are illegal in service names.

lpDisplayName: A pointer to a null-terminated Unicode string that contains the display name by which user interface programs identify the service.

dwDesiredAccess: A value that specifies the access to the service. This MUST be one of the values as specified in section 3.1.4.

dwServiceType: A value that specifies the type of service. This MUST be one or a combination of the following values.

Value

Meaning

SERVICE_KERNEL_DRIVER

0x00000001

A driver service. These are services that manage devices on the system.

SERVICE_FILE_SYSTEM_DRIVER

0x00000002

A file system driver service. These are services that manage file systems on the system.

SERVICE_WIN32_OWN_PROCESS

0x00000010

Service that runs within its own process.

SERVICE_WIN32_SHARE_PROCESS

0x00000020

Service that shares a process with other services.

SERVICE_INTERACTIVE_PROCESS

0x00000100

The service can interact with the desktop.

dwStartType: A value that specifies when to start the service. This MUST be one of the following values.

Value

Meaning

SERVICE_BOOT_START

0x00000000

Starts the driver service when the system boots up. This value is valid only for driver services.

SERVICE_SYSTEM_START

0x00000001

Starts the driver service when the system boots up. This value is valid only for driver services. The services marked SERVICE_SYSTEM_START are started after all SERVICE_BOOT_START services have been started.

SERVICE_AUTO_START

0x00000002

Starts the service automatically during system startup.

SERVICE_DEMAND_START

0x00000003

Starts the service when a client requests the SCM to start the service.

SERVICE_DISABLED

0x00000004

Service cannot be started.

dwErrorControl: A value that specifies the severity of the error if the service fails to start and determines the action that the SCM takes. This MUST be one of the following values.

Value

Meaning

SERVICE_ERROR_IGNORE

0x00000000

The SCM ignores the error and continues the startup operation.

SERVICE_ERROR_NORMAL

0x00000001

The SCM logs the error, but continues the startup operation.

SERVICE_ERROR_SEVERE

0x00000002

The SCM logs the error. If the last-known good configuration is being started, the startup operation continues. Otherwise, the system is restarted with the last-known good configuration.

SERVICE_ERROR_CRITICAL

0x00000003

The SCM SHOULD log the error 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.

lpBinaryPathName: A pointer to a null-terminated UNICODE string that contains the fully qualified path to the service binary file. The path MAY include arguments. If the path contains a space, it MUST be quoted so that it is correctly interpreted. For example, "d:\\my share\\myservice.exe" is specified as "\"d:\\my share\\myservice.exe\"".

lpLoadOrderGroup: A pointer to a null-terminated UNICODE string that names 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 load-ordering group.

lpdwTagId: A pointer to a variable that receives a tag value. The value is unique to the group specified in the lpLoadOrderGroup parameter.

lpDependencies: A pointer to an array of null-separated names of services or load ordering groups that MUST start before this service. The array is doubly null-terminated. Load ordering group names are prefixed with a "+" character (to distinguish them from service names). If the pointer is NULL or if it points to an empty string, the service has no dependencies. Cyclic dependency between services is not allowed. The character set is Unicode. Dependency on a service means that this service can run only if the service it depends on is running. 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.

dwDependSize: The size, in bytes, of the string specified by the dwDependSize parameter.

lpServiceStartName: A pointer to a null-terminated UNICODE string that specifies the name of the account under which the service runs.

lpPassword: A pointer to a null-terminated UNICODE string that contains the password of the account whose name was specified by the lpServiceStartName parameter.

dwPwSize: The size, in bytes, of the password specified by the lpPassword parameter.

dwServiceWowType: The image file machine constant corresponding to the architecture that the service binary is compiled for. This MUST be one of the following values.

Value

Meaning

IMAGE_FILE_MACHINE_UNKNOWN

0

Unknown or unspecified

IMAGE_FILE_MACHINE_TARGET_HOST

0x0001

Interacts with the host and not a WOW64 guest<84>

IMAGE_FILE_MACHINE_I386

0x014c

Intel 386 (also known as x86)

IMAGE_FILE_MACHINE_R3000

0x0160

MIPS 32-bit big-endian (R3000)

IMAGE_FILE_MACHINE_R3000

0x0162

MIPS 32-bit little-endian (R3000)

IMAGE_FILE_MACHINE_R4000

0x0166

MIPS 64-bit little-endian (R4000)

IMAGE_FILE_MACHINE_R10000

0x0168

MIPS 64-bit little-endian (R10000 MIPS IV)

IMAGE_FILE_MACHINE_WCEMIPSV2

0x0169

MIPS little-endian Windows Compact Edition (WCE) v2

IMAGE_FILE_MACHINE_ALPHA

0x0184

DEC Alpha AXP 32-bit

IMAGE_FILE_MACHINE_SH3

0x01a2

Hitachi SH-3 32-bit little-endian

IMAGE_FILE_MACHINE_SH3DSP

0x01a3

Hitachi SH-3 DSP 32-bit

IMAGE_FILE_MACHINE_SH3E

0x01a4

Hitachi SH-3E 32-bit little-endian

IMAGE_FILE_MACHINE_SH4

0x01a6

Hitachi SH-4 32-bit little-endian

IMAGE_FILE_MACHINE_SH5

0x01a8

Hitachi SH-5 64-bit

IMAGE_FILE_MACHINE_ARM

0x01c0

ARM Little-Endian

IMAGE_FILE_MACHINE_THUMB

0x01c2

ARM Thumb/Thumb-2 Little-Endian

IMAGE_FILE_MACHINE_ARMNT

0x01c4

ARM Thumb-2 Little-Endian<85>

IMAGE_FILE_MACHINE_AM33

0x01d3

Matsushita AM33, now Panasonic MN103

IMAGE_FILE_MACHINE_POWERPC

0x01F0

IBM PowerPC 32-bit Little-Endian

IMAGE_FILE_MACHINE_POWERPCFP

0x01f1

PowerPC 32-bit with FPU

IMAGE_FILE_MACHINE_IA64

0x0200

Intel IA-64 (also known as Itanium Architecture)

IMAGE_FILE_MACHINE_MIPS16

0x0266

MIPS 16-bit

IMAGE_FILE_MACHINE_ALPHA64

0x0284

DEC Alpha AXP 64-bit (same as IMAGE_FILE_MACHINE_AXP64)

IMAGE_FILE_MACHINE_MIPSFPU

0x0366

MIPS 32-bit with FPU

IMAGE_FILE_MACHINE_MIPSFPU16

0x0466

MIPS 16-bit with FPU

IMAGE_FILE_MACHINE_AXP64

0x0284

DEC Alpha AXP 64-bit (same as IMAGE_FILE_MACHINE_ALPHA64)

IMAGE_FILE_MACHINE_TRICORE

0x0520

Infineon AUDO 32-bit

IMAGE_FILE_MACHINE_CEF

0x0CEF

CEF

IMAGE_FILE_MACHINE_EBC

0x0EBC

EFI/UEFI Byte Code

IMAGE_FILE_MACHINE_AMD64

0x8664

AMD64 (also known as x64)

IMAGE_FILE_MACHINE_M32R

0x9041

Mitsubishi M32R 32-bit little-endian

IMAGE_FILE_MACHINE_ARM64

0xAA64

ARM64 little-endian<86>

IMAGE_FILE_MACHINE_CEE

0xC0EE

CEE

lpServiceHandle: An LPSC_RPC_HANDLE (section 2.2.4) data type that defines the handle to the newly created service record.

Return Values: The method returns 0x00000000 (ERROR_SUCCESS) on success; otherwise, it returns one of the following error codes.

Return value/code

Description

5

ERROR_ACCESS_DENIED

The SC_MANAGER_CREATE_SERVICE access right had not been granted to the caller when the RPC context handle to the SCM was created.

6

ERROR_INVALID_HANDLE

The handle specified is invalid.

13

ERROR_INVALID_DATA

The data is invalid.

50

ERROR_NOT_SUPPORTED

dwServiceWowType was an architecture that is not supported.

87

ERROR_INVALID_PARAMETER

A parameter that was specified is invalid.

123

ERROR_INVALID_NAME

The specified service name is invalid.

1057

ERROR_INVALID_SERVICE_ACCOUNT

The user account name specified in the lpServiceStartName parameter does not exist.

1059

ERROR_CIRCULAR_DEPENDENCY

A circular service dependency was specified.

1072

ERROR_SERVICE_MARKED_FOR_DELETE

The service record with a specified name already exists, and RDeleteService has been called for it.

1073

ERROR_SERVICE_EXISTS

The service record with the ServiceName matching the specified lpServiceName already exists.

1078

ERROR_DUPLICATE_SERVICE_NAME

The service record with the same DisplayName or the same ServiceName as the passed-in lpDisplayName already exists in the service control manager database.

1115

ERROR_SHUTDOWN_IN_PROGRESS

The system is shutting down.

In response to this request from the client, for a successful operation the server MUST use the service name specified in the lpServiceName parameter to create a new service record in the SCM database and use the values from the appropriate parameters of the client request to update the attributes of this newly created service record.

The server MUST convert the location specified in the lpBinaryPathName parameter to the appropriate WoW redirected location if the service binary is compiled for an architecture other than the server’s native architecture.

If the service is created successfully, the server MUST return a handle to the service in the lpServiceHandle parameter with the access rights associated with this handle as specified in the dwDesiredAccess parameter of the client request.

The only valid combinations of values for dwServiceType are SERVICE_INTERACTIVE_PROCESS and SERVICE_WIN32_OWN_PROCESS or SERVICE_INTERACTIVE_PROCESS and SERVICE_WIN32_SHARE_PROCESS. If the value of dwServiceType has more than one bit set and the combination of bits is not equal to SERVICE_INTERACTIVE_PROCESS and SERVICE_WIN32_OWN_PROCESS or SERVICE_INTERACTIVE_PROCESS and SERVICE_WIN32_SHARE_PROCESS, the server MUST fail the method and return the error ERROR_INVALID_PARAMETER.

If lpBinaryPathName contains arguments, the server MUST pass these arguments to the service entry point.

If lpdwTagId has a valid value and lpLoadOrderGroup is either NULL or an empty string, then the server MUST return ERROR_INVALID_PARAMETER.