Service Category

Service API functions control network services. The Service category functions, data types, structures, and constants are defined in the netcons.h, neterr.h, and service.h header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETSERVICE and including the lan.h master header file. To use NetServiceGetStartup and NetServiceSetStartup, the lmsec.h, winsvc.h, and unixapi.h files also must be included.

These are the functions in the Service category.

Function	Description
NetServiceControl	Controls the operations of network services.
NetServiceEnum	Retrieves information about all network services installed on a server.
NetServiceGetInfo	Retrieves information about a specified network service installed on a server.
NetServiceGetStartup	Retrieves the configuration parameters of the specified service.
NetServiceSetStartup	Changes the configuration parameters of a service.
NetServiceStatus	Sets status and code information for a network service.

A service is a program of any size and function that other applications can use to perform some set of tasks on the network. An application installs and controls the operation of services with the functions in the Service category.

Services allow administrators to control applications on the network and maintain the integrity of users’ data. On a typical network, applications are shared by many users. If an administrator terminates an application running on a server, a user who has not finished working with that application can lose important data. When an application is implemented as a service, the Advanced Server checks the status before changing the state of the service.

The Advanced Server provides several standard services, such as the Server and Alerter services.

To create and install a service on the Advanced Server, the following conditions must exist:

1. Any application or service that needs to be started automatically on the server must be installed in the /var/opt/lanman/service directory.

2. To make the Advanced Server aware of these applications or services, each must call the NetServiceStatus API.

The Advanced Server will send a signal to each of these services when the Advanced Server software is stopped.

Many of the Service category API functions require a service name. The service.h header file defines the following names for the standard services:

Code	ASCIIZ String	Service
SERVICE_WORKSTATION	WORKSTATION	Workstation
SERVICE_SERVER	SERVER	Server
SERVICE_MESSENGER	MESSENGER	Messenger
SERVICE_NETRUN	NETRUN	Netrun
SERVICE_ALERTER	ALERTER	Alerter
SERVICE_NETLOGON	NETLOGON	Net Logon
SERVICE_REPL	REPLICATOR	Directory Replicator
SERVICE_RIPL	REMOTEBOOT	Remoteboot
SERVICE_TIMESOURCE	TIMESOURCE	Time Source

Service Category Data Structures

NetServiceControl, NetServiceEnum, and NetServiceGetInfo use the service_info data structures. NetServiceEnum and NetServiceGetInfo return information at three levels of detail (0, 1, or 2). NetServiceControl uses the level 2 data structure only.

Service Information (level 0)

The service_info_0 data structure has the following format:

struct service_info_0 {

char svci0_name[LM20_SNLEN+1];

};

Within this structure, svci0_name is an ASCIIZ string containing the name of the network service to monitor.

Service Information (level 1)

The service_info_1 data structure has the following format:

struct service_info_1 {

char svci1_name[LM20_SNLEN+1];

unsigned short svci1_status;

unsigned long svci1_code;

unsigned short svci1_pid;

};

Within this structure, the following parameters are defined:

svci1_name is an ASCIIZ string naming the network service to monitor.

svci1_status through svci1_pid are the same as the corresponding elements of the service_status data structure (see Service Status).

Service Information (level 2)

The service_info_2 data structure has the following format:

struct service_info_2 {

char svci2_name[LM20_SNLEN+1];

unsigned short svci2_status;

unsigned long svci2_code;

unsigned short svci2_pid;

char svci2_text[LM20_STXTLEN+1];

};

Within this structure, the following parameters are defined:

svci2_name through svci2_text are the same as the corresponding parameters in the previous section. See Service Status for detailed descriptions.

Service Status

The NetServiceStatus function uses the following data structure:

struct service_status {

unsigned short svcs_status;

unsigned long svcs_code;

unsigned short svcs_pid;

char svcs_text[STXTLEN+1];

};

Within this structure, the following parameters are defined:

svcs_status specifies the status of the service. The status element is composed of several sub fields. The service.h header file defines these possible values:

Bits	Code	Bit Mask	Description
0-1	SERVICE_INSTALL_STATE	0x03	General status of the service.
2-3	SERVICE_PAUSE_STATE	0x0C	Paused/active state.
4	—	—	Service can or cannot be installed.
5	—	—	Service can or cannot be paused.
6-7	—	—	Reserved.
8-10	SERVICE_REDIR_PAUSED	0x0700	Redirection paused/active.
11-15	—	—	Reserved.

Bits 0-1 have the following values:

Manifest	Value	Meaning
SERVICE_UNINSTALLED	0x00	Service uninstalled.
SERVICE_INSTALL_PENDING	0x01	Service install pending.
SERVICE_UNINSTALL_PENDING	0x02	Service uninstall pending.
SERVICE_INSTALLED	0x03	Service installed.

Bits 2-3 have the following values:

Manifest	Value	Meaning
SERVICE_ACTIVE	0x00	Service active.
SERVICE_CONTINUE_PENDING	0x04	Service continue pending.
SERVICE_PAUSE_PENDING	0x08	Service pause pending.
SERVICE_PAUSED	0x0C	Service paused.

Bit 4 has the following values:

Manifest	Value	Meaning
SERVICE_NOT_UNINSTALLABLE	0x00	Service cannot be removed.
SERVICE_UNINSTALLABLE	0x10	Service can be removed.

Bit 5 has the following values:

Manifest	Value	Meaning
SERVICE_NOT_PAUSABLE	0x00	Service cannot be paused.
SERVICE_PAUSABLE	0x20	Service can be paused.

Bit 6 has the following values:

Manifest	Value	Meaning
SERVICE_NOT_SECURE	0x00	Anyone can remove the service.
SERVICE_SECURE	0x40	Only the system administrator can remove the service.

Bits 8-10 have the following values:

Manifest	Value	Meaning
SERVICE_REDIR_PAUSED	0x700	Redirector paused.
SERVICE_REDIR_DISK_PAUSED	0x100	Redirector for disks paused.
SERVICE_REDIR_PRINT_PAUSED	0x200	Redirector for spooled devices paused.
SERVICE_REDIR_COMM_PAUSED	0x400	Redirector for communication devices paused. Specifies a code that indicates the service’s status.

svcs_code is the return code returned if the designated service uninstalls or fails to install properly.

For uninstalled services (SERVICE_UNINSTALL), the high word of svci1_code defines primary return codes and the low word of svci1_code defines secondary return codes. High-word values of svci1_code are defined as follows:

Manifest	Value	Meaning
SERVICE_UIC_NORMAL	0	Normal
SERVICE_UIC_BADPARMVAL	3051	Bad parameter value specified.
SERVICE_UIC_MISSPARM	3052	Missing parameter.
SERVICE_UIC_UNKPARM	3053	Unknown parameter specified.
SERVICE_UIC_RESOURCE	3054	Insufficient resource.
SERVICE_UIC_CONFIG	3055	Configuration faulty.
SERVICE_UIC_SYSTEM	3056	OS/2 error.
SERVICE_UIC_INTERNAL	3057	Internal error encountered.
SERVICE_UIC_AMBIGPARM	3058	Ambiguous parameter name.
SERVICE_UIC_DUPPARM	3059	Parameter duplicated.
SERVICE_UIC_KILL	3060	Killed by NetServiceControl: no response.
SERVICE_UIC_EXEC	3061	Could not execute service program.
SERVICE_UIC_SUBSERV	3062	Subservice failed to install.
SERVICE_UIC_CONFLPARM	3063	Conflict in value or parameters.
SERVICE_UIC_FILE	3064	Problem with the file.

Low-word values of svci1_code are defined as follows:

Manifest	Value	Meaning
SERVICE_UIC_M_NULL	0	Normal.
SERVICE_UIC_M_MEMORY	3070	Insufficient memory.
SERVICE_UIC_M_DISK	3071	Insufficient disk space.
SERVICE_UIC_M_THREADS	3072	Unable to create thread.
SERVICE_UIC_M_PROCESSES	3073	Unable to create process.
SERVICE_UIC_M_SECURITY	3074	Security failure.
SERVICE_UIC_M_LANROOT	3075	Bad default path.
SERVICE_UIC_M_REDIR	3076	Network software not installed.
SERVICE_UIC_M_SERVER	3077	Server software not installed.
SERVICE_UIC_M_SEC_FILE_ERR	3078	The server could not access the user or security database.
SERVICE_UIC_M_LOGS	3080	Invalid lanman logs directory.
SERVICE_UIC_M_LANGROUP	3081	Domain could not be used.
SERVICE_UIC_M_MSGNAME	3082	Computername being used as a message alias on another computer.
SERVICE_UIC_M_ANNOUNCE	3083	Client failed to announce the server name.
SERVICE_UIC_M_UAS	3084	The user accounts system is not configured correctly.
SERVICE_UIC_M_WKSTA	3087	The workstation is not configured properly.
SERVICE_UIC_M_ERRLOG	3088	View error log details.
SERVICE_UIC_M_FILE_UW	3089	Unable to write to file.
SERVICE_UIC_M_ADDPAK	3090	The addpak file is corrupt. Delete the file and reapply all addpaks.

For install or uninstall pending (SERVICE_INSTALL_PENDING or SERVICE_UNINSTALL_PENDING) services, the bits of svci1_code are defined in the service.h file, as follows:

Bits	Code	Bit Mask	Meaning
0-7	SERVICE_IP_NO_HINT SERVICE_IP_CHKPT_NUM	0x0FF	Checkpoint number.
8-15	SERVICE_CCP_WAIT_TIMESERVICE_IP_WAIT_TIME	0x0FF00	Time to wait (in tenths of a second) for install or uninstall.
16	SERVICE_CCP_QUERY_HINTSERVICE_IP_QUERY_HINT	0x10000	If 1, a hint is given.
17-32			Reserved; must be 0.

svcs_pid is a service’s program identification number (PID).

svcs_text contains an ASCIIZ string if the service is stopped or a null string if the service is running. In this case, svcs_text can contain a parameter string related to the CCP code contained in the svcs_code element. The constant STXTLEN is defined in the netcons.h file.

Service Configuration

The NetServiceGetStartup function uses the following data structure:

typedef struct _QUERY_SERVICE_CONFIG {

DWORD dwServiceType;

DWORD dwStartType;

DWORD dwErrorControl;

LPTSTR lpBinaryPathName;

LPTSTR lpLoadOrderGroup;

DWORD dwTagId;

LPTSTR lpDependencies;

LPTSTR lpServiceStartName;

LPTSTR lpDisplayName;

} QUERY_SERVICE_CONFIG, LPQUERY_SERVICE_CONFIG;

Within this structure, the following parameters are defined:

dwServiceType indicates the type of service. One of the following values is specified:

Type	Meaning
SERVICE_WIN32_OWN_PROCESS	Specifies a service that runs in its own Win32 process.
SERVICE_WIN32_SHARE_PROCESS	Specifies a service that shares a Win32 process with other services.
SERVICE_KERNEL_DRIVER	Specifies a Windows NT device driver.
SERVICE_FILE_SYSTEM_DRIVER	Specifies a Windows NT file system driver.

Only SERVICE_WIN32_OWN_PROCESS value is valid for the Advanced Server.

dwStartType specifies when to start the service. One of the following values is specified:

Value	Meaning
SERVICE_BOOT_START	Specifies a device driver started by the operating system loader. This value is valid only if service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_SYSTEM_START	Specifies a device driver started by the IoInitSystem function. This value is valid only if service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_AUTO_START	Specifies a service or a device driver started by the service control manager automatically during system startup.
SERVICE_DEMAND_START	Specifies a service or a device driver started by the service control manager on demand.
SERVICE_DISABLED	Specifies service or device driver that can no longer be started.

Only SERVICE_AUTO_START, SERVICE_DEMAND_START and SERVICE_DISABLED values are valid in Advanced Server.

dwErrorControl specifies the severity of the error if this service fails to start during startup and determines the action taken by the startup program if failure occurs. One of the following values can be specified:

Value	Meaning
SERVICE_ERROR_IGNORE	The startup program logs the error but continues the startup operation.
SERVICE_ERROR_NORMAL	The startup program logs the error and puts up a message box pop-up but continues the startup operation.
SERVICE_ERROR_SEVERE	The startup program 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	The startup program logs 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.

Only SERVICE_ERROR_IGNORE value is valid for the Advanced Server.

lpBinaryPathName points to a null-terminated string that contains the fully qualified path to the service binary file.

This field is meaningless for the Advanced Server.

lpLoadOrderGroup points to a null-terminated string that names the load ordering group of which this service is a member. If the pointer is NULL or if it points to an empty string, the service does not belong to a group. The registry has a list of load ordering groups at HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ ServiceGroupOrder.

The startup program uses this list to load groups of services in a specified order with respect to the other groups in the list. You can place a service in a group so that another service can depend on the group.

The order in which a service starts is determined by these criteria:

1. The order of groups in the registry's load-ordering group list. Services in groups in the load-ordering group list are started first, followed by services in groups not in the load-ordering group list and then services that do not belong to a group.

2. The service's dependencies listed in the lpszDependencies parameter and the dependencies of other services dependent on the service.

This field is meaningless for the Advanced Server.

dwTagId specifies a unique tag value for this service in the group specified by the lpLoadOrderGroup parameter. A value of zero indicates that the service has not been assigned a tag.

You can use a tag for ordering service startup within a load order group by specifying a tag order vector in the registry at HKEY_LOCAL_MACHINE\ System\CurrentControlSet\Control\GroupOrderList.

Tags are only evaluated for SERVICE_KERNEL_DRIVER and SERVICE_FILE_SYSTEM_DRIVER type services that have SERVICE_BOOT_START or SERVICE_SYSTEM_START start types.

This field is meaningless for the Advanced Server.

lpDependencies points 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. If the pointer is NULL or if it points to an empty string, the service has no dependencies.

If a group name is specified, it must be prefixed by the SC_GROUP_IDENTIFIER (defined in the WINSVC.H file) character to differentiate it from a service name, because services and service groups share the same name space.

Dependency on a service means that this service can only run 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.

This field is meaningless for the Advanced Server.

lpServiceStartName points to a null-terminated string. If the service type is SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS. This name is the account name in the form of "DomainName\Username" which the service process will be logged on as when it runs.

If the account belongs to the built-in domain, .\Username can be specified. If NULL is specified, the service will be logged on as the LocalSystem account.

If the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER, this name is the Windows NT driver object name (that is, \FileSystem\Rdr or \Driver\Xns) which the input and output (I/O) system uses to load the device driver.

If NULL is specified, the driver is run with a default object name created by the I/O system based on the service name.

lpDisplayName points to a null-terminated string to be used by user interface programs to identify the service. This string has a maximum length of 256 characters. The name is case-preserved in the Service Control Manager.

Display name comparisons are case-insensitive.