NetServiceControl or Net32ServiceControl

The NetServiceControl API manages the operations of network services.

Restrictions

This API can be called from DLS and OS/2 workstations. User authority is allowed limited access to this API. Administrator authority is required for full access.

 
#include <netcons.h>
#include <service.h>
 
NetServiceControl(pszServername, service, opcode,
                  arg, buf, usBuflen);         /*16 bit*/
 
Net32ServiceControl(pszServername, service, opcode,
              arg, buf, ulBuflen);       /*32 bit*/

See Common Parameter Definitions for descriptions of parameters not defined here.

service

(const unsigned char *) points to an ASCIIZ string containing the name of the network service being managed.

opcode

arg

arg values for each service are defined in the SERVICE.H header file. The requester PAUSE and CONTINUE commands include the following options: ┌───────────────────────────┬───────┬──────────────────────────────────────────┐
│ SYMBOLIC CONSTANT │ VALUE │ MEANING │
├───────────────────────────┼───────┼──────────────────────────────────────────┤
│ SERVICE_CTRL_REDIR_DISK │ 1 │ Disk resource │
├───────────────────────────┼───────┼──────────────────────────────────────────┤
│ SERVICE_CTRL_REDIR_PRINT │ 2 │ Print resource │
├───────────────────────────┼───────┼──────────────────────────────────────────┤
│ SERVICE_CTRL_REDIR_COMM │ 4 │ Serial device │
└───────────────────────────┴───────┴──────────────────────────────────────────┘

buf
(unsigned char LSFAR *) points to the data structure described in Service Level 2.

Return Codes

The following table lists the return codes most significant to this API. (See API Return Codes for a complete list of return codes.) ┌──────────────────────────────┬───────┬───────────────────────────────────────┐│SYMBOLICCONSTANT │VALUE│MEANING │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ NERR_Success │ 0 │ No errors were encountered. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ ERROR_ACCESS_DENIED │ 5 │ Administrator privilege is required. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ ERROR_BAD_NETPATH │ 53 │ The network path cannot be found. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ ERROR_NETWORK_ACCESS_DENIED │ 65 │ Network access is denied. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ NERR_NetNotStarted │ 2102 │ The redirector NETWKSTA.200 has not │
│ │ │ been started. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ NERR_ShareMem │ 2104 │ An internal error occurred-the │
│ │ │ network cannot access a shared memory │
│ │ │ segment. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ NERR_BufTooSmall │ 2123 │ The buffer is too small for fixed- │
│ │ │ length data. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ NERR_InternalError │ 2140 │ An internal error has occurred. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ NERR_BadTransactConfig │ 2141 │ The server is not configured for │
│ │ │ transactions. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ NERR_InvalidAPI │ 2142 │ The requested API is not supported on │
│ │ │ the remote server. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ NERR_ServiceTableLocked │ 2180 │ The service does not respond to │
│ │ │ control actions. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ NERR_ServiceNotInstalled │ 2184 │ The service has not been started. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ NERR_ServiceCtlTimeout │ 2186 │ The service is not responding to the │
│ │ │ control function. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ NERR_ServiceCtlBusy │ 2187 │ The service control is busy. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ NERR_ServiceNotCtrl │ 2189 │ The service cannot be controlled in │
│ │ │ its present state. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ NERR_ServiceKillProc │ 2190 │ The service was ended abnormally. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ NERR_ServiceCtlNotValid │ 2191 │ The requested pause or stop is not │
│ │ │ valid for this service. │
├──────────────────────────────┼───────┼───────────────────────────────────────┤
│ NERR_InvalidComputer │ 2351 │ The specified computer name is not │
│ │ │ valid. │
└──────────────────────────────┴───────┴───────────────────────────────────────┘

Other codes could be returned from the following functions:

DosFlagProcess

DosFsCtl

DosGetInfoSeg

DosGetShrSeg

DosSemWait

Remarks

If the operation requested by the control opcode takes a long time to finish, the status and code values that the NetServiceControl API returns might be intermediate. Thus, for long-running operations, an application should issue successive calls to the NetServiceControl API to verify that the operation has been completed.
The NetServiceControl API acts only on services that are started. If a service is in the UNINSTALLED, UNINSTALL_PENDING, or INSTALL_PENDING state, the NetServiceControl API returns the NERR_ServiceCtlNotValid error code. There is one exception to this rule. An application can pass the opcode parameter with the value 0 (interrogation) to query the last known state of a stopped service. (If a service never has been started, the NetServiceControl API returns the NERR_ServiceNotInstalled error code.)
Services can be written to recognize a particular set of opcodes, as appropriate.
Related Information

For information about:

Listing the services started on a server, see Services - NetServiceEnum.

Updating status and code information for a service, see Services - NetServiceStatus.

[Back: Service Status Data Structure]
[Next: NetServiceEnum or Net32ServiceEnum]